Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (88 loc) · 5.16 KB

AGENTS.md

File metadata and controls

97 lines (88 loc) · 5.16 KB
Raw

Plugins Boundary

This directory owns plugin discovery, manifest validation, loading, registry assembly, and contract enforcement.

Public Contracts

  • Docs:
    • docs/plugins/architecture.md
    • docs/plugins/manifest.md
    • docs/plugins/sdk-overview.md
    • docs/plugins/sdk-entrypoints.md
  • Definition files:
    • src/plugins/types.ts
    • src/plugins/runtime/types.ts
    • src/plugins/contracts/registry.ts
    • src/plugins/public-surface-loader.ts
    • src/plugins/public-surface-runtime.ts
    • src/plugins/provider-public-artifacts.ts
    • src/plugins/web-provider-public-artifacts.ts

Boundary Rules

  • Keep control-plane and runtime-plane concerns separate: discovery, manifest parsing, config validation, setup/onboarding hints, and activation planning belong to the control plane; actual plugin execution belongs to runtime resolution.
  • Preserve manifest-first behavior: discovery, config validation, and setup should work from metadata before plugin runtime executes.
  • Keep loader behavior aligned with the documented Plugin SDK and manifest contracts. Do not create private backdoors that bundled plugins can use but external plugins cannot.
  • Preserve laziness in discovery and activation flows. Loader, registry, and public-artifact changes must not eagerly import bundled plugin runtime barrels when metadata, light exports, or typed contracts are sufficient.
  • If a plugin exposes separate light and heavy runtime surfaces, keep discovery, inventory, and setup-state checks on the light path until actual execution needs the heavy module.
  • If a loader or registry change affects plugin authors, update the public SDK, docs, and contract tests instead of relying on incidental internals.
  • Prefer explicit activation planning from manifest/descriptor ownership over “load everything in this scope” behavior. Broad registry materialization should be the exception, not the design center.
  • Do not normalize "plugin-owned" into "core-owned" by scattering direct reads of plugins.entries.<id>.config through unrelated core paths. Prefer generic helpers, plugin runtime hooks, manifest metadata, and explicit auto-enable wiring.
  • When plugin-owned tools or provider fallbacks need core participation, keep the contract generic and honor plugin disablement plus SecretRef semantics.
  • Keep contract loading and contract tests on the dedicated bundled registry path. Do not make contract validation depend on activating providers through unrelated production resolution flows.
  • Prefer shared provider-family helpers over ad hoc policy in plugin registry hooks. If multiple providers need the same replay policy, tool compat, stream wrapper composition, or payload patch behavior, centralize that helper before adding another plugin-local lambda.
  • Keep provider policy layers separated: auth/catalog/onboarding stay plugin-owned, transport/replay/tool compat families belong in shared helpers, registry/runtime code should compose those layers rather than re-encoding policy inline.
  • When a provider hook grows a nested chain of wrapper composition or repeated compat flags, treat that as a regression signal. Extract the shared helper or composer instead of letting one more plugin carry a near-copy.
  • Treat mutable global runtime registry state as compatibility scaffolding, not the desired source of truth for request-time execution. Prefer immutable or request-scoped handles when adding new runtime flows.
  • If setup, discovery, or doctor flows need plugin runtime, make that need explicit and narrow. Do not let cold control-plane paths quietly import broad runtime surfaces.
  • Resolver and public-surface loader tests must use generated tiny plugin fixtures for broad api.js / runtime-api.js fallback behavior. Do not point those tests at real bundled plugin source APIs just to prove path resolution.

Availability And Selection

  • Gateway plugin metadata is stable while the Gateway runs. Reuse current snapshots, install records, discovery, lookup tables, and bounded process caches; avoid per-call stat/read/hash freshness. Metadata changes require restart or the plugin owner's explicit reload/install/doctor flow. Keep caches lifecycle-owned and test-clearable, not broad persistent stores.
  • Repeated availability checks and catalog selection consume prepared local facts. Remote catalog discovery and provider probes belong to initialization or the owner's refresh operation, not each request or UI render. A second request-time cache or polling loop is not the fix for repeated discovery.
  • Keep configured/eligible state distinct from live health. A present credential or cached descriptor does not prove a service is reachable. Explicit health probes, credential refresh, and actual provider/tool execution retain their network contracts.

Verification

  • If you touch loader, registry, activation, or public-artifact code that can change bundled plugin import fanout, run pnpm build.
  • If the change can alter bundled plugin startup cost, re-profile the affected plugin entrypoint with: OPENCLAW_LOCAL_CHECK=0 node --import tsx scripts/profile-extension-memory.mts --extension <id> --skip-combined --concurrency 1