stageflow 0.35.0 → 0.39.0

package/README.md

@@ -34,8 +34,11 @@ The same pipeline runs three ways without rewriting anything:
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
 - **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
-- **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
+- **Agents** — project-owned, revisioned agents (`agents/*.agent.yaml`) with granted tools, ask-first approvals, traces, channels, schedules and a public web chat page ([guide](docs/agents.md))
+- **Operator console** — an Inbox for gates and agent approvals, pipeline runs, agents and their sessions, connections, MCP servers and settings at `http://127.0.0.1:3847` ([guide](docs/operator-console.md))
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
+- **MCP servers for agents and stages** — add servers, secrets and OAuth sign-in from Settings → Project MCP, or in the project `.mcp.json` ([guide](docs/mcp-servers.md))
+- **Connections** — Slack, Telegram, iMessage, WhatsApp and AgentMail channels, and email accounts, managed from one page ([guide](docs/channels.md))
 - **Standalone stage execution** — run a single stage directly with `run_stage` (MCP tool, `sf run-stage` CLI, or the A2A `run_stage` operation), no pipeline file required; chain calls with `envelope_ref` (one or many prior results) instead of a pipeline DAG
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
@@ -97,7 +100,7 @@ sf ui                          # operator console at http://127.0.0.1:3847
 sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
 ```
 
-**Workshop** (rail → `#/workshop`) drafts a pipeline in chat and saves it under `workshop/<pipeline-id>/` so it shows up on Run. Guide: [docs/workshop.md](docs/workshop.md).
+**Workshop** (**New pipeline** on the Pipelines page, or `#/workshop`; it has no rail item) drafts a pipeline in chat and saves it under `workshop/<pipeline-id>/` so it shows up on Run. Guide: [docs/workshop.md](docs/workshop.md).
 
 Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
@@ -140,11 +143,14 @@ Full reference: [docs/providers.md](docs/providers.md)
 
 Start the console with `sf ui` (default `http://127.0.0.1:3847`).
 
-- **Runs** — active and recent pipeline runs, capacity, and status at a glance
-- **Run detail** — spatial stage map; select a stage for the gated workspace (logs, files, envelopes, HITL). Created runs show **not started** with a **Start run** action until history exists
-- **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
-- **Pipelines** — browse manifest-declared pipeline definitions
-- **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)
+- **Inbox** — pipeline gates and agent approvals that wait on you, then failed and finished runs; Approve or Deny without leaving the page, with optional desktop notifications
+- **Pipeline runs** — active and recent runs, capacity, and status at a glance
+- **Run detail** — Timeline, Graph or List of the stages; select a stage for its transcript, events, envelope and artifacts. Created runs show **not started** with a **Start run** action until history exists
+- **Pipelines, Tasks, Catalog, Triggers** — browse and edit the YAML, start runs; **New pipeline** drafts one in the Workshop
+- **Agents** and **Agent sessions** — a directory with each agent's reach (web chat link, channel, schedule), cost and status; create and edit with version history; sessions, approvals and a run inspector
+- **Connections** — channels, email accounts and tool servers
+- **Settings** — Providers (`pi_home` or `sf_owned` credential storage), Concurrency, MCP server, Project MCP (servers, secrets, sign-in) and Notifications
+- **Command palette** — `⌘K` from any page. Page-by-page guide: [docs/operator-console.md](docs/operator-console.md)
 
 Brand assets live under `docs/img/` (`stageflow-og.svg`, `stageflow-icon.svg`).
 
@@ -266,7 +272,11 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/a2a.md](docs/a2a.md) | Publish pipelines for other agents to call over JSON-RPC (A2A), plus the wildcard-access `run_stage` operation |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
 | [docs/docker.md](docs/docker.md) | Docker Compose local try, image pull/run, backup, self-hosting |
-| [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
+| [docs/operator-console.md](docs/operator-console.md) | Console navigation, command palette, shortcuts and routes; one page per area ([Inbox](docs/console-inbox.md), [Runs](docs/console-runs.md), [Agents](docs/console-agents.md), [Connections](docs/console-connections.md), [Settings](docs/console-settings.md)) |
+| [docs/agents.md](docs/agents.md) | Agents: definition, runtime, approvals, channels, schedules, web chat |
+| [docs/mcp-servers.md](docs/mcp-servers.md) | Add MCP servers, secrets and OAuth; use them from agents and stages |
+| [docs/channels.md](docs/channels.md) | Connections and communication channels |
+| [docs/environment-variables.md](docs/environment-variables.md) | Every `STAGEFLOW_*` environment variable |
 | [docs/workshop.md](docs/workshop.md) | Workshop Author — chat-draft a pipeline, save it, and run it |
 | [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 

package/dist/agent/claudeAdapter.js

@@ -78,6 +78,18 @@ function preflight(input) {
             reason: `stage declares skill "${input.stage.skill}"; the claude agent backend does not support skills yet`,
         };
     }
+    if (input.stage.channels?.length) {
+        return {
+            ok: false,
+            reason: "stage declares channels; the claude agent backend does not provide send_message yet, so the stage would run without it",
+        };
+    }
+    if (input.stage.memories?.length) {
+        return {
+            ok: false,
+            reason: "stage pipeline declares memories; the claude agent backend does not provide read_memory, replace_memory, add_memory_card, update_memory_card, read_memory_card, and search_memory_cards yet, so the stage would run without them",
+        };
+    }
     return resolveClaudeModel(input.stage.model);
 }
 function resultFromCapture(capture, providerError) {

package/dist/agent/piAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type ExtensionFactory, SessionManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type ExtensionFactory, DefaultResourceLoader, SessionManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -76,6 +76,14 @@ export type RouteSessionEventToProgressOptions = {
 export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
 export declare function composeFeedbackResumePrompt(input: StageRunInput): string;
+export declare function mcpToolMetadataMissing(loader: DefaultResourceLoader): boolean;
+export declare function collectMcpExtensionToolNames(loader: DefaultResourceLoader): {
+    ok: true;
+    names: string[];
+} | {
+    ok: false;
+    unrequested: string[];
+};
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;
 export declare function resolveStageSessionFile(input: StageRunInput): string;

package/dist/agent/piAdapter.js

@@ -49,6 +49,9 @@ import { remindUntilEmitted } from "./stageTurnDriver.js";
 import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
 import { createSendEmailTool } from "../tools/sendEmail.js";
+import { createSendMessageTool } from "../tools/sendMessage.js";
+import { createMemoryStoreBashDenyExtension } from "../memory/bashDeny.js";
+import { memorySession } from "../tools/memoryTools.js";
 import { createReplyEmailTool } from "../tools/replyEmail.js";
 import { createGetEmailTool, createSearchEmailTool, createDownloadEmailAttachmentTool } from "../tools/readEmail.js";
 import "./cursorProvider.js";
@@ -493,6 +496,14 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             ].join("\n")
             : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
     return [
+        ...(input.stage.channels?.length ? [
+            `Stageflow channels: ${JSON.stringify(input.stage.channels.map(channel => ({ channel: channel.alias ?? channel.connection, operations: channel.operations })))}. Use send_message with the channel name. Recipients are fixed by configuration and you cannot change them. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
+        ] : []),
+        ...(input.memoryPrompt !== undefined
+            ? [input.memoryPrompt]
+            : input.memory
+                ? [memorySession(input.memory).prompt]
+                : []),
         ...(input.stage.email?.length ? [
             `Stageflow email permissions: ${JSON.stringify(input.stage.email)}. Use only declared accounts and operations. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
         ] : []),
@@ -562,10 +573,10 @@ function mcpExtensionTools(loader) {
         .extensions.filter((ext) => ext.path === inlinePath)
         .flatMap((ext) => [...ext.tools.keys()]);
 }
-function mcpToolMetadataMissing(loader) {
+export function mcpToolMetadataMissing(loader) {
     return mcpExtensionTools(loader).includes("mcp");
 }
-function collectMcpExtensionToolNames(loader) {
+export function collectMcpExtensionToolNames(loader) {
     const names = [];
     const unrequested = [];
     for (const name of mcpExtensionTools(loader)) {
@@ -924,6 +935,12 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                         : {}),
                 }),
             },
+            ...(input.stage.memories?.length
+                ? [{
+                        name: "stageflow-memory-bash-deny",
+                        factory: createMemoryStoreBashDenyExtension({ home: globalStageflowHome() }),
+                    }]
+                : []),
             {
                 name: STAGEFLOW_TOOL_OUTPUT_EXTENSION_NAME,
                 factory: createToolOutputBudgetExtension({
@@ -998,6 +1015,17 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             }
             tools.push(...mcpTools.names);
         }
+        if (input.channels && input.stage.channels?.some(channel => channel.operations.includes("send"))) {
+            const definition = createSendMessageTool(input.channels);
+            customTools.push(defineTool(definition));
+            tools.push(definition.name);
+        }
+        if (input.memory) {
+            for (const definition of memorySession(input.memory).tools) {
+                customTools.push(defineTool(definition));
+                tools.push(definition.name);
+            }
+        }
         if (input.email) {
             const permitted = new Set(input.stage.email?.flatMap(permission => permission.operations));
             const definitions = [

package/dist/agent/piIsolatedMcp.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { createEventBus, } from "@earendil-works/pi-coding-agent";
+import { prepareMcpOAuth } from "../config/mcpOAuth.js";
 import { StageMcpError, } from "../config/resolveStageMcpServers.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { TOOL_OUTPUT_HARD_CEILING_BYTES } from "./toolOutputBudget.js";
@@ -48,7 +49,7 @@ const EMPTY_ATTACH = {
     connecting: undefined,
 };
 let cachedCreateMcpAdapter;
-function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
+function toIsolatedMcpConfig(snapshot, lifecycle = "lazy", oauth = false) {
     const mcpServers = {};
     for (const [name, entry] of Object.entries(snapshot)) {
         const isolated = {
@@ -65,6 +66,7 @@ function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
         mcpServers,
         settings: {
             ...ISOLATED_MCP_SETTINGS,
+            ...(oauth ? { oauthCredentialStore: "encrypted-file" } : {}),
             outputGuard: { ...ISOLATED_MCP_SETTINGS.outputGuard },
         },
     };
@@ -235,11 +237,21 @@ export async function attachIsolatedMcp(snapshot, options) {
         return EMPTY_ATTACH;
     }
     const createMcpAdapter = await loadCreateMcpAdapter();
+    let oauth = false;
+    if (Object.values(snapshot).some((entry) => typeof entry.url === "string")) {
+        try {
+            prepareMcpOAuth();
+            oauth = true;
+        }
+        catch {
+            // Sign-in is optional; a store that cannot be prepared must not stop servers that need none.
+        }
+    }
     const extensionFactories = [
         {
             name: STAGEFLOW_PI_MCP_EXTENSION_NAME,
             factory: createMcpAdapter({
-                config: toIsolatedMcpConfig(snapshot, options?.lifecycle ?? "lazy"),
+                config: toIsolatedMcpConfig(snapshot, options?.lifecycle ?? "lazy", oauth),
             }),
         },
     ];

package/dist/agent/piIsolatedMcpProbe.d.ts

@@ -1,15 +1,19 @@
 import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
+import { type McpToolInfo } from "../config/mcpToolCache.js";
 export declare const PROJECT_MCP_PROBE_TIMEOUT_MS = 30000;
 export type ProjectMcpProbeStatus = "connected" | "needs_auth" | "connect_failed" | "unresolved_var" | "invalid_config" | "missing_catalog" | "cancelled";
 export type ProjectMcpProbeResult = {
     name: string;
     status: ProjectMcpProbeStatus;
     error?: string;
+    /** Tools the server lists, set when the probe connected. */
+    tools?: McpToolInfo[];
 };
 export type ProbeProjectMcpServerOptions = {
     projectRoot: string;
     name: string;
-    env?: NodeJS.ProcessEnv;
+    /** Host env that STAGEFLOW_MCP_ENV_ALLOW may draw from. Defaults to process.env; nothing else is read. */
+    hostEnv?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
     timeoutMs?: number;
 };

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

@@ -8,6 +8,8 @@ import type { StageActivityEvent } from "./activity.js";
 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. */
@@ -65,6 +67,11 @@ export type StageRunInput = {
     onAssistantTextDelta?: (delta: string) => void;
     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/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;
+}