stageflow 0.36.0 → 0.39.0

package/dist/runstore/sqlite/migrations/index.js

@@ -11,6 +11,8 @@ import { MIGRATION_009 } from "./009-trigger-next-run.js";
 import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
 import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 import { MIGRATION_012 } from "./012-trigger-fires.js";
+import { MIGRATION_013 } from "./013-agents.js";
+import { MIGRATION_014 } from "./014-agent-deliveries.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -24,6 +26,8 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_010,
     MIGRATION_011,
     MIGRATION_012,
+    MIGRATION_013,
+    MIGRATION_014,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,6 +1,10 @@
 import { emailHostFor, stageEmail, workerStageEmail, validateStageEmailAccounts } from "../email/host.js";
 import { ChannelError } from "../channels/errors.js";
 import { channelHostFor, stageChannels, validateStageChannelConnections, workerStageChannels } from "../channels/host.js";
+import { bindStageMemory } from "../memory/access.js";
+import { memoryHostFor } from "../memory/host.js";
+import { workerMemoryForStage } from "../memory/worker.js";
+import { memoryPrompt } from "../tools/memoryTools.js";
 import { EmailError } from "../email/port.js";
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
 import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
@@ -98,12 +102,13 @@ async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir, opt
     };
     const stageIdOpt = options.stageId !== undefined ? { stageId: options.stageId } : {};
     const bindingKind = bindingKindForOrigin(options.bindingKind);
-    if (factoryCwd !== undefined && (await mcpCatalogExists(factoryCwd))) {
+    if (factoryCwd !== undefined && (await mcpCatalogExists(factoryCwd, { scope: { kind: "validate" } }))) {
         await mkdir(artifactsDir, { recursive: true });
         const resolved = await resolveStageMcpServers({
             projectRoot: factoryCwd,
             allowlist: names,
             env,
+            scope: { kind: "stage", secrets: options.declaredSecrets ?? [] },
             bindingKind,
             trustWorkspaceConfig: options.trustWorkspaceConfig,
             ...stageIdOpt,
@@ -187,6 +192,7 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
             trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
             stageEnv: resolveOptions.stageEnv,
             stageId: input.stageId,
+            declaredSecrets: (input.stage.secrets ?? []).map((d) => d.name),
         });
         resolvedMcpServers = mcp.servers;
         origins.push(...mcp.origins);
@@ -462,6 +468,11 @@ export async function openStageAttempt(input) {
             throw error;
         }
     }
+    const stageMemory = input.stage.memories?.length
+        ? process.env.SF_STAGE_WORKER === "1"
+            ? await workerMemoryForStage(input.stage.memories)
+            : await bindStageMemory(memoryHostFor(), input.stage.memories)
+        : undefined;
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -481,6 +492,9 @@ export async function openStageAttempt(input) {
             channels: process.env.SF_STAGE_WORKER === "1" ? workerStageChannels()
                 : stageChannels(channelHostFor(input.factoryCwd ?? process.cwd()), input.stage, input.runId),
         } : {}),
+        ...(stageMemory
+            ? { memory: stageMemory, memoryPrompt: await memoryPrompt(stageMemory) }
+            : {}),
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
             input.onActivity?.(input.stage.browser !== undefined

package/dist/runtime/stageEnvironment.d.ts

@@ -2,6 +2,7 @@ export declare const STAGE_ENV_PASSTHROUGH = "STAGEFLOW_STAGE_ENV_PASSTHROUGH";
 export declare const STAGE_ENV_ALLOW = "STAGEFLOW_STAGE_ENV_ALLOW";
 /** Names copied from Host when present (exact-name allowlist; no prefix wildcards). */
 export declare const STAGE_ENV_ALLOWLIST: readonly string[];
+export declare const PROVIDER_AND_CLOUD_NAMES: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_API_KEY_FILE", "GOOGLE_API_KEY", "GEMINI_API_KEY", "GROQ_API_KEY", "MISTRAL_API_KEY", "DEEPSEEK_API_KEY", "TOGETHER_API_KEY", "FIREWORKS_API_KEY", "PERPLEXITY_API_KEY", "XAI_API_KEY", "COHERE_API_KEY", "OPENROUTER_API_KEY", "AZURE_OPENAI_API_KEY", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_SECURITY_TOKEN", "AWS_PROFILE", "AWS_DEFAULT_REGION", "AWS_REGION", "GOOGLE_APPLICATION_CREDENTIALS", "GCLOUD_PROJECT", "AZURE_CLIENT_SECRET", "AZURE_TENANT_ID", "AZURE_CLIENT_ID", "NPM_TOKEN", "NODE_AUTH_TOKEN", "SSH_AUTH_SOCK", "SSH_AGENT_PID", "GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN_FILE", "GH_TOKEN_FILE"];
 /** Never grantable — even via secrets `as: env`. */
 export declare const FOREVER_DENIED_SECRET_NAMES: ReadonlySet<string>;
 /** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
@@ -29,6 +30,7 @@ export type BuildStageEnvironmentResult = {
     passthroughActive: boolean;
 };
 export declare function isForeverDeniedSecret(name: string): boolean;
+export declare function isProviderOrCloudName(name: string): boolean;
 export declare function isAmbientBlockedEnv(name: string): boolean;
 /**
  * Construct the stage child environment. Exact-name allowlist only — never a

package/dist/runtime/stageEnvironment.js

@@ -27,7 +27,7 @@ export const STAGE_ENV_ALLOWLIST = [
     "STAGEFLOW_HOME",
     "STAGEFLOW_CURSOR_EXTENSION",
 ];
-const PROVIDER_AND_CLOUD_NAMES = [
+export const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",
     "OPENAI_API_KEY",
     "OPENAI_API_KEY_FILE",
@@ -70,6 +70,8 @@ export const FOREVER_DENIED_SECRET_NAMES = new Set([
     "STAGEFLOW_CONTROL_TOKEN_FILE",
     "STAGEFLOW_READ_TOKEN",
     "STAGEFLOW_READ_TOKEN_FILE",
+    // Host-generated key for the MCP OAuth token store; never hand it to a stage or an MCP server.
+    "PI_MCP_ADAPTER_OAUTH_FILE_KEY",
 ]);
 /** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
 export const AMBIENT_BLOCKED_ENV_NAMES = new Set([
@@ -94,6 +96,9 @@ export function isForeverDeniedSecret(name) {
         return true;
     return name.startsWith("STAGEFLOW_CONTROL_TOKEN_");
 }
+export function isProviderOrCloudName(name) {
+    return PROVIDER_AND_CLOUD_NAMES.includes(name);
+}
 export function isAmbientBlockedEnv(name) {
     return isForeverDeniedSecret(name) || AMBIENT_BLOCKED_ENV_NAMES.has(name);
 }

package/dist/runtime/stageProcessLauncher.js

@@ -15,6 +15,8 @@ import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 import { emailHostFor, emailWorkerEnvironment, stageEmail, validateStageEmailAccounts } from "../email/host.js";
 import { ChannelError } from "../channels/errors.js";
 import { channelFault, channelHostFor, channelsWorkerEnvironment, stageChannels, validateStageChannelConnections } from "../channels/host.js";
+import { MemoryError, memoryHostFor } from "../memory/host.js";
+import { isMemoryVerb, runMemoryRequest } from "../memory/access.js";
 import { EmailError } from "../email/port.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
 function defaultStageCliEntry() {
@@ -443,6 +445,27 @@ export class StageProcessLauncher {
                     })();
                     return;
                 }
+                const memoryVerb = request?.type;
+                if (!settled && isMemoryVerb(memoryVerb)) {
+                    void (async () => {
+                        if (typeof request.requestId !== "string" || request.requestId.length > 100)
+                            return;
+                        let response;
+                        try {
+                            const stage = input.stage;
+                            if (!stage || settled)
+                                throw new MemoryError("MEMORY_NOT_ATTACHED");
+                            response = await runMemoryRequest(memoryHostFor(), stage.memories ?? [], memoryVerb, request.input);
+                        }
+                        catch (error) {
+                            const code = error instanceof MemoryError ? error.code : "MEMORY_UNREADABLE";
+                            response = { error: { code } };
+                        }
+                        if (child.connected && !settled)
+                            child.send({ type: "memory.response", requestId: request.requestId, ...response });
+                    })();
+                    return;
+                }
                 if (!settled && request?.type === "channel.send") {
                     void (async () => {
                         if (typeof request.requestId !== "string" || request.requestId.length > 100)

package/dist/runtime/stageSecrets.d.ts

@@ -9,6 +9,11 @@ export type SecretRegistryEntry = {
     name: string;
     source: string;
     pointerVar: string;
+}
+/** A secret saved from the console (Settings → Project MCP). It only fills `${NAME}` in MCP servers; never the stage environment. */
+ | {
+    kind: "console";
+    name: string;
 };
 export type SecretRegistry = Map<string, SecretRegistryEntry>;
 export declare class SecretUnavailableError extends Error {
@@ -35,6 +40,6 @@ export type ResolveStageSecretsResult = {
     credentialDirs: string[];
 };
 /** Presence-only check (no materialisation) for preflight / start gates. */
-export declare function assertSecretPresent(name: string, registry: SecretRegistry, hostEnv: NodeJS.ProcessEnv): void;
+export declare function assertSecretPresent(name: string, registry: SecretRegistry, hostEnv: NodeJS.ProcessEnv, home?: string): void;
 export declare function resolveStageSecrets(input: ResolveStageSecretsInput): ResolveStageSecretsResult;
 export { cleanupCredentialsDir };

package/dist/runtime/stageSecrets.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { shouldRegisterValue } from "../logging/redact.js";
+import { readMcpSecrets } from "../config/mcpHostCatalog.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { attemptCredentialsDir, cleanupCredentialsDir, ensureStageAskpassHelper, materialiseCredentialFile, materialiseSecretBytes, readFileCredentialRegistry, } from "./credentialMaterialisation.js";
 import { defaultSecretDelivery, } from "./stageSecretDecl.js";
@@ -66,10 +67,20 @@ export function loadSecretRegistry(env = process.env, home = globalStageflowHome
             continue;
         registry.set(name, { kind: "env", name });
     }
+    // Console-stored MCP secrets: a stage may declare them so its `mcp:` servers can be filled.
+    try {
+        for (const name of Object.keys(readMcpSecrets(home))) {
+            if (!isForeverDeniedSecret(name) && !registry.has(name))
+                registry.set(name, { kind: "console", name });
+        }
+    }
+    catch {
+        // A corrupt host-state file is reported by the MCP routes; it must not stop other stages.
+    }
     return registry;
 }
 /** Presence-only check (no materialisation) for preflight / start gates. */
-export function assertSecretPresent(name, registry, hostEnv) {
+export function assertSecretPresent(name, registry, hostEnv, home) {
     if (isForeverDeniedSecret(name)) {
         throw new Error(`secret "${name}" is permanently denied`);
     }
@@ -86,11 +97,24 @@ export function assertSecretPresent(name, registry, hostEnv) {
         }
         return;
     }
+    if (entry.kind === "console") {
+        if (!readMcpSecretValue(name, home))
+            throw new SecretUnavailableError(name);
+        return;
+    }
     const value = readEnvSecretValue(name, hostEnv);
     if (value === undefined || value === "") {
         throw new SecretUnavailableError(name);
     }
 }
+function readMcpSecretValue(name, home) {
+    try {
+        return readMcpSecrets(home)[name];
+    }
+    catch {
+        return undefined;
+    }
+}
 function materialiseGitAskpassGrant(grantEnv, credentialDirs, opts) {
     const destDir = attemptCredentialsDir(opts.attemptDir, opts.secretName);
     const tokenFile = materialiseSecretBytes({
@@ -119,6 +143,15 @@ export function resolveStageSecrets(input) {
         if (entry === undefined) {
             throw new Error(`stage.unknown_secret: "${decl.name}"`);
         }
+        if (entry.kind === "console") {
+            const stored = readMcpSecretValue(decl.name, input.home);
+            if (!stored)
+                throw new SecretUnavailableError(decl.name);
+            if (shouldRegisterValue(stored))
+                knownValues.push({ name: decl.name, value: stored });
+            warnings.push(`secrets: ${decl.name} is a console secret; it fills MCP servers only and is not set in the stage environment`);
+            continue;
+        }
         if (entry.kind === "file") {
             const destDir = attemptCredentialsDir(input.attemptDir, decl.name);
             const homeRoot = input.home ?? globalStageflowHome();

package/dist/server/agentAuthorRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OperatorAgentHost } from "../operatorAgent/index.js";
+type Json = (res: ServerResponse, status: number, body: unknown) => void;
+export declare function handleAgentAuthorRoutes(req: IncomingMessage, method: string, pathname: string, projectRoot: string, host: OperatorAgentHost, res: ServerResponse, json: Json): Promise<boolean>;
+export {};

package/dist/server/agentAuthorRoutes.js

@@ -0,0 +1,64 @@
+import { parseAgentAuthorDraft, runAgentAuthorTurn, undoAgentAuthorTurn } from "../agents/authorChat.js";
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buffer.length;
+        if (size > 65536)
+            return { __tooLarge: true };
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : { __invalid: true };
+    }
+    catch {
+        return { __invalid: true };
+    }
+}
+export async function handleAgentAuthorRoutes(req, method, pathname, projectRoot, host, res, json) {
+    const chat = pathname === "/api/agent-author/chat";
+    const undo = pathname === "/api/agent-author/undo";
+    if (!chat && !undo)
+        return false;
+    if (method !== "POST") {
+        json(res, 405, { code: "agent.invalid" });
+        return true;
+    }
+    const body = await readBody(req);
+    if (body.__tooLarge || body.__invalid) {
+        json(res, 400, { code: "agent.invalid" });
+        return true;
+    }
+    try {
+        if (undo) {
+            const sessionId = typeof body.sessionId === "string" ? body.sessionId.trim() : "";
+            if (!sessionId) {
+                json(res, 400, { code: "agent.invalid" });
+                return true;
+            }
+            json(res, 200, { draft: undoAgentAuthorTurn(sessionId) });
+            return true;
+        }
+        const message = typeof body.message === "string" ? body.message : "";
+        const result = await runAgentAuthorTurn({
+            host,
+            projectRoot,
+            message,
+            ...(typeof body.sessionId === "string" ? { sessionId: body.sessionId } : {}),
+            draft: parseAgentAuthorDraft(body.draft),
+        });
+        json(res, 200, result);
+    }
+    catch (err) {
+        const code = err instanceof Error ? err.message : "agent.internal";
+        const status = code === "agent.session_not_found" ? 404 : code === "agent.conflict" ? 409 : 400;
+        json(res, status, { code: code.startsWith("agent.") ? code : "agent.internal" });
+    }
+    return true;
+}

package/dist/server/agentRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AgentHostContext } from "../agents/hostContext.js";
+type Json = (res: ServerResponse, status: number, body: unknown) => void;
+export declare function handleAgentRoutes(req: IncomingMessage, method: string, pathname: string, host: AgentHostContext, projectRoot: string, res: ServerResponse, json: Json): Promise<boolean>;
+export {};

package/dist/server/agentRoutes.js

@@ -0,0 +1,323 @@
+import { AgentError, isAgentError } from "../agents/errors.js";
+import { describeToolkit } from "../toolkit/index.js";
+import { isSessionStatus } from "../agents/store.js";
+import { BodyError, readJsonBody, writeFrame } from "../agents/ndjson.js";
+const MAX_BODY_BYTES = 256 * 1024;
+const CONSOLE_ACTOR = { source: "console" };
+async function readBody(req) {
+    try {
+        return await readJsonBody(req, MAX_BODY_BYTES);
+    }
+    catch (error) {
+        if (!(error instanceof BodyError))
+            throw error;
+        throw new AgentError("agent.invalid", error.reason === "too_large" ? "Request body is too large" : error.reason === "not_json" ? "Request body is not JSON" : "Request body must be a JSON object");
+    }
+}
+function requireInt(value, name) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new AgentError("agent.invalid", `${name} must be a non-negative integer`);
+    }
+    return value;
+}
+function requireText(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new AgentError("agent.invalid", `${name} is required`);
+    return value.trim();
+}
+function optionalText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function sessionQuery(url) {
+    const status = url.searchParams.get("status") ?? undefined;
+    if (status !== undefined && !isSessionStatus(status)) {
+        throw new AgentError("agent.invalid", "Unknown session status");
+    }
+    const limit = Number(url.searchParams.get("limit") ?? 25);
+    return {
+        limit: Number.isInteger(limit) && limit > 0 && limit <= 100 ? limit : 25,
+        ...(status && isSessionStatus(status) ? { status } : {}),
+        ...(url.searchParams.get("source") ? { source: url.searchParams.get("source") } : {}),
+        ...(url.searchParams.get("q")?.trim() ? { search: url.searchParams.get("q").trim() } : {}),
+        ...(url.searchParams.get("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+    };
+}
+/** A session must belong to the agent named in the path, or the request is a 404. */
+async function sessionFor(ctx, agentId, sessionId) {
+    const detail = await ctx.host.service.getSession(ctx.projectRoot, sessionId);
+    if (detail.session.agentId !== agentId)
+        throw new AgentError("agent.session_not_found");
+    return detail;
+}
+async function chat(ctx, agentId) {
+    const body = await readBody(ctx.req);
+    const message = requireText(body.message, "message");
+    const sessionId = optionalText(body.sessionId);
+    const wantsStream = body.stream === true || String(ctx.req.headers.accept ?? "").includes("application/x-ndjson");
+    const send = (onDelta, onSessionOpened) => ctx.host.chat.send({
+        projectRoot: ctx.projectRoot,
+        agentId,
+        text: message,
+        source: "console",
+        ...(sessionId ? { sessionId } : {}),
+        ...(onDelta ? { onDelta } : {}),
+        ...(onSessionOpened ? { onSessionOpened } : {}),
+    });
+    if (!wantsStream) {
+        ctx.json(ctx.res, 200, await send());
+        return;
+    }
+    ctx.res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-store" });
+    let writes = Promise.resolve();
+    let finished = false;
+    let openedId = sessionId;
+    ctx.res.once("close", () => {
+        if (finished)
+            return;
+        if (openedId)
+            ctx.host.chat.stop(openedId);
+        else
+            ctx.host.chat.stopOpening(agentId);
+    });
+    try {
+        const detail = await send((text) => {
+            writes = writes.then(() => writeFrame(ctx.res, { type: "delta", text }));
+        }, (id) => {
+            openedId = id;
+            writes = writes.then(() => writeFrame(ctx.res, { type: "session", sessionId: id }));
+        });
+        finished = true;
+        await writes;
+        await writeFrame(ctx.res, { type: "done", session: detail });
+    }
+    catch (error) {
+        finished = true;
+        await writes.catch(() => undefined);
+        await writeFrame(ctx.res, {
+            type: "error",
+            code: isAgentError(error) ? error.code : "agent.internal",
+            ...(isAgentError(error) && error.message !== error.code ? { message: error.message } : {}),
+        });
+    }
+    finally {
+        if (!ctx.res.writableEnded && !ctx.res.destroyed)
+            ctx.res.end();
+    }
+}
+const routes = [
+    {
+        method: "GET",
+        pattern: /^\/api\/agents$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { agents: await ctx.host.service.list(ctx.projectRoot) }),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 201, await ctx.host.service.create(ctx.projectRoot, body.definition, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/validate$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.validate(ctx.projectRoot, body.definition));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/stageflow-tools$/,
+        handle: async ({ res, json }) => json(res, 200, describeToolkit()),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/channel$/,
+        handle: async (ctx) => {
+            const detail = await ctx.host.service.get(ctx.projectRoot, ctx.params[0]);
+            const connectionId = detail.definition?.channel?.connection_id ?? null;
+            // `listener` is absent for webhook providers and for agents that are disabled.
+            const listener = connectionId ? ctx.host.channelListeners?.status(connectionId) : undefined;
+            const failed = ctx.host.service.latestUndelivered(ctx.projectRoot, ctx.params[0]);
+            ctx.json(ctx.res, 200, {
+                connectionId,
+                ...(listener ? { listener } : {}),
+                ...(failed ? { lastUndelivered: { turnId: failed.turnId, sessionId: failed.sessionId, state: failed.state, code: failed.errorCode, message: failed.errorMessage, at: failed.updatedAt } } : {}),
+            });
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/turns\/([^/]+)\/delivery\/(resend|delivered)$/,
+        handle: async (ctx) => {
+            const [agentId, sessionId, turnId, action] = ctx.params;
+            const session = await ctx.host.service.getSession(ctx.projectRoot, sessionId);
+            if (session.session.agentId !== agentId || !session.turns.some((turn) => turn.id === turnId))
+                throw new AgentError("agent.session_not_found");
+            if (action === "resend")
+                await ctx.host.delivery.resend(turnId);
+            else
+                ctx.host.delivery.markDelivered(turnId);
+            ctx.json(ctx.res, 200, await ctx.host.service.getSession(ctx.projectRoot, sessionId));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/channel\/contact$/,
+        handle: async (ctx) => {
+            const detail = await ctx.host.service.get(ctx.projectRoot, ctx.params[0]);
+            const connectionId = detail.definition?.channel?.connection_id;
+            const found = connectionId ? await ctx.host.channelContact(connectionId) : undefined;
+            ctx.json(ctx.res, 200, { connectionId: connectionId ?? null, ...(found ?? {}) });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/sessions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.listAllSessions(ctx.projectRoot, sessionQuery(ctx.url), ctx.url.searchParams.get("agent") || undefined)),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/approvals$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { approvals: await ctx.host.service.pendingApprovals(ctx.projectRoot) }),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.get(ctx.projectRoot, ctx.params[0])),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/save$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.save(ctx.projectRoot, ctx.params[0], {
+                baseRevision: requireInt(body.baseRevision, "baseRevision"),
+                definition: body.definition,
+                summary: optionalText(body.summary) ?? null,
+            }, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/(enable|disable)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.setEnabled(ctx.projectRoot, ctx.params[0], ctx.params[1] === "enable", CONSOLE_ACTOR)),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/archive$/,
+        handle: async (ctx) => {
+            await ctx.host.service.archive(ctx.projectRoot, ctx.params[0]);
+            ctx.json(ctx.res, 200, { archived: true });
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, { revisions: await ctx.host.service.listRevisions(ctx.projectRoot, ctx.params[0]) }),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.getRevision(ctx.projectRoot, ctx.params[0], Number(ctx.params[1]))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)\/diff\/(\d+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, {
+            lines: await ctx.host.service.diffRevisions(ctx.projectRoot, ctx.params[0], Number(ctx.params[1]), Number(ctx.params[2])),
+        }),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/revisions\/(\d+)\/restore$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            ctx.json(ctx.res, 200, await ctx.host.service.restore(ctx.projectRoot, ctx.params[0], { revision: Number(ctx.params[1]), baseRevision: requireInt(body.baseRevision, "baseRevision") }, CONSOLE_ACTOR));
+        },
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await ctx.host.service.listSessions(ctx.projectRoot, ctx.params[0], sessionQuery(ctx.url))),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)$/,
+        handle: async (ctx) => ctx.json(ctx.res, 200, await sessionFor(ctx, ctx.params[0], ctx.params[1])),
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/otlp$/,
+        handle: async (ctx) => {
+            await sessionFor(ctx, ctx.params[0], ctx.params[1]);
+            ctx.res.setHeader("Content-Disposition", `attachment; filename="${ctx.params[1]}.otlp.json"`);
+            ctx.json(ctx.res, 200, ctx.host.service.exportSessionOtlp(ctx.projectRoot, ctx.params[1]));
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/approval\/(approve|deny)$/,
+        handle: async (ctx) => {
+            await sessionFor(ctx, ctx.params[0], ctx.params[1]);
+            const approval = await ctx.host.service.decideApproval(ctx.projectRoot, ctx.params[1], ctx.params[2] === "approve" ? "approve" : "deny", { kind: "operator" });
+            ctx.json(ctx.res, 200, { approval, session: await sessionFor(ctx, ctx.params[0], ctx.params[1]) });
+        },
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/chat$/,
+        handle: async (ctx) => chat(ctx, ctx.params[0]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/api\/agents\/([^/]+)\/chat\/stop$/,
+        handle: async (ctx) => {
+            const body = await readBody(ctx.req);
+            const sessionId = requireText(body.sessionId, "sessionId");
+            await sessionFor(ctx, ctx.params[0], sessionId);
+            ctx.json(ctx.res, 200, { stopped: ctx.host.chat.stop(sessionId) });
+        },
+    },
+];
+export async function handleAgentRoutes(req, method, pathname, host, projectRoot, res, json) {
+    for (const route of routes) {
+        const match = route.pattern.exec(pathname);
+        if (!match)
+            continue;
+        if (route.method !== method)
+            continue;
+        try {
+            const params = match.slice(1).map((segment) => decodeURIComponent(segment));
+            await route.handle({ req, res, json, host, projectRoot, params, url: new URL(req.url ?? pathname, "http://agents") });
+        }
+        catch (error) {
+            if (res.headersSent) {
+                if (!res.writableEnded)
+                    res.end();
+                return true;
+            }
+            if (error instanceof URIError) {
+                json(res, 400, { code: "agent.invalid", message: "Malformed path" });
+            }
+            else if (isAgentError(error)) {
+                json(res, error.httpStatus, {
+                    code: error.code,
+                    ...(error.message !== error.code ? { message: error.message } : {}),
+                    ...(error.issues.length > 0 ? { issues: error.issues } : {}),
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+        return true;
+    }
+    const known = routes.some((route) => route.pattern.test(pathname));
+    if (known) {
+        json(res, 405, { code: "agent.method_not_allowed" });
+        return true;
+    }
+    return false;
+}