docs: define plugin marketplace and sdk boundary contracts#1196
Open
chumyin wants to merge 3 commits intoeastreams:devfrom
Open
docs: define plugin marketplace and sdk boundary contracts#1196chumyin wants to merge 3 commits intoeastreams:devfrom
chumyin wants to merge 3 commits intoeastreams:devfrom
Conversation
The existing plugin package and compatibility contracts already define strong kernel and governance boundaries, but future SDK and marketplace work still lacked one strategy document that tied native authoring, foreign-dialect compatibility, marketplace packaging, and migration together. This adds that strategy layer and links it from the existing package and OpenClaw compatibility contracts so follow-on SDK and ecosystem work has one public architecture source of truth. Constraint: Existing plugin package and compatibility documents remain the normative source for manifest and activation behavior Rejected: Copy OpenClaw runtime registration semantics into the native SDK | conflicts with kernel-first, fail-closed boundaries Rejected: Fold marketplace metadata into kernel activation metadata | would blur display/install policy with activation authority Confidence: high Scope-risk: narrow Reversibility: clean Directive: Treat the named SDK layers as illustrative architecture slices, not as a locked future crate layout, unless a later RFC explicitly commits to that packaging Tested: cargo fmt --all -- --check; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo test --workspace --locked; cargo test --workspace --all-features --locked Not-tested: LOONGCLAW_RELEASE_DOCS_STRICT=1 scripts/check-docs.sh still fails on untouched release-trace/debug-doc baseline gaps under .docs/ and docs/releases
The package, compatibility, and SDK strategy docs already describe runtime truth, but marketplace, install-policy, and interface-metadata concerns were still implied across multiple places without one contract. That left future catalog and install work vulnerable to parallel metadata drift. This adds a dedicated marketplace contract and links it from the existing plugin package, compatibility, and SDK strategy docs so future catalog work has one explicit package-versus-marketplace boundary. Constraint: Marketplace metadata must remain listing-scoped and may not widen activation or governance authority Rejected: Let catalog metadata double as activation truth | would create shadow authority outside manifest, preflight, and attestation boundaries Rejected: Delay marketplace contract until the full SDK crate lands | leaves registry and install tooling without a stable catalog contract Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep future marketplace implementations aligned with this catalog contract and the existing `marketplace_submission` preflight lane instead of introducing a separate policy parser Tested: cargo fmt --all -- --check; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo test --workspace --locked; cargo test -p loongclaw-app channel::http::tests::outbound_http_client_does_not_follow_redirects -- --exact --nocapture; cargo test --workspace --all-features --locked Not-tested: LOONGCLAW_RELEASE_DOCS_STRICT=1 scripts/check-docs.sh still fails on untouched release-trace/debug-doc baseline gaps under .docs/ and docs/releases
📝 WalkthroughWalkthroughAdds three new design documents (marketplace contract, SDK boundary contract, SDK & ecosystem strategy), updates the design-doc index to list them as Active, and adds cross-references from existing compatibility and manifest contract docs to the new documents. All changes are documentation-only. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
documentation
The plugin package, compatibility, marketplace, and ecosystem strategy docs already define lower-level truth, but future SDK work still lacked one explicit boundary for contract types, bridge helpers, compatibility helpers, and the separate native host-extension lane. This adds that boundary contract and links it back into the existing docs so future SDK work can advance in smaller slices without re-opening the whole architecture question. Constraint: SDK helper layers must consume package, marketplace, and governance truth rather than redefining it Rejected: Treat the WASM guest SDK RFC as the total plugin SDK architecture | would overfit one helper slice into the whole SDK story Rejected: Expose host internals through one broad default SDK crate | would blur guest-side helpers, host-native extension lanes, and compatibility tooling Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep future SDK implementations aligned with this boundary and keep native host-extension APIs separately host-approved, non-default, and distinct from compatibility-origin helper lanes Tested: cargo fmt --all -- --check; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo test --workspace --locked; cargo test --workspace --all-features --locked Not-tested: LOONGCLAW_RELEASE_DOCS_STRICT=1 scripts/check-docs.sh still fails on untouched release-trace/debug-doc baseline gaps under .docs/ and docs/releases
chumyin
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/design-docs/plugin-sdk-and-ecosystem-strategy.md (1)
124-172: Trim detailed external comparison content in public strategy docs.This section is very detailed about an external project’s internal paths and structure. Consider reducing it to a short, LoongClaw-focused principle summary and moving detailed comparisons to the knowledge-base.
Based on learnings: Public-repo issues, PRs, and public documentation should stay LoongClaw-centric; keep detailed external project comparisons in
loongclaw-ai/knowledge-baseunless naming an external project is strictly necessary.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/design-docs/plugin-sdk-and-ecosystem-strategy.md` around lines 124 - 172, The "What Codex Teaches" section exposes too many external-project internals (e.g., references to `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`)—trim this to a short LoongClaw-focused principles summary (keep the three high-level lessons: separate marketplace policy from runtime contract, plugin bundles compose product surfaces, and interface metadata belongs in a stable contract) and move the detailed external-path comparisons into the knowledge-base (loongclaw-ai/knowledge-base) or an appendix; preserve the conceptual points and remove or genericize explicit external file-path examples so the public doc remains LoongClaw-centric.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/design-docs/plugin-sdk-and-ecosystem-strategy.md`:
- Around line 52-66: The executive summary currently claims "five layers" but
lists only four and omits the previously defined foreign-dialect normalization
layer (Layer 2); update the paragraph to include the missing "Foreign-dialect
normalization" layer and renumber the list 1–5 so each named layer matches its
detailed definition: insert a new item "2. Foreign-dialect normalization layer —
one normalization/translation boundary for foreign dialects and compatibility
transforms" (or similar wording), shift "Marketplace and interface contract" to
3, "Runtime bridge contract" to 4, and "SDK and migration contract" to 5, and
ensure the opening line still reads "The mature ecosystem shape has five layers"
to reflect the corrected mapping.
---
Nitpick comments:
In `@docs/design-docs/plugin-sdk-and-ecosystem-strategy.md`:
- Around line 124-172: The "What Codex Teaches" section exposes too many
external-project internals (e.g., references to `.codex-plugin/plugin.json` and
`.agents/plugins/marketplace.json`)—trim this to a short LoongClaw-focused
principles summary (keep the three high-level lessons: separate marketplace
policy from runtime contract, plugin bundles compose product surfaces, and
interface metadata belongs in a stable contract) and move the detailed
external-path comparisons into the knowledge-base (loongclaw-ai/knowledge-base)
or an appendix; preserve the conceptual points and remove or genericize explicit
external file-path examples so the public doc remains LoongClaw-centric.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 776154e2-7fea-4e8f-b6e5-519b2ebb5373
📒 Files selected for processing (5)
docs/design-docs/index.mddocs/design-docs/plugin-marketplace-contract.mddocs/design-docs/plugin-package-manifest-contract.mddocs/design-docs/plugin-sdk-and-ecosystem-strategy.mddocs/design-docs/plugin-sdk-boundary-contract.md
✅ Files skipped from review due to trivial changes (4)
- docs/design-docs/index.md
- docs/design-docs/plugin-sdk-boundary-contract.md
- docs/design-docs/plugin-package-manifest-contract.md
- docs/design-docs/plugin-marketplace-contract.md
Comment on lines
+52
to
+66
| The mature ecosystem shape has five layers: | ||
|
|
||
| 1. **Native package contract** | ||
| - one stable host-facing plugin contract | ||
| - one typed manifest-first package shape | ||
| 2. **Marketplace and interface contract** | ||
| - one user-facing catalog shape for install, auth, category, and display | ||
| - decoupled from kernel activation semantics | ||
| 3. **Runtime bridge contract** | ||
| - one bridge-oriented execution boundary for `process_stdio`, `http_json`, | ||
| `mcp_server`, future WASM, and related lanes | ||
| 4. **SDK and migration contract** | ||
| - one native SDK family for LoongClaw packages | ||
| - one compatibility SDK family for OpenClaw ingestion and migration | ||
|
|
There was a problem hiding this comment.
Fix the executive-summary layer count and mapping.
Line 52 says “five layers,” but only four are listed, and the list omits the foreign-dialect normalization layer that is later defined as Layer 2. This creates architectural ambiguity for readers implementing the strategy.
Suggested doc fix
-The mature ecosystem shape has five layers:
+The mature ecosystem shape has five layers:
1. **Native package contract**
- one stable host-facing plugin contract
- one typed manifest-first package shape
-2. **Marketplace and interface contract**
+2. **Foreign dialect normalization contract**
+ - one normalization seam that projects foreign descriptors into canonical LoongClaw truth
+ - explicit compatibility-mode selection before activation
+3. **Marketplace and interface contract**
- one user-facing catalog shape for install, auth, category, and display
- decoupled from kernel activation semantics
-3. **Runtime bridge contract**
+4. **Runtime bridge contract**
- one bridge-oriented execution boundary for `process_stdio`, `http_json`,
`mcp_server`, future WASM, and related lanes
-4. **SDK and migration contract**
+5. **SDK and migration contract**
- one native SDK family for LoongClaw packages
- one compatibility SDK family for OpenClaw ingestion and migration📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The mature ecosystem shape has five layers: | |
| 1. **Native package contract** | |
| - one stable host-facing plugin contract | |
| - one typed manifest-first package shape | |
| 2. **Marketplace and interface contract** | |
| - one user-facing catalog shape for install, auth, category, and display | |
| - decoupled from kernel activation semantics | |
| 3. **Runtime bridge contract** | |
| - one bridge-oriented execution boundary for `process_stdio`, `http_json`, | |
| `mcp_server`, future WASM, and related lanes | |
| 4. **SDK and migration contract** | |
| - one native SDK family for LoongClaw packages | |
| - one compatibility SDK family for OpenClaw ingestion and migration | |
| The mature ecosystem shape has five layers: | |
| 1. **Native package contract** | |
| - one stable host-facing plugin contract | |
| - one typed manifest-first package shape | |
| 2. **Foreign dialect normalization contract** | |
| - one normalization seam that projects foreign descriptors into canonical LoongClaw truth | |
| - explicit compatibility-mode selection before activation | |
| 3. **Marketplace and interface contract** | |
| - one user-facing catalog shape for install, auth, category, and display | |
| - decoupled from kernel activation semantics | |
| 4. **Runtime bridge contract** | |
| - one bridge-oriented execution boundary for `process_stdio`, `http_json`, | |
| `mcp_server`, future WASM, and related lanes | |
| 5. **SDK and migration contract** | |
| - one native SDK family for LoongClaw packages | |
| - one compatibility SDK family for OpenClaw ingestion and migration |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/design-docs/plugin-sdk-and-ecosystem-strategy.md` around lines 52 - 66,
The executive summary currently claims "five layers" but lists only four and
omits the previously defined foreign-dialect normalization layer (Layer 2);
update the paragraph to include the missing "Foreign-dialect normalization"
layer and renumber the list 1–5 so each named layer matches its detailed
definition: insert a new item "2. Foreign-dialect normalization layer — one
normalization/translation boundary for foreign dialects and compatibility
transforms" (or similar wording), shift "Marketplace and interface contract" to
3, "Runtime bridge contract" to 4, and "SDK and migration contract" to 5, and
ensure the opening line still reads "The mature ecosystem shape has five layers"
to reflect the corrected mapping.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
LoongClaw already had a manifest-first plugin package contract, an OpenClaw compatibility contract, an ecosystem strategy document, and a marketplace contract, but it still lacked one explicit boundary contract for the author-facing SDK family. Without that layer, future SDK work can sprawl across guest-side helpers, host-native extension APIs, and compatibility tooling without a clear separation rule.
Without an SDK boundary contract, the project risks letting a single bridge-targeted SDK slice (such as the WASM guest SDK in
#426) become the accidental shape of the whole plugin SDK story, while helper crates drift into parallel metadata or policy models.docs/design-docs/plugin-sdk-boundary-contract.md#426WASM guest SDKLinked Issues
Change Type
Touched Areas
Risk Track
Validation
cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo test --workspace --lockedcargo test --workspace --all-features --lockedCommands and evidence:
User-visible / Operator-visible Changes
Failure Recovery
Revert the documentation changes or drop the SDK boundary contract from this branch before merge.
Boundary drift between package truth, marketplace truth, compatibility truth, and future SDK helper responsibilities.
Reviewer Focus
#426is now framed as one implementation slice rather than the total plugin SDK architecture.Summary by CodeRabbit