@zooid/transport-http 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+import { AcpRegistry, ApprovalCorrelator, TransportContextProvider } from '@zooid/core';
+
+interface CreateAppOptions {
+    /** Long-lived registry that fronts every ACP agent. */
+    agents: AcpRegistry;
+    /**
+     * Correlator that pairs ACP `requestPermission` calls with HTTP-side
+     * decisions. The transport listens to its `'registered'` and `'timeout'`
+     * events to drive the SSE wire and resolves it via the POST decision route.
+     */
+    approvals: ApprovalCorrelator;
+    /** Bearer token; constant-time compared against `Authorization`. */
+    token: string;
+    /**
+     * Keepalive interval for open SSE streams (proxies kill idle connections).
+     * 0 disables. Default: 30_000ms.
+     */
+    keepaliveMs?: number;
+}
+declare function createApp({ agents, approvals, token, keepaliveMs, }: CreateAppOptions): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+
+/**
+ * HTTP transport owns no durable conversation context in MVP. Returning null
+ * tells the daemon to omit `zooid-context` from `session/new mcpServers` so
+ * the shim never surfaces tools that would return nothing. See [ZOD046] for
+ * the follow-on that would change this.
+ */
+declare function getContextProvider(): TransportContextProvider | null;
+
+export { type CreateAppOptions, createApp, getContextProvider };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/server.ts
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { timingSafeEqual, randomUUID } from "crypto";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function isAuthorized(token, header) {
+  if (!header || !header.startsWith("Bearer ")) return false;
+  const provided = header.slice("Bearer ".length);
+  if (provided.length !== token.length) return false;
+  return timingSafeEqual(Buffer.from(provided), Buffer.from(token));
+}
+function parsePromptBody(raw) {
+  if (!raw || typeof raw !== "object") return { error: "body must be a JSON object" };
+  const obj = raw;
+  if (typeof obj.prompt !== "string" || obj.prompt.length === 0) {
+    return { error: "missing or empty prompt" };
+  }
+  return { prompt: obj.prompt };
+}
+async function readJson(c) {
+  const raw = await c.req.text();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { error: "body must be valid JSON" };
+  }
+}
+function parseDecisionBody(raw) {
+  if (!raw || typeof raw !== "object") return { error: "body must be a JSON object" };
+  const obj = raw;
+  if (obj.decision !== "allow" && obj.decision !== "cancel") {
+    return { error: 'decision must be "allow" or "cancel"' };
+  }
+  if (obj.decision === "allow" && typeof obj.option_id !== "string") {
+    return { error: 'option_id is required when decision is "allow"' };
+  }
+  return {
+    decision: obj.decision,
+    option_id: typeof obj.option_id === "string" ? obj.option_id : void 0
+  };
+}
+function approvalRequestFrame(handle) {
+  return JSON.stringify({
+    type: "approval.request",
+    approval_id: handle.approvalId,
+    session_id: handle.sessionId,
+    tool_call_id: handle.toolCallId,
+    options: handle.options
+  });
+}
+function createApp({
+  agents,
+  approvals,
+  token,
+  keepaliveMs = 3e4
+}) {
+  const app = new Hono();
+  const streams = /* @__PURE__ */ new Map();
+  agents.onEvent = (_name, event) => {
+    const stream = streams.get(event.sessionId);
+    if (!stream) return;
+    void stream.writeSSE({ data: JSON.stringify(event) });
+  };
+  agents.onApprovalRequest = async (name, req) => {
+    const handle = approvals.register(name, req.sessionId, req, {
+      timeoutMs: agents.getApprovalTimeoutMs(name)
+    });
+    return handle.decisionPromise;
+  };
+  approvals.on("registered", (handle) => {
+    const stream = streams.get(handle.sessionId);
+    if (!stream) return;
+    void stream.writeSSE({ data: approvalRequestFrame(handle) });
+  });
+  approvals.on("timeout", ({ approvalId, sessionId }) => {
+    const stream = streams.get(sessionId);
+    if (!stream) return;
+    void stream.writeSSE({
+      data: JSON.stringify({ type: "approval.timeout", approval_id: approvalId, session_id: sessionId })
+    });
+  });
+  function checkAgent(c, name) {
+    if (!agents.hasAgent(name)) {
+      return c.json({ error: "unknown agent" }, 404);
+    }
+    return null;
+  }
+  function attachKeepalive(sse) {
+    if (!keepaliveMs || keepaliveMs <= 0) return null;
+    const timer = setInterval(() => {
+      void sse.writeSSE({ data: "", event: "keepalive" }).catch(() => {
+      });
+    }, keepaliveMs);
+    timer.unref?.();
+    return timer;
+  }
+  app.post("/agents/:name/sessions", async (c) => {
+    if (!isAuthorized(token, c.req.header("authorization"))) {
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    const name = c.req.param("name");
+    const reject = checkAgent(c, name);
+    if (reject) return reject;
+    const parsed = await readJson(c);
+    if (parsed && typeof parsed === "object" && "error" in parsed) {
+      return c.json({ error: parsed.error }, 400);
+    }
+    const body = parsePromptBody(parsed);
+    if ("error" in body) return c.json({ error: body.error }, 400);
+    const threadId = randomUUID();
+    return streamSSE(c, async (sse) => {
+      let sessionId = null;
+      let keepalive = null;
+      try {
+        sessionId = await agents.ensureSession(name, threadId);
+        streams.set(sessionId, sse);
+        keepalive = attachKeepalive(sse);
+        await sse.writeSSE({
+          data: JSON.stringify({ type: "session.start", session_id: sessionId })
+        });
+        await sse.writeSSE({ data: JSON.stringify({ type: "turn.start" }) });
+        const result = await agents.prompt(name, {
+          threadId,
+          content: [{ type: "text", text: body.prompt }]
+        });
+        await sse.writeSSE({
+          data: JSON.stringify({ type: "turn.end", stop_reason: result.stopReason })
+        });
+      } catch (err) {
+        await sse.writeSSE({
+          data: JSON.stringify({
+            type: "turn.end",
+            stop_reason: "error",
+            error: err.message
+          })
+        });
+      } finally {
+        if (keepalive) clearInterval(keepalive);
+        if (sessionId) {
+          approvals.cancelSession(sessionId);
+          if (streams.get(sessionId) === sse) {
+            streams.delete(sessionId);
+          }
+        }
+      }
+    });
+  });
+  app.get("/agents/:name/sessions/:id/events", async (c) => {
+    if (!isAuthorized(token, c.req.header("authorization"))) {
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    const name = c.req.param("name");
+    const reject = checkAgent(c, name);
+    if (reject) return reject;
+    const id = c.req.param("id");
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: "session id must be a UUID" }, 400);
+    }
+    if (!streams.has(id)) {
+      return c.json({ error: "no in-flight session" }, 404);
+    }
+    return streamSSE(c, async (sse) => {
+      streams.set(id, sse);
+      const keepalive = attachKeepalive(sse);
+      for (const handle of approvals.listPending(id)) {
+        await sse.writeSSE({ data: approvalRequestFrame(handle) });
+      }
+      try {
+        while (streams.get(id) === sse) {
+          await new Promise((r) => setTimeout(r, 250));
+        }
+      } finally {
+        if (keepalive) clearInterval(keepalive);
+      }
+    });
+  });
+  app.post("/agents/:name/sessions/:sid/approvals/:approval_id", async (c) => {
+    if (!isAuthorized(token, c.req.header("authorization"))) {
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    const name = c.req.param("name");
+    const reject = checkAgent(c, name);
+    if (reject) return reject;
+    const sid = c.req.param("sid");
+    const approvalId = c.req.param("approval_id");
+    const parsed = await readJson(c);
+    if (parsed && typeof parsed === "object" && "error" in parsed) {
+      return c.json({ error: parsed.error }, 400);
+    }
+    const body = parseDecisionBody(parsed);
+    if ("error" in body) return c.json({ error: body.error }, 400);
+    const decision = body.decision === "cancel" ? { decision: "cancel" } : { decision: "allow", optionId: body.option_id };
+    const ok = approvals.resolve(sid, approvalId, decision);
+    if (!ok) return c.json({ error: "unknown approval" }, 404);
+    return c.json({ ok: true });
+  });
+  app.post("/agents/:name/sessions/:sid/cancel", async (c) => {
+    if (!isAuthorized(token, c.req.header("authorization"))) {
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    const name = c.req.param("name");
+    const reject = checkAgent(c, name);
+    if (reject) return reject;
+    const sid = c.req.param("sid");
+    approvals.cancelSession(sid);
+    return c.body(null, 204);
+  });
+  return app;
+}
+
+// src/context.ts
+function getContextProvider() {
+  return null;
+}
+export {
+  createApp,
+  getContextProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts","../src/context.ts"],"sourcesContent":["import { Hono, type Context } from 'hono'\nimport { streamSSE, type SSEStreamingApi } from 'hono/streaming'\nimport { timingSafeEqual, randomUUID } from 'node:crypto'\nimport type {\n  AcpRegistry,\n  ApprovalCorrelator,\n  RegisteredApproval,\n} from '@zooid/core'\nimport type {\n  AgentEvent,\n  ApprovalDecision,\n} from '@zooid/acp-client'\n\nexport interface CreateAppOptions {\n  /** Long-lived registry that fronts every ACP agent. */\n  agents: AcpRegistry\n  /**\n   * Correlator that pairs ACP `requestPermission` calls with HTTP-side\n   * decisions. The transport listens to its `'registered'` and `'timeout'`\n   * events to drive the SSE wire and resolves it via the POST decision route.\n   */\n  approvals: ApprovalCorrelator\n  /** Bearer token; constant-time compared against `Authorization`. */\n  token: string\n  /**\n   * Keepalive interval for open SSE streams (proxies kill idle connections).\n   * 0 disables. Default: 30_000ms.\n   */\n  keepaliveMs?: number\n}\n\nconst UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/\n\ninterface PromptBody {\n  prompt: string\n}\n\nfunction isAuthorized(token: string, header: string | undefined): boolean {\n  if (!header || !header.startsWith('Bearer ')) return false\n  const provided = header.slice('Bearer '.length)\n  if (provided.length !== token.length) return false\n  return timingSafeEqual(Buffer.from(provided), Buffer.from(token))\n}\n\nfunction parsePromptBody(raw: unknown): PromptBody | { error: string } {\n  if (!raw || typeof raw !== 'object') return { error: 'body must be a JSON object' }\n  const obj = raw as Record<string, unknown>\n  if (typeof obj.prompt !== 'string' || obj.prompt.length === 0) {\n    return { error: 'missing or empty prompt' }\n  }\n  return { prompt: obj.prompt }\n}\n\nasync function readJson(c: Context): Promise<unknown | { error: string }> {\n  const raw = await c.req.text()\n  try {\n    return JSON.parse(raw)\n  } catch {\n    return { error: 'body must be valid JSON' }\n  }\n}\n\ninterface DecisionBody {\n  decision: 'allow' | 'cancel'\n  option_id?: string\n}\n\nfunction parseDecisionBody(raw: unknown): DecisionBody | { error: string } {\n  if (!raw || typeof raw !== 'object') return { error: 'body must be a JSON object' }\n  const obj = raw as Record<string, unknown>\n  if (obj.decision !== 'allow' && obj.decision !== 'cancel') {\n    return { error: 'decision must be \"allow\" or \"cancel\"' }\n  }\n  if (obj.decision === 'allow' && typeof obj.option_id !== 'string') {\n    return { error: 'option_id is required when decision is \"allow\"' }\n  }\n  return {\n    decision: obj.decision,\n    option_id: typeof obj.option_id === 'string' ? obj.option_id : undefined,\n  }\n}\n\nfunction approvalRequestFrame(handle: RegisteredApproval): string {\n  return JSON.stringify({\n    type: 'approval.request',\n    approval_id: handle.approvalId,\n    session_id: handle.sessionId,\n    tool_call_id: handle.toolCallId,\n    options: handle.options,\n  })\n}\n\nexport function createApp({\n  agents,\n  approvals,\n  token,\n  keepaliveMs = 30_000,\n}: CreateAppOptions) {\n  const app = new Hono()\n\n  // Per-session SSE handle. The registry's onEvent dispatcher and the\n  // correlator's `'registered'` / `'timeout'` listeners look up the\n  // currently-attached stream by session id.\n  const streams = new Map<string, SSEStreamingApi>()\n\n  agents.onEvent = (_name, event: AgentEvent) => {\n    const stream = streams.get(event.sessionId)\n    if (!stream) return\n    void stream.writeSSE({ data: JSON.stringify(event) })\n  }\n  // Always wire the registry's approval handler to the correlator. The\n  // per-agent `approval_timeout_ms` is read off the registry so YAML-driven\n  // timeouts still apply.\n  agents.onApprovalRequest = async (name, req) => {\n    const handle = approvals.register(name, req.sessionId, req, {\n      timeoutMs: agents.getApprovalTimeoutMs(name),\n    })\n    return handle.decisionPromise\n  }\n\n  approvals.on('registered', (handle: RegisteredApproval) => {\n    const stream = streams.get(handle.sessionId)\n    if (!stream) return\n    void stream.writeSSE({ data: approvalRequestFrame(handle) })\n  })\n\n  approvals.on('timeout', ({ approvalId, sessionId }: { approvalId: string; sessionId: string }) => {\n    const stream = streams.get(sessionId)\n    if (!stream) return\n    void stream.writeSSE({\n      data: JSON.stringify({ type: 'approval.timeout', approval_id: approvalId, session_id: sessionId }),\n    })\n  })\n\n  function checkAgent(c: Context, name: string): Response | null {\n    if (!agents.hasAgent(name)) {\n      return c.json({ error: 'unknown agent' }, 404)\n    }\n    return null\n  }\n\n  function attachKeepalive(sse: SSEStreamingApi): NodeJS.Timeout | null {\n    if (!keepaliveMs || keepaliveMs <= 0) return null\n    const timer = setInterval(() => {\n      void sse.writeSSE({ data: '', event: 'keepalive' }).catch(() => {})\n    }, keepaliveMs)\n    timer.unref?.()\n    return timer\n  }\n\n  /**\n   * POST /agents/:name/sessions — start a new ACP session.\n   *\n   *   { session.start, session_id }\n   *   { turn.start }\n   *   ... ACP AgentEvents\n   *   { approval.request, ... } / { approval.timeout, ... } as they arrive\n   *   { turn.end, stop_reason }\n   */\n  app.post('/agents/:name/sessions', async (c) => {\n    if (!isAuthorized(token, c.req.header('authorization'))) {\n      return c.json({ error: 'unauthorized' }, 401)\n    }\n    const name = c.req.param('name')\n    const reject = checkAgent(c, name)\n    if (reject) return reject\n\n    const parsed = await readJson(c)\n    if (parsed && typeof parsed === 'object' && 'error' in parsed) {\n      return c.json({ error: (parsed as { error: string }).error }, 400)\n    }\n    const body = parsePromptBody(parsed)\n    if ('error' in body) return c.json({ error: body.error }, 400)\n\n    const threadId = randomUUID()\n    return streamSSE(c, async (sse) => {\n      let sessionId: string | null = null\n      let keepalive: NodeJS.Timeout | null = null\n      try {\n        sessionId = await agents.ensureSession(name, threadId)\n        streams.set(sessionId, sse)\n        keepalive = attachKeepalive(sse)\n        await sse.writeSSE({\n          data: JSON.stringify({ type: 'session.start', session_id: sessionId }),\n        })\n        await sse.writeSSE({ data: JSON.stringify({ type: 'turn.start' }) })\n        const result = await agents.prompt(name, {\n          threadId,\n          content: [{ type: 'text', text: body.prompt }],\n        })\n        await sse.writeSSE({\n          data: JSON.stringify({ type: 'turn.end', stop_reason: result.stopReason }),\n        })\n      } catch (err) {\n        await sse.writeSSE({\n          data: JSON.stringify({\n            type: 'turn.end',\n            stop_reason: 'error',\n            error: (err as Error).message,\n          }),\n        })\n      } finally {\n        if (keepalive) clearInterval(keepalive)\n        if (sessionId) {\n          // The turn is over; cancel any approvals that the shim left\n          // dangling so future POSTs against them 404 fast.\n          approvals.cancelSession(sessionId)\n          if (streams.get(sessionId) === sse) {\n            streams.delete(sessionId)\n          }\n        }\n      }\n    })\n  })\n\n  /**\n   * GET /agents/:name/sessions/:id/events — reattach to an in-flight stream.\n   *\n   * When a turn is in flight: replays any pending approvals via\n   * `approvals.listPending(sid)`, then forwards live events until the turn\n   * ends. When no turn is in flight: 404.\n   */\n  app.get('/agents/:name/sessions/:id/events', async (c) => {\n    if (!isAuthorized(token, c.req.header('authorization'))) {\n      return c.json({ error: 'unauthorized' }, 401)\n    }\n    const name = c.req.param('name')\n    const reject = checkAgent(c, name)\n    if (reject) return reject\n    const id = c.req.param('id')\n    if (!UUID_RE.test(id)) {\n      return c.json({ error: 'session id must be a UUID' }, 400)\n    }\n    if (!streams.has(id)) {\n      return c.json({ error: 'no in-flight session' }, 404)\n    }\n    return streamSSE(c, async (sse) => {\n      // Take ownership of dispatch for this session id.\n      streams.set(id, sse)\n      const keepalive = attachKeepalive(sse)\n      // Replay any approvals that are still pending so the reconnecting\n      // client can decide on them.\n      for (const handle of approvals.listPending(id)) {\n        await sse.writeSSE({ data: approvalRequestFrame(handle) })\n      }\n      try {\n        while (streams.get(id) === sse) {\n          await new Promise((r) => setTimeout(r, 250))\n        }\n      } finally {\n        if (keepalive) clearInterval(keepalive)\n      }\n    })\n  })\n\n  /**\n   * POST /agents/:name/sessions/:sid/approvals/:approval_id — resolve a\n   * pending permission request.\n   */\n  app.post('/agents/:name/sessions/:sid/approvals/:approval_id', async (c) => {\n    if (!isAuthorized(token, c.req.header('authorization'))) {\n      return c.json({ error: 'unauthorized' }, 401)\n    }\n    const name = c.req.param('name')\n    const reject = checkAgent(c, name)\n    if (reject) return reject\n\n    const sid = c.req.param('sid')\n    const approvalId = c.req.param('approval_id')\n    const parsed = await readJson(c)\n    if (parsed && typeof parsed === 'object' && 'error' in parsed) {\n      return c.json({ error: (parsed as { error: string }).error }, 400)\n    }\n    const body = parseDecisionBody(parsed)\n    if ('error' in body) return c.json({ error: body.error }, 400)\n\n    const decision: ApprovalDecision =\n      body.decision === 'cancel'\n        ? { decision: 'cancel' }\n        : { decision: 'allow', optionId: body.option_id! }\n    const ok = approvals.resolve(sid, approvalId, decision)\n    if (!ok) return c.json({ error: 'unknown approval' }, 404)\n    return c.json({ ok: true })\n  })\n\n  /**\n   * POST /agents/:name/sessions/:sid/cancel — cancel every pending approval\n   * for the session. Idempotent. Returns 204.\n   */\n  app.post('/agents/:name/sessions/:sid/cancel', async (c) => {\n    if (!isAuthorized(token, c.req.header('authorization'))) {\n      return c.json({ error: 'unauthorized' }, 401)\n    }\n    const name = c.req.param('name')\n    const reject = checkAgent(c, name)\n    if (reject) return reject\n    const sid = c.req.param('sid')\n    approvals.cancelSession(sid)\n    return c.body(null, 204)\n  })\n\n  return app\n}\n","import type { TransportContextProvider } from '@zooid/core'\n\n/**\n * HTTP transport owns no durable conversation context in MVP. Returning null\n * tells the daemon to omit `zooid-context` from `session/new mcpServers` so\n * the shim never surfaces tools that would return nothing. See [ZOD046] for\n * the follow-on that would change this.\n */\nexport function getContextProvider(): TransportContextProvider | null {\n  return null\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@zooid/transport-http",
+  "version": "0.7.0",
+  "description": "HTTP transport for zooid. POST /sessions to start a session, POST /sessions/:id/turns to resume, GET /sessions/:id/events to tail. Bearer-auth, SSE responses.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "hono": "^4.6.0",
+    "@zooid/acp-client": "^0.7.0",
+    "@zooid/core": "^0.7.0"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0",
+    "@zooid/runtime-local": "^0.7.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/context.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest'
+import { getContextProvider } from './context.js'
+
+describe('transport-http context surface', () => {
+  it('returns null — HTTP has no durable conversation context in MVP (see ZOD046)', () => {
+    expect(getContextProvider()).toBeNull()
+  })
+})

package/src/context.ts

@@ -0,0 +1,11 @@
+import type { TransportContextProvider } from '@zooid/core'
+
+/**
+ * HTTP transport owns no durable conversation context in MVP. Returning null
+ * tells the daemon to omit `zooid-context` from `session/new mcpServers` so
+ * the shim never surfaces tools that would return nothing. See [ZOD046] for
+ * the follow-on that would change this.
+ */
+export function getContextProvider(): TransportContextProvider | null {
+  return null
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createApp } from './server.js'
+export type { CreateAppOptions } from './server.js'
+export { getContextProvider } from './context.js'

package/src/server.test.ts

@@ -0,0 +1,421 @@
+import { describe, it, expect, vi } from 'vitest'
+import type {
+  AcpRegistry,
+  AcpRegistryEventHandler,
+  AcpRegistryApprovalHandler,
+} from '@zooid/core'
+import { ApprovalCorrelator } from '@zooid/core'
+import type {
+  AgentEvent,
+  ApprovalRequest,
+  PromptInput,
+  PromptResult,
+} from '@zooid/acp-client'
+import { createApp } from './server.js'
+
+const TOKEN = 'test-token-0123456789abcdef'
+const SID = '11111111-2222-3333-4444-555555555555'
+
+interface FakeRegistryOptions {
+  agents?: string[]
+  events?: AgentEvent[]
+  stopReason?: PromptResult['stopReason']
+  sessionId?: string
+  ensureSession?: (name: string, threadId: string) => Promise<string>
+  prompt?: (name: string, input: PromptInput) => Promise<PromptResult>
+}
+
+function makeRegistry(opts: FakeRegistryOptions = {}): AcpRegistry {
+  const known = new Set(opts.agents ?? ['triage'])
+  const events = opts.events ?? []
+  let onEvent: AcpRegistryEventHandler = () => {}
+  let onApprovalRequest: AcpRegistryApprovalHandler = async () => ({ decision: 'cancel' })
+
+  const reg: AcpRegistry = {
+    hasAgent: (n) => known.has(n),
+    getApprovalTimeoutMs: () => 0,
+    ensureSession:
+      opts.ensureSession ??
+      vi.fn(async () => opts.sessionId ?? SID),
+    endSession: vi.fn(),
+    prompt:
+      opts.prompt ??
+      vi.fn(async (name) => {
+        for (const e of events) onEvent(name, e)
+        return { stopReason: opts.stopReason ?? 'end_turn' }
+      }),
+    stopAll: vi.fn(async () => {}),
+    get onEvent() {
+      return onEvent
+    },
+    set onEvent(h) {
+      onEvent = h
+    },
+    get onApprovalRequest() {
+      return onApprovalRequest
+    },
+    set onApprovalRequest(h) {
+      onApprovalRequest = h
+    },
+  }
+  return reg
+}
+
+function parseFrames(text: string): unknown[] {
+  return text
+    .split('\n\n')
+    .filter((f) => f.startsWith('data: '))
+    .map((f) => JSON.parse(f.slice('data: '.length)))
+}
+
+async function postJson(
+  app: ReturnType<typeof createApp>,
+  path: string,
+  body: object,
+  authOverride?: string | null,
+) {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (authOverride !== null) {
+    headers.authorization = authOverride ?? `Bearer ${TOKEN}`
+  }
+  return app.request(path, { method: 'POST', headers, body: JSON.stringify(body) })
+}
+
+function newApprovals(): ApprovalCorrelator {
+  return new ApprovalCorrelator()
+}
+
+// ─── auth ────────────────────────────────────────────────────────────────
+
+describe('auth', () => {
+  it('401 when Authorization header missing', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, '/agents/triage/sessions', { prompt: 'hi' }, null)
+    expect(res.status).toBe(401)
+  })
+
+  it('401 when token is wrong', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(
+      app,
+      '/agents/triage/sessions',
+      { prompt: 'hi' },
+      'Bearer wrong-token-of-different-length-xx',
+    )
+    expect(res.status).toBe(401)
+  })
+
+  it('401 with non-Bearer scheme', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(
+      app,
+      '/agents/triage/sessions',
+      { prompt: 'hi' },
+      `Basic ${TOKEN}`,
+    )
+    expect(res.status).toBe(401)
+  })
+
+  it('401 with same-length wrong token (constant-time guard)', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const wrong = 'X'.repeat(TOKEN.length)
+    const res = await postJson(
+      app,
+      '/agents/triage/sessions',
+      { prompt: 'hi' },
+      `Bearer ${wrong}`,
+    )
+    expect(res.status).toBe(401)
+  })
+})
+
+// ─── POST /agents/:name/sessions ─────────────────────────────────────────
+
+describe('POST /agents/:name/sessions', () => {
+  it('404 unknown agent', async () => {
+    const app = createApp({ agents: makeRegistry({ agents: ['triage'] }), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, '/agents/nobody/sessions', { prompt: 'hi' })
+    expect(res.status).toBe(404)
+    expect(await res.json()).toMatchObject({ error: expect.stringMatching(/unknown/i) })
+  })
+
+  it('400 missing prompt', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, '/agents/triage/sessions', {})
+    expect(res.status).toBe(400)
+  })
+
+  it('400 non-JSON body', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await app.request('/agents/triage/sessions', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${TOKEN}` },
+      body: 'not-json',
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('happy path: SSE stream — session.start → turn.start → ACP events → turn.end', async () => {
+    const events: AgentEvent[] = [
+      { type: 'agent_message_chunk', sessionId: SID, content: { type: 'text', text: 'hi' } },
+      { type: 'plan', sessionId: SID, entries: [] },
+    ]
+    const app = createApp({
+      agents: makeRegistry({ events, stopReason: 'end_turn' }),
+      approvals: newApprovals(),
+      token: TOKEN,
+    })
+    const res = await postJson(app, '/agents/triage/sessions', { prompt: 'hi' })
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toContain('text/event-stream')
+    const frames = parseFrames(await res.text()) as Array<Record<string, unknown>>
+    expect(frames[0]).toEqual({ type: 'session.start', session_id: SID })
+    expect(frames[1]).toEqual({ type: 'turn.start' })
+    expect(frames.slice(2, -1).map((f) => f.type)).toEqual(['agent_message_chunk', 'plan'])
+    const last = frames[frames.length - 1]
+    expect(last.type).toBe('turn.end')
+    expect(last.stop_reason).toBe('end_turn')
+  })
+
+  it('calls registry.prompt(name, { threadId, content }) with a server-generated threadId', async () => {
+    const promptMock = vi.fn(async () => ({ stopReason: 'end_turn' as const }))
+    const app = createApp({
+      agents: makeRegistry({ prompt: promptMock }),
+      approvals: newApprovals(),
+      token: TOKEN,
+    })
+    const res = await postJson(app, '/agents/triage/sessions', { prompt: 'hello' })
+    await res.text()
+    expect(promptMock).toHaveBeenCalledTimes(1)
+    const [name, input] = promptMock.mock.calls[0]
+    expect(name).toBe('triage')
+    expect(input.threadId).toMatch(/^[0-9a-f-]{8,}$/)
+    expect(Array.isArray(input.content)).toBe(true)
+    expect(input.content[0]).toMatchObject({ type: 'text', text: 'hello' })
+  })
+})
+
+// ─── GET /agents/:name/sessions/:id/events ───────────────────────────────
+
+describe('GET /agents/:name/sessions/:id/events', () => {
+  it('404 when no turn is currently in flight for that session id', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await app.request(`/agents/triage/sessions/${SID}/events`, {
+      headers: { authorization: `Bearer ${TOKEN}` },
+    })
+    expect(res.status).toBe(404)
+  })
+
+  it('400 on non-UUID id', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await app.request('/agents/triage/sessions/not-a-uuid/events', {
+      headers: { authorization: `Bearer ${TOKEN}` },
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('404 unknown agent', async () => {
+    const app = createApp({ agents: makeRegistry({ agents: ['triage'] }), approvals: newApprovals(), token: TOKEN })
+    const res = await app.request(`/agents/ghost/sessions/${SID}/events`, {
+      headers: { authorization: `Bearer ${TOKEN}` },
+    })
+    expect(res.status).toBe(404)
+  })
+
+  it('401 without auth', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await app.request(`/agents/triage/sessions/${SID}/events`)
+    expect(res.status).toBe(401)
+  })
+})
+
+// ─── legacy routes ──────────────────────────────────────────────────────
+
+describe('legacy /sessions and /run routes are gone', () => {
+  it('POST /run → 404', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, '/run', { prompt: 'hi' })
+    expect(res.status).toBe(404)
+  })
+
+  it('POST /sessions → 404', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, '/sessions', { prompt: 'hi' })
+    expect(res.status).toBe(404)
+  })
+})
+
+// ─── approval round-trip (Plan-02) ───────────────────────────────────────
+
+const APPROVAL_ID_RE = /^[0-9a-f-]{30,}$/
+
+function approvalRequest(toolCallId: string): ApprovalRequest {
+  return {
+    sessionId: SID,
+    toolCallId,
+    options: [
+      { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+      { optionId: 'reject-once', name: 'Reject once', kind: 'reject_once' },
+    ],
+  }
+}
+
+describe('SSE approval.request emission', () => {
+  it('emits approval.request when the agent requests permission', async () => {
+    const approvals = newApprovals()
+    const reg: AcpRegistry = makeRegistry({
+      prompt: async (name) => {
+        // The transport replaces registry.onApprovalRequest with one that
+        // registers on the correlator + emits approval.request on the SSE.
+        // The AcpClient would call it — we do so directly to simulate.
+        const decisionPromise = reg.onApprovalRequest(name, approvalRequest('tc-1'))
+        // Wait until the approval is registered, then resolve it.
+        await new Promise((r) => setTimeout(r, 30))
+        const pending = approvals.listPending(SID)
+        expect(pending.length).toBeGreaterThan(0)
+        approvals.resolve(SID, pending[0].approvalId, {
+          decision: 'allow',
+          optionId: 'allow-once',
+        })
+        const decision = await decisionPromise
+        return { stopReason: decision.decision === 'allow' ? 'end_turn' : 'refusal' }
+      },
+    })
+
+    const app = createApp({ agents: reg, approvals, token: TOKEN })
+    const res = await postJson(app, '/agents/triage/sessions', { prompt: 'hi' })
+    expect(res.status).toBe(200)
+    const frames = parseFrames(await res.text()) as Array<Record<string, unknown>>
+    const approvalFrame = frames.find((f) => f.type === 'approval.request')
+    expect(approvalFrame).toBeDefined()
+    expect((approvalFrame as { approval_id: string }).approval_id).toMatch(APPROVAL_ID_RE)
+    const last = frames[frames.length - 1]
+    expect(last.type).toBe('turn.end')
+  })
+})
+
+describe('POST /agents/:name/sessions/:sid/approvals/:approval_id', () => {
+  it('401 without bearer token', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/abc`,
+      { decision: 'cancel' },
+      null,
+    )
+    expect(res.status).toBe(401)
+  })
+
+  it('404 for unknown agent', async () => {
+    const app = createApp({
+      agents: makeRegistry({ agents: ['triage'] }),
+      approvals: newApprovals(),
+      token: TOKEN,
+    })
+    const res = await postJson(
+      app,
+      `/agents/ghost/sessions/${SID}/approvals/abc`,
+      { decision: 'cancel' },
+    )
+    expect(res.status).toBe(404)
+  })
+
+  it('404 for unknown approval id (correlator returns false)', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/nope`,
+      { decision: 'cancel' },
+    )
+    expect(res.status).toBe(404)
+  })
+
+  it('400 for body missing decision', async () => {
+    const approvals = newApprovals()
+    const app = createApp({ agents: makeRegistry(), approvals, token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/anything`,
+      {},
+    )
+    expect(res.status).toBe(400)
+  })
+
+  it('400 when allow lacks option_id', async () => {
+    const approvals = newApprovals()
+    const handle = approvals.register('triage', SID, approvalRequest('tc-1'))
+    const app = createApp({ agents: makeRegistry(), approvals, token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/${handle.approvalId}`,
+      { decision: 'allow' },
+    )
+    expect(res.status).toBe(400)
+    void handle.decisionPromise.catch(() => {})
+  })
+
+  it('200 + resolves the in-flight Promise on valid allow', async () => {
+    const approvals = newApprovals()
+    const handle = approvals.register('triage', SID, approvalRequest('tc-1'))
+    const app = createApp({ agents: makeRegistry(), approvals, token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/${handle.approvalId}`,
+      { decision: 'allow', option_id: 'allow-once' },
+    )
+    expect(res.status).toBe(200)
+    await expect(handle.decisionPromise).resolves.toEqual({
+      decision: 'allow',
+      optionId: 'allow-once',
+    })
+  })
+
+  it('200 + resolves with cancel on { decision: "cancel" }', async () => {
+    const approvals = newApprovals()
+    const handle = approvals.register('triage', SID, approvalRequest('tc-1'))
+    const app = createApp({ agents: makeRegistry(), approvals, token: TOKEN })
+    const res = await postJson(
+      app,
+      `/agents/triage/sessions/${SID}/approvals/${handle.approvalId}`,
+      { decision: 'cancel' },
+    )
+    expect(res.status).toBe(200)
+    await expect(handle.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+  })
+})
+
+describe('POST /agents/:name/sessions/:sid/cancel', () => {
+  it('401 without bearer token', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, `/agents/triage/sessions/${SID}/cancel`, {}, null)
+    expect(res.status).toBe(401)
+  })
+
+  it('404 for unknown agent', async () => {
+    const app = createApp({
+      agents: makeRegistry({ agents: ['triage'] }),
+      approvals: newApprovals(),
+      token: TOKEN,
+    })
+    const res = await postJson(app, `/agents/ghost/sessions/${SID}/cancel`, {})
+    expect(res.status).toBe(404)
+  })
+
+  it('204 and cancels every pending approval for the session', async () => {
+    const approvals = newApprovals()
+    const a = approvals.register('triage', SID, approvalRequest('tc-1'))
+    const b = approvals.register('triage', SID, approvalRequest('tc-2'))
+    const app = createApp({ agents: makeRegistry(), approvals, token: TOKEN })
+    const res = await postJson(app, `/agents/triage/sessions/${SID}/cancel`, {})
+    expect(res.status).toBe(204)
+    await expect(a.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+    await expect(b.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+    expect(approvals.size()).toBe(0)
+  })
+
+  it('204 even with no pending approvals (idempotent)', async () => {
+    const app = createApp({ agents: makeRegistry(), approvals: newApprovals(), token: TOKEN })
+    const res = await postJson(app, `/agents/triage/sessions/${SID}/cancel`, {})
+    expect(res.status).toBe(204)
+  })
+})

package/src/server.ts

@@ -0,0 +1,303 @@
+import { Hono, type Context } from 'hono'
+import { streamSSE, type SSEStreamingApi } from 'hono/streaming'
+import { timingSafeEqual, randomUUID } from 'node:crypto'
+import type {
+  AcpRegistry,
+  ApprovalCorrelator,
+  RegisteredApproval,
+} from '@zooid/core'
+import type {
+  AgentEvent,
+  ApprovalDecision,
+} from '@zooid/acp-client'
+
+export interface CreateAppOptions {
+  /** Long-lived registry that fronts every ACP agent. */
+  agents: AcpRegistry
+  /**
+   * Correlator that pairs ACP `requestPermission` calls with HTTP-side
+   * decisions. The transport listens to its `'registered'` and `'timeout'`
+   * events to drive the SSE wire and resolves it via the POST decision route.
+   */
+  approvals: ApprovalCorrelator
+  /** Bearer token; constant-time compared against `Authorization`. */
+  token: string
+  /**
+   * Keepalive interval for open SSE streams (proxies kill idle connections).
+   * 0 disables. Default: 30_000ms.
+   */
+  keepaliveMs?: number
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+interface PromptBody {
+  prompt: string
+}
+
+function isAuthorized(token: string, header: string | undefined): boolean {
+  if (!header || !header.startsWith('Bearer ')) return false
+  const provided = header.slice('Bearer '.length)
+  if (provided.length !== token.length) return false
+  return timingSafeEqual(Buffer.from(provided), Buffer.from(token))
+}
+
+function parsePromptBody(raw: unknown): PromptBody | { error: string } {
+  if (!raw || typeof raw !== 'object') return { error: 'body must be a JSON object' }
+  const obj = raw as Record<string, unknown>
+  if (typeof obj.prompt !== 'string' || obj.prompt.length === 0) {
+    return { error: 'missing or empty prompt' }
+  }
+  return { prompt: obj.prompt }
+}
+
+async function readJson(c: Context): Promise<unknown | { error: string }> {
+  const raw = await c.req.text()
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return { error: 'body must be valid JSON' }
+  }
+}
+
+interface DecisionBody {
+  decision: 'allow' | 'cancel'
+  option_id?: string
+}
+
+function parseDecisionBody(raw: unknown): DecisionBody | { error: string } {
+  if (!raw || typeof raw !== 'object') return { error: 'body must be a JSON object' }
+  const obj = raw as Record<string, unknown>
+  if (obj.decision !== 'allow' && obj.decision !== 'cancel') {
+    return { error: 'decision must be "allow" or "cancel"' }
+  }
+  if (obj.decision === 'allow' && typeof obj.option_id !== 'string') {
+    return { error: 'option_id is required when decision is "allow"' }
+  }
+  return {
+    decision: obj.decision,
+    option_id: typeof obj.option_id === 'string' ? obj.option_id : undefined,
+  }
+}
+
+function approvalRequestFrame(handle: RegisteredApproval): string {
+  return JSON.stringify({
+    type: 'approval.request',
+    approval_id: handle.approvalId,
+    session_id: handle.sessionId,
+    tool_call_id: handle.toolCallId,
+    options: handle.options,
+  })
+}
+
+export function createApp({
+  agents,
+  approvals,
+  token,
+  keepaliveMs = 30_000,
+}: CreateAppOptions) {
+  const app = new Hono()
+
+  // Per-session SSE handle. The registry's onEvent dispatcher and the
+  // correlator's `'registered'` / `'timeout'` listeners look up the
+  // currently-attached stream by session id.
+  const streams = new Map<string, SSEStreamingApi>()
+
+  agents.onEvent = (_name, event: AgentEvent) => {
+    const stream = streams.get(event.sessionId)
+    if (!stream) return
+    void stream.writeSSE({ data: JSON.stringify(event) })
+  }
+  // Always wire the registry's approval handler to the correlator. The
+  // per-agent `approval_timeout_ms` is read off the registry so YAML-driven
+  // timeouts still apply.
+  agents.onApprovalRequest = async (name, req) => {
+    const handle = approvals.register(name, req.sessionId, req, {
+      timeoutMs: agents.getApprovalTimeoutMs(name),
+    })
+    return handle.decisionPromise
+  }
+
+  approvals.on('registered', (handle: RegisteredApproval) => {
+    const stream = streams.get(handle.sessionId)
+    if (!stream) return
+    void stream.writeSSE({ data: approvalRequestFrame(handle) })
+  })
+
+  approvals.on('timeout', ({ approvalId, sessionId }: { approvalId: string; sessionId: string }) => {
+    const stream = streams.get(sessionId)
+    if (!stream) return
+    void stream.writeSSE({
+      data: JSON.stringify({ type: 'approval.timeout', approval_id: approvalId, session_id: sessionId }),
+    })
+  })
+
+  function checkAgent(c: Context, name: string): Response | null {
+    if (!agents.hasAgent(name)) {
+      return c.json({ error: 'unknown agent' }, 404)
+    }
+    return null
+  }
+
+  function attachKeepalive(sse: SSEStreamingApi): NodeJS.Timeout | null {
+    if (!keepaliveMs || keepaliveMs <= 0) return null
+    const timer = setInterval(() => {
+      void sse.writeSSE({ data: '', event: 'keepalive' }).catch(() => {})
+    }, keepaliveMs)
+    timer.unref?.()
+    return timer
+  }
+
+  /**
+   * POST /agents/:name/sessions — start a new ACP session.
+   *
+   *   { session.start, session_id }
+   *   { turn.start }
+   *   ... ACP AgentEvents
+   *   { approval.request, ... } / { approval.timeout, ... } as they arrive
+   *   { turn.end, stop_reason }
+   */
+  app.post('/agents/:name/sessions', async (c) => {
+    if (!isAuthorized(token, c.req.header('authorization'))) {
+      return c.json({ error: 'unauthorized' }, 401)
+    }
+    const name = c.req.param('name')
+    const reject = checkAgent(c, name)
+    if (reject) return reject
+
+    const parsed = await readJson(c)
+    if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+      return c.json({ error: (parsed as { error: string }).error }, 400)
+    }
+    const body = parsePromptBody(parsed)
+    if ('error' in body) return c.json({ error: body.error }, 400)
+
+    const threadId = randomUUID()
+    return streamSSE(c, async (sse) => {
+      let sessionId: string | null = null
+      let keepalive: NodeJS.Timeout | null = null
+      try {
+        sessionId = await agents.ensureSession(name, threadId)
+        streams.set(sessionId, sse)
+        keepalive = attachKeepalive(sse)
+        await sse.writeSSE({
+          data: JSON.stringify({ type: 'session.start', session_id: sessionId }),
+        })
+        await sse.writeSSE({ data: JSON.stringify({ type: 'turn.start' }) })
+        const result = await agents.prompt(name, {
+          threadId,
+          content: [{ type: 'text', text: body.prompt }],
+        })
+        await sse.writeSSE({
+          data: JSON.stringify({ type: 'turn.end', stop_reason: result.stopReason }),
+        })
+      } catch (err) {
+        await sse.writeSSE({
+          data: JSON.stringify({
+            type: 'turn.end',
+            stop_reason: 'error',
+            error: (err as Error).message,
+          }),
+        })
+      } finally {
+        if (keepalive) clearInterval(keepalive)
+        if (sessionId) {
+          // The turn is over; cancel any approvals that the shim left
+          // dangling so future POSTs against them 404 fast.
+          approvals.cancelSession(sessionId)
+          if (streams.get(sessionId) === sse) {
+            streams.delete(sessionId)
+          }
+        }
+      }
+    })
+  })
+
+  /**
+   * GET /agents/:name/sessions/:id/events — reattach to an in-flight stream.
+   *
+   * When a turn is in flight: replays any pending approvals via
+   * `approvals.listPending(sid)`, then forwards live events until the turn
+   * ends. When no turn is in flight: 404.
+   */
+  app.get('/agents/:name/sessions/:id/events', async (c) => {
+    if (!isAuthorized(token, c.req.header('authorization'))) {
+      return c.json({ error: 'unauthorized' }, 401)
+    }
+    const name = c.req.param('name')
+    const reject = checkAgent(c, name)
+    if (reject) return reject
+    const id = c.req.param('id')
+    if (!UUID_RE.test(id)) {
+      return c.json({ error: 'session id must be a UUID' }, 400)
+    }
+    if (!streams.has(id)) {
+      return c.json({ error: 'no in-flight session' }, 404)
+    }
+    return streamSSE(c, async (sse) => {
+      // Take ownership of dispatch for this session id.
+      streams.set(id, sse)
+      const keepalive = attachKeepalive(sse)
+      // Replay any approvals that are still pending so the reconnecting
+      // client can decide on them.
+      for (const handle of approvals.listPending(id)) {
+        await sse.writeSSE({ data: approvalRequestFrame(handle) })
+      }
+      try {
+        while (streams.get(id) === sse) {
+          await new Promise((r) => setTimeout(r, 250))
+        }
+      } finally {
+        if (keepalive) clearInterval(keepalive)
+      }
+    })
+  })
+
+  /**
+   * POST /agents/:name/sessions/:sid/approvals/:approval_id — resolve a
+   * pending permission request.
+   */
+  app.post('/agents/:name/sessions/:sid/approvals/:approval_id', async (c) => {
+    if (!isAuthorized(token, c.req.header('authorization'))) {
+      return c.json({ error: 'unauthorized' }, 401)
+    }
+    const name = c.req.param('name')
+    const reject = checkAgent(c, name)
+    if (reject) return reject
+
+    const sid = c.req.param('sid')
+    const approvalId = c.req.param('approval_id')
+    const parsed = await readJson(c)
+    if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+      return c.json({ error: (parsed as { error: string }).error }, 400)
+    }
+    const body = parseDecisionBody(parsed)
+    if ('error' in body) return c.json({ error: body.error }, 400)
+
+    const decision: ApprovalDecision =
+      body.decision === 'cancel'
+        ? { decision: 'cancel' }
+        : { decision: 'allow', optionId: body.option_id! }
+    const ok = approvals.resolve(sid, approvalId, decision)
+    if (!ok) return c.json({ error: 'unknown approval' }, 404)
+    return c.json({ ok: true })
+  })
+
+  /**
+   * POST /agents/:name/sessions/:sid/cancel — cancel every pending approval
+   * for the session. Idempotent. Returns 204.
+   */
+  app.post('/agents/:name/sessions/:sid/cancel', async (c) => {
+    if (!isAuthorized(token, c.req.header('authorization'))) {
+      return c.json({ error: 'unauthorized' }, 401)
+    }
+    const name = c.req.param('name')
+    const reject = checkAgent(c, name)
+    if (reject) return reject
+    const sid = c.req.param('sid')
+    approvals.cancelSession(sid)
+    return c.body(null, 204)
+  })
+
+  return app
+}