stageflow 0.36.0 → 0.40.0

package/dist/agent/piIsolatedMcpProbe.js

@@ -1,30 +1,11 @@
 import { StageMcpError, resolveStageMcpServers, } from "../config/resolveStageMcpServers.js";
+import { collectSecretValues, scrubText } from "../config/mcpRedaction.js";
+import { listCachedMcpTools } from "../config/mcpToolCache.js";
 import * as piIsolatedMcp from "./piIsolatedMcp.js";
 export const PROJECT_MCP_PROBE_TIMEOUT_MS = 30_000;
 const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
 function scrub(message, secrets) {
-    let out = message;
-    for (const secret of secrets) {
-        if (secret.length === 0)
-            continue;
-        out = out.split(secret).join("[redacted]");
-    }
-    return out;
-}
-function collectInterpolatedSecrets(entry) {
-    const secrets = [];
-    for (const field of ["env", "headers"]) {
-        const value = entry[field];
-        if (value === null || typeof value !== "object" || Array.isArray(value)) {
-            continue;
-        }
-        for (const item of Object.values(value)) {
-            if (typeof item === "string" && item.length > 0) {
-                secrets.push(item);
-            }
-        }
-    }
-    return secrets;
+    return scrubText(message, secrets);
 }
 function catalogErrorResult(name, err) {
     if (!(err instanceof StageMcpError))
@@ -35,6 +16,9 @@ function catalogErrorResult(name, err) {
     if (err.code === "missing_catalog") {
         return { name, status: "missing_catalog" };
     }
+    if (err.code === "host_state_corrupt") {
+        return { name, status: "invalid_config", error: err.message };
+    }
     if (err.code === "invalid_config" ||
         err.code === "reserved_name" ||
         err.code === "unknown_server") {
@@ -136,7 +120,7 @@ function instantiateProbeFactories(attached, projectRoot) {
     probeApi.emitSessionStart(projectRoot);
     return () => probeApi.emitSessionShutdown();
 }
-function mapConnectingError(err, aborted) {
+function mapConnectingError(err, aborted, secrets = []) {
     const message = err instanceof Error ? err.message : String(err);
     if (aborted || /cancelled/i.test(message)) {
         return { kind: "cancelled" };
@@ -147,7 +131,7 @@ function mapConnectingError(err, aborted) {
     return {
         kind: "mapped",
         status: "connect_failed",
-        error: message.length > 0 ? message : undefined,
+        error: message.length > 0 ? scrubText(message, secrets) : undefined,
     };
 }
 async function waitForProbeStatus(eventBus, serverName, connecting, options) {
@@ -193,7 +177,7 @@ async function waitForProbeStatus(eventBus, serverName, connecting, options) {
         const maybeUnsub = eventBus.on(MCP_STATUS_EVENT, handler);
         unsubscribe = typeof maybeUnsub === "function" ? maybeUnsub : undefined;
         options.signal?.addEventListener("abort", onAbort, { once: true });
-        void (connecting ?? Promise.resolve()).then(() => finish({ kind: "mapped", status: "connected" }), (err) => finish(mapConnectingError(err, options.signal?.aborted === true)));
+        void (connecting ?? Promise.resolve()).then(() => finish({ kind: "mapped", status: "connected" }), (err) => finish(mapConnectingError(err, options.signal?.aborted === true, options.secrets)));
         timer = setTimeout(() => {
             finish({
                 kind: "mapped",
@@ -206,7 +190,6 @@ async function waitForProbeStatus(eventBus, serverName, connecting, options) {
 export async function probeProjectMcpServer(options) {
     const name = options.name;
     const timeoutMs = options.timeoutMs ?? PROJECT_MCP_PROBE_TIMEOUT_MS;
-    const env = options.env ?? process.env;
     if (options.signal?.aborted) {
         return { name, status: "cancelled" };
     }
@@ -215,7 +198,9 @@ export async function probeProjectMcpServer(options) {
         snapshot = await resolveStageMcpServers({
             projectRoot: options.projectRoot,
             allowlist: [name],
-            env,
+            env: {},
+            hostEnv: options.hostEnv ?? process.env,
+            scope: { kind: "probe" },
         });
     }
     catch (err) {
@@ -228,7 +213,7 @@ export async function probeProjectMcpServer(options) {
     if (resolved === undefined) {
         return { name, status: "invalid_config" };
     }
-    const secrets = collectInterpolatedSecrets(resolved);
+    const secrets = collectSecretValues(resolved);
     let attached;
     let shutdownFactories;
     const dispose = async () => {
@@ -254,7 +239,7 @@ export async function probeProjectMcpServer(options) {
             return { name, status: "invalid_config" };
         }
         shutdownFactories = instantiateProbeFactories(attached, options.projectRoot);
-        const waited = await waitForProbeStatus(attached.eventBus, name, attached.connecting, { timeoutMs, signal: options.signal });
+        const waited = await waitForProbeStatus(attached.eventBus, name, attached.connecting, { timeoutMs, signal: options.signal, secrets });
         if (waited.kind === "cancelled") {
             return { name, status: "cancelled" };
         }
@@ -267,7 +252,8 @@ export async function probeProjectMcpServer(options) {
                     : {}),
             };
         }
-        return { name, status: waited.status };
+        const tools = waited.status === "connected" ? listCachedMcpTools(name)?.tools : undefined;
+        return { name, status: waited.status, ...(tools ? { tools } : {}) };
     }
     catch (err) {
         if (options.signal?.aborted) {

package/dist/agent/port.d.ts

@@ -9,6 +9,7 @@ import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import type { StageEmail } from "../email/host.js";
 import type { StageChannels } from "../channels/host.js";
+import type { StageMemory } from "../memory/access.js";
 import type { QaExchange } from "../hitl/qaTrail.js";
 import type { StageUsage } from "../types/usage.js";
 /** Opaque to runtime; adapters interpret. */
@@ -67,6 +68,10 @@ export type StageRunInput = {
     skillFilePath?: string;
     email?: StageEmail;
     channels?: StageChannels;
+    /** Memories attached to this stage. The host reads and replaces the page. */
+    memory?: StageMemory;
+    /** Refreshed memory prompt; preferred over deriving from `memory` at prompt build time. */
+    memoryPrompt?: string;
     /** Bundled browser skill; set by the runtime when the stage has `browser`. */
     browserSkillFilePath?: string;
     forkEmitContext?: ForkEmitContext;

package/dist/agent/sandboxPiTools.d.ts

@@ -0,0 +1,99 @@
+import { Type } from "typebox";
+import { type SandboxFileTarget } from "../runtime/sandboxFiles.js";
+export type SandboxPiToolOptions = SandboxFileTarget;
+export declare function createSandboxReadTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        offset: Type.TOptional<Type.TNumber>;
+        limit: Type.TOptional<Type.TNumber>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxWriteTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        content: Type.TString;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        content: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxEditTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        edits: Type.TArray<Type.TObject<{
+            oldText: Type.TString;
+            newText: Type.TString;
+        }>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        edits: Array<{
+            oldText: string;
+            newText: string;
+        }>;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxBashTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        command: Type.TString;
+        timeout: Type.TOptional<Type.TNumber>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        command: string;
+        timeout?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};

package/dist/agent/sandboxPiTools.js

@@ -0,0 +1,109 @@
+import { Type } from "typebox";
+import { editSandboxFile, readSandboxFile, runSandboxBash, sliceSandboxLines, writeSandboxFile, } from "../runtime/sandboxFiles.js";
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details: undefined,
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function failure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return textResult(message, true);
+}
+export function createSandboxReadTool(options) {
+    return {
+        name: "read",
+        label: "read",
+        description: "Read a file inside this stage's sandbox. Paths are relative to /workspace (artifacts/, checkout/, grants/, work/) or absolute under /workspace. Host paths are rejected.",
+        promptSnippet: "Read file contents inside /workspace",
+        promptGuidelines: [
+            "Use read to examine files under /workspace instead of cat or sed.",
+        ],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to read, relative to /workspace or absolute under /workspace" }),
+            offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+            limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                const text = await readSandboxFile(options, params.path);
+                return textResult(sliceSandboxLines(text, params.offset, params.limit));
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxWriteTool(options) {
+    return {
+        name: "write",
+        label: "write",
+        description: "Write a file inside this stage's sandbox. Paths are relative to /workspace or absolute under /workspace. Parent directories are created. Host paths are rejected.",
+        promptSnippet: "Create or overwrite files inside /workspace",
+        promptGuidelines: ["Use write only for new files or complete rewrites under /workspace."],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to write, relative to /workspace or absolute under /workspace" }),
+            content: Type.String({ description: "Content to write to the file" }),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                await writeSandboxFile(options, params.path, params.content);
+                return textResult(`Successfully wrote to ${params.path}`);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxEditTool(options) {
+    return {
+        name: "edit",
+        label: "edit",
+        description: "Edit a file inside this stage's sandbox with exact text replacement. Paths are relative to /workspace or absolute under /workspace. Each oldText must match exactly once in the original file.",
+        promptSnippet: "Make precise file edits inside /workspace",
+        promptGuidelines: [
+            "Use edit for precise changes under /workspace (edits[].oldText must match exactly once).",
+        ],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to edit, relative to /workspace or absolute under /workspace" }),
+            edits: Type.Array(Type.Object({
+                oldText: Type.String({ description: "Exact text to replace. It must be unique in the original file." }),
+                newText: Type.String({ description: "Replacement text." }),
+            }), { description: "One or more targeted replacements against the original file." }),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                await editSandboxFile(options, params.path, params.edits);
+                return textResult(`Successfully edited ${params.path}`);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxBashTool(options) {
+    return {
+        name: "bash",
+        label: "bash",
+        description: "Execute a bash command in this stage's sandbox. The working directory is /workspace. The host filesystem is not mounted.",
+        promptSnippet: "Execute bash commands in /workspace",
+        promptGuidelines: ["The shell starts in /workspace. Do not use host paths."],
+        parameters: Type.Object({
+            command: Type.String({ description: "Shell command to execute" }),
+            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                const text = await runSandboxBash(options, params.command, params.timeout !== undefined ? params.timeout * 1000 : undefined);
+                return textResult(text);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}

package/dist/agents/agentId.d.ts

@@ -0,0 +1,8 @@
+/** What an agent id looks like. Lives here, not in the loader, so the loader can import the reserved list without a cycle. */
+export declare const AGENT_ID_PATTERN: RegExp;
+/** Ids that collide with fixed `/api/agents/<word>` routes. The single list: the loader and the generator both read it. */
+export declare const RESERVED_AGENT_IDS: ReadonlySet<string>;
+export declare function isReservedAgentId(id: string): boolean;
+export declare function slugAgentId(name: string): string;
+/** An id from the agent's name, made unique with a numeric suffix. Names with no usable letters become `agent`. */
+export declare function generateAgentId(name: string, isTaken: (id: string) => Promise<boolean>): Promise<string>;

package/dist/agents/agentId.js

@@ -0,0 +1,27 @@
+/** What an agent id looks like. Lives here, not in the loader, so the loader can import the reserved list without a cycle. */
+export const AGENT_ID_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+/** Ids that collide with fixed `/api/agents/<word>` routes. The single list: the loader and the generator both read it. */
+export const RESERVED_AGENT_IDS = new Set(["sessions", "approvals", "new"]);
+export function isReservedAgentId(id) {
+    return RESERVED_AGENT_IDS.has(id);
+}
+export function slugAgentId(name) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 56);
+    return AGENT_ID_PATTERN.test(slug) ? slug : "";
+}
+/** An id from the agent's name, made unique with a numeric suffix. Names with no usable letters become `agent`. */
+export async function generateAgentId(name, isTaken) {
+    const base = slugAgentId(name) || "agent";
+    for (let attempt = 1; attempt < 1000; attempt += 1) {
+        const candidate = attempt === 1 ? base : `${base}_${attempt}`;
+        if (!RESERVED_AGENT_IDS.has(candidate) && !(await isTaken(candidate)))
+            return candidate;
+    }
+    throw new Error("Could not generate a unique agent id");
+}

package/dist/agents/approvalBroker.d.ts

@@ -0,0 +1,16 @@
+export type ApprovalOutcome = "approved" | "denied" | "expired";
+/**
+ * In-process rendezvous between a turn paused at an ask-first tool and the
+ * decision that arrives later (console, CLI, MCP or a channel). A waiter only
+ * exists while the Host process that started the turn is alive.
+ */
+export declare class ApprovalBroker {
+    private readonly waiters;
+    wait(approvalId: string, options: {
+        expiresAt: string;
+        signal: AbortSignal;
+        now?: () => number;
+    }): Promise<ApprovalOutcome | "aborted">;
+    settle(approvalId: string, outcome: ApprovalOutcome): void;
+    pending(): number;
+}

package/dist/agents/approvalBroker.js

@@ -0,0 +1,45 @@
+/**
+ * In-process rendezvous between a turn paused at an ask-first tool and the
+ * decision that arrives later (console, CLI, MCP or a channel). A waiter only
+ * exists while the Host process that started the turn is alive.
+ */
+export class ApprovalBroker {
+    waiters = new Map();
+    wait(approvalId, options) {
+        return new Promise((resolve) => {
+            let timer;
+            const finish = (outcome) => {
+                if (timer)
+                    clearTimeout(timer);
+                options.signal.removeEventListener("abort", onAbort);
+                this.waiters.get(approvalId)?.delete(listener);
+                if (this.waiters.get(approvalId)?.size === 0)
+                    this.waiters.delete(approvalId);
+                resolve(outcome);
+            };
+            const listener = (outcome) => finish(outcome);
+            const onAbort = () => finish("aborted");
+            if (options.signal.aborted)
+                return resolve("aborted");
+            options.signal.addEventListener("abort", onAbort, { once: true });
+            const set = this.waiters.get(approvalId) ?? new Set();
+            set.add(listener);
+            this.waiters.set(approvalId, set);
+            const arm = () => {
+                const remaining = Date.parse(options.expiresAt) - (options.now?.() ?? Date.now());
+                if (remaining <= 0)
+                    return finish("expired");
+                // setTimeout caps at ~24.8 days; longer waits re-arm until the real expiry.
+                timer = setTimeout(arm, Math.min(remaining, 2 ** 31 - 1));
+            };
+            timer = setTimeout(arm, 0);
+        });
+    }
+    settle(approvalId, outcome) {
+        for (const listener of [...(this.waiters.get(approvalId) ?? [])])
+            listener(outcome);
+    }
+    pending() {
+        return this.waiters.size;
+    }
+}

package/dist/agents/authorChat.d.ts

@@ -0,0 +1,19 @@
+import { type SummaryLine } from "./definitionSummary.js";
+import { type AgentAuthorDraft, type OperatorAgentHost } from "../operatorAgent/index.js";
+export type AgentAuthorTurnResult = {
+    sessionId: string;
+    text: string;
+    draft: AgentAuthorDraft;
+    /** One line per config section this turn changed. Empty when the turn only talked. */
+    summaryLines: SummaryLine[];
+};
+export declare function resetAgentAuthorSessionsForTests(): void;
+export declare function runAgentAuthorTurn(input: {
+    host: OperatorAgentHost;
+    projectRoot: string;
+    message: string;
+    sessionId?: string;
+    draft?: AgentAuthorDraft;
+}): Promise<AgentAuthorTurnResult>;
+export declare function undoAgentAuthorTurn(sessionId: string): AgentAuthorDraft;
+export declare function parseAgentAuthorDraft(body: unknown): AgentAuthorDraft;

package/dist/agents/authorChat.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import { describeChanges } from "./definitionSummary.js";
+import { AGENT_AUTHOR_PROFILE_ID, createAgentAuthorContext, isAgentAuthorContext, readAgentAuthorDraft, } from "../operatorAgent/index.js";
+const sessions = new Map();
+export function resetAgentAuthorSessionsForTests() {
+    for (const session of sessions.values())
+        session.close();
+    sessions.clear();
+}
+export async function runAgentAuthorTurn(input) {
+    const message = input.message.trim();
+    if (!message)
+        throw new Error("agent.invalid");
+    let sessionId = input.sessionId?.trim();
+    let session = sessionId ? sessions.get(sessionId) : undefined;
+    if (sessionId && !session)
+        throw new Error("agent.session_not_found");
+    const posted = createAgentAuthorContext({
+        projectRoot: input.projectRoot,
+        draft: input.draft,
+    });
+    if (!session) {
+        sessionId = randomUUID();
+        session = input.host.openSession({
+            profileId: AGENT_AUTHOR_PROFILE_ID,
+            context: posted,
+        });
+        sessions.set(sessionId, session);
+    }
+    else {
+        session.setContext(posted);
+    }
+    const before = readAgentAuthorDraft(session.getContext());
+    const events = await session.send(message);
+    const text = events
+        .filter((event) => event.type === "message" && event.role === "assistant")
+        .map((event) => (event.type === "message" ? event.text : ""))
+        .filter(Boolean)
+        .join("\n\n");
+    const error = events.find((event) => event.type === "error");
+    const draft = readAgentAuthorDraft(session.getContext());
+    return {
+        sessionId: sessionId,
+        text: text || (error && error.type === "error" ? error.message : ""),
+        draft,
+        summaryLines: describeChanges(before, draft),
+    };
+}
+export function undoAgentAuthorTurn(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        throw new Error("agent.session_not_found");
+    const undone = session.undoMutation();
+    if (!undone.ok)
+        throw new Error(undone.reason === "conflict" ? "agent.conflict" : "agent.invalid");
+    const context = session.getContext();
+    if (!isAgentAuthorContext(context))
+        throw new Error("agent.invalid");
+    return readAgentAuthorDraft(context);
+}
+export function parseAgentAuthorDraft(body) {
+    return body !== null && typeof body === "object" && !Array.isArray(body) ? body : {};
+}

package/dist/agents/chatTurn.d.ts

@@ -0,0 +1,23 @@
+import type { AgentSessionDetail } from "./service.js";
+import { type ConversationOptions, type SendTurnInput } from "./sessions.js";
+/**
+ * Serializes turns per session (or per agent while a session is being
+ * opened) and keeps a handle on the running turn so it can be stopped.
+ */
+export declare class AgentChatController {
+    private readonly options;
+    private readonly turnChains;
+    private readonly activeBySession;
+    private readonly activeByAgent;
+    /** Sessions whose turn was stopped: their runtime session is released once the turn has wound down. */
+    private readonly stopped;
+    constructor(options: ConversationOptions);
+    private runExclusive;
+    send(input: SendTurnInput): Promise<AgentSessionDetail>;
+    /** Stop the running turn on a session. Returns false when nothing was running. */
+    stop(sessionId: string): boolean;
+    /** Let the runtime drop what it holds for a session (model session, isolated MCP processes). Never throws. */
+    release(sessionId: string): Promise<void>;
+    /** Stop a turn that is still opening its session (client left before the session id arrived). */
+    stopOpening(agentId: string): boolean;
+}

package/dist/agents/chatTurn.js

@@ -0,0 +1,77 @@
+import { AgentConversation } from "./sessions.js";
+/**
+ * Serializes turns per session (or per agent while a session is being
+ * opened) and keeps a handle on the running turn so it can be stopped.
+ */
+export class AgentChatController {
+    options;
+    turnChains = new Map();
+    activeBySession = new Map();
+    activeByAgent = new Map();
+    /** Sessions whose turn was stopped: their runtime session is released once the turn has wound down. */
+    stopped = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    runExclusive(key, work) {
+        const previous = this.turnChains.get(key) ?? Promise.resolve();
+        const run = previous.then(work, work);
+        this.turnChains.set(key, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    send(input) {
+        return this.runExclusive(input.sessionId ?? `agent:${input.agentId}`, async () => {
+            const chat = new AgentConversation(this.options);
+            if (input.sessionId)
+                this.activeBySession.set(input.sessionId, chat);
+            else
+                this.activeByAgent.set(input.agentId, chat);
+            let openedSessionId;
+            try {
+                return await chat.send({
+                    ...input,
+                    onSessionOpened: (sessionId) => {
+                        openedSessionId = sessionId;
+                        this.activeBySession.set(sessionId, chat);
+                        input.onSessionOpened?.(sessionId);
+                    },
+                });
+            }
+            finally {
+                const sessionId = input.sessionId ?? openedSessionId;
+                if (sessionId && this.stopped.delete(sessionId))
+                    await this.release(sessionId);
+                if (sessionId && this.activeBySession.get(sessionId) === chat)
+                    this.activeBySession.delete(sessionId);
+                if (this.activeByAgent.get(input.agentId) === chat)
+                    this.activeByAgent.delete(input.agentId);
+            }
+        });
+    }
+    /** Stop the running turn on a session. Returns false when nothing was running. */
+    stop(sessionId) {
+        const chat = this.activeBySession.get(sessionId);
+        if (!chat)
+            return false;
+        this.stopped.add(sessionId);
+        chat.stop();
+        return true;
+    }
+    /** Let the runtime drop what it holds for a session (model session, isolated MCP processes). Never throws. */
+    async release(sessionId) {
+        try {
+            await this.options.backend.release?.(sessionId);
+        }
+        catch (error) {
+            this.options.logError?.(`releasing agent session ${sessionId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Stop a turn that is still opening its session (client left before the session id arrived). */
+    stopOpening(agentId) {
+        const chat = this.activeByAgent.get(agentId);
+        if (!chat)
+            return false;
+        chat.stop();
+        return true;
+    }
+}

package/dist/agents/communications/agentmail.d.ts

@@ -0,0 +1,19 @@
+import type { AgentInboundMessage } from "./port.js";
+export type AgentMailInboundConfig = {
+    connectionId: string;
+    webhookSecret: string;
+};
+export type AgentMailParseResult = {
+    ok: true;
+    message: AgentInboundMessage;
+} | {
+    ok: false;
+    code: "agent.signature_invalid" | "agent.invalid";
+};
+export declare function verifyAgentMailSignature(config: AgentMailInboundConfig, signatureHeader: string | undefined, rawBody: string): {
+    ok: true;
+} | {
+    ok: false;
+    code: "agent.signature_invalid";
+};
+export declare function parseAgentMailInbound(config: AgentMailInboundConfig, payload: unknown): AgentMailParseResult;