Host API

Every plugin calls the same methods. In JavaScript they are api.host.<group>.<method>(params) (camelCase); on the wire, which a plugin's runtime speaks for it, they are host/<group>.<method> (snake_case). All params and results are JSON objects. Ids are strings.

api.host.call(method, params, { signal }) and api.host.kernel(method, params, { signal }) accept an AbortSignal. An abort rejects with its reason and sends host/cancel for the outstanding request; a signal already aborted sends no request. Completed calls remove the listener. Kernel method names omit the kernel/ prefix.

Agent approvals have no general host method. A plugin may answer them only through the manifest's tool_approval hook with the dangerous approvals.auto grant (see Hooks); the kernel card handles user answers.

The files, network, programs and environment a plugin reaches go through the broker methods at the end of the table. JavaScript calls them through api.fs, api.net, api.process and api.env (ui-plugins.md), which also wrap their streams; the table is the wire.

Each plugin has a data folder of its own, <data dir>/plugin-data/<id> (the id with / as __), which the data scope of its fs.read and fs.write grants names. The host makes it before the plugin loads and gives a JavaScript plugin its absolute path (api.paths.data). The first time an official JavaScript plugin loads in the place of the native provider of the same folder name (before the providers' port to JavaScript), the host moves what that provider kept in <data dir>/agents/<folder>/ into the data folder as legacy/, once; the plugin reads it from there.

Permissions

The host checks every call before it runs it. The plugin must be enabled, and it must hold a grant for the permission in the last column (see ../AGENTS.md, Permissions). A method with no permission needs only an enabled plugin. A call without the grant fails, and nothing happens:

  • in JavaScript, the Promise rejects with an Error whose name is PermissionNotGranted (or NeedsReview, see plugins.set_enabled), with permission and scope set to what was missing, and a message such as PermissionNotGranted: tabs has no grant for fs.read /etc/hosts;
  • on the wire, the answer is an error with code -32001, that message, and data: { code, message, permission?, scope? }, which the runtime turns into that Error.

Any other failure has the name Error. A method that does not exist fails with unknown host method <method>.

fs.* methods check the path itself: a path relative to a workspace resolves inside that workspace root (it cannot leave it with .., an absolute path or a symlink), and the grant must cover the real file after symlinks are resolved. The broker then opens the file inside the folder the grant names, so a symlink swapped in after the check cannot lead it out either.

Method Params Result Permission
workspaces.list {} { workspaces: Workspace[], colors: PresetColor[] } (icon: the project's icon file when the folder has a favicon, icon or logo; found once per minute per folder. mark: divergence on the Plugins workspace only, which is also named "Divergence" and has no icon. color: the folder's preset colour, given in turn to each folder without an icon (all twelve before one repeats); its mark is a folder-solid in that colour when there is no icon or mark, or with useColor) chats.read
workspaces.add { path } Workspace (a folder new to the app then imports, in the background, the sessions its enabled agents already keep there, each reported as a chat_changed event) chats.control
workspaces.remove { workspaceId } {} chats.control
workspaces.set_color { workspaceId, color } {}: the mark becomes a folder in color (one of colors), or with color: null the project icon again chats.control
chats.list { workspaceId? } { chats: Chat[] } chats.read
chats.create { workspaceId, agentId, title?, taskId?, inUse? } Chat (reuses an empty draft, never one named in inUse: drafts the caller holds unsent text for or has queued) chats.control
chats.reserve { workspaceId, agentId, inUse? } Chat: the draft chats.create with the same arguments would open now. When there is none it is made ahead and left out of chats.list, the tasks and every event until chats.create opens it as a chat made then, so a New chat key can show a page prepared for it at once chats.control
chats.transcript { chatId, limit?, before? } { items: TranscriptItem[], start, total, userSessions, running, pendingApprovals, pendingQuestions, plan, usage, turnChanges, liveTasks }: the limit items before index before (the end by default; every item without limit), start the index of the first and total the transcript's length; a pane reads the newest page first and the rows before it right after, and pages a very long chat on scroll up. (userSessions: { [itemId]: { agentId, sessionId } }, the agent and native session each archived user message was sent in; a message not archived yet belongs to the chat's current session.) (turnChanges: [{ itemId, files: [{ path, added?, removed? }], before? }], each turn that changed files and whose last item is on this page, even when its prompt itemId is on an earlier one; its summary goes before the message before, the next one you sent once the turn had ended, or ends the transcript when before is absent.) (liveTasks: the task items before the page that are, or hold, a subagent or command that still runs, so a pane showing the newest rows can list and open everything the chat's working counts; absent on older hosts.) An image block keeps path, width and height (a stored copy, docs/adr/0003), not data chats.read
chats.peek { chatId, limit? } { items }: the end of the chat (limit items, default 50) without loading it, for a glance such as the sidebar's latest line chats.read
chats.close { chatId } {}: no pane shows the chat any more, so the host keeps less of its transcript in memory chats.read
archive.attachments { chatId } { activeAttachmentId, attachments: SessionAttachment[] }: native-session provenance and each attachment's options chats.read
archive.snapshot { chatId } ArchiveSnapshot: exact revision membership of the active lineage, after flushing current host transcript changes; no inference or context delivery chats.read
archive.records { chatId, snapshotId, offset?, limit? } { records: ArchiveRecord[] }, chronological pages (default offset 0, limit 100; limit 1–256); rejects a snapshot belonging to another chat chats.read
chats.handoff { chatId, agentId, revision, draftRevision }, or { chatId, agentId, newChat: true } { chat, snapshot: InputSnapshot, draft: ComposerDraft, recovered }; prepares without inference, then atomically selects the destination and holds queued inputs. With newChat, the chat goes on in a new chat right after it in its task: a copy of its conversation, prepared for agentId, which takes the prompt box's draft; chat, snapshot and draft are the new chat's, and the original keeps its agent and session chats.control
chats.prepare { chatId } InputSnapshot; the chat is on screen: a detached, idle chat with a native session resumes it now (no new session, no inference). Session creation and resumption wait for the initial enabled-plugin catalog so all tools and rules are included. preparing is true while it awaits the resume; a failure is returned and kept in prepareError until the next successful preparation or Send chats.control
chats.contextPolicy {} { provider: string | null, available: boolean }; selected policy registration, unavailable while missing/reloading; not private policy settings chats.read
artifacts.list { chatId } { artifacts: ContextArtifact[] }; published, authorized references for this chat, including expired disk copies; excludes revoked exports chats.control
artifacts.create { chatId, snapshotId, configuration, stubAfterSeconds, deleteAfterSeconds } ContextArtifact; only the selected context renderer can issue an export. Positive lifetimes require deletion after stubbing chats.control
artifacts.regenerate { chatId, artifactId } ContextArtifact; regenerates the original pinned revisions/configuration at its managed path chats.control
artifacts.revoke { chatId, artifactId } {}; permanently revokes regeneration and removes managed files chats.control
chats.send { chatId, text } or { chatId, blocks: ContentBlock[] } {} (progress arrives as events) chats.control
chats.cancel { chatId } {} chats.control
chats.cancel_task { chatId, taskId } {} — stops one subagent (capabilities.cancelTask) chats.control
chats.respond_question { chatId, questionId, answer: { values, cancelled } } {} chats.control
chats.update { chatId, title?, archived?, completed?, agentId?, workspaceId? } Chat (agentId and workspaceId only before the first prompt; completed checks the chat off or opens it again) chats.control
chats.delete { chatId } {} chats.control
chats.set_option { chatId, optionId, value } { options: ConfigOption[] } (the choice is also remembered for the chats that have not started) chats.control
chats.options { chatId } { options: ConfigOption[] } (current values: a chat that has not started shows the last choices made in any chat of its agent, a started chat keeps the values it started with) chats.read
chats.commands { chatId } { commands: SlashCommand[] }; the live or cached list returns immediately. Session commands refresh after creation/resume succeeds and arrive as a commands event; refresh failures keep the cached list and report a warning chats.read
chats.skills { chatId } { skills } (the agent's) chats.read
chats.checkpoints { chatId } { checkpoints: [{ itemId, createdAt }] } (the prompts the workspace can be put back to) chats.read
chats.checkpoint_coverage { chatId, itemId } { degraded, expired, unknownPaths } (what restoring that checkpoint could not undo) chats.read
chats.restore_checkpoint { chatId, itemId } {} (the files and the transcript go back to before that prompt) chats.control
chats.edit_message { chatId, itemId, text } or { chatId, itemId, blocks } {} (restores to before that prompt and sends the new one) chats.control
chats.compact { chatId } {} (asks the agent to summarize the conversation) chats.control
chats.fork { chatId, title?, before? } Chat (a new chat with the same history; with before, a user message, only what came before it, which needs capabilities.forkAt once the agent has answered that message) chats.control
chats.turn_changes { chatId } { itemId, workspaceId, paths, files, endedAt } or null: the files the chat's last finished turn changed, relative to the workspace (itemId is that turn's prompt), and in files the same with the lines it added and removed in each ({ path, added?, removed? }, no counts for a file whose text the journal did not keep); null when no finished turn had a checkpoint before it chats.read
chats.turn_diff { chatId, itemId, path } { diff }: what the turn the prompt itemId began did to path, a unified diff of the whole file between the checkpoints before and after the turn; fails when the journal no longer keeps that turn or did not keep the file's text chats.read
chats.import { workspaceId, agentId } { imported } chats.control
chats.load_history { chatId } { items } (resulting item count; 0 when unchanged). Reconciles the active attachment's native records by identity, retaining original host ids/checkpoints and missing archive rows, in the agent's order. Unknown alignment fails without a partial write; no positional/text matching. Runs on every call, since the agent's record may have moved on in another program (a call while a read of the chat is still going answers 0; an older host reads once per chat per app start). Passes the provider the version its last reconciled read answered, so an unchanged record is not read. Skipped while work runs or settles, and for an agent without sessionHistory. chats.control
chats.load_task { chatId, taskId } { items } as chats.load_history. Reads one subagent's transcript, which a reconcile leaves out once the subagent settled (the chat calls it when the subagent's tab opens). chats.control
tasks.list { workspaceIds? } { tasks: Task[] }: every task (a row of the sidebar) with its layout chats.read
tasks.update { taskId, title?, completed? } { changed }: renames a task (null goes back to its first chat's title) or checks it off or back on chats.control
tasks.archive { taskId } {}: archives every chat of the task, which removes its row chats.control
layouts.side {} SideSplit: the window's side split, its tabs, and whether it is open chats.read
layouts.current {} { task: Task | null, side: SideSplit }: the task on screen and the side split chats.read
layouts.new_chat { paneId, onScreen } { chat, changed }: a new chat in the pane, after its active tab, with the agent of the chat on screen; an empty draft already in the task is shown instead chats.control
layouts.split { paneId, direction: "right" | "down", onScreen } { chat, changed }: splits the pane and puts a new chat in the new half chats.control
layouts.place { tab: Tab, target: PlaceTarget, onScreen } { changed }: moves a tab to a strip, an edge of a pane, another task (join) or a row of its own (alone) chats.control
layouts.close_tab { tab: Tab, confirmed? } { changed, closed: ClosedTab | null, question? }: an item closes; an empty draft is deleted; any other chat leaves for a row of its own, checked off. An item whose kind has beforeClose answers its question and stays, until the same call comes with confirmed: true chats.control
layouts.reopen { closed: ClosedTab } { changed }: puts the last closed chat back where it was chats.control
layouts.update { paneId?, active?: Tab, focused?, shares?: { splitId, shares }, side?: { open?, width? }, onScreen? } { changed }: what the user's clicks and drags change in place: the active tab, the focused pane, the shares of a split, the side split chats.control
layouts.equalize { onScreen } { changed }: makes every split of the task on screen and of the side split equal and forgets their resizes, so panes added later share the room equally again chats.control
layouts.kinds { kinds: { kind, needsChat? }[] } {}: the tab kinds this plugin declares (definePlugin({ tabs }) sends it)
layouts.open { kind, key, title, icon?, file?, chatId?, where?, gesture, onScreen? } (file: the name of the file the tab shows, whose file tree icon its tab draws) { changed, paneId, itemId }: opens a tab of one of this plugin's kinds, or shows it if it is open; without a recent gesture it waits in the strip, marked
layouts.mine {} { items: Item[] }: this plugin's open tabs, so a reloaded plugin draws them again
layouts.drop_item { item: { kind, key, chatId? }, target: PlaceTarget, onScreen } { changed? }: another plugin's tab dropped on a pane or strip; its owner (kind is <plugin>.<kind>) opens it in that pane through tab/open, and a drop on an edge then gives it a pane of its own there, which the host does itself; fails when that plugin is off chats.control
inputs.list { chatId } InputSnapshot: durable inputs, attachment generation, CAS revision, running/settling state, last settled run and opaque policyState chats.read
inputs.enqueue { chatId, id, blocks, intent: send | steer | queue, origin?, append? } InputSnapshot; persists structured bytes without sending; id is an idempotency key chats.control
inputs.update { chatId, revision, inputId?, blocks?, composition?, intent?, remove?, before?: string | null, pauseReason?: string | null, policyState? } InputSnapshot; CAS checks the snapshot revision. Content/provenance edits, removal and moves require held or positively rejected state. before moves the input ahead of another input, or to the end with null; a scheduler releases queued input in this order chats.control
inputs.dispatch { chatId, inputId, revision, policy?, scope? } InputSnapshot; claims an attempt before provider I/O. Omit policy for an explicit manual action; automatic dispatch must use the selected scheduler token chats.control
inputs.withdraw { chatId, inputId } InputSnapshot; takes back a steer the agent was handed (native_admitted or delivery_unknown) through the agent's native withdraw and removes it, so it never joins the transcript. Fails, leaving the steer in place, when the agent lacks capabilities.withdraw or already picked it up chats.control
inputs.policy {} { token: string | null }; authority of the live divergence/input-scheduler service registration chats.read
inputs.to_draft { chatId, inputId, revision, draftRevision } { snapshot: InputSnapshot, draft: ComposerDraft }; atomically removes a held/rejected input into an empty editable draft, preserving identity and structured content. Occupied/image-only drafts, stale revisions and admitted/uncertain/reserved inputs fail without removal. No dispatch chats.control
drafts.get { chatId } ComposerDraft: { chatId, revision, blocks, composition?, inputId? }. Distinct from pending inputs and transcript history chats.read
drafts.update { chatId, revision, blocks, composition? } ComposerDraft; CAS update. Empty text-only composition discards a moved input but retains its old enqueue tombstone. Images/resources count as occupied; text is not trimmed chats.control
drafts.enqueue { chatId, revision, id, intent: send | steer | queue } { snapshot: InputSnapshot, draft: ComposerDraft }; explicitly claims composition into held input and clears the draft in one transaction. A moved input retains its original logical id/date/intent provenance. id is an idempotency key; retrying an acknowledged claim preserves later draft edits. This does not dispatch chats.control
agents.list {} { agents: AgentInfo[] } (enabled only)
agents.all {} { agents: (AgentInfo & { enabled })[] }
agents.options { agentId, workspaceId } { options: ConfigOption[] }
agents.refresh_usage { agentId } { limits: UsageLimits | null }; fresh native read, without the five-minute cache; calls made while a read of the same agent is under way share it. Null does not mean allowed chats.control
agents.set_enabled { agentId, enabled } {} agents.manage
agents.authenticate { agentId, method } {} agents.manage
agents.logout { agentId } {} agents.manage
agents.update { agentId } {} (upgrades the agent's program with the installer that owns it) agents.manage
agents.changed { agentIds? } (a request, or a notification) {}: the plugin registered or removed agents after it loaded; the host lists its agents again (agents/list), serves the new ones and stops the ones it no longer lists (agent-protocol.md). A JavaScript plugin's runtime sends it for api.agents.register and api.agents.unregister after the load. agentIds names agents of the plugin whose initialize answer is out of date: the host forgets it and asks the enabled ones again agents.provide
fs.read { workspaceId?, path, encoding?: utf8 | base64, offset?, length? } { text }, or { data } (base64); with offset/length (bytes) only that range, shorter at the end of the file; a host before this answers the whole file fs.read covering the file
fs.write { workspaceId?, path, text } or { workspaceId?, path, encoding: "base64", data } {} fs.write covering the file
fs.search { workspaceId, query?, limit?, depth?, folders? } { paths }; with folders: true, the folders that hold the files rank among them, each written with a trailing slash (src/view/), and an empty query lists the top of the workspace first; a host before this ignores folders and answers files only. With depth: 1 and no query, { paths, folders }: the names of the files and folders directly in the workspace folder path (the top when it is empty), by the same ignore rules, which a file tree lists one open folder at a time. A host before this ignores depth and path and answers every path without folders, so pass limit too fs.read covering the workspace
fs.list { workspaceId?, path } { entries: [{ name, kind: file | dir | symlink | other, size, modified }] } (modified in milliseconds since 1970) fs.read covering the folder
fs.stat { workspaceId?, path } { kind, size, modified } fs.read covering it
fs.mkdir { workspaceId?, path, recursive? } {} fs.write covering it
fs.remove { workspaceId?, path, recursive? } {} fs.write covering it
fs.rename { workspaceId?, from, to } {} fs.write covering both
fs.watch { workspaceId?, path } { watchId }; changes arrive as the notification fs/changed { watchId, paths } fs.read covering it
fs.unwatch { watchId } {} the plugin that watches
net.fetch { url, method, headers (lower-case names), body? (base64), bodyStream? } { status, statusText?, headers, url?, stream }: the body arrives on stream. A bodyStream id is sent up with stream.write and stream.close while the call is out net covering the host (checked again at each redirect, at most 5)
net.websocket { url, protocols } { stream, protocol? }: messages arrive on stream, stream.write sends net covering the host
process.spawn { program, args, cwd?, env? } (api.process.start(..., { outsideSandbox: true }) calls it) { pid, stdin, stdout, stderr } (stream ids); the end arrives as process/exit { pid, code, signal }. stdout and stderr carry everything the child wrote, also what it wrote just before it exited process naming the program, or process.any for a path or an interpreter
process.kill { pid, signal? } {} the plugin that started it
process.which { program } { path, realPath }: where spawn finds the program, and that file with its links followed; both null when it is not there as process.spawn for that program
env.get { name } { value } (from the login environment; null when unset) env naming the variable
stream.write { stream, data } (base64) or { stream, text } (a text message of a socket) {} once the host took it. The writes and the close of one stream run one at a time, in the order they came, whether or not the plugin waits for each answer; different streams run side by side the stream's plugin
stream.close { stream } {}; also a notification, to stop reading the stream's plugin
stream.ack { stream, bytes } (notification) the plugin took that much; the host sends at most 1 MiB ahead of it the stream's plugin
slash.run { name, input, context } { action: prompt | message | none, text? }: runs another plugin's slash command in that plugin chats.control
git.status { workspaceId } { branch, upstream, ahead, behind, isRepo, entries: [{ path, origPath?, staged, unstaged }] } (paths relative to the repository root; staged/unstaged are the porcelain letters, ? in staged for an untracked file; untracked folders are listed file by file) git.read
git.diff { workspaceId, path?, origPath?, staged?, wholeFile? } { diff } (an untracked file comes back as an addition; origPath shows a staged rename as one; wholeFile gives every unchanged line as context, for a ui.diff that folds them) git.read
git.watch { workspaceId } {}: watches that workspace's repository and stops watching the one before; changes arrive as git_changed git.read
git.run { workspaceId, args } { stdout, stderr, code } (runs at the repository root, where status paths point) git.write
storage.get { key } { value } (private to the plugin)
storage.get_many { keys } { values }, one value (or null) per key, in order
storage.set { key, value } {}
tools.list {} { mode: code|direct, tools: [{ plugin, name, exposedAs, description, enabled }], rules: [{ plugin, file, text, enabled }] } settings.read
tools.call { agentId, sessionId?, workspace?, name, input, callId? } MCP CallToolResult (providers pass on their agent's tool calls; see tools.md) agents.provide
artifacts.publish { scope, artifact: { type, version, title, summary, data } } { id }: commits a host-owned transcript document, stamped with this plugin's folder, independently of tool output (tools.md, Transcript artifacts) tools.provide and a live tool scope owned by this plugin in an active user turn
web.preview { html, width?, appearance? } { available: true, png, width, contentHeight, capturedHeight, consoleMessages }: the self-contained page rendered in the host's confined, offline browser, a PNG (base64) of its top and what it logged; { available: false, reason } where no confined browser can start here, and nothing runs unconfined instead tools.provide
mcp.serve { agentId, sessionId?, workspace?, tools, url?, callIdMeta? } { url }: the host serves tools as a streamable HTTP MCP server on the loopback address, each tools/call run like tools.call, for agents that take extra tools only as MCP servers; with url (one this plugin was given) the same address serves the new scope; callIdMeta names the _meta key of a tools/call in which the agent sends its own id for the call (default callId), which the call carries as callId; it stops when the plugin unloads (agent-protocol.md) agents.provide
mcp.close { url } {}: stops serving an mcp.serve address of this plugin agents.provide
services.provide { name, version, access, methods: { m: { params, result, errors } }, events: { e: schema } } (JSON Schema 2020-12) {}: registers a service the manifest declares in provides. access is "any", "official" or a list of plugin ids. The schemas are the contract: the host validates every call's params and result and every event's payload against them. One plugin per name: the user's choice (the serviceProviders setting), an official plugin, the first by name; another provider is refused with ProvidedElsewhere the manifest's provides
services.call { name, method, params } the method's result, or a service error (code -32010, data._tag: ServiceUnavailable, NotAllowed, InvalidParams (with issues), ContractViolation, Interrupted, or the provider's own declared error). Cancellable like any request (host/cancel), which cancels it in the provider the manifest's inject/optional, and the provider's access list
services.emit { name, event, payload } (notification) the provider's event, to the plugins that declared the service and subscribed with services.subscribe the provider
services.subscribe { name, event } (notification) hear that event as services/event { name, event, payload } the manifest's inject/optional
services.unsubscribe { name, event } (notification) stop hearing it
subagent.start { scope, title, name?, agent?, model?, effort?, prompt? } { taskId }: a subagent of the chat, nested under the tool call scope came with (tools.md, Subagents) a scope of this plugin's running tool call
subagent.update { scope, taskId, title?, activity?, summary?, usage?, toolUses?, model?, effort?, status? } {}; a final status (completed, failed, cancelled) ends it. The runtime sends it as a notification, and the end as a request as subagent.start
subagent.event { scope, taskId, event } {}: text_delta, reasoning_delta, tool_call_started, tool_call_updated, usage or notice in the subagent's own transcript; a notification, so events keep their order as subagent.start
subagents.types {} { types: [{ plugin, id, title, description, inputSchema }] }: every subagent type of a plugin with models.use
subagents.run { type, input, scope? } { result }: runs the type (id or plugin/id) in its plugin (subagent/run), under the caller's tool call when scope names it models.use
models.list { workspaceId? } { agents: [{ id, name, icon?, model, effort, models: [{ value, name, group?, efforts: [{ value, name }] }], error? }] }: the enabled agents models.use
models.prompt { agentId, model?, effort?, prompt | blocks, workspaceId?, promptId?, display?: { scope, taskId } } { text, usage, status, message?, agentId, model, effort } after the run; its events come first as models/event { promptId, event } notifications. The agent must be enabled; the session is hidden and closed after the run; display shows the run in one of the caller's subagents, whose approvals and questions then go to the chat. Cancelling the request cancels the run models.use
tools.changed {} (notification) the plugin's tool list changed; the host asks tools/list again (JavaScript plugins send it for you) tools.provide
settings.get {} Settings settings.read
settings.update partial Settings Settings settings.write
updates.status {} UpdateStatus plugins.manage
updates.check {} UpdateStatus, after asking the update server plugins.manage
updates.apply_plugins {} { report: { updated, added, removed, modified, skipped, newer }, chatId }: applies the installed app's default plugin set that the start could not apply (UpdateStatus.pluginUpdate; it fails when there is none). Default plugins the user left alone are replaced; chatId is the chat where an agent merges the update into the changed ones, or null plugins.manage
updates.install_app {} { restart }: the app update is downloaded and ready; when restart is true, quit (api.host.kernel("quit")) to finish plugins.manage
plugins.list {} { plugins: PluginSummary[] } plugins.manage
plugins.request_enable { name, chatId? } { requestId }: asks the app to show its native card for the plugin: the enable card when it is not enabled, the permission card when it is enabled and asks for more. requestId is null when there is nothing to review. With chatId the card sits in that chat; without it the card is a modal over the window. It grants nothing: only the user's answer on the card does. chats.control (it only shows the card, where the user decides)
plugins.set_enabled { name, enabled } {}. Off always works. On works only for a plugin the user enabled before with nothing new to review; otherwise it fails with NeedsReview, and the caller uses plugins.request_enable plugins.manage
plugins.revoke { name, permission, scope? } {}: takes one grant back; the plugin keeps running and calls that need the grant fail from now on. Refused for official plugins (turn them off instead) plugins.manage
plugins.reload { name } {} (the plugin loads again in a new runtime, which also ends one whose event loop is stuck; for one that was stopped, this is "Start again") plugins.manage
plugins.settings { name } the plugin's settings section: { name, id, title, properties: [{ key, type, title, description?, default?, options?, minimum?, maximum?, kind?, placeholder?, value, secretSet?, locked, error? }], notices, view }. value is what the plugin reads, or the value waiting on its change card (a secret has only secretSet); locked: a permission refers to the setting; error: its value cannot fill that permission; notices: values an update put back to their defaults; view: the plugin's settings view module plugins.manage
plugins.set_setting { name, key, value } { value, requestId }: the user changed the setting (null goes back to the default). For a setting a permission refers to whose new value needs a grant the plugin does not have, requestId names the change card, which shows the old and the new scope and holds the new value: the plugin keeps the old value and its grant until the user allows it, Cancel drops it, and plugins.settings shows the waiting value meanwhile. A later change of the setting replaces the card, or removes it when the value goes back to one the plugin is granted. A secret is only cleared here (value: null); it is typed into the native field (ui.secretInput), never sent through a plugin plugins.manage
own_settings.get {} { values }: the calling plugin's own settings, without secrets (api.settings.get)
own_settings.set { key, value } { values }: writes one of the calling plugin's own settings, checked against its type; refused (PermissionNotGranted for settings.own) for a setting a permission refers to, which only the user changes. A secret goes to the system credential store
own_settings.secret { key } { value }: one of the calling plugin's own secrets, from the system credential store, or null
security.pending { chatId } { requests: SecurityRequest[] }: the requests whose cards sit in that chat chats.read
market.search { query?, sort?, page?, category? } the registry's search page { results, page, pageSize, total }, each result with installed as market.listing has it (sort: relevance, downloads, rating, recent, name; category: official, agents, tools, interface, git, terminal, web, mods) market
market.listing { id } the listing (id, name, description, publisher: { name, displayName, verified }, latestVersion, updatedAt, categories, downloads, rating, basedOn, mods, permissions, versions, and listing: { version, icon, screenshots: [{ path, sha256, width, height, caption?, url }], homepage, repository, readme } | null, what the latest version's plugin.json listing declares) plus installed: { folder, path, version, enabled, source } | null market
market.read { id, version?, path? } without path the release: { id, version, official, publisher, basedOn, permissions, targets, yanked, files: [{ path, size, sha256, executable, binary }] }; with path one file: { path, size, sha256, text, truncated } or { ..., binary: true }. Read from the verified package; nothing is saved market
market.media { id, version, path, sha256 } { path }: a picture the listing names (listing.icon or a screenshot, with the sha256 the listing gives), fetched from the registry the first time, checked against that hash and kept in the app's own cache by it; ui.image draws that path for any plugin market
market.similar { id } publishers and plugins with similar names, with creation dates, install counts and the verified flag market
market.categories {} { categories: [{ id, title, … }] } from the registry the app uses (marketplaceUrl, else the default) market
market.comments { id } { threads }: the listing's comments, from the same registry market
market.install { id, version?, chatId? } { id, version, folder, path, official, enabled: false, yanked, basedOn, permissions, requestId }: verifies, downloads and extracts into the writable plugins folder, not enabled; with chatId the enable card shows in that chat market
market.updates { cached? } { updates: MarketUpdate[] } (with cached, the last check's answer, without asking the registry) market
market.update { name } { updated: true, id, folder, from, to } for an unmodified official plugin (replaced after the official signature check), else { needsAgent: true, id, folder, path, from, to, official, modified, baseline, changedFiles, permissions: { added, removed, changed }, newPermissions, basedOn, read: { id, version } } market
market.publish { name, visibility?, share? } { jobId, state, id, version, basedOn, permissions, error?, errorFile?, errorLine? }. For dvg and the app's own publish row; the marketplace plugin never calls it (its market_publish tool asks for the row) market
market.publish_setting { name, setting? } { setting }: the plugin's publish setting, kept in its install record (never in its folder); with setting (an object, or null) replaced. { mode: "never" } is "Never for this plugin" market
market.request_publish { name, chatId, visibility?, share? } { requestId }: the publish row for that plugin in that chat, for a user who asked an agent to publish. visibility and share only fill in the row's form; the plugin is published only from the row. Refused for an official plugin as shipped market
market.request_report { id, version?, reason, files?, kind?: agent | user, chatId? } { requestId }: the report card, showing exactly what is sent (in the chat, or a modal without chatId); the report is sent only from the card market
market.report { id, version?, reason, files?, kind? } { id }: sends a report at once (dvg report); the marketplace plugin uses market.request_report market
market.unpublish { id } { ok } market
market.yank { id, version } { ok } market
market.share { id, add?, remove? } { added, removed } market
market.login {} { userCode, verificationUri, verificationUriComplete, expiresIn, interval }: a device sign-in; show the code, and open the page when the user clicks. The outcome arrives as market_account market
market.logout {} {} market
market.login_cancel {} {}: stops the sign-in that waits, so no market_account arrives for it market
market.whoami {} { signedIn, registry, account?, picture?, expired? } (no network when nobody is signed in; picture is the signed-in publisher's picture as a file any plugin may draw, or null) market
market.claim_username { name } the publisher: claims name as the signed-in account's username market
market.update_profile { fields } the publisher's profile: saves displayName, bio, website, github, x, bluesky, mastodon, publicEmail and creditOptOut (null or "" clears a field; the registry checks each) market
market.set_avatar { path } { avatar }: uploads the PNG, JPEG or WebP picture at path (at most 2 MB), which the user must have just chosen in api.pickImages, once; { path: null } removes the picture market
market.workspace {} { workspaceId, path }: the Plugins workspace, added when the user has none market
market.bug_draft { chatId? } { plugins: [{ name, id, version, official, listed, enabled, changed, baseline, suggested, reasons }], note, registry, signedIn, appVersion }: the bug report form's plugins, the suggested ones first (changed against their release, changed by the chat's last turn, named in an error of the log) market
market.bug_preview { plugins, fullSource?, screenshots? } { plugins, attachments: BugAttachment[], note }: every attachment those choices send, with its full content (text, or path of a screenshot) market
market.request_bug_report { text, plugins, contactEmail?, attachments?, fullSource?, screenshots?, chatId?, kind?: user | agent } { requestId }: the send card with the full preview (in the chat, or a modal without chatId); attachments are the ids to send (the default ones when left out); the report is sent only from the card, which answers market_bug_report market
market.bug_reports {} { reports: [{ id, number, registry, text, plugins, source, createdAt, requestId? }] }: the reports this app sent market
market.link_fix_chat { chatId, report } { reportId, number }: the chat fixes that report (bug_… or #N): a turn there that changes a marketplace plugin leaves the attach row instead of the publish row market
market.request_attach_fix { report, folders?, chatId? } { requestId, plugins }: the attach card for the diffs of folders (every changed marketplace plugin when left out) against their base versions; the fix is attached only from the card market
market.open_bug_form { plugins?, text? } {}: opens the bug report form (the market plugin hears market_bug_form); for Settings and the Help menu plugins.manage
ui.notify { message, level? } {}
ui.context {} { workspaceId?, chatId?, agentId? }
ui.invalidate_panel { panel } {} (declarative panels)
ui.open_chat { chatId } {} chats.read
log { level, message } {} (writes to the app log; console.* sends it)
cancel { id } (notification) the plugin gave up its request id (a fetch aborted before its headers): the host stops the work, and the request's answer is an error nobody waits for
events.subscribe / events.unsubscribe { events?: string[], allBut?: string[] } {} (the runtime subscribes for a JavaScript plugin, with the events its listeners and views use; api.on listens). events names the events wanted ("*" for all), allBut the ones not wanted; neither asks for every event. The runtime sends later changes as a host/events.subscribe notification with the same params, which replaces the last one.

The market.* methods belong to the official marketplace plugin (market is reserved to official plugins; ../market/ is the plugin). JavaScript calls them through api.host.call("host/market.search", params). None of them enables, publishes from a chat or sends a report behind the user's back: the plugin asks for the enable card (plugins.request_enable), the publish row (market.request_publish), the report card (market.request_report), the bug report's send card (market.request_bug_report) and the attach card (market.request_attach_fix), and only the app's own buttons act on them.

chats.respond_approval is gone. Only the app's own card answers an agent's approval, so a plugin cannot allow a tool call the user did not see: the chat plugin places that card with <security_card> (see ui-plugins.md), and a call to the old method fails with unknown host method host/chats.respond_approval. Questions stay with the plugin: answering one (chats.respond_question) is user input to the agent, as chats.send is.

Types:

UpdateStatus  { enabled, target, appVersion, plugins?: { version, build, pluginApi }, checking, busy?, lastChecked?,
                error?, appUpdate?: { version, releaseNotes?, url, sha256, size?, kind }, pluginUpdate?: { version, build,
                pluginApi, releaseNotes?, url, sha256, size? } }
              `enabled` is false when the app runs its plugins from a source tree. See `scripts/RELEASES.md`.
Workspace     { id, path, name, position }
Chat          { id, workspaceId, agentId, sessionId?, title, createdAt, updatedAt, archived, options, status, task }
              status: idle | running | waiting_approval | waiting_question | failed
              task: the id of its home, the task (and so the sidebar row) it belongs to
Task          { id, title?, layout: TaskLayout, completedAt?, createdAt, updatedAt }
              title: the name the user gave a task of two or more chats; without one the row shows its first chat's title.
              completedAt: set when the user checks the row off, or when an import brings in an old chat;
              a prompt (or a new run) in any of its chats clears it.
TaskLayout    { root: Layout, focused: PaneId }
Layout        { kind: "pane", id, tabs: Tab[], active: Tab } | { kind: "split", id, direction: row | column,
                children: [{ share, layout: Layout }] }
              A split has two or more children whose shares add up to 1, none a split of its own direction.
Tab           { kind: "chat", chatId } | { kind: "item", ...Item }
Item          { id, owner, itemKind, key, title, icon?, chatId?, unseen }
              owner: the plugin whose tab kind it is; chatId: the chat it belongs to, which ties it to that chat's task.
SideSplit     { layout: TaskLayout | null, remembered: [{ pane, task?, tab }], open, width }
PlaceTarget   { kind: "strip", paneId, index } | { kind: "edge", paneId, edge: left | right | top | bottom }
              | { kind: "join", taskId } | { kind: "alone" }
ClosedTab     { chatId, home, paneId, index }
Settings      { appearance, theme, fontSize, enabledAgents, agents, keybindings, autoApprove, checkpoints,
                checkpointRetentionDays: number | null, checkpointMaxMegabytes: number | null,
                tools: { mode: code | direct, disabled: ["plugin/tool"], disabledRules: ["plugin/file" | plugin] }, marketplaceUrl? }
              `marketplaceUrl`: the registry the marketplace uses (a self-hosted or local one); unset means the
              default, or `DIVERGENCE_REPO_URL` when that is set.
              (`disabledPlugins` is read once, into the plugins' install records, and is empty after that.
              `keybindings` is not read: the user's keys are in `<data>/keybindings.json`, see `ui-plugins.md`,
              Commands and keys. A plugin's own settings are not here either: see `plugins.settings`.)
AgentInfo     { id, name, description, version?, capabilities, authMethods, status: { state, message? }, icon? }
              icon: the agent's mark as inline SVG; pass it to `<icon svg={icon} />`
ConfigOption  { id, name, description?, category: mode|model|reasoning|approval|<other>, kind: select|toggle, value, choices: [{ value, name, description?, group?, reasoningLevels }] }
TranscriptItem { id, createdAt?, role: user|assistant|reasoning|tool|plan|notice, ...body }
                (a user row with `from` is a message another agent sent; see agent-protocol.md)
PluginSummary { name, id, version, description, official, claimsOfficial, source: official-bundle | marketplace | local,
                enabled, disabledByDefault?, state: loaded | disabled | not_enabled | failed | reload_pending, error?, ui,
                sandboxed: bool | null, basedOn?: { id, version }, permissions: PermissionEntry[],
                pending: PermissionEntry[], settings?: string, commands: number }
              `name` is the folder name, `id` the manifest id (`local:<folder>` without one). `disabled` is a plugin
              the user turned off; `not_enabled` one nobody enabled yet. `failed` with the error `Stopped: too much memory` or
              `Stopped: crashed` is a plugin that was stopped (`plugins.reload` starts it again). `ui`: runs as
              JavaScript (`main`). `claimsOfficial`: a `divergence/` id on a plugin that is not official.
              `disabledByDefault`: the manifest's fresh-install default, independent of `enabled`; absent on older hosts.
              `sandboxed`: whether the OS
              sandbox holds the plugin's runtime (`false` where the system has none: Windows for now; `null` before
              any runtime started). `pending`: what the manifest asks for that nobody reviewed yet. `settings`: the
              title of its section of the settings page, when it declares settings; `commands`: how many it declares.
PermissionEntry { permission, scope?, reason, risk: always | low | medium | high | dangerous | unsafe | reserved, granted,
                  setting?, settingTitle? }
              `setting`: the scope is that setting's value (`${settings.<key>}` in the manifest), parsed; the card
              says so with the setting's title.
              A reserved permission in a plugin that is not official has `risk: "reserved"`, is never granted and
              never pending.
SecurityRequest { id, chatId?, afterItemId?, kind: "enable", plugin: PluginSummary, createdAt, stale }
              | { id, chatId?, afterItemId?, kind: "permissions", plugin: PluginSummary, new: PermissionEntry[], createdAt, stale }
              | { id, chatId, afterItemId?, kind: "publish", plugin: PluginSummary, changed: string[], visibility?, share?,
                  createdAt, stale: false }
              | { id, chatId?, afterItemId?, kind: "report", report: { id, version?, reason, files, kind, registry },
                  plugin?: PluginSummary, createdAt, stale: false }
              | { id, kind: "setting", plugin: PluginSummary, key, title, from, to,
                  changes: [{ permission, from?, to?, risk, reason }], createdAt, stale }
              | { id, chatId?, afterItemId?, kind: "bug_report", report: { text, plugins: BugPlugin[], contactEmail?,
                  attachments: BugAttachment[], source: app | agent, registry, account?, appVersion }, createdAt, stale: false }
              | { id, chatId?, afterItemId?, kind: "attach_fix", fix: { reportId, number?, registry, plugins: [{ folder, id,
                  baseVersion, official, files, permissionsAdded, permissionsRemoved, permissionsChanged, diffSize }] },
                  createdAt, stale: false }
              `afterItemId` is the chat's last item when the request was made. `stale`: the manifest on disk changed
              since, and the card offers to review again. `publish` is the publish row (`MARKETPLACE.md` §10.6): after a
              turn that changed files (`changed`, relative to the plugin's folder) of a plugin with no publish setting
              that is not an official plugin as shipped; it goes below the chat's latest response only, and the next
              prompt, or a newer row, takes it away. `report` holds exactly what the report sends. `setting` is the
              change card (`MARKETPLACE.md` §15.3): the user changed a setting a permission refers to, from `from` to
              `to`, and `changes` are the scopes that change; it is a modal, `stale` once the value changed again.
              `bug_report` is a bug report's send card (`MARKETPLACE.md` §14.1) and `attach_fix` a fix's attach row
              (§14.2): a request never carries an attachment's content or a diff; only the kernel's card shows them.
BugPlugin     { folder?, id, version?, official }   (`id` is `local:<folder>` for a plugin without one)
BugAttachment { id, kind: diff | source | config | diagnostics | screenshot, title, name, pluginId?, size,
                removed: [{ line, kind }], defaultOn }   (`market.bug_preview` adds `text`, or `path` and `mimeType`)
MarketUpdate  { id, folder, installed, latest?, official, direct, malicious, yanked, reason? }
              `direct`: an unmodified official plugin that `market.update` replaces at once; anything else goes to an agent.

Context policy, selection and managed exports

The selected divergence/chat-context@1.0.0 service supplies two methods; chat/context-contract.ts defines their schemas. prepare({ snapshot, records, destination, configuration }) returns { instructions, text, artifacts, covers }. records are exact pinned revisions, already filtered to the destination's missing history when resuming. covers contains record IDs from that input only. render({ snapshot, records, configuration }) returns artifact text without inference. Both methods report { _tag: "ContextPreparationFailed", message } on failure.

Use the existing service provider selection in Settings to choose a replacement. The stock chat's handoffEnabled setting disables only its preparation method; it does not prevent a selected replacement or revoke existing regeneration. A replacement must package its own copy of the public contract, not import a different plugin's implementation. No policy or an unverified destination capability blocks established-chat switching and lost-session recovery.

chats.handoff checks idle work, requests, settlement and unresolved admissions. revision comes from inputs.list; draftRevision comes from drafts.get. Preparation runs outside the state lock; concurrent edits or policy replacement abort commit. The destination, context barrier, queue ownership and draft move commit together. An empty draft takes the first held queue entry. An occupied draft, including image-only content, keeps every queued entry. Selection never sends; the next explicit Send delivers the packet alongside the human request. Remaining transferred entries wait for that explicitly started run to settle.

Preparation-owned managed exports are adopted in that same transaction. Failure/cancellation/restart revokes uncommitted exports and fences late creates; exports omitted from a successful packet are revoked too. Older exports and immutable inline artifacts are unaffected. chats.contextPolicy reports the selected plugin folder and registration availability; a policy owns its private enabled setting. The stock UI disables established-chat switching when its own selected policy is disabled, but permits an available selected replacement.

The built-in inline transcript retains human/assistant text and compact tool blocks: called names/counts plus detailed-file section and physical line ranges. A newest complete contiguous suffix fits 24,000 estimated tokens (ceil(UTF-8 bytes / 4)), including guidance; this is not exact model tokenization. Tool payloads and reasoning do not consume that inline allowance.

Every nonempty handoff publishes a complete pinned-chat JSONL file, even below the budget. Returning sessions get only missing revisions inline, but the file still contains the whole chat. Each line is { section, ...ArchiveRecord }; item preserves all original stored fields, including reasoning, full recorded tool inputs/results/content, user blocks, assistant messages, plans, notices and nested task transcripts. Consecutive tools from one source share a numeric section. Missing provider fields are not fabricated. The handoff includes a schema example and a selective jq query, with ordinary file/parser alternatives. Managed files currently have .txt extensions but their contents are JSONL. Paths remain on-demand references, never eager attachments or custom tools; ordinary destination file access is required for nonempty history.

Managed files live under .divergence/handoff-<data-root-id>/ in the workspace, excluded locally from Git and checkpoints. Tracked/user-owned/symlink conflicts fail without overwriting them. Workspace placement is not per-chat filesystem isolation. Each reference pins the snapshot, renderer identity/version, configuration, data root and output. After 24 hours the stock export is a command stub; after 30 days without successful regeneration the disk copy is deleted. Reads and failed renders do not renew clocks. Cleanup runs while open and on restart; closed/asleep apps may retain files longer. Disk deletion does not revoke regeneration; chat deletion and invalidating restore do.

The returned regenerateCommand uses dvg --data-dir <issuing-root> artifact regenerate --reference <scoped-capability>. It works from ordinary workspaces without a marketplace launch token. It cannot select arbitrary chats or paths, impersonate a plugin, or read the database directly. The issuing app and pinned renderer must be running and authorized. UI plugins can use artifacts.regenerate when native command access is unavailable.

Durable input and scheduler authority

ComposerDraft and PendingInput optionally carry composition: { text, generated: number[] }. text is the original editable source, including whitespace. generated explicitly indexes the blocks projected from that source: primary text/skill, file mentions and generated mention instructions. All unlisted blocks are opaque and must be preserved, even extra text, files or skills resembling generated content. Do not infer provenance from contents. Rebuild the listed blocks from edited source; removing a tag removes its derived instructions/file/skill, not an opaque attachment. Without metadata, the stock editor uses only the existing first-text editable convention and retains every later block; it cannot identify legacy expansions reliably.

Pass metadata with drafts.update when saving raw input or capturing send-time expansion. drafts.enqueue atomically carries it to the pending input and clears the draft. Queue-to-draft and handoff transfers retain it; appended draft steers combine editable sources and offset generated indices without marking opaque contributions. inputs.update accepts metadata (or null to clear it); replacing blocks without metadata clears obsolete indices. Plain inputs.enqueue remains an opaque-block API; use the atomic draft claim for editable composition. This additive host-only metadata is never part of PromptInput or native block transport and adds no permission. Old hosts that lack structured drafts keep the text/send path; they cannot persist this new provenance.

inputs.enqueue acknowledges persistence, not delivery. append: true adds blocks to the last held steer, separated by a newline; attachments keep their order and bytes. The resulting input may retain that earlier steer's id. Ordinary user input supersedes editable generated_continue input; that origin is admitted only when no unconsumed input exists, so generation cannot race a user's queue. Removed and amended enqueue ids remain idempotency keys.

Input states are held, dispatching, delivery_unknown, rejected, native_admitted, and observed_consumed. A write acknowledgement does not prove native admission or model pickup. Never automatically replay uncertain/admitted input. A correlated provider event can establish consumption after the dispatch call returns. Rejection positively establishes non-admission; preserve the same logical input id when retrying it. Refresh the snapshot before a CAS retry; never retry provider delivery just because a request timed out. A call made against an older revision fails with code -32020 (STALE_REVISION): nothing changed, so read the snapshot again and decide again. It is the expected result of a race with an event, an enqueue or a user action, not a failure to show.

running includes preparation. settling lasts through required transcript and checkpoint finalization. Use run_settled, not run_finished, as a release boundary. The host never drains an ordinary queue: a scheduler chooses an input and calls dispatch. Native steers share the initiating run's checkpoint and join the transcript when the agent picks them up (input_consumed), or when the run ends without picking them up; simulated steering reserves one replacement, cancels the original prompt, and waits for real settlement in the same session. Stop/edit/remove can revoke that held reservation; a cancellation timeout cannot authorize a new prompt.

Any plugin may provide divergence/input-scheduler with the service APIs. The live provider's registration yields the opaque token returned by inputs.policy; automatic dispatch validates that token against the caller and registration. Reload/disable/replacement invalidates it. The stock chat service contract is chat/scheduler-contract.ts; consumers need not use the stock FIFO policy. policyState is durable JSON the host does not interpret. Alternative policies may release inputs in a different order, while claims, CAS, lineage and delivery evidence remain host-owned. An optional scope coordinates a claim across chats until actual run settlement; a recovered ambiguous run retains its claim.

Availability reads are observations, not permission inferred from a meter. Use UsageLimits.recovery with native account identity, quota scope, observation time and availability. A missing reset cannot invent a timer; null/unknown/unsupported does not override a fresh rejection. Stock recovery uses one bounded attempt at a trustworthy future reset and holds when identity or delivery cannot be reconciled.

See agent-protocol.md for ToolCall, ApprovalRequest, QuestionRequest and the event payloads.

Source: plugins/docs/host-api.md in the Divergence repository, built with this site.