feat(plugins): add embedding provider contract#84947
Conversation
|
Codex review: needs real behavior proof before merge. Workflow note: Future ClawSweeper reviews update this same comment in place. How this review workflow works
Summary Reproducibility: not applicable. this is a feature PR adding a new plugin contract, not a bug report. Source inspection confirms current main only has memory-scoped embedding provider APIs and manifest contracts. PR rating Rank-up moves:
What the crustacean ranks mean
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics. Real behavior proof Risk before merge
Maintainer options:
Next step before merge Security Review detailsBest possible solution: Land this base contract only after maintainers approve the public API/security boundary and the contributor supplies exact-head real behavior proof; then review the memory bridge and concrete provider PRs separately. Do we have a high-confidence way to reproduce the issue? Not applicable: this is a feature PR adding a new plugin contract, not a bug report. Source inspection confirms current main only has memory-scoped embedding provider APIs and manifest contracts. Is this the best way to solve the issue? Unclear until maintainers approve the public API direction. The implementation matches existing manifest-owned registry patterns, but the stable SDK shape and credential boundary are product/security decisions rather than mechanical correctness questions. Label changes:
Label justifications:
What I checked:
Likely related people:
Codex review notes: model gpt-5.5, reasoning high; reviewed against eb7f3b7b50c5. |
|
ClawSweeper PR egg 🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat. Where did the egg go?
|
abf59e6 to
ec86340
Compare
Current-head proof for 41ebd66Behavior addressed: adds the generic plugin-layer Real environment tested: local OpenClaw source checkout on the PR head Exact steps or command run after this patch: node scripts/run-vitest.mjs src/plugins/embedding-provider-runtime.test.ts src/plugins/loader.test.ts src/plugins/loader.runtime-registry.test.ts src/plugins/embedding-providers.test.ts src/plugins/contracts/embedding-provider.contract.test.ts src/plugins/loader-records.test.ts
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-embedding-providers-localtest.tsbuildinfo
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test-embedding-providers-localtest.tsbuildinfo
node scripts/run-oxlint.mjs src/plugins/embedding-provider-runtime.ts src/plugins/embedding-provider-runtime.test.ts src/plugins/registry.ts src/plugins/loader.test.ts src/plugin-sdk/embedding-providers.ts src/plugins/contracts/embedding-provider.contract.test.ts
node --max-old-space-size=8192 --import tsx scripts/generate-plugin-sdk-api-baseline.ts --check
node scripts/sync-plugin-sdk-exports.mjs --check
node scripts/check-plugin-sdk-subpath-exports.mjs
node scripts/check-docs-mdx.mjs docs/plugins/sdk-subpaths.md
git diff --checkEvidence after fix:
Observed result after fix: the generic embedding provider contract and runtime registration path are covered by focused tests, the public SDK subpath remains read-only so plugins cannot bypass manifest ownership, and the generated Plugin SDK API baseline now matches the current public surface at head. What was not tested: no real embedding model or live embedding endpoint was run for this PR. That belongs to the stacked provider/bridge PRs, especially #84998. |
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
|
@clawsweeper automerge |
|
🦞✅ Approver: What merged:
Automerge notes:
The automerge loop is complete. Automerge progress:
|
|
🦞✅ Source: Why human review is needed: What the maintainer can do as a next step: I added |
|
@clawsweeper approve |
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary: - Merged feat(plugins): add embedding provider contract after ClawSweeper review. Automerge notes: - PR branch already contained follow-up commit before automerge: chore(plugins): refresh embedding provider sdk baseline - PR branch already contained follow-up commit before automerge: docs(plugins): document embedding provider contract - PR branch already contained follow-up commit before automerge: fix(plugins): restore embedding providers after snapshot loads - PR branch already contained follow-up commit before automerge: fix(plugins): resolve embedding providers from manifests - PR branch already contained follow-up commit before automerge: fix(plugin-sdk): keep embedding provider registry mutators internal - PR branch already contained follow-up commit before automerge: chore(plugin-sdk): refresh embedding provider API baseline Validation: - ClawSweeper review passed for head 41ebd66. - Required merge gates passed before the squash merge. Prepared head SHA: 41ebd66 Review: openclaw#84947 (comment) Co-authored-by: Bob <dutifulbob@gmail.com> Co-authored-by: Mariano Belinky <mbelinky@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: osolmaz Co-authored-by: osolmaz <2453968+osolmaz@users.noreply.github.com>
Summary
Embeddings are not only a memory feature.
This adds the first plugin-layer contract for general embedding providers, without moving memory or adding a real provider yet.
It gives future provider plugins a
contracts.embeddingProvidersmanifest key andapi.registerEmbeddingProvider(...)registration API so later PRs can bridge memory and add OpenAI-compatible embeddings cleanly.What Changed
This is the contract plumbing PR only.
It deliberately avoids adding production provider behavior so the new public surface can be reviewed on its own.
contracts.embeddingProvidersmanifest parsing and merge support.api.registerEmbeddingProvider(...)to the plugin API and test API.openclaw/plugin-sdk/embedding-providersfor safe read helpers and types; registration stays behindapi.registerEmbeddingProvider(...)so manifest ownership is enforced.Testing
Latest local checks at
fad85638a03657f8354bb19768c109d5270a8354:node scripts/run-vitest.mjs src/plugins/embedding-provider-runtime.test.ts src/plugins/loader.test.ts src/plugins/loader.runtime-registry.test.ts src/plugins/embedding-providers.test.ts src/plugins/contracts/embedding-provider.contract.test.ts src/plugins/loader-records.test.ts-> passed, 6 files / 172 tests.node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-embedding-providers.tsbuildinfo-> passed.node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test-embedding-providers.tsbuildinfo-> passed.node scripts/run-oxlint.mjs src/plugins/embedding-provider-runtime.ts src/plugins/embedding-provider-runtime.test.ts src/plugins/registry.ts src/plugins/loader.test.ts src/plugin-sdk/embedding-providers.ts src/plugins/contracts/embedding-provider.contract.test.ts-> passed.pnpm plugin-sdk:api:check-> passed.pnpm plugin-sdk:check-exports-> passed.node scripts/check-plugin-sdk-subpath-exports.mjs-> passed.node scripts/check-docs-mdx.mjs docs/plugins/sdk-subpaths.md-> passed.git diff --check-> passed.Earlier docs checks on this branch:
node scripts/format-docs.mjs --check-> passed.node scripts/check-docs-mdx.mjs docs/plugins/manifest.md docs/plugins/sdk-overview.md docs/plugins/sdk-subpaths.md docs/plugins/sdk-provider-plugins.md docs/plugins/architecture.md docs/plugins/adding-capabilities.md-> passed.node scripts/check-changed.mjs --helpaccidentally ran the fail-safe changed check before later follow-up commits; it completed all selected lanes successfully, including all-project typecheck, lint shards, and runtime import cycle check.Risks
The main risk is public SDK surface shape.
This PR adds the registry and API but does not yet migrate memory or any real provider, so runtime behavior should remain unchanged unless a plugin opts into the new API.
Follow-ups
embeddingProvidersto memory embedding providers.openai-compatibleas a general embedding provider after the bridge exists.Real behavior proof
Behavior addressed: Adds a general plugin contract and registration API for embedding providers; no production provider behavior is enabled in this PR.
Real environment tested: Local OpenClaw source checkout using a temporary real plugin load path and temporary
openclaw.jsonconfig.Exact steps or command run after this patch: Ran a
node --import tsxproof script that created a temporary plugin withopenclaw.plugin.jsondeclaringcontracts.embeddingProviders: ["proof-embedding"], loaded that plugin through OpenClaw's plugin registry/status code, and runtime-registeredapi.registerEmbeddingProvider(...).Evidence after fix: Terminal output from the proof run:
{ "configPath": "<temp>/state/openclaw.json", "pluginLoadPath": "<temp>/proof-embedding", "snapshot": { "id": "proof-embedding", "status": "loaded", "embeddingProviderIds": [ "proof-embedding" ] }, "runtime": { "id": "proof-embedding", "status": "loaded", "embeddingProviderIds": [ "proof-embedding" ] }, "inspect": { "shape": "plain-capability", "capabilities": [ { "kind": "embedding", "ids": [ "proof-embedding" ] } ] }, "registered": { "id": "proof-embedding", "ownerPluginId": "proof-embedding", "defaultModel": "proof-embedding-v1", "transport": "local" } }Observed result after fix: OpenClaw discovers the manifest-declared
embeddingProviderscontract, reports the plugin as a plainembeddingcapability, runtime-registers the adapter, and preserves the owner plugin id on the registered adapter. Focused follow-up regression tests atfad85638a03657f8354bb19768c109d5270a8354also prove cold manifest resolution through the SDK-backed runtime helper, scoped non-activating loads with active global providers, and that the public SDK subpath cannot bypass manifest-owned registration.What was not tested: Full GitHub CI is running now that the PR is ready for review.