Skip to main content

Compositor plugin standard 1

A plugin is an independently versioned package. Agent services/hooks, tools, UI, skills and stdio MCP can be combined in that package. Installing a package, activating it, selecting a replacement provider and updating its version are separate decisions. The compositor owns tiling; domain behavior belongs in plugins.

Package contract​

First-party native packages contain:

  • plugin.json: identity, independent SemVer, trust, entry/components and "compositor":{"standard":1,"apiVersion":1}.
  • README.md: purpose, requirements and observable usage.
  • CHANGELOG.md: an entry for the current plugin version, including migrations.
  • plugin.test.json: v2 profiles, individually bound mandatory cases and optional convenience suites. The test plan is metadata, never a runtime import.
  • The required hooks/tools, skills/, MCP declarations and declared resources.

API version 1 names the current public host contracts. Unsupported standards or API versions fail metadata validation before executable import. A missing compositor declaration remains accepted for legacy/third-party packages; it is not sufficient for a first-party release. Trust describes host execution powers, not an OS sandbox. Dependency installation is explicit and requires a lockfile; package scripts are disabled during normal marketplace installation.

Keep credentials out of packages, model-visible instructions and fixtures. Use scoped settings, cancellation signals and truthful tool descriptors. Tools and MCP calls pass through normal policy. Replacement services/controllers require explicit selection and must preserve policy, privacy, journal and budget behavior. dispose() stops subprocesses, connections, timers and listeners; reload restores required state without depending on the previous module instance.

A successful tool result may include optional modelText with its structured data. This supplies a model-facing text view while callers/UI keep the data. See presentation bounds and journal compatibility before using it; omitted text preserves the legacy representation.

Tools may provide a pure synchronous validate(args) callback returning an error string or undefined. The host checks detached effective arguments after tool rewrites and before permission review or execution. Validators neither perform effects nor grant authority; retain execution-time safeguards. See argument admission and compatibility. The disk loader preserves this callback across load/reload and rejects a provided non-function value as a plugin load error. It checks the field without invoking the validator; malformed owners do not block unrelated valid or legacy tools. Tools may also be class instances. Composition retains inherited describe, execute and validate methods bound to the original instance, including private state, and copies their declared metadata even when supplied by getters. Ordinary object tools and native function identity keep their behavior.

Finite query tools​

Tools may opt in to repeated-observation recovery with loopGuard: "query" on their ToolSpec. Use it only for finite read-only queries. Omit it for status polling, streams and effectful operations. It does not grant read permission or change the model-facing schema; ordinary descriptors and policy still apply. Legacy tools without this optional field keep their behavior. See the exact recovery window and limits.

Immediate user commands​

Declare "execution":"immediate" on a command to handle an explicit user control independently of model turns. The host dispatches command.invoke with {plugin,name,text,args} to its loaded owner. For example:

{"name":"/control","description":"Change session controls","execution":"immediate"}

Handle command.invoke in the plugin; validate args before taking action. The loader rejects immediate declarations without that handler. Arguments are literal text, not shell input. A notification is enough for a short control; a handler may explicitly publish a view for richer interaction. No UI component, prompt hook, model request or conversation entry is implied. This works in the TUI and through AgentCore.submit/steer, including while the model runs or user prompts are queued. Agent-origin follow-ups do not use this user-control path. Unmarked commands retain their existing prompt behavior.

The core tracks at most four simultaneous commands separately from user tools, with five-minute deadlines, owner-scoped cancellation and shutdown cleanup. Hook deadlines still apply. Tools use ordinary permissions and independent user operations; auxiliary model usage consumes session/command budgets rather than the active model turn's allowance. command.operation reports start and settlement. AgentCore.invokeCommand(text, callerSignal?) returns false for an unregistered control; failures of registered controls are errors, never fallback prompts. The optional AbortSignal cancels only this invocation and its foreground tool and auxiliary-model work. An already-aborted caller is rejected before handler admission. Cancellation preserves Main and other invocations, including commands from the same owner; ordinary permission checks and accounting still apply. Explicit $.background() work and an already-started background exec retain their documented independent lifetime. Cancellation does not roll back completed effects. Embedders supply loaded {name,plugin} registrations through userCommands. AgentCore.hasImmediateCommand(text) checks that live owner registry without invoking a handler, for input dispatchers that preserve setup ordering while keeping controls independent of the model queue. These additive contracts require catalog 0.25 or later.

In the configured OpenTUI frontend, a command or UI action that needs manual tool approval, a question or a private form receives an independent request window without declaring a ui component. Normal policy and automatic review run first. Retained background requests have their own lifetime and bounded owner; they never queue behind Main merely because Main is awaiting an answer. See request windows for focus, cancellation, privacy and concurrency limits.

Catalog 0.26 adds service.agent.open for an explicit user control to open a persisted shared-workspace conversation, or reopen one by id. Optional prompt starts its independent turn; name labels a new agent. The result contains id and sessionId. Agent-hub must be enabled. The host verifies user provenance, retains ordinary workspace/permission/budget limits, and focuses the agent's own Reply field. It does not interrupt or append a prompt to the main turn. Models cannot use this service to change the user's focus. Existing agent and tool contracts are unchanged.

Commands that open UI​

Catalog 0.27 adds optional semantic tables to UiTextView; omitted tables preserve the existing text-view contract. Columns, unique rows, expanded details and ordinary action IDs are renderer-independent. See expandable tables. Catalog 0.28 adds optional semantic tabs. Independently distributed packages must feature-detect $.ui.supports?.('tabs') and retain an appropriate older-host view; the SDK version inside a bundle is not a host feature probe.

An optional command route, "ui":{"site":"main"}, sends a TUI command directly to the existing ui.press chain. For plugin project-helper, the event is {site:"plugin-project-helper-main",key:"command:/project-helper arguments"}. The host qualifies the local site with the loaded owner's name. Local site IDs use lowercase letters, digits and hyphens, begin with a letter and have at most 64 characters. Arguments remain literal text, not shell input.

Handle that event in ui.press, validate arguments, and render progress/errors. The TUI runs these explicit UI commands during an agent turn, without entering prompt hooks, model context or the prompt queue. Successful opens focus the declared surface on its workspace. Commands without either immediate execution or this route retain normal queued prompt behavior. Keep a prompt.submit handler for the line-based interface and older hosts. Do not opt conversation-changing/model-prompt commands into this route. Tool calls from the handler still use $.agent.tool and its ordinary permissions, independent cancellation and operation limits.

Only loaded plugins contribute command routes; activation/reload controls when they appear. The route does not grant execution or activate a plugin. See authoring contracts for an example.

Do not combine execution and ui on one declaration. An immediate handler can open its own view; the ui field preserves the older surface-specific route.

Activation and scope​

All filesystem plugins start off. A bundled package or an installed directory is available code, not consent to execute it. Inactive packages contribute no hooks, tools, UI, skills or MCP servers, and executable modules are not imported. The repository's agent-compositor marketplace ships as an offline catalog with the application. Bundled packages are an inactive cache: install a package in the chosen scope before enabling it, so its locked version survives host upgrades. Local development directories can be enabled directly in project scope. Refreshing that catalog and updating installed plugins are explicit operations; application startup does not fetch remote code.

/marketplace
/extensions install mascot@agent-compositor --project
/extensions enable mascot --project
/reload
/extensions disable mascot --project
/reload

The TUI [Plugins] manager connects catalog search, scoped installation, explicit enable, update checks and application without requiring slash commands. Management remains available while the agent runs or waits for an answer. TUI updates, rollbacks and removals requested while busy remain deferred in memory until Apply plugin changes (or /reload); running package files are retained until idle. See the terminal flow for cancellation, restart and queued-application behavior. The line-based interface retains its existing turn-based command handling.

Deferred file operations belong to the requesting management signal. Aborting that signal discards its unapplied update, rollback or removal. Replacing a queued action transfers that queue entry to the latest caller. Saved installation and activation choices have their ordinary persistence. The source-only OpenTUI preview uses this lifecycle and applies its pending changes automatically after Main becomes idle.

--project changes this project; --user changes the user's defaults across projects. Project decisions override user decisions, including project enable over user disable. A user-scoped grant selects shared code; a project-local copy of the same name needs an explicit project decision and cannot silently shadow it. Activation records bind the chosen code directory; a missing installation does not silently switch to another discovered copy. Installation always leaves a new package off in its chosen scope. Updating or rolling back preserves activation decisions. A configured enabledPlugins list remains an exact capability ceiling; disabledPlugins remains binding. Directory discovery and --plugins do not grant activation.

Kernel implementations of the base loop/file tools, session/model/settings and management commands remain available to bootstrap the app. They are not packages from the marketplace. Existing explicit composition/tool selections can also restrict these host adapters. The low-level PluginLoader SDK is a loading primitive; the application supplies the activation policy before calling it.

Project activation and version locks live in the project's private storage state (storage.paths.state/extensions-state.json); user decisions live under the configured Agent home. Installed project code lives in .agent-compositor/plugins. Project selections survive restart and do not affect another project. When the workspace itself is HOME, project installations use private project storage to keep them separate from user installations. Legacy locations remain readable. Filesystem edits to active local development plugins still use /reload; managed release updates must use a new version.

Mandatory certification​

The plugin testing model is enforced by schemaVersion 2 plans and plugin:certify. The package standard and host API remain version 1; the test-plan schema evolves independently. Legacy schemaVersion 1 plans can still run with plugin:test, but cannot certify a release.

Every plan declares component and behavior profiles, supported platforms, previousVersion (null only for the first independent release), and cases. The runner derives the union of mandatory requirements from every selected profile. Missing bindings, skipped/failed cases, no evidence, duplicate names, retries/flaky passes, and mismatched source/artifact contexts block certification. There is currently no author-controlled waiver or skip-to-pass mechanism. Applicability is expressed by accurate component/trait declarations, reviewed with the implementation. Metadata checks reject obvious omitted command, tool, skill, agent-service and MCP profiles; arbitrary trusted code still needs review.

A case has a stable ID, requirement IDs, kind, initial setup, expected/forbidden effects, a timeout, and an execution binding. A vitest binding names a repository file and the exact full name from its JSON report (ancestor titles separated by spaces). A scenario binding names an executable Bun script and arguments. Scenario scripts use tools/plugins/scenario.ts: read scenarioContext(), make real assertions, save observations under the supplied output directory, then call finishScenario(). UI/live/upgrade/artifact cases require scenarios. Binding labels do not replace assertion review.

npm run plugin:check -- notify-done
npm run plugin:test -- notify-done # legacy convenience suites, not a release gate
npm run plugin:certify -- notify-done # mandatory deterministic PR matrix
npm run plugin:audit -- --stage release # inventory missing bindings; nonzero if incomplete
npm run plugin:certify -- notify-done --stage release
npm run plugin:build -- notify-done
npm run plugin:certify -- notify-done --stage artifact --artifact path/to/candidate.tar.gz

See plugins/notify-done/plugin.test.json for a working deterministic example. All current native packages have v2 profiles and actual installed-package lifecycle, domain, UI and model scenarios where applicable. Binding completeness is not execution: certificates still require passing results for the exact source, reference configuration and every declared archive platform.

PR certification runs adversarial shared host contracts and every applicable bound deterministic case. Release certification requires clean committed inputs, mandatory real PTY/model cases and the preceding tagged release's upgrade/rollback when one exists. Native archive certification repeats upgrade/rollback from the previous platform archive using artifact cases bound to the same release requirements; previous-version/hash evidence must match that platform's pins. Model policy (reference provider/model, public configuration, task-set checksum, repeats, success floor and baseline) is declared before running; scripted providers cannot satisfy it. Exact model/config/task metadata and objective observations accompany live results. Fixture task definitions without an executing grader/transcript are missing coverage, not passing evaluations.

Archive certification securely installs the exact candidate, verifies its embedded source/plan/tooling identity, and repeats the applicable deterministic/UI behavior matrix against that candidate. A single successful install/operation is only the baseline and cannot replace the remaining component cases. The common scenario checks inactive installation, useful operation, repeated invocation, double reload, fresh-process restart, disabling, re-enabling and removal preserving independent settings. It does not invent plugin-specific migration or model-quality evidence.

Results live in reports/certification/<plugin>/<stage>/<platform>/ as a strict certificate, readiness report, JUnit/JSON diagnostics and hashed observations. Source, package, plan, host API, Git snapshot, platform and archive digest are bound to the evidence. Tests use isolated homes/projects and local dependencies; positive fixtures explicitly opt in. Do not enable packages in production just to make test setup easier.

Independent versions and releases​

The host, marketplace metadata and each plugin have separate versions. For first-party packages in this repository, a push to main runs plugin-release-preparation, which creates or refreshes the automation/plugin-releases pull request. It prepares plugin SemVer, changelogs, relative development catalog versions and the generated plugin reference from committed history. Routine contributions do not hand-edit those release fields. A published catalog version must match the released artifact. The working tree may be ahead of a pinned published entry; new plugins can be developed and tested before being listed. Relative development entries must match their source manifest. Normal CI reports versions pending automatic preparation; the generated release PR uses strict version checks. No host version bump is needed to publish a compatible plugin update.

Commit messages supply the release intent: fix(callix): ... selects a patch, feat(callix): ... a minor, and ! or a BREAKING CHANGE: body a major. Other runtime changes default to patch. The highest level in a batch wins per plugin. Affected files, rather than the optional commit scope, select the plugin. Include migration details in the breaking commit body and review the generated notes. Documentation/test-only changes do not bump versions. Changes to bundled workspace inputs, selected runtime lockfile dependencies and distribution packaging do. Unrelated documentation-site dependencies do not. New plugins start at their manifest's initial version. Their first release history begins with the manifest's introduction commit; earlier shared-code and packaging changes do not become notes for a package that did not yet exist. Later bundled changes remain included. Existing higher development versions are preserved during the transition to automation.

.plugin-release.json records the bootstrap snapshot and each prepared source baseline. Generated version/changelog commits do not cause another release PR; new runtime changes accumulate until the open PR is refreshed or merged. The catalog metadata version advances once per changed batch. Published archive entries remain pinned until the separate certified catalog promotion below. For an affected relative development entry, preparation also copies the source manifest's description when provided, so marketplace search describes the same behavior as the prepared package. Published archive descriptions remain pinned with their released versions until catalog promotion.

For local diagnosis, use a clean committed checkout:

npm run plugin:prepare # inspect the deterministic plan
npm run plugin:prepare -- --write # apply it locally, normally done by the bot

The generator refuses a dirty checkout and does not stage unrelated developer work. GitHub Actions must be allowed to create pull requests. The workflow keeps default token permissions read-only, requests write permissions only for its preparation job, and explicitly dispatches CI and documentation checks on the generated commit: events created with GITHUB_TOKEN do not start those workflows automatically. No separate personal token is needed. The PR still needs normal review/merge; preparation does not create tags, publish artifacts or substitute for release certification. Tag validation rejects a plugin with source changes still pending automatic version preparation. External plugin repositories provide their own release automation.

Use an annotated plugin/<name>/v<version> tag after verification. The independent plugin-release workflow validates identity/version, runs the plugin's behavior and lifecycle tests, enforces the complete release matrix, builds and certifies four native archives, then publishes that plugin's release with checksums. It never moves the application's latest release. Manual workflow dispatch builds only. Release notes contain only the selected version's changelog entry.

Before creating a tag, manually dispatch plugin-release.yml on main with candidate_name and candidate_sha. The SHA must be the full 40-character commit of a pushed, clean source snapshot that includes this candidate workflow support. The metadata step uses explicit Bash pipeline failure handling: a rejected source stops verification even when its output is also saved with tee. Pending automatic version preparation still blocks certification; merge its generated PR first. All release checks, mandatory UI/live cases and the four native archive checks remain required. For example:

candidate_sha=$(git rev-parse HEAD)
gh workflow run plugin-release.yml --ref main \
-f candidate_name=project-checks -f candidate_sha="$candidate_sha"

This creates no tag or release. Download the plugin-source-evidence and plugin-<runner> workflow artifacts to review certificates, screenshots and archives. The separate quality-plugin-source and quality-plugin-<runner> artifacts retain diagnostics even after failed certification. They are excluded from the publication download set. source.json records the resolved commit, mode and intended plugin identity; a candidate's intended tag need not exist. source-commit.txt records the resolved SHA independently of the selected revision's metadata helper, including when validating an older existing tag. Packaging jobs use the exact verified SHA, even if a branch or tag later moves. Manual validation of an existing tag remains available with tag=plugin/<name>/v<version>; do not combine it with candidate inputs. Publication requires a tag push and rejects a tag that no longer points to the verified commit.

npm run plugin:build -- todos
npm run plugin:smoke -- todos

Artifacts are platform-specific archives under dist/plugins/<name>/<version>. Callix includes its verified native dependency; Monty includes its worker modules. Public SDK imports are bundled and runtime resources retained. Release artifacts are available independently. The marketplace installer consumes local/pinned Git packages or platform archives pinned by SHA-256. Native release archives use ustar with regular files/directories; extraction rejects links, special entries, path escapes and duplicates, with bounded download/decompression sizes. Other marketplaces may use a Git source object with a plugin tag or commit and a path selecting its package. Official archive entries require certification. Relative entries inherit the catalog's pinned snapshot. Installed applications use a matching self-contained bundled snapshot; newer first-party versions require a published archive entry instead of incomplete raw sources. Commit/version locks are recorded per installed plugin.

The release also publishes certification.tar.gz with the matching evidence and marketplace-entry.json, containing all four artifact URLs and checksums. Apply that reviewed entry with npm run plugin:catalog -- path/to/marketplace-entry.json path/to/certification/<name>; it revalidates complete evidence against the immutable plugin tag, retains it under .claude-plugin/certification/<name>/<version>/, and updates only that entry (or adds a newly released plugin) and increments the independent catalog metadata version. Development can continue at a later version while an earlier release is being promoted. Commit/push the catalog change and its retained evidence explicitly. Official archive entries without matching certification also fail marketplace validation, including manual catalog edits. Users can then refresh the catalog and update that plugin without updating the host. Existing relative entries remain usable as bundled snapshots/development sources before their first independent release.

Explicit updates and rollback​

/marketplace update agent-compositor
/extensions check-updates
/extensions update todos --project
/reload
/extensions rollback todos --project
/reload

Catalog refresh does not replace code or change activation. check-updates reads the current catalog without importing plugin code. Install/update validates the manifest identity, catalog version, compatibility and resource/MCP paths first. The installed state records the plugin version, source/ref/commit and SHA-256 content lock. Same-version changed content is rejected; downgrades require rollback. Invalid candidates leave the installed version intact.

Successful updates retain the previous package and lock. Rollback verifies that backup against its content lock before restoring it and preserves activation. After reload, old resources are disposed and the restored version supplies all components. Removal is explicit, keeps a backup and does not delete independent user settings. Removing a marketplace registration retains installed plugins. The marketplace UI requires selecting its confirmation toggle before submitting Remove marketplace; Cancel or an unchecked confirmation retains the registration.

On Bun, loading a filesystem plugin clears that package's canonical-path module cache before importing its hooks and tools. Relative dependencies inside the package then refresh together, and both entry points share their new instance. Linked host SDK modules outside the package retain their identity. A changed manifest alone does not establish that new code is running; verify the updated plugin's behavior. This package-local refresh is tested on Bun. Node's ESM relative-dependency cache has different behavior and is not covered by that claim.