Skip to main content

Native plugin contracts

A local extension is a directory containing plugin.json and a hook/controller entry, tools.ts/tools.js, skills or MCP declarations. Components can be combined in one package; pure data/MCP packages need no executable entry. Default project location: .agent-compositor/plugins/<name>. Installed/user plugins may override bundled plugins of the same name; choose a distinct name for a new capability.

{
"name": "project-helper",
"version": "0.1.0",
"trust": "trusted",
"main": "hooks.ts",
"commands": [{"name":"/project-helper","description":"Open project helper"}]
}

Hook entries default to hooks.ts, index.ts, index.js, index.mjs. For tools-only plugins omit main and provide tools.ts or tools.js. TypeScript and ESM are supported by the installed host. JS dependencies must be available beside the plugin or bundled; npm package installation is not automatic on reload. plugin_dev init links the public host SDK (including core, session, events, hooks, tools and app/controller types) from the installation used to create the plugin. Keep that installation while using its SDK links. You may add type imports without runtime dependencies.

Finite read-only tools may declare loopGuard: 'query' on their ToolSpec to opt in to repeated-result recovery. Omit it for polling, streams and effects. This does not grant permissions or alter the model-facing schema. The default loop warns after three repeated query steps and stops after six, counting steps with no new observations rather than calls inside a batch. The host setting agent.maxRepeatedQuerySteps controls the ceiling; the recent window is bounded.

For a command that opens UI, add "ui":{"site":"main"} to its command declaration and handle ui.press with event.site === 'plugin-project-helper-main' and event.key === 'command:/project-helper'. The TUI delivers the complete trimmed command after command:, including literal arguments, immediately even while the agent runs. Validate those arguments; show usage/errors for unsupported values. Keep the prompt handler for line-based/older hosts. Do not replace only the prompt handler in a generated starter: the TUI uses its UI handler. Do not route conversation-changing or model-prompt commands this way. Commands without ui keep the usual queued prompt path. Tool calls from either handler still use $.agent.tool and normal permissions.

A hook receives (event, $). No result continues normally. {drop:reason} consumes a recognized prompt command; {text:replacement} rewrites a prompt. For middleware use const downstream = await $.next(rewrittenEvent) and return its result or a compatible response. Read the exact installed schema using the events guide; do not guess names or response shapes.

Useful APIs: $.session.id/cwd, $.signal, $.state.get/set, $.storage.config(name), $.storage.configure(name,value,scope), $.ui.notify, $.ui.view, $.ui.remove, and $.emit(canonicalEvent,input). Settings are scoped; do not overwrite raw global settings or store credentials in prompts. Hooks use shared permission/cancellation services. Trusted modules can also use host Node APIs; the trust label is not an OS sandbox.

A tool exports a default array (or named tools) of objects with name, description, parameters (JSON Schema), describe(args) and async execute(ctx,args). Use truthful descriptors for permission matching, pass ctx.signal to I/O, and resolve filesystem paths with ctx.resolvePath. ToolContext supplies request, fetch, settings, cwd, sessionId and undo. Native tool result: {ok:true,data} or {ok:false,error}. A tool name collision does not replace the built-in tool; explicit replacement uses toolProviders:{"read":"my-plugin"}.

For a trusted native tool that needs a process, discover the installed service.exec.run schema before calling ctx.request. Its payload requires the owning plugin name as well as cmd, optional args and timeoutMs; raw tool requests do not inject that name. Use fixed argument arrays, truthful tool descriptors and a finite timeout. The host propagates ctx.signal, reaps owned processes before settling, and revokes them on unload. Do not race execution against an early cancellation result that leaves the process running. A hook's $.exec.run supplies its owner and operation signal automatically.

Native plugin skills live in skills/<skill>/SKILL.md; name and description go in YAML frontmatter. The registry advertises only descriptions and loads full bodies using the skills tool. User/project skills have priority over plugin skills. Only loaded plugins contribute; disable/remove/reload updates discovery.

Native manifests also accept mcpServers and resources. MCP config files and inline declarations use the common native/Claude stdio reader. See the composition guide for schema, ownership and release resources.

Runtime replacements declare provides (for example service.agent.instructions) and are selected via serviceProviders. Private UI replacements export named controllers and are selected via ui.controllers; session repositories export a named sessionRepository factory and are selected by sessionProvider. These configuration selections are read at startup. They must preserve cancellation, private input, journal ownership and the normal policy path. Tiling remains host-owned. Use public controller types or installed event schemas for details; do not patch compositor internals to implement a local extension.

Session start initializes state. Session reload reconstructs it after composition changes; in-memory plugin state may be reset. Export dispose() from hook/tool modules for timers, subprocesses and connections. Do not mutate state during ui.render. Use bounded hookTimeouts only where the actual operation needs them.