LLM/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-05-13 15:44:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: generate

Browse Source
This commit is contained in:
opencode-agent[bot]
2026-05-13 14:59:13 +00:00
parent d43124abe0
commit e7aed64949
1 changed files with 565 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

750
specs/v2/api.html
View File

@@ -17,7 +17,13 @@
--accent: #496b5a; --accent: #496b5a;
--accent-soft: #dce7dc; --accent-soft: #dce7dc;
font-family: font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; Inter,
ui-sans-serif,
system-ui,
-apple-system,
BlinkMacSystemFont,
"Segoe UI",
sans-serif;
} }
* { * {
@@ -34,8 +40,7 @@
background: background:
radial-gradient(circle at 12% 0%, rgba(73, 107, 90, 0.12), transparent 34rem), radial-gradient(circle at 12% 0%, rgba(73, 107, 90, 0.12), transparent 34rem),
linear-gradient(90deg, rgba(38, 52, 47, 0.055) 1px, transparent 1px), linear-gradient(90deg, rgba(38, 52, 47, 0.055) 1px, transparent 1px),
linear-gradient(rgba(38, 52, 47, 0.045) 1px, transparent 1px), linear-gradient(rgba(38, 52, 47, 0.045) 1px, transparent 1px), var(--bg);
var(--bg);
background-size: 72px 72px; background-size: 72px 72px;
color: var(--fg); color: var(--fg);
line-height: 1.5; line-height: 1.5;
@@ -231,7 +236,13 @@
.diagram text { .diagram text {
fill: var(--fg); fill: var(--fg);
font-family: font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; Inter,
ui-sans-serif,
system-ui,
-apple-system,
BlinkMacSystemFont,
"Segoe UI",
sans-serif;
} }
.diagram .box { .diagram .box {
@@ -412,7 +423,10 @@
<section class="grid"> <section class="grid">
<article class="span-8 rule"> <article class="span-8 rule">
<strong>Everything has one canonical route. Some routes are server-scoped; runtime routes use context; session item routes use the session.</strong> <strong
>Everything has one canonical route. Some routes are server-scoped; runtime routes use context; session item
routes use the session.</strong
>
<p> <p>
Server-scoped routes manage the whole server: projects, workspace lifecycle, and auth accounts. Runtime Server-scoped routes manage the whole server: projects, workspace lifecycle, and auth accounts. Runtime
context is for anything resolved from an active directory, including config, provider capabilities, tools, context is for anything resolved from an active directory, including config, provider capabilities, tools,
@@ -432,7 +446,9 @@
<h2>Context Model</h2> <h2>Context Model</h2>
<svg class="diagram" viewBox="0 0 1280 360" role="img" aria-labelledby="ctx-title ctx-desc"> <svg class="diagram" viewBox="0 0 1280 360" role="img" aria-labelledby="ctx-title ctx-desc">
<title id="ctx-title">API context resolution</title> <title id="ctx-title">API context resolution</title>
<desc id="ctx-desc">Non-session routes resolve from request context, session item routes resolve from session storage.</desc> <desc id="ctx-desc">
Non-session routes resolve from request context, session item routes resolve from session storage.
</desc>
<defs> <defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"> <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
<path d="M0,0 L0,6 L9,3 z" fill="#26342f" /> <path d="M0,0 L0,6 L9,3 z" fill="#26342f" />
@@ -468,8 +484,8 @@
<article class="span-6 panel panel-pad stack"> <article class="span-6 panel panel-pad stack">
<h3>Request-context calls</h3> <h3>Request-context calls</h3>
<p class="muted"> <p class="muted">
These calls operate against a directory, optionally through a workspace. Simple clients omit context and These calls operate against a directory, optionally through a workspace. Simple clients omit context and use
use the default runtime. the default runtime.
</p> </p>
<pre><code>GET /api/fs/tree?path=.&directory=/repo/app&workspace=ws_123</code></pre> <pre><code>GET /api/fs/tree?path=.&directory=/repo/app&workspace=ws_123</code></pre>
</article> </article>
@@ -491,187 +507,551 @@ sessionID -&gt; { directory, workspaceID? }</code></pre>
<div class="span-12 stack"> <div class="span-12 stack">
<h2>Operation Inventory</h2> <h2>Operation Inventory</h2>
<p class="muted"> <p class="muted">
The SDK is the source of truth. HTTP routes are mounts for RPC-style operations. <span class="context-tag server">server</span> operations do not use runtime context. <span class="context-tag request">request</span> operations use request/default runtime context from <code>directory</code> and <code>workspace</code> query parameters. <span class="context-tag session">session</span> operations use pinned session context and should not accept context input. The SDK is the source of truth. HTTP routes are mounts for RPC-style operations.
<span class="context-tag server">server</span> operations do not use runtime context.
<span class="context-tag request">request</span> operations use request/default runtime context from
<code>directory</code> and <code>workspace</code> query parameters.
<span class="context-tag session">session</span> operations use pinned session context and should not accept
context input.
</p> </p>
</div> </div>
<article class="span-12 panel panel-pad stack"> <article class="span-12 panel panel-pad stack">
<table> <table>
<thead><tr><th>Operation</th><th>Input</th><th>Context</th><th>HTTP mount</th><th>Purpose</th></tr></thead> <thead>
<tr>
<th>Operation</th>
<th>Input</th>
<th>Context</th>
<th>HTTP mount</th>
<th>Purpose</th>
</tr>
</thead>
<tbody> <tbody>
<tr><td class="operation"><code>agent.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/agent</code></td><td>Available agents.</td></tr> <tr>
<tr><td class="operation"><code>auth.activate</code></td><td class="body"><code>{ accountID: AccountID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>POST /api/auth/:accountID/activate</code></td><td>Set the account as active for its service.</td></tr> <td class="operation"><code>agent.list</code></td>
<tr><td class="operation"><code>auth.create</code></td><td class="body"><code>{ <td class="body"><code>{}</code></td>
serviceID: ServiceID <td><span class="context-tag request">request</span></td>
credential: <td class="route"><code>GET /api/agent</code></td>
| { type: "oauth", refresh: string, access: string, expires: number } <td>Available agents.</td>
| { type: "api", key: string, metadata?: Record&lt;string, string&gt; } </tr>
description?: string <tr>
active?: boolean <td class="operation"><code>auth.activate</code></td>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>POST /api/auth</code></td><td>Create an auth account.</td></tr> <td class="body"><code>{ accountID: AccountID }</code></td>
<tr><td class="operation"><code>auth.delete</code></td><td class="body"><code>{ accountID: AccountID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>DELETE /api/auth/:accountID</code></td><td>Remove an auth account.</td></tr> <td><span class="context-tag server">server</span></td>
<tr><td class="operation"><code>auth.get</code></td><td class="body"><code>{ accountID: AccountID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/auth/:accountID</code></td><td>Get one auth account.</td></tr> <td class="route"><code>POST /api/auth/:accountID/activate</code></td>
<tr><td class="operation"><code>auth.list</code></td><td class="body"><code>{ serviceID?: ServiceID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/auth</code></td><td>List saved auth accounts. Response includes active account mapping.</td></tr> <td>Set the account as active for its service.</td>
<tr><td class="operation"><code>auth.update</code></td><td class="body"><code>{ </tr>
accountID: AccountID <tr>
description?: string <td class="operation"><code>auth.create</code></td>
credential?: <td class="body">
| { type: "oauth", refresh: string, access: string, expires: number } <code
| { type: "api", key: string, metadata?: Record&lt;string, string&gt; } >{ serviceID: ServiceID credential: | { type: "oauth", refresh: string, access: string, expires:
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>PATCH /api/auth/:accountID</code></td><td>Update account description or credential.</td></tr> number } | { type: "api", key: string, metadata?: Record&lt;string, string&gt; } description?:
<tr><td class="operation"><code>catalog.model.get</code></td><td class="body"><code>{ string active?: boolean }</code
providerID: ProviderID >
modelID: ModelID </td>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/catalog/model/:providerID/:modelID</code></td><td>Get one catalog model.</td></tr> <td><span class="context-tag server">server</span></td>
<tr><td class="operation"><code>catalog.model.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/catalog/model</code></td><td>List flattened catalog models.</td></tr> <td class="route"><code>POST /api/auth</code></td>
<tr><td class="operation"><code>command.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/command</code></td><td>Available commands.</td></tr> <td>Create an auth account.</td>
<tr><td class="operation"><code>config.get</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/config</code></td><td>Resolved config.</td></tr> </tr>
<tr><td class="operation"><code>config.update</code></td><td class="body"><code>{ config: Config }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>PATCH /api/config</code></td><td>Update config.</td></tr> <tr>
<tr><td class="operation"><code>event.subscribe</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/event</code></td><td>Server-sent events for the resolved runtime context.</td></tr> <td class="operation"><code>auth.delete</code></td>
<tr><td class="operation"><code>formatter.status</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/formatter</code></td><td>Formatter status.</td></tr> <td class="body"><code>{ accountID: AccountID }</code></td>
<tr><td class="operation"><code>fs.file</code></td><td class="body"><code>{ path: string }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/fs/file</code></td><td>Read one file.</td></tr> <td><span class="context-tag server">server</span></td>
<tr><td class="operation"><code>fs.grep</code></td><td class="body"><code>{ <td class="route"><code>DELETE /api/auth/:accountID</code></td>
pattern: string <td>Remove an auth account.</td>
include?: string </tr>
limit?: number <tr>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/fs/grep</code></td><td>Search file contents.</td></tr> <td class="operation"><code>auth.get</code></td>
<tr><td class="operation"><code>fs.search</code></td><td class="body"><code>{ <td class="body"><code>{ accountID: AccountID }</code></td>
query: string <td><span class="context-tag server">server</span></td>
type?: "file" | "directory" <td class="route"><code>GET /api/auth/:accountID</code></td>
limit?: number <td>Get one auth account.</td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/fs/search</code></td><td>Search paths by name.</td></tr> </tr>
<tr><td class="operation"><code>fs.tree</code></td><td class="body"><code>{ path: string }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/fs/tree</code></td><td>Browse a directory.</td></tr> <tr>
<tr><td class="operation"><code>lsp.status</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/lsp</code></td><td>LSP status.</td></tr> <td class="operation"><code>auth.list</code></td>
<tr><td class="operation"><code>mcp.prompt.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/mcp/prompt</code></td><td>List MCP prompts.</td></tr> <td class="body"><code>{ serviceID?: ServiceID }</code></td>
<tr><td class="operation"><code>mcp.prompt.render</code></td><td class="body"><code>{ <td><span class="context-tag server">server</span></td>
server: string <td class="route"><code>GET /api/auth</code></td>
name: string <td>List saved auth accounts. Response includes active account mapping.</td>
arguments?: Record&lt;string, string&gt; </tr>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/mcp/prompt/render</code></td><td>Render one MCP prompt.</td></tr> <tr>
<tr><td class="operation"><code>mcp.resource.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/mcp/resource</code></td><td>List MCP resources.</td></tr> <td class="operation"><code>auth.update</code></td>
<tr><td class="operation"><code>mcp.resource.read</code></td><td class="body"><code>{ <td class="body">
server: string <code
uri: string >{ accountID: AccountID description?: string credential?: | { type: "oauth", refresh: string,
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/mcp/resource/read</code></td><td>Read one MCP resource.</td></tr> access: string, expires: number } | { type: "api", key: string, metadata?: Record&lt;string,
<tr><td class="operation"><code>mcp.server.create</code></td><td class="body"><code>{ string&gt; } }</code
name: string >
config: </td>
| { type: "local", command: string, arguments?: string[], environment?: Record&lt;string, string&gt; } <td><span class="context-tag server">server</span></td>
| { type: "remote", url: string, headers?: Record&lt;string, string&gt;, oauth?: boolean | object } <td class="route"><code>PATCH /api/auth/:accountID</code></td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/mcp/server</code></td><td>Add an MCP server to runtime config.</td></tr> <td>Update account description or credential.</td>
<tr><td class="operation"><code>mcp.server.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/mcp/server</code></td><td>List MCP servers with status and auth state.</td></tr> </tr>
<tr><td class="operation"><code>mcp.server.oauth.callback</code></td><td class="body"><code>{ <tr>
name: string <td class="operation"><code>catalog.model.get</code></td>
code: string <td class="body"><code>{ providerID: ProviderID modelID: ModelID }</code></td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/mcp/server/:name/oauth/callback</code></td><td>Complete MCP OAuth.</td></tr> <td><span class="context-tag server">server</span></td>
<tr><td class="operation"><code>mcp.server.oauth.delete</code></td><td class="body"><code>{ name: string }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>DELETE /api/mcp/server/:name/oauth</code></td><td>Remove MCP OAuth credentials.</td></tr> <td class="route"><code>GET /api/catalog/model/:providerID/:modelID</code></td>
<tr><td class="operation"><code>mcp.server.oauth.start</code></td><td class="body"><code>{ name: string }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/mcp/server/:name/oauth</code></td><td>Start MCP OAuth.</td></tr> <td>Get one catalog model.</td>
<tr><td class="operation"><code>permission.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/permission</code></td><td>Pending permission requests.</td></tr> </tr>
<tr><td class="operation"><code>permission.reply</code></td><td class="body"><code>{ <tr>
permissionID: PermissionID <td class="operation"><code>catalog.model.list</code></td>
response: PermissionReply <td class="body"><code>{}</code></td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/permission/:permissionID/reply</code></td><td>Reply to a permission request.</td></tr> <td><span class="context-tag server">server</span></td>
<tr><td class="operation"><code>project.get</code></td><td class="body"><code>{ projectID: ProjectID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/project/:projectID</code></td><td>Get project metadata.</td></tr> <td class="route"><code>GET /api/catalog/model</code></td>
<tr><td class="operation"><code>project.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/project</code></td><td>List projects known to this server.</td></tr> <td>List flattened catalog models.</td>
<tr><td class="operation"><code>project.update</code></td><td class="body"><code>{ </tr>
projectID: ProjectID <tr>
name?: string <td class="operation"><code>command.list</code></td>
icon?: string <td class="body"><code>{}</code></td>
commands?: Array&lt;{ <td><span class="context-tag request">request</span></td>
name: string <td class="route"><code>GET /api/command</code></td>
command: string <td>Available commands.</td>
}&gt; </tr>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>PATCH /api/project/:projectID</code></td><td>Update project metadata.</td></tr> <tr>
<tr><td class="operation"><code>provider.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/provider</code></td><td>Provider inventory for the runtime context.</td></tr> <td class="operation"><code>config.get</code></td>
<tr><td class="operation"><code>pty.create</code></td><td class="body"><code>{ <td class="body"><code>{}</code></td>
command?: string <td><span class="context-tag request">request</span></td>
cwd?: string <td class="route"><code>GET /api/config</code></td>
shell?: string <td>Resolved config.</td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/pty</code></td><td>Create PTY in the runtime context.</td></tr> </tr>
<tr><td class="operation"><code>pty.delete</code></td><td class="body"><code>{ ptyID: PtyID }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>DELETE /api/pty/:ptyID</code></td><td>Delete PTY.</td></tr> <tr>
<tr><td class="operation"><code>pty.get</code></td><td class="body"><code>{ ptyID: PtyID }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/pty/:ptyID</code></td><td>Get PTY info.</td></tr> <td class="operation"><code>config.update</code></td>
<tr><td class="operation"><code>pty.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/pty</code></td><td>List PTYs for the runtime.</td></tr> <td class="body"><code>{ config: Config }</code></td>
<tr><td class="operation"><code>pty.update</code></td><td class="body"><code>{ <td><span class="context-tag request">request</span></td>
ptyID: PtyID <td class="route"><code>PATCH /api/config</code></td>
title?: string <td>Update config.</td>
size?: { columns: number, rows: number } </tr>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>PATCH /api/pty/:ptyID</code></td><td>Update PTY.</td></tr> <tr>
<tr><td class="operation"><code>question.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/question</code></td><td>Pending user questions.</td></tr> <td class="operation"><code>event.subscribe</code></td>
<tr><td class="operation"><code>question.reject</code></td><td class="body"><code>{ questionID: QuestionID }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/question/:questionID/reject</code></td><td>Reject a question.</td></tr> <td class="body"><code>{}</code></td>
<tr><td class="operation"><code>question.reply</code></td><td class="body"><code>{ <td><span class="context-tag request">request</span></td>
questionID: QuestionID <td class="route"><code>GET /api/event</code></td>
response: QuestionResponse <td>Server-sent events for the resolved runtime context.</td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/question/:questionID/reply</code></td><td>Reply to a question.</td></tr> </tr>
<tr><td class="operation"><code>session.compact</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>POST /api/session/:sessionID/compact</code></td><td>Compact the session conversation.</td></tr> <tr>
<tr><td class="operation"><code>session.context</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>GET /api/session/:sessionID/context</code></td><td>Return active context messages after the last compaction.</td></tr> <td class="operation"><code>formatter.status</code></td>
<tr><td class="operation"><code>session.create</code></td><td class="body"><code>{ <td class="body"><code>{}</code></td>
title?: string <td><span class="context-tag request">request</span></td>
agent?: string <td class="route"><code>GET /api/formatter</code></td>
model?: { providerID: ProviderID, modelID: ModelID } <td>Formatter status.</td>
permission?: PermissionRule[] </tr>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/session</code></td><td>Create a session pinned to resolved runtime context.</td></tr> <tr>
<tr><td class="operation"><code>session.delete</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>DELETE /api/session/:sessionID</code></td><td>Delete a session.</td></tr> <td class="operation"><code>fs.file</code></td>
<tr><td class="operation"><code>session.diff</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>GET /api/session/:sessionID/diff</code></td><td>Return session diff summary.</td></tr> <td class="body"><code>{ path: string }</code></td>
<tr><td class="operation"><code>session.get</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>GET /api/session/:sessionID</code></td><td>Get one session.</td></tr> <td><span class="context-tag request">request</span></td>
<tr><td class="operation"><code>session.list</code></td><td class="body"><code>{ <td class="route"><code>GET /api/fs/file</code></td>
limit?: number <td>Read one file.</td>
order?: "asc" | "desc" </tr>
path?: string <tr>
roots?: boolean <td class="operation"><code>fs.grep</code></td>
start?: number <td class="body"><code>{ pattern: string include?: string limit?: number }</code></td>
search?: string <td><span class="context-tag request">request</span></td>
cursor?: string <td class="route"><code>POST /api/fs/grep</code></td>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/session</code></td><td>List sessions for the current runtime context by default.</td></tr> <td>Search file contents.</td>
<tr><td class="operation"><code>session.message.list</code></td><td class="body"><code>{ </tr>
sessionID: SessionID <tr>
limit?: number <td class="operation"><code>fs.search</code></td>
order?: "asc" | "desc" <td class="body"><code>{ query: string type?: "file" | "directory" limit?: number }</code></td>
cursor?: string <td><span class="context-tag request">request</span></td>
}</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>GET /api/session/:sessionID/message</code></td><td>Page through session messages.</td></tr> <td class="route"><code>POST /api/fs/search</code></td>
<tr><td class="operation"><code>session.prompt</code></td><td class="body"><code>{ <td>Search paths by name.</td>
sessionID: SessionID </tr>
prompt: Prompt <tr>
delivery?: "immediate" | "deferred" <td class="operation"><code>fs.tree</code></td>
}</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>POST /api/session/:sessionID/prompt</code></td><td>Create a user message and queue the agent loop.</td></tr> <td class="body"><code>{ path: string }</code></td>
<tr><td class="operation"><code>session.todo</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>GET /api/session/:sessionID/todo</code></td><td>Return todos associated with the session.</td></tr> <td><span class="context-tag request">request</span></td>
<tr><td class="operation"><code>session.update</code></td><td class="body"><code>{ <td class="route"><code>GET /api/fs/tree</code></td>
sessionID: SessionID <td>Browse a directory.</td>
title?: string </tr>
archived?: number <tr>
permission?: PermissionRule[] <td class="operation"><code>lsp.status</code></td>
}</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>PATCH /api/session/:sessionID</code></td><td>Update title, archival state, or session metadata.</td></tr> <td class="body"><code>{}</code></td>
<tr><td class="operation"><code>session.wait</code></td><td class="body"><code>{ sessionID: SessionID }</code></td><td><span class="context-tag session">session</span></td><td class="route"><code>POST /api/session/:sessionID/wait</code></td><td>Wait until the session is idle.</td></tr> <td><span class="context-tag request">request</span></td>
<tr><td class="operation"><code>skill.list</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/skill</code></td><td>Available skills.</td></tr> <td class="route"><code>GET /api/lsp</code></td>
<tr><td class="operation"><code>vcs.diff</code></td><td class="body"><code>{ <td>LSP status.</td>
format?: "json" | "patch" </tr>
mode?: "worktree" | "default" <tr>
}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/vcs/diff</code></td><td>Diff for the runtime directory.</td></tr> <td class="operation"><code>mcp.prompt.list</code></td>
<tr><td class="operation"><code>vcs.get</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/vcs</code></td><td>VCS metadata.</td></tr> <td class="body"><code>{}</code></td>
<tr><td class="operation"><code>vcs.patch</code></td><td class="body"><code>{ patch: string }</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>POST /api/vcs/patch</code></td><td>Apply a patch to the runtime directory.</td></tr> <td><span class="context-tag request">request</span></td>
<tr><td class="operation"><code>vcs.status</code></td><td class="body"><code>{}</code></td><td><span class="context-tag request">request</span></td><td class="route"><code>GET /api/vcs/status</code></td><td>Changed files.</td></tr> <td class="route"><code>GET /api/mcp/prompt</code></td>
<tr><td class="operation"><code>workspace.create</code></td><td class="body"><code>{ <td>List MCP prompts.</td>
projectID?: ProjectID </tr>
name?: string <tr>
directory?: string <td class="operation"><code>mcp.prompt.render</code></td>
type: string <td class="body">
metadata?: Record&lt;string, unknown&gt; <code>{ server: string name: string arguments?: Record&lt;string, string&gt; }</code>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>POST /api/workspace</code></td><td>Create or register a workspace.</td></tr> </td>
<tr><td class="operation"><code>workspace.delete</code></td><td class="body"><code>{ workspaceID: WorkspaceID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>DELETE /api/workspace/:workspaceID</code></td><td>Remove a workspace registration.</td></tr> <td><span class="context-tag request">request</span></td>
<tr><td class="operation"><code>workspace.get</code></td><td class="body"><code>{ workspaceID: WorkspaceID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/workspace/:workspaceID</code></td><td>Get workspace metadata.</td></tr> <td class="route"><code>POST /api/mcp/prompt/render</code></td>
<tr><td class="operation"><code>workspace.list</code></td><td class="body"><code>{ projectID?: ProjectID }</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/workspace</code></td><td>List workspaces, optionally filtered by project.</td></tr> <td>Render one MCP prompt.</td>
<tr class="question-row"><td class="operation"><code>workspace.status</code></td><td class="body"><code>{}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>GET /api/workspace/status</code></td><td>Connection/lifecycle status for all workspaces. Needs team discussion.</td></tr> </tr>
<tr class="question-row"><td class="operation"><code>workspace.sync</code></td><td class="body"><code>{}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>POST /api/workspace/sync</code></td><td>Sync workspace metadata from adapters. Needs team discussion.</td></tr> <tr>
<tr><td class="operation"><code>workspace.update</code></td><td class="body"><code>{ <td class="operation"><code>mcp.resource.list</code></td>
workspaceID: WorkspaceID <td class="body"><code>{}</code></td>
name?: string <td><span class="context-tag request">request</span></td>
metadata?: Record&lt;string, unknown&gt; <td class="route"><code>GET /api/mcp/resource</code></td>
archived?: boolean <td>List MCP resources.</td>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>PATCH /api/workspace/:workspaceID</code></td><td>Update workspace metadata or lifecycle state.</td></tr> </tr>
<tr class="question-row"><td class="operation"><code>workspace.warp</code></td><td class="body"><code>{ <tr>
workspaceID?: WorkspaceID <td class="operation"><code>mcp.resource.read</code></td>
sessionID: SessionID <td class="body"><code>{ server: string uri: string }</code></td>
copyChanges: boolean <td><span class="context-tag request">request</span></td>
}</code></td><td><span class="context-tag server">server</span></td><td class="route"><code>POST /api/workspace/warp</code></td><td>Move a session into or out of a workspace. Needs team discussion.</td></tr> <td class="route"><code>GET /api/mcp/resource/read</code></td>
<td>Read one MCP resource.</td>
</tr>
<tr>
<td class="operation"><code>mcp.server.create</code></td>
<td class="body">
<code
>{ name: string config: | { type: "local", command: string, arguments?: string[], environment?:
Record&lt;string, string&gt; } | { type: "remote", url: string, headers?: Record&lt;string,
string&gt;, oauth?: boolean | object } }</code
>
</td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/mcp/server</code></td>
<td>Add an MCP server to runtime config.</td>
</tr>
<tr>
<td class="operation"><code>mcp.server.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/mcp/server</code></td>
<td>List MCP servers with status and auth state.</td>
</tr>
<tr>
<td class="operation"><code>mcp.server.oauth.callback</code></td>
<td class="body"><code>{ name: string code: string }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/mcp/server/:name/oauth/callback</code></td>
<td>Complete MCP OAuth.</td>
</tr>
<tr>
<td class="operation"><code>mcp.server.oauth.delete</code></td>
<td class="body"><code>{ name: string }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>DELETE /api/mcp/server/:name/oauth</code></td>
<td>Remove MCP OAuth credentials.</td>
</tr>
<tr>
<td class="operation"><code>mcp.server.oauth.start</code></td>
<td class="body"><code>{ name: string }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/mcp/server/:name/oauth</code></td>
<td>Start MCP OAuth.</td>
</tr>
<tr>
<td class="operation"><code>permission.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/permission</code></td>
<td>Pending permission requests.</td>
</tr>
<tr>
<td class="operation"><code>permission.reply</code></td>
<td class="body"><code>{ permissionID: PermissionID response: PermissionReply }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/permission/:permissionID/reply</code></td>
<td>Reply to a permission request.</td>
</tr>
<tr>
<td class="operation"><code>project.get</code></td>
<td class="body"><code>{ projectID: ProjectID }</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>GET /api/project/:projectID</code></td>
<td>Get project metadata.</td>
</tr>
<tr>
<td class="operation"><code>project.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>GET /api/project</code></td>
<td>List projects known to this server.</td>
</tr>
<tr>
<td class="operation"><code>project.update</code></td>
<td class="body">
<code
>{ projectID: ProjectID name?: string icon?: string commands?: Array&lt;{ name: string command:
string }&gt; }</code
>
</td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>PATCH /api/project/:projectID</code></td>
<td>Update project metadata.</td>
</tr>
<tr>
<td class="operation"><code>provider.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/provider</code></td>
<td>Provider inventory for the runtime context.</td>
</tr>
<tr>
<td class="operation"><code>pty.create</code></td>
<td class="body"><code>{ command?: string cwd?: string shell?: string }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/pty</code></td>
<td>Create PTY in the runtime context.</td>
</tr>
<tr>
<td class="operation"><code>pty.delete</code></td>
<td class="body"><code>{ ptyID: PtyID }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>DELETE /api/pty/:ptyID</code></td>
<td>Delete PTY.</td>
</tr>
<tr>
<td class="operation"><code>pty.get</code></td>
<td class="body"><code>{ ptyID: PtyID }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/pty/:ptyID</code></td>
<td>Get PTY info.</td>
</tr>
<tr>
<td class="operation"><code>pty.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/pty</code></td>
<td>List PTYs for the runtime.</td>
</tr>
<tr>
<td class="operation"><code>pty.update</code></td>
<td class="body">
<code>{ ptyID: PtyID title?: string size?: { columns: number, rows: number } }</code>
</td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>PATCH /api/pty/:ptyID</code></td>
<td>Update PTY.</td>
</tr>
<tr>
<td class="operation"><code>question.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/question</code></td>
<td>Pending user questions.</td>
</tr>
<tr>
<td class="operation"><code>question.reject</code></td>
<td class="body"><code>{ questionID: QuestionID }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/question/:questionID/reject</code></td>
<td>Reject a question.</td>
</tr>
<tr>
<td class="operation"><code>question.reply</code></td>
<td class="body"><code>{ questionID: QuestionID response: QuestionResponse }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/question/:questionID/reply</code></td>
<td>Reply to a question.</td>
</tr>
<tr>
<td class="operation"><code>session.compact</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>POST /api/session/:sessionID/compact</code></td>
<td>Compact the session conversation.</td>
</tr>
<tr>
<td class="operation"><code>session.context</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>GET /api/session/:sessionID/context</code></td>
<td>Return active context messages after the last compaction.</td>
</tr>
<tr>
<td class="operation"><code>session.create</code></td>
<td class="body">
<code
>{ title?: string agent?: string model?: { providerID: ProviderID, modelID: ModelID } permission?:
PermissionRule[] }</code
>
</td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/session</code></td>
<td>Create a session pinned to resolved runtime context.</td>
</tr>
<tr>
<td class="operation"><code>session.delete</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>DELETE /api/session/:sessionID</code></td>
<td>Delete a session.</td>
</tr>
<tr>
<td class="operation"><code>session.diff</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>GET /api/session/:sessionID/diff</code></td>
<td>Return session diff summary.</td>
</tr>
<tr>
<td class="operation"><code>session.get</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>GET /api/session/:sessionID</code></td>
<td>Get one session.</td>
</tr>
<tr>
<td class="operation"><code>session.list</code></td>
<td class="body">
<code
>{ limit?: number order?: "asc" | "desc" path?: string roots?: boolean start?: number search?:
string cursor?: string }</code
>
</td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/session</code></td>
<td>List sessions for the current runtime context by default.</td>
</tr>
<tr>
<td class="operation"><code>session.message.list</code></td>
<td class="body">
<code>{ sessionID: SessionID limit?: number order?: "asc" | "desc" cursor?: string }</code>
</td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>GET /api/session/:sessionID/message</code></td>
<td>Page through session messages.</td>
</tr>
<tr>
<td class="operation"><code>session.prompt</code></td>
<td class="body">
<code>{ sessionID: SessionID prompt: Prompt delivery?: "immediate" | "deferred" }</code>
</td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>POST /api/session/:sessionID/prompt</code></td>
<td>Create a user message and queue the agent loop.</td>
</tr>
<tr>
<td class="operation"><code>session.todo</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>GET /api/session/:sessionID/todo</code></td>
<td>Return todos associated with the session.</td>
</tr>
<tr>
<td class="operation"><code>session.update</code></td>
<td class="body">
<code>{ sessionID: SessionID title?: string archived?: number permission?: PermissionRule[] }</code>
</td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>PATCH /api/session/:sessionID</code></td>
<td>Update title, archival state, or session metadata.</td>
</tr>
<tr>
<td class="operation"><code>session.wait</code></td>
<td class="body"><code>{ sessionID: SessionID }</code></td>
<td><span class="context-tag session">session</span></td>
<td class="route"><code>POST /api/session/:sessionID/wait</code></td>
<td>Wait until the session is idle.</td>
</tr>
<tr>
<td class="operation"><code>skill.list</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/skill</code></td>
<td>Available skills.</td>
</tr>
<tr>
<td class="operation"><code>vcs.diff</code></td>
<td class="body"><code>{ format?: "json" | "patch" mode?: "worktree" | "default" }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/vcs/diff</code></td>
<td>Diff for the runtime directory.</td>
</tr>
<tr>
<td class="operation"><code>vcs.get</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/vcs</code></td>
<td>VCS metadata.</td>
</tr>
<tr>
<td class="operation"><code>vcs.patch</code></td>
<td class="body"><code>{ patch: string }</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>POST /api/vcs/patch</code></td>
<td>Apply a patch to the runtime directory.</td>
</tr>
<tr>
<td class="operation"><code>vcs.status</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag request">request</span></td>
<td class="route"><code>GET /api/vcs/status</code></td>
<td>Changed files.</td>
</tr>
<tr>
<td class="operation"><code>workspace.create</code></td>
<td class="body">
<code
>{ projectID?: ProjectID name?: string directory?: string type: string metadata?: Record&lt;string,
unknown&gt; }</code
>
</td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>POST /api/workspace</code></td>
<td>Create or register a workspace.</td>
</tr>
<tr>
<td class="operation"><code>workspace.delete</code></td>
<td class="body"><code>{ workspaceID: WorkspaceID }</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>DELETE /api/workspace/:workspaceID</code></td>
<td>Remove a workspace registration.</td>
</tr>
<tr>
<td class="operation"><code>workspace.get</code></td>
<td class="body"><code>{ workspaceID: WorkspaceID }</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>GET /api/workspace/:workspaceID</code></td>
<td>Get workspace metadata.</td>
</tr>
<tr>
<td class="operation"><code>workspace.list</code></td>
<td class="body"><code>{ projectID?: ProjectID }</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>GET /api/workspace</code></td>
<td>List workspaces, optionally filtered by project.</td>
</tr>
<tr class="question-row">
<td class="operation"><code>workspace.status</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>GET /api/workspace/status</code></td>
<td>Connection/lifecycle status for all workspaces. Needs team discussion.</td>
</tr>
<tr class="question-row">
<td class="operation"><code>workspace.sync</code></td>
<td class="body"><code>{}</code></td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>POST /api/workspace/sync</code></td>
<td>Sync workspace metadata from adapters. Needs team discussion.</td>
</tr>
<tr>
<td class="operation"><code>workspace.update</code></td>
<td class="body">
<code
>{ workspaceID: WorkspaceID name?: string metadata?: Record&lt;string, unknown&gt; archived?:
boolean }</code
>
</td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>PATCH /api/workspace/:workspaceID</code></td>
<td>Update workspace metadata or lifecycle state.</td>
</tr>
<tr class="question-row">
<td class="operation"><code>workspace.warp</code></td>
<td class="body">
<code>{ workspaceID?: WorkspaceID sessionID: SessionID copyChanges: boolean }</code>
</td>
<td><span class="context-tag server">server</span></td>
<td class="route"><code>POST /api/workspace/warp</code></td>
<td>Move a session into or out of a workspace. Needs team discussion.</td>
</tr>
</tbody> </tbody>
</table> </table>
</article> </article>
@@ -681,8 +1061,8 @@ sessionID -&gt; { directory, workspaceID? }</code></pre>
<article class="span-12 panel panel-pad stack"> <article class="span-12 panel panel-pad stack">
<h2>Event Envelope</h2> <h2>Event Envelope</h2>
<p class="muted"> <p class="muted">
Every event uses the same envelope. Resource identity belongs in <code>payload</code>. Runtime identity belongs Every event uses the same envelope. Resource identity belongs in <code>payload</code>. Runtime identity
in <code>context</code>. belongs in <code>context</code>.
</p> </p>
<div class="grid"> <div class="grid">
<pre class="span-6"><code>type ApiEvent&lt;Payload&gt; = { <pre class="span-6"><code>type ApiEvent&lt;Payload&gt; = {