开发服务器 HTTP

agent-bundle dev 在其 loopback 前台服务器上为 Workbench 挂载这些路由。它们是开发协议，不是公开部署端点。浏览器路由要求前台会话守卫，并强制执行安全中描述的 Workbench origin 策略。除非另有说明，游标都是非负安全整数，响应均为 JSON。

路由调用

方法	路径	响应
`POST`	`/api/routes/invocations`	`{ invocation: RouteInvocation }`；传入 `stream: true` 时返回 `202` 与 `{ invocation: RunningRouteInvocation }`
`GET`	`/api/routes/invocations?limit=<1..200>`	`{ invocations: RouteInvocationSummary[] }`，最新优先
`GET`	`/api/routes/invocations/<id>`	`{ invocation: RouteInvocation }`
`GET`	`/api/routes/invocations/<id>/stream`	服务器发送的 `render`、`trace`、`truncated` 与终止 `final` 事件
`POST`	`/api/routes/invocations/<id>/cancel`	`202` 与最终 `{ invocation: RouteInvocation }`

POST 正文是一份 RouteInvocationRequest：包含 routeId，以及可选的 input、args、 correlationId、调用方 requestId 与事件夹具选项。前台会把这两个标识回显到调用上，使路由工作区与 Trace 可以关联此次运行。完成后的信封包含输入、provenance 上下文、providers、渲染事件、Agent Document、结果、投影、诊断与计时。Trace 条目链接到这份完整快照，而不会复制它。渲染事件即渲染历史窗口（至多 256 条事件与 2 MiB，并始终保留最新一条事件与最新一条携带文档的事件，仅这两条本身可能超过 2 MiB），由信封、单项路由与流重放共享；一旦有事件被淘汰，信封会携带 retention（producedEvents、evictedEvents、evictedBytes 与 retainedBytes），流也会发送一次 truncated。Agent Document、结果与 outcome 永不被该窗口截断。取消后的调用带有 status: "cancelled" 且不含 outcome；取消已终止的调用会返回 AB8256（409）。

宿主会话

下表每条路由都要求前台会话 cookie 或 x-agent-bundle-session bearer 值。会话 id 匹配 hs_[0-9a-z]{16}，JSON 请求正文采用严格校验，输入最多为 16 KiB UTF-8 文本，终端尺寸必须是 1 到 500 的整数。

方法	路径	正文与响应
`GET`	`/api/sessions`	`{ sessions: HostSession[], hosts: HostAvailability[] }`
`POST`	`/api/sessions`	`{ host: "claude" \| "codex", prompt?: string, cols, rows }`；`201` 与 `{ session }`
`GET`	`/api/sessions/<id>`	`{ session }`
`GET`	`/api/sessions/<id>/stream`	服务器发送的 `state`、`output` 与终止 `end` 事件
`POST`	`/api/sessions/<id>/input`	`{ data: string }`；`204`
`POST`	`/api/sessions/<id>/resize`	`{ cols, rows }`；`204`
`POST`	`/api/sessions/<id>/terminate`	`{}`；`200` 与 `{ session }`
`POST`	`/api/sessions/<id>/restart`	`{ cols, rows }`；`201` 与替代会话 `{ session }`
`DELETE`	`/api/sessions/<id>`	`204`；不能遗忘仍在运行的会话

HostSession 报告 id、host、state、startedAt、可选的终止字段 endedAt、exitCode、 signal、pid、cols、rows、可选的初始 prompt，以及可选的 restartOf 与 traceSessionId。其 authority 包含绝对 projectRoot、已采用的 epochId 与宿主插件 install 目的地。HostAvailability 包含 host、launchable，以及可选的 reason 与已解析 executable。

流以一条 state 帧开始，以一帧重放最多 256 KiB 的保留输出，再继续发送实时 state 与 output。它每 15 秒发送一条 keep-alive 注释，并在 end 后关闭。每个事件带有一个 JSON data: 对象：

event: state
data: { "session": HostSession }

event: output
data: { "data": "<base64 PTY bytes>" }

event: end
data: { "session": HostSession }

宿主会话失败使用以下诊断：

代码	含义
`AB8260`	项目与框架后备位置均无法提供 `@lydell/node-pty`。
`AB8261`	正文、路径、查询、尺寸、输入、方法状态或删除活动会话的请求格式错误。
`AB8262`	会话 id 格式正确但未知。
`AB8263`	`PATH` 中没有可执行文件、已采用 epoch 没有附加开发安装，或生成进程失败。
`AB8264`	已有四个活动会话。
`AB8265`	宿主会话服务已关闭或不可用。
`AB8266`	钩子收据或代理请求提供了无效的 `AGENT_BUNDLE_DEV_SESSION` 值。

开发运行时运行

POST /api/runtime/runs 接受一份 DevRuntimeInvocationRequest，其中包含 surfaceId、target、 input，以及可选的 fixtureId 与 expectedGenerationId。GET /api/runtime/runs 列出最近的运行， GET /api/runtime/runs/<id> 读取一次运行。

MCP 操作与关联

GET /api/mcp/launches?epochId=<epoch>&serverName=<server> 列出某服务器在已发布 epoch 上可用的 App 启动方式：共享同一启动身份的 { launchId, targets } 分组，从产物声明的 projection 解析并参考已安装的宿主。 Workbench 的 App 工作区从该列表中选择，而不是从构建的全局 target 中选择。

POST /api/mcp/sessions/<session-id>/apps 接受只有 input 而没有 result 的请求，为仍在进行中的调用挂载预览；此时 App 只收到 ui/notifications/tool-input。POST /api/mcp/apps/<binding-id>/result 携带 { result } 或 { cancelled } 发布该绑定唯一的终态通知（tool-result 或 tool-cancelled）；对已结算或创建时已带结果的绑定应答 accepted: false，绑定关闭后应答 404（AB8022）。

POST /api/mcp/sessions/<session-id>/operations 保留现有操作联合类型。tools/call 操作额外接受一个最多 256 个字符的可选顶层 correlationId。浏览器不能直接提供 _meta；前台在发送请求前会把该值复制到 params._meta["agent-bundle/correlationId"]。

MCP Trace 会提取 JSON-RPC id 与方法，以及有界的宿主元数据。请求/响应对共享 mcpRequestId 与耗时；工具调用和 prompt 读取会通过 ?session=<session-id> 链接到其 Application 路由。无法解析到路由的操作会链接到 /advanced/protocol?session=<session-id>。

统一 Trace

方法	路径	传输
`GET`	`/api/trace?after=<sequence>`	`TraceReplay` JSON
`GET`	`/api/trace/stream?after=<sequence>`	`TraceMessage` 的 `application/x-ndjson` 帧

省略 after 等同于 after=0。重放形状如下：

interface TraceReplay {
  readonly entries: readonly TraceEntry[];
  readonly gap?: TraceReplayGap;
  readonly latestSequence: number;
}

每个 TraceEntry 包含：

interface TraceEntry {
  readonly id: string;
  readonly sequence: number;
  readonly occurredAt: string;
  readonly source:
    | 'invocation'
    | 'kernel'
    | 'mcp'
    | 'hook'
    | 'session'
    | 'log'
    | 'diagnostic';
  readonly kind: string;
  readonly summary: string;
  readonly correlation: TraceCorrelation;
  readonly status?: 'ok' | 'error' | 'running';
  readonly durationMs?: number;
  readonly details?: JsonValue;
  readonly href?: string;
}

TraceCorrelation 可以携带 correlationId、conversationId、epochId、executionId、host、 invocationId、mcpRequestId、mcpSessionId、requestId、routeId 与 sessionId。生产者只填充自己已知的键。details 是有界且已确保安全的 JSON 投影，不是载荷正文。

当请求的游标早于保留的历史时，重放会返回一个 gap，流也会把同一份 TraceReplayGap 作为一个 NDJSON 帧发出：

interface TraceReplayGap {
  readonly droppedCount: number;
  readonly firstAvailableSequence: number;
  readonly requestedAfterSequence: number;
  readonly type: 'trace.gap';
}

格式错误的游标返回 400，超前于当前历史的游标返回 409，已关闭或不可用的 Trace hub 返回 503。这些响应使用生成式诊断参考中登记的 Trace 诊断。

Raw logs

方法	路径	传输
`GET`	`/api/logs/replay?after=<sequence>`	`{ replay: DevLogReplay }` JSON
`GET`	`/api/logs/stream?after=<sequence>`	`DevLogMessage` 的 `application/x-ndjson` 帧

Raw logs 仍是框架诊断流。记录只暴露白名单中的上下文值与浏览器安全文本。带有 correlationId、 invocationId 或 mcpSessionId 的记录可以链接到 /trace?correlation=<value>；未关联的记录仍留在 Advanced → Raw logs。

宿主钩子收据

方法	路径	传输
`POST`	`/api/trace/receipts`	一份最多 16 KiB 的 `EventTraceReceipt` JSON 正文；成功返回 `204`

生成式钩子进程会向这个仅限前台的路由提交一份有界收据。它不是浏览器 API：会拒绝 Origin 标头与非 loopback 对端，要求收据端点在每次开发服务器运行时随机生成的 bearer token，并且不暴露读取或命令操作。 Workbench cookie 与会话标头不能授权它。收据包含版本 1、一份 EventTraceExecution、不含载荷的内核事件及其挂钟开始时间、宿主/会话/请求标识和解析后的 lineage 轴。原生事件正文、工具输入或输出、渲染文档、环境值、凭据、文件系统路径与错误堆栈均不存在。

对于宿主调用，包装器会在已安装捆绑包旁查找 .agent-bundle-dev.json，再从其中所指项目的 .agent-bundle/hook-receipts.json 读取当前端点。由开发服务器生成的模拟调用通过两个内部收据环境变量取得相同的 loopback URL 与 token。端点文件会以仅所有者可读模式替换，并在服务器关闭时移除。只接受精确的 http://127.0.0.1:<port> 或 http://[::1]:<port> origin。包装器为提交保留 750 ms，并忽略传输失败，因此 Workbench 观察绝不会改变钩子结果。

收据与内核条目在时间线中的呈现方式见 Trace。

#开发服务器 HTTP

#路由调用

#宿主会话

#开发运行时运行

#MCP 操作与关联

#统一 Trace

#Raw logs

#宿主钩子收据