@tea-agent/loop-agent 0.22.0 → 0.24.0

package/dist/worker/console/chat/pi-runtime.js

@@ -0,0 +1,1143 @@
+/**
+ * Operator Chat — Pi SDK runtime wrapper (plan W1 / M1).
+ *
+ * Wraps the Pi SDK's services-mode session API
+ * (createAgentSessionServices + createAgentSessionFromServices + SessionManager)
+ * into a small, testable surface that the Console HTTP layer can drive.
+ *
+ * Isolation guarantees (plan D4 / V12 / V14):
+ *   - Chat sessions are persisted to a DEDICATED sessionDir (not the user's
+ *     default ~/.pi/agent/sessions). Naming prefix `operator-chat-` makes them
+ *     auditable and cleanable (plan Q4 / Q8).
+ *   - The ResourceLoader is configured to NOT auto-load user extensions/skills
+ *     (noContextFiles / closed surface); credential/model plane is shared via
+ *     the same agentDir auth.json/models.json.
+ *   - Active tools are pinned to the operator-chat surface at session create
+ *     AND re-pinned before each prompt (three-gate, design §7.5): the FULL
+ *     operator action set (dynamic, from the registry) PLUS the built-in
+ *     read/explore tools (bash/read/grep/find/ls). File-WRITING coding tools
+ *     (edit/write/apply_patch/full-tools/shell/coding-chat) are excluded from
+ *     the SDK registry and can never be activated (2026-07-25 widening).
+ *
+ * The actual SDK calls are injected via `PiSdkBindings` so this module is
+ * unit-testable without a live Pi install. Production bindings come from
+ * `createDefaultPiSdkBindings()`.
+ */
+import { randomBytes } from "node:crypto";
+import { projectCompactSnapshot } from "./chat-event-store.js";
+import path from "node:path";
+import { extractUsageSample } from "./usage.js";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, authorizeOperatorChatTool, assertNoWriteToolInList, } from "./tools.js";
+import { createOperatorChatResourceLoader, } from "./resource-loader.js";
+import { loadOperatorChatInstructionSkills, composeInstructionSkillsPrompt, OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS, } from "./instruction-skills.js";
+import { buildModelCallableToolSchemas } from "./tool-adapter.js";
+import { resolveDefaultChatModel, } from "./model-resolver.js";
+import { filterActiveInterviewTools } from "../interview/tools.js";
+/**
+ * Base system prompt fragment every General Operator Chat session receives.
+ *
+ * Establishes the operator-vs-implementer role boundary (ADR 0005 D2) and the
+ * current tool surface contract (2026-07-25 widening): the Chat exposes the
+ * FULL operator action surface (all registry actions, including high-risk
+ * mutations like contractApply / runDag / dagRerun) PLUS the built-in
+ * read/explore tools (bash / read / grep / find / ls). The ONLY thing still
+ * forbidden is direct file-WRITING via coding tools (edit / write /
+ * apply_patch / full-tools / shell / coding-chat) — those are excluded from
+ * the SDK registry entirely and can never be activated.
+ *
+ * Instruction skills are appended AFTER this as read-only context (plan D1).
+ */
+const OPERATOR_CHAT_SYSTEM_PROMPT_BASE = [
+    "You are the General Operator Chat for loop-agent / agent-worker.",
+    "You are an OPERATOR: you orchestrate and inspect via the registered operator_* tools. You are NOT an implementer.",
+    "Tool surface: you have safe read-only explore tools (safe-read, safe-grep, git-status, git-diff, find, ls) to probe the repo, AND the model-callable operator_* tools. bash is NOT available (it was removed to close a write-via-redirect escape); use safe-read / safe-grep / git-status / git-diff instead.",
+    "safe-read / safe-grep enforce a repo-relative path boundary, a sensitive-file denylist (.env* / *.key / *.pem / .git/** / auth.json / sessions/**) and secret scrubbing. Do not attempt to read those files via any other path.",
+    "You do NOT have edit / write / apply_patch / full-tools / shell / coding-chat — file-WRITING is gated behind the DAG path. All canonical writes still go through DAG implement-pi / repair-pi, never via this chat.",
+    "High-risk mutations are not model-executable tools. Prepare contract via interview then apply via contractApply, prepare DAG runs via prepareDagConfirmation, prepare other mutations via prepareMutationGate, then confirm in the browser Human Gate. When a high-risk action (contractApply / runDag / dagRerun / etc.) fails on missing prepared state, use read-only tools (status, doctor, dagReport, inspect, contractShow, safe-read, safe-grep) to diagnose.",
+    "You cannot self-confirm a DAG run: confirmDagConfirmation is a human-only action (executed by the browser with a server-signed confirmation token). You may only prepare it via prepareDagConfirmation; the user must confirm in the UI.",
+    "Prefer read-only tools (status, doctor, dagReport, inspect, contractShow, safe-read, safe-grep, git-status) to diagnose before acting.",
+].join("\n");
+/**
+ * Built-in SDK read/explore tool names registered for every Chat session.
+ *
+ * M0-A (roadmap §14 工作块 A): bash is REMOVED — it could write files via
+ * `echo >` / `tee` / `sed -i` / `node -e writeFile`, bypassing the DAG write
+ * boundary. The residual read-only repo probing is served by the custom
+ * safe-read / safe-grep / find / ls tools (see buildExploreCustomTools) which
+ * enforce a repo-relative path boundary, a sensitive-file denylist, and
+ * secret scrubbing on the returned content. edit/write/... stay excluded.
+ */
+export const OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS = Object.freeze([
+    "find",
+    "ls",
+]);
+/**
+ * Canonical active tool-set handed to setActiveToolsByName at every gate:
+ * every model-callable operator action (dynamic, from the registry) PLUS the
+ * built-in explore tools (find/ls) PLUS the safe explore custom tools
+ * (safe-read / safe-grep / git-status / git-diff). bash is NOT here (M0-A).
+ * File-WRITING coding tools (edit/write/...) are never here — they are
+ * excluded at the registry level and thus cannot be activated.
+ */
+export const OPERATOR_CHAT_SAFE_EXPLORE_TOOL_IDS = Object.freeze([
+    "safe-read",
+    "safe-grep",
+    "git-status",
+    "git-diff",
+]);
+export function OPERATOR_CHAT_ACTIVE_TOOL_NAMES() {
+    return [
+        ...OPERATOR_CHAT_ALLOWED_TOOLS,
+        ...OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS,
+        ...OPERATOR_CHAT_SAFE_EXPLORE_TOOL_IDS,
+    ];
+}
+/**
+ * Build Pi custom ToolDefinition objects for every whitelisted operator action.
+ * Each tool's execute() routes into the operator action dispatcher (Gate 3).
+ * Requires the `typebox` + `defineTool` packages (both bundled with the SDK).
+ */
+async function buildCustomOperatorTools(options) {
+    // typebox is a transitive dep of @earendil-works/pi-coding-agent; Node's
+    // resolver hoists to the SDK's nested copy. defineTool is re-exported by SDK.
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const schemas = buildModelCallableToolSchemas();
+    const ctx = options.actionContext;
+    return schemas.map((schema) => {
+        // TypeBox schema is built dynamically; cast through unknown to the builder
+        // since Static<TParams> is structural and cannot be statically inferred here.
+        const parameters = Type.Object(schema.inputParams.reduce((acc, param) => {
+            let t;
+            switch (param.type) {
+                case "string":
+                    t = Type.String();
+                    break;
+                case "boolean":
+                    t = Type.Boolean();
+                    break;
+                case "number":
+                    t = Type.Number();
+                    break;
+                case "array":
+                    t = Type.Array(Type.String());
+                    break;
+                default:
+                    t = Type.Object({}, { additionalProperties: true });
+            }
+            acc[param.name] = param.required
+                ? t
+                : Type.Optional(t);
+            return acc;
+        }, {}), { additionalProperties: false });
+        return defineTool({
+            name: schema.toolId,
+            label: schema.toolId,
+            description: `${schema.description} (kind=${schema.kind}; cli: ${schema.cli})`,
+            promptSnippet: `${schema.toolId}: ${schema.description}`,
+            parameters: parameters,
+            async execute(toolCallId, params) {
+                const decision = authorizeOperatorChatTool(schema.toolId);
+                if (!decision.ok) {
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify({ error: decision.message, code: decision.code }) },
+                        ],
+                        details: { error: decision.message, code: decision.code },
+                    };
+                }
+                // Defer require to avoid circular import at module load.
+                const { dispatchChatToolCall } = await import("./session-store.js");
+                const result = await dispatchChatToolCall(ctx, decision.toolId, params, toolCallId);
+                const payload = result.ok
+                    ? result.result
+                    : { error: result.message, code: result.errorCode };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload) }],
+                    details: payload,
+                };
+            },
+        });
+    });
+}
+/**
+ * Build the safe explore custom tools (roadmap M0-A / G16): safe-read,
+ * safe-grep, gitStatus, gitDiff. These replace the bare SDK bash/read/grep so
+ * the model can probe the repo WITHOUT write escapes (echo redirect, tee,
+ * sed -i, node -e) and WITHOUT reading sensitive files (env files, key/pem,
+ * auth.json, sessions dir) — and every returned byte is secret-scrubbed
+ * before reaching the model context.
+ *
+ * gitStatus/gitDiff use a FIXED argv (typed, no shell) so they cannot be
+ * turned into an arbitrary-shell vector.
+ */
+async function buildExploreCustomTools(options) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const { execFileSync } = await import("node:child_process");
+    const repoRoot = options.repoRoot;
+    const { safeReadFile, safeGrep, scrubSecrets } = await import("./explore-tools.js");
+    function safeGit(args) {
+        try {
+            const stdout = execFileSync("git", args, {
+                cwd: repoRoot,
+                encoding: "utf8",
+                // Fixed argv, no shell, bounded output.
+                maxBuffer: 512 * 1024,
+                timeout: 10_000,
+                windowsHide: true,
+            });
+            return { ok: true, stdout };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                code: "GIT_FAILED",
+                message: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    const safeReadTool = defineTool({
+        name: "safe-read",
+        label: "safe-read",
+        description: "Read a repo-relative file with sensitive-file denylist (.env*/*.key/*.pem/.git/**/auth.json/sessions/**) and secret scrubbing. Absolute paths and .. are rejected.",
+        promptSnippet: "safe-read: read a repo file (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            path: Type.String({ description: "repo-relative file path" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const raw = String(params.path ?? "");
+            try {
+                const result = await safeReadFile(repoRoot, raw);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "READ_FAILED",
+                            }),
+                        },
+                    ],
+                    details: { error: err.message ?? String(e), code: err.code ?? "READ_FAILED" },
+                };
+            }
+        },
+    });
+    const safeGrepTool = defineTool({
+        name: "safe-grep",
+        label: "safe-grep",
+        description: "Line search across the repo working tree with sensitive-file denylist and secret scrubbing. pattern is a JS regex source; optional glob filters paths.",
+        promptSnippet: "safe-grep: search repo files (safe; secrets scrubbed)",
+        parameters: Type.Object({
+            pattern: Type.String({ description: "regex source (no shell)" }),
+            caseInsensitive: Type.Optional(Type.Boolean()),
+            glob: Type.Optional(Type.String({ description: "optional glob filter e.g. *.ts" })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const result = await safeGrep(repoRoot, String(params.pattern ?? ""), {
+                    caseInsensitive: Boolean(params.caseInsensitive),
+                    glob: params.glob ? String(params.glob) : undefined,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result) }],
+                    details: result,
+                };
+            }
+            catch (e) {
+                const err = e;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: err.message ?? String(e),
+                                code: err.code ?? "GREP_FAILED",
+                            }),
+                        },
+                    ],
+                    details: { error: err.message ?? String(e), code: err.code ?? "GREP_FAILED" },
+                };
+            }
+        },
+    });
+    const gitStatusTool = defineTool({
+        name: "git-status",
+        label: "git-status",
+        description: "Typed `git status --porcelain` (fixed argv, no shell). Returns scrubbed working-tree status.",
+        promptSnippet: "git-status: working tree status (read-only)",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute() {
+            const r = safeGit(["status", "--porcelain"]);
+            if (!r.ok) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: r.message, code: r.code }) }],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { status: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    const gitDiffTool = defineTool({
+        name: "git-diff",
+        label: "git-diff",
+        description: "Typed `git diff` (fixed argv: --stat or a single -- path; no shell). Returns scrubbed diff. path must be repo-relative and not sensitive.",
+        promptSnippet: "git-diff: diff (read-only, scrubbed)",
+        parameters: Type.Object({
+            path: Type.Optional(Type.String({ description: "optional repo-relative path to diff (default: whole tree --stat)" })),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            let rawPath = params.path ? String(params.path) : undefined;
+            // If a path is supplied, validate it via the read-path guard so git diff
+            // cannot be aimed at sensitive files (.env* / auth.json / sessions).
+            if (rawPath) {
+                const { guardReadPath } = await import("./explore-tools.js");
+                const g = await guardReadPath(repoRoot, rawPath);
+                if (!g.ok) {
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify({ error: g.message, code: g.code }) },
+                        ],
+                        details: { error: g.message, code: g.code },
+                    };
+                }
+                rawPath = g.repoRelative;
+            }
+            const args = rawPath
+                ? ["diff", "--", rawPath]
+                : ["diff", "--stat"];
+            const r = safeGit(args);
+            if (!r.ok) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: r.message, code: r.code }) }],
+                    details: { error: r.message, code: r.code },
+                };
+            }
+            const { scrubbed, redactions } = scrubSecrets(r.stdout);
+            const payload = { diff: scrubbed, redactions };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload) }],
+                details: payload,
+            };
+        },
+    });
+    return [safeReadTool, safeGrepTool, gitStatusTool, gitDiffTool];
+}
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * Extract the latest assistant text fragment from an SDK message object.
+ * Tolerant of multiple message shapes the SDK emits.
+ */
+export function extractAssistantText(message) {
+    if (!message || typeof message !== "object")
+        return "";
+    const m = message;
+    if (typeof m.text === "string")
+        return m.text;
+    const contents = Array.isArray(m.content) ? m.content : [];
+    const parts = Array.isArray(m.parts) ? m.parts : [];
+    const segments = [];
+    for (const c of [...contents, ...parts]) {
+        if (!c || typeof c !== "object")
+            continue;
+        const seg = c;
+        if (typeof seg.text === "string")
+            segments.push(seg.text);
+    }
+    return segments.join("");
+}
+/**
+ * Console Pi runtime — holds Chat sessions and drives prompt() with three-gate
+ * tool enforcement. Session-per-sessionId; cross-request reuse via open().
+ */
+export class ConsolePiRuntime {
+    options;
+    loader;
+    sessions = new Map();
+    modelRuntimes = new Map();
+    sessionManagers = new Map();
+    mainlineLeaves = new Map();
+    bindings;
+    disabledInstructionSkills = new Set();
+    constructor(options) {
+        this.options = options;
+        this.loader = createOperatorChatResourceLoader();
+        this.bindings =
+            options.bindings ?? createDefaultPiSdkBindings();
+    }
+    get sessionDir() {
+        return this.options.sessionDir;
+    }
+    /** Resolve the Pi agent directory for bounded Console configuration APIs. */
+    async getAgentDir() {
+        return safeGetAgentDir(this.bindings);
+    }
+    async testConfiguredModel(model) {
+        const { services } = await this.bindings.createServices({ cwd: this.options.cwd, agentDir: await this.getAgentDir() });
+        return { available: Boolean(this.bindings.resolveModel({ modelRuntime: services.modelRuntime, provider: model.provider, modelId: model.modelId })) };
+    }
+    setDisabledInstructionSkills(names) {
+        this.disabledInstructionSkills = new Set(names);
+    }
+    /** Operator action context used by custom-tool dispatchers (Gate 3). */
+    get actionContext() {
+        return this.options.actionContext;
+    }
+    /**
+     * Resolve the Chat default model descriptor from harness.json
+     * executors.pi.MED + the SDK available-model list. Returns undefined when
+     * harness is unset or no provider surfaces the model. No hardcoded fallback.
+     */
+    async resolveDefaultModel() {
+        let available;
+        try {
+            // Build a throwaway services just to read modelRuntime.snapshot. This is
+            // cheap (SDK caches); tests inject bindings that stub listAvailableModels.
+            const { services } = await this.bindings.createServices({
+                cwd: this.options.cwd,
+                agentDir: await safeGetAgentDir(this.bindings),
+            });
+            available = this.bindings.listAvailableModels({
+                modelRuntime: services.modelRuntime,
+            });
+        }
+        catch {
+            return undefined;
+        }
+        const descriptor = await resolveDefaultChatModel(this.options.cwd, available);
+        if (!descriptor)
+            return undefined;
+        return {
+            provider: descriptor.provider,
+            modelId: descriptor.modelId,
+        };
+    }
+    /**
+     * Load the operator-context instruction skills (plan D1) and compose the
+     * read-only methodology fragment for the Chat system prompt. Returns an
+     * empty string when no skills load (e.g. skills dir missing) so the
+     * session still boots — skills are context, not a hard dependency.
+     */
+    async composeSystemPromptSkills() {
+        try {
+            const result = await loadOperatorChatInstructionSkills(this.options.skillsDir, OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.filter((name) => !this.disabledInstructionSkills.has(name)));
+            return composeInstructionSkillsPrompt(result.loaded);
+        }
+        catch (error) {
+            process.stderr.write(`[console] chat instruction-skills load failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            return "";
+        }
+    }
+    /** Create a new isolated Chat session pinned to the operator-chat tool set. */
+    async createSession(init) {
+        const sessionId = `operator-chat-${randomBytes(12).toString("hex")}`;
+        const agentDir = await safeGetAgentDir(this.bindings);
+        // Resolve default model from harness.json executors.pi.MED (no hardcode).
+        // Caller may pass an explicit model; otherwise we read the repo harness and
+        // search the SDK available-model list for a credentialled provider.
+        let model = init?.model;
+        if (!model) {
+            const resolved = await this.resolveDefaultModel();
+            if (resolved)
+                model = resolved;
+        }
+        // Final fallback only when nothing resolved: let the SDK pick its default
+        // (we do NOT hardcode a provider here).
+        // Load operator-context instruction skills (plan D1) and compose the
+        // read-only methodology fragment injected into the Chat system prompt.
+        // Skills are NEVER registered as executable tools (D1 hard rule).
+        const skillFragment = await this.composeSystemPromptSkills();
+        const appendSystemPrompt = [
+            OPERATOR_CHAT_SYSTEM_PROMPT_BASE,
+            ...(skillFragment ? [skillFragment] : []),
+            ...(init?.systemPromptSuffix ? [init.systemPromptSuffix] : []),
+        ];
+        const { services } = await this.bindings.createServices({
+            cwd: this.options.cwd,
+            agentDir,
+            resourceLoaderOptions: {
+                // Closed surface: do not load user/project extensions, skills,
+                // AGENTS.md, context files. The Chat tool surface is fixed by
+                // the whitelist, not by filesystem discovery.
+                noContextFiles: true,
+                noSkills: true,
+                noExtensions: true,
+                // Inject the audited instruction skills as READ-ONLY context
+                // (plan D1). appendSystemPrompt is the SDK's documented entry
+                // point for adding system-prompt text without enabling tools.
+                appendSystemPrompt,
+            },
+        });
+        const modelRuntime = services.modelRuntime;
+        // Resolve the concrete SDK model only when we have a descriptor. When no
+        // model is resolved (harness unset + no snapshot match), we omit `model`
+        // and let the SDK session use its own default (no hardcoded fallback).
+        const resolvedModel = model
+            ? (this.bindings.resolveModel({
+                modelRuntime,
+                provider: model.provider,
+                modelId: model.modelId,
+            }) ?? undefined)
+            : undefined;
+        const sessionManager = await this.bindings.createSessionManager({
+            cwd: this.options.cwd,
+            sessionDir: this.options.sessionDir,
+            sessionId,
+        });
+        // Gate 1: pin the tool set at session create. assertNoWriteTool guards
+        // that no file-WRITING coding tool slipped into the allowed list (bash
+        // is intentionally allowed since the 2026-07-25 widening).
+        assertNoWriteToolInList(OPERATOR_CHAT_ALLOWED_TOOLS);
+        // Build custom Pi tools that route whitelisted operator actions into
+        // the dispatcher (Gate 3 lives inside each tool's execute()).
+        let operatorCustomTools = [];
+        if (this.options.actionContext) {
+            try {
+                operatorCustomTools = await buildCustomOperatorTools({
+                    actionContext: this.options.actionContext,
+                });
+            }
+            catch (error) {
+                // If custom-tool build fails (e.g. typebox unavailable), fall back to
+                // a tool-less session — Chat still works as text-only, and the
+                // failure is surfaced via doctor / readiness diagnostics.
+                process.stderr.write(`[console] chat custom-tools build failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        // M0-A: also register the safe explore tools (safe-read / safe-grep /
+        // git-status / git-diff) so the model can probe the repo without bash.
+        let exploreCustomTools = [];
+        try {
+            exploreCustomTools = await buildExploreCustomTools({
+                repoRoot: this.options.cwd,
+            });
+        }
+        catch (error) {
+            process.stderr.write(`[console] chat explore-tools build failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        const customTools = [...operatorCustomTools, ...exploreCustomTools];
+        // Tool surface (roadmap M0):
+        //   - ALL model-callable operator actions are registered as customTools.
+        //   - Safe explore tools (safe-read / safe-grep / git-status / git-diff)
+        //     are also registered as customTools (bash is GONE — M0-A removes
+        //     the write-via-redirect escape).
+        //   - Built-in find/ls are registered by passing `tools:` (Gate 1). The
+        //     default builtin read/bash/edit/write are EXCLUDED: read/bash/grep
+        //     are replaced by the safe custom versions above; edit/write stay
+        //     excluded (file-writing never activated).
+        //     by passing `tools: OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS` (Gate 1).
+        //     This is REQUIRED: the SDK's default builtin set is only
+        //     `read, bash, edit, write` (grep/find/ls are NOT default builtins —
+        //     see SDK CreateAgentSessionOptions.tools docs). Without `tools`, the
+        const { session } = await this.bindings.createSessionFromServices({
+            services,
+            sessionManager,
+            // Explicitly register the explore-tool builtin set (Gate 1): find/ls.
+            // The default builtin read/bash/edit/write are EXCLUDED below; read/
+            // grep/bash are replaced by the safe customTools (M0-A).
+            tools: [...OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS],
+            excludeTools: [
+                "edit",
+                "write",
+                "apply_patch",
+                "apply-patch",
+                "full-tools",
+                "full_tools",
+                "coding-chat",
+                "coding_chat",
+                "shell",
+                // M0-A: bash is removed entirely (write-via-redirect escape). The
+                // model gets safe-read / safe-grep custom tools instead.
+                "bash",
+                // M0-A: built-in read/grep are replaced by custom safe-read/safe-grep
+                // that enforce a repo-relative boundary, a sensitive-file denylist,
+                // and secret scrubbing (roadmap G16).
+                "read",
+                "grep",
+            ],
+            ...(customTools && customTools.length > 0
+                ? { customTools }
+                : {}),
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+        });
+        // Gate 2: re-pin active tools (defensive — some SDK paths may seed
+        // defaults). Active set = all operator actions + built-in explore tools.
+        // File-writing tools are excluded above and thus cannot appear here.
+        session.setActiveToolsByName(OPERATOR_CHAT_ACTIVE_TOOL_NAMES());
+        this.sessions.set(sessionId, session);
+        this.sessionManagers.set(sessionId, sessionManager);
+        this.modelRuntimes.set(sessionId, modelRuntime);
+        return {
+            sessionId,
+            sessionFile: session.sessionFile,
+            createdAt: new Date().toISOString(),
+            model,
+            activeTools: session.getActiveToolNames(),
+        };
+    }
+    async forkSession(init) {
+        if (!this.bindings.forkSessionManager)
+            throw new Error("SESSION_FORK_UNSUPPORTED");
+        const sessionId = `operator-chat-${randomBytes(12).toString("hex")}`;
+        const sessionManager = await this.bindings.forkSessionManager({
+            sourcePath: init.sourceSessionFile,
+            targetCwd: this.options.cwd,
+            targetSessionDir: this.options.sessionDir,
+            targetSessionId: sessionId,
+        });
+        const built = await this.buildSessionWithServices({ sessionManager, model: init.model });
+        built.session.setActiveToolsByName(OPERATOR_CHAT_ACTIVE_TOOL_NAMES());
+        this.sessions.set(sessionId, built.session);
+        this.sessionManagers.set(sessionId, sessionManager);
+        this.modelRuntimes.set(sessionId, built.modelRuntime);
+        return { sessionId, sessionFile: built.session.sessionFile, createdAt: new Date().toISOString(), model: init.model, activeTools: built.session.getActiveToolNames() };
+    }
+    async branchSession(input) {
+        const session = this.sessions.get(input.sessionId);
+        const manager = this.sessionManagers.get(input.sessionId);
+        if (!session || !manager)
+            throw new Error(`chat session not active: ${input.sessionId}`);
+        if (session.isStreaming === true || session.isIdle === false)
+            throw new Error("CHAT_TURN_ACTIVE");
+        if (!manager.getEntry?.(input.branchFromEntryId))
+            throw new Error("BRANCH_ENTRY_NOT_FOUND");
+        if (!this.mainlineLeaves.has(input.sessionId))
+            this.mainlineLeaves.set(input.sessionId, manager.getLeafId?.());
+        const entry = input.summary
+            ? manager.branchWithSummary?.(input.branchFromEntryId, input.summary)
+            : (manager.branch(input.branchFromEntryId), undefined);
+        return { branchedFromEntryId: input.branchFromEntryId, ...(entry?.id ? { branchSummaryEntryId: entry.id } : {}) };
+    }
+    switchToMainline(sessionId) {
+        const manager = this.sessionManagers.get(sessionId);
+        if (!manager)
+            throw new Error(`chat session not active: ${sessionId}`);
+        manager.branch(this.mainlineLeaves.get(sessionId));
+        this.mainlineLeaves.delete(sessionId);
+    }
+    getBranchContext(sessionId) {
+        const manager = this.sessionManagers.get(sessionId);
+        if (!manager)
+            throw new Error(`chat session not active: ${sessionId}`);
+        return { leafId: manager.getLeafId?.() ?? null, entries: manager.getBranch?.() ?? [] };
+    }
+    async listModels(sessionId) {
+        const modelRuntime = this.modelRuntimes.get(sessionId);
+        if (!this.sessions.has(sessionId) || !modelRuntime)
+            throw new Error(`chat session not active: ${sessionId}`);
+        return this.bindings.listAvailableModels({ modelRuntime });
+    }
+    async applyModel(sessionId, model) {
+        const session = this.sessions.get(sessionId);
+        const modelRuntime = this.modelRuntimes.get(sessionId);
+        if (!session || !modelRuntime)
+            throw new Error(`chat session not active: ${sessionId}`);
+        if (!session.setModel)
+            throw new Error("MODEL_SWITCH_UNSUPPORTED");
+        const resolved = this.bindings.resolveModel({ modelRuntime, provider: model.provider, modelId: model.modelId });
+        if (!resolved)
+            throw new Error("MODEL_NOT_AVAILABLE");
+        await session.setModel(resolved);
+        return { provider: session.model?.provider ?? model.provider, modelId: session.model?.id ?? session.model?.modelId ?? model.modelId };
+    }
+    applyThinkingLevel(sessionId, level) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`chat session not active: ${sessionId}`);
+        if (!THINKING_LEVELS.includes(level) || !session.setThinkingLevel)
+            throw new Error("THINKING_LEVEL_UNSUPPORTED");
+        session.setThinkingLevel(level);
+        return session.thinkingLevel ?? level;
+    }
+    getRuntimeSelection(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return { activeTools: [] };
+        const provider = session.model?.provider;
+        const modelId = session.model?.id ?? session.model?.modelId;
+        return { ...(provider && modelId ? { model: { provider, modelId } } : {}), ...(session.thinkingLevel ? { thinkingLevel: session.thinkingLevel } : {}), activeTools: session.getActiveToolNames() };
+    }
+    /**
+     * Re-open a previously persisted Chat session after Console restart or
+     * browser refresh (roadmap M1-S04 / S05).
+     *
+     * Unlike `createSession`, this reuses the EXISTING Pi JSONL session file so
+     * the conversation history is preserved. The SDK's `SessionManager.open(path)`
+     * loads the file; we then rebuild the same services + pinned tool surface so
+     * the operator-chat three-gate policy still applies after a restart.
+     *
+     * Fail-closed contract: if `sessionFile` is missing, or the SDK cannot open
+     * it (file deleted/corrupt), returns an `{ ok: false, code }` result rather
+     * than silently creating a fresh empty session and losing prior context.
+     */
+    async reopenSession(init) {
+        const sessionId = init.sessionId;
+        // Already active in-memory: idempotent reopen is a no-op success.
+        if (this.sessions.has(sessionId)) {
+            return { ok: true, handle: await this.snapshotActive(sessionId) };
+        }
+        if (!init.sessionFile) {
+            return {
+                ok: false,
+                code: "NO_SESSION_FILE",
+                message: `cannot reopen chat session ${sessionId}: no persisted Pi session file`,
+            };
+        }
+        let sessionManager;
+        try {
+            sessionManager = await this.bindings.openSessionManager({
+                sessionFile: init.sessionFile,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: "REOPEN_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (!sessionManager) {
+            return {
+                ok: false,
+                code: "REOPEN_FAILED",
+                message: `Pi session file not openable: ${init.sessionFile}`,
+            };
+        }
+        try {
+            const built = await this.buildSessionWithServices({
+                sessionManager,
+                model: init.model,
+                systemPromptSuffix: init.systemPromptSuffix,
+            });
+            const session = built.session;
+            // The reopened session MUST report the SAME sessionId as the durable
+            // record, otherwise we'd be serving a different conversation under a
+            // stale id. Mismatch is a fail-closed reopen failure.
+            if (session.sessionId !== sessionId) {
+                try {
+                    session.dispose();
+                }
+                catch {
+                    // ignore
+                }
+                return {
+                    ok: false,
+                    code: "REOPEN_FAILED",
+                    message: `reopened Pi sessionId mismatch: expected ${sessionId}, got ${session.sessionId}`,
+                };
+            }
+            session.setActiveToolsByName(OPERATOR_CHAT_ACTIVE_TOOL_NAMES());
+            this.sessions.set(sessionId, session);
+            this.sessionManagers.set(sessionId, sessionManager);
+            this.modelRuntimes.set(sessionId, built.modelRuntime);
+            return {
+                ok: true,
+                handle: {
+                    sessionId,
+                    sessionFile: session.sessionFile ?? init.sessionFile,
+                    createdAt: new Date().toISOString(),
+                    model: init.model,
+                    activeTools: session.getActiveToolNames(),
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: "REOPEN_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /** Build a handle for an already-active session (idempotent reopen path). */
+    async snapshotActive(sessionId) {
+        const session = this.sessions.get(sessionId);
+        return {
+            sessionId,
+            sessionFile: session.sessionFile,
+            createdAt: new Date().toISOString(),
+            model: undefined,
+            activeTools: session.getActiveToolNames(),
+        };
+    }
+    /**
+     * Shared services + pinned-tool materialization for both createSession and
+     * reopenSession. Loads closed-surface services, resolves the model, builds
+     * the operator + safe explore customTools, and calls the SDK with the same
+     * excludeTools / tools policy (M0-A three-gate).
+     */
+    async buildSessionWithServices(init) {
+        const agentDir = await safeGetAgentDir(this.bindings);
+        const skillFragment = await this.composeSystemPromptSkills();
+        const appendSystemPrompt = [
+            OPERATOR_CHAT_SYSTEM_PROMPT_BASE,
+            ...(skillFragment ? [skillFragment] : []),
+            ...(init.systemPromptSuffix ? [init.systemPromptSuffix] : []),
+        ];
+        const { services } = await this.bindings.createServices({
+            cwd: this.options.cwd,
+            agentDir,
+            resourceLoaderOptions: {
+                noContextFiles: true,
+                noSkills: true,
+                noExtensions: true,
+                appendSystemPrompt,
+            },
+        });
+        const modelRuntime = services.modelRuntime;
+        const resolvedModel = init.model
+            ? (this.bindings.resolveModel({
+                modelRuntime,
+                provider: init.model.provider,
+                modelId: init.model.modelId,
+            }) ?? undefined)
+            : undefined;
+        assertNoWriteToolInList(OPERATOR_CHAT_ALLOWED_TOOLS);
+        let operatorCustomTools = [];
+        if (this.options.actionContext) {
+            try {
+                operatorCustomTools = await buildCustomOperatorTools({
+                    actionContext: this.options.actionContext,
+                });
+            }
+            catch (error) {
+                process.stderr.write(`[console] chat custom-tools build failed: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        let exploreCustomTools = [];
+        try {
+            exploreCustomTools = await buildExploreCustomTools({
+                repoRoot: this.options.cwd,
+            });
+        }
+        catch (error) {
+            process.stderr.write(`[console] chat explore-tools build failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        const customTools = [...operatorCustomTools, ...exploreCustomTools];
+        const { session } = await this.bindings.createSessionFromServices({
+            services,
+            sessionManager: init.sessionManager,
+            tools: [...OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS],
+            excludeTools: [
+                "edit",
+                "write",
+                "apply_patch",
+                "apply-patch",
+                "full-tools",
+                "full_tools",
+                "coding-chat",
+                "coding_chat",
+                "shell",
+                "bash",
+                "read",
+                "grep",
+            ],
+            ...(customTools && customTools.length > 0 ? { customTools } : {}),
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+        });
+        return { session, modelRuntime };
+    }
+    /** Re-open a previously created session (cross-request). */
+    open(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    hasSession(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * Send a prompt and stream events. Gate 3: each tool invocation is
+     * re-authorized by authorizeOperatorChatTool before the dispatcher runs it
+     * (the dispatcher is wired by the HTTP layer, see chat-session.ts).
+     */
+    async prompt(sessionId, text, onEvent, options) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`chat session not found: ${sessionId}`);
+        }
+        // Gate 2 (re-pin before each turn): interview turns pass through the
+        // existing closed interview allow/deny registry. The next ordinary turn
+        // explicitly restores the normal Operator Chat set.
+        const requestedTools = OPERATOR_CHAT_ACTIVE_TOOL_NAMES();
+        const activeTools = options?.mode === "requirement-interview"
+            ? filterActiveInterviewTools(requestedTools).allowed
+            : requestedTools;
+        session.setActiveToolsByName(activeTools);
+        const unsub = session.subscribe((event) => {
+            const mapped = mapSdkEvent(sessionId, event);
+            if (mapped)
+                onEvent(mapped);
+        });
+        const onAbort = () => {
+            // M1 T08: Stop must abort only the current turn, NOT dispose the
+            // session. SDK AgentSession.abort() aborts the current operation and
+            // waits for the agent to become idle, keeping the session reusable for
+            // the next turn. Only fall back to dispose if the session has no abort()
+            // (e.g. a minimal stub), since a stuck turn should not leak forever.
+            try {
+                if (typeof session.abort === "function") {
+                    void session.abort();
+                }
+                else {
+                    session.dispose();
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        options?.signal?.addEventListener("abort", onAbort);
+        try {
+            await session.prompt(text, options?.images?.length ? { images: options.images } : undefined);
+            // Wait until the session reports idle / not streaming. The SDK prompt()
+            // resolves when the agent turn completes, but post-turn continuation
+            // (auto-compaction / follow-up) may still be in flight. We poll isIdle.
+            // While polling we emit periodic heartbeat events so the SSE stream
+            // keeps proxies/browsers from timing out (no other data is flowing).
+            await waitForIdle(session, {
+                signal: options?.signal,
+                onHeartbeat: () => onEvent({ type: "heartbeat", sessionId }),
+            });
+            onEvent({ type: "agent_settled", sessionId });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            onEvent({ type: "error", sessionId, message });
+            throw error;
+        }
+        finally {
+            options?.signal?.removeEventListener("abort", onAbort);
+            unsub();
+        }
+    }
+    async compact(sessionId, customInstructions) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`chat session not found: ${sessionId}`);
+        if (session.isStreaming === true || session.isIdle === false)
+            throw new Error("CHAT_TURN_ACTIVE");
+        if (typeof session.compact !== "function")
+            throw new Error("COMPACTION_UNSUPPORTED");
+        const result = await session.compact(customInstructions);
+        return projectCompactSnapshot(result ?? {});
+    }
+    dispose(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            try {
+                session.dispose();
+            }
+            catch {
+                // ignore
+            }
+            this.sessions.delete(sessionId);
+            this.sessionManagers.delete(sessionId);
+            this.mainlineLeaves.delete(sessionId);
+            this.modelRuntimes.delete(sessionId);
+        }
+    }
+    disposeAll() {
+        for (const id of [...this.sessions.keys()])
+            this.dispose(id);
+    }
+}
+function mapSdkEvent(sessionId, event) {
+    switch (event.type) {
+        case "agent_start":
+            return { type: "agent_start", sessionId };
+        case "agent_end":
+            return {
+                type: "agent_end",
+                sessionId,
+                willRetry: Boolean(event.willRetry),
+            };
+        case "message_update":
+            return {
+                type: "message_update",
+                sessionId,
+                text: extractAssistantText(event.message),
+            };
+        case "message_end":
+            return { type: "message_end", sessionId, text: extractAssistantText(event.message) };
+        case "turn_end": {
+            const usage = extractUsageSample(event);
+            return usage ? { type: "usage", sessionId, usage } : undefined;
+        }
+        case "tool_execution_start":
+            return {
+                type: "tool_call",
+                sessionId,
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                args: event.args,
+            };
+        case "tool_execution_end":
+            return {
+                type: "tool_result",
+                sessionId,
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                result: event.result,
+                isError: event.isError,
+            };
+        case "agent_settled":
+            return { type: "agent_settled", sessionId };
+        default:
+            return undefined;
+    }
+}
+async function waitForIdle(session, options) {
+    // Default 45s — shorter than the previous 120s so a stuck SDK session does
+    // not pin an HTTP connection for two full minutes. The SDK agent turn
+    // normally settles in seconds; 45s covers auto-compaction/follow-up tails
+    // while staying under typical proxy idle timeouts (60s).
+    const timeoutMs = options?.timeoutMs ?? 45_000;
+    const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 10_000;
+    const start = Date.now();
+    let lastHeartbeat = start;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (options?.signal?.aborted)
+            return;
+        if (session.isIdle === true)
+            return;
+        if (session.isStreaming === false)
+            return;
+        const now = Date.now();
+        if (now - start > timeoutMs)
+            return;
+        if (options?.onHeartbeat && now - lastHeartbeat >= heartbeatIntervalMs) {
+            lastHeartbeat = now;
+            try {
+                options.onHeartbeat();
+            }
+            catch {
+                // Heartbeat is best-effort; never let it break the wait loop.
+            }
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+async function safeGetAgentDir(bindings) {
+    try {
+        return await bindings.getAgentDir();
+    }
+    catch {
+        // Fall back to a Console-app-data scoped agent dir so we never accidentally
+        // touch the user's real ~/.pi/agent config if getAgentDir throws.
+        return path.join(process.cwd(), ".harness", "console", "pi-agent-dir");
+    }
+}
+/**
+ * Cached SDK module loader. The pi-coding-agent package is ESM-only, so we
+ * must use dynamic import() (not require). Cached to avoid repeated imports.
+ */
+let cachedSdk;
+async function loadSdk() {
+    if (!cachedSdk) {
+        cachedSdk = import("@earendil-works/pi-coding-agent");
+    }
+    return cachedSdk;
+}
+/**
+ * Default production bindings backed by the real Pi SDK (services mode).
+ * Dynamically imported so the worker bundle does not hard-fail if the SDK is
+ * absent at module load (discovered lazily by pi-readiness instead).
+ */
+export function createDefaultPiSdkBindings() {
+    return {
+        getAgentDir: async () => {
+            const sdk = (await loadSdk());
+            return sdk.getAgentDir();
+        },
+        createServices: async (opts) => {
+            const sdk = (await loadSdk());
+            // createAgentSessionServices returns the full AgentSessionServices object
+            // directly (cwd/agentDir/modelRuntime/settingsManager/resourceLoader).
+            // Wrap it so our type contract is satisfied.
+            const result = await sdk.createAgentSessionServices({
+                cwd: opts.cwd,
+                agentDir: opts.agentDir,
+                resourceLoaderOptions: opts.resourceLoaderOptions,
+            });
+            return { services: result };
+        },
+        createSessionFromServices: async (opts) => {
+            const sdk = (await loadSdk());
+            return sdk.createAgentSessionFromServices({
+                services: opts.services,
+                sessionManager: opts.sessionManager,
+                ...(opts.tools ? { tools: opts.tools } : {}),
+                ...(opts.noTools ? { noTools: opts.noTools } : {}),
+                ...(opts.excludeTools ? { excludeTools: opts.excludeTools } : {}),
+                ...(opts.customTools ? { customTools: opts.customTools } : {}),
+                ...(opts.model ? { model: opts.model } : {}),
+            });
+        },
+        createSessionManager: async (opts) => {
+            const sdk = (await loadSdk());
+            return sdk.SessionManager.create(opts.cwd, opts.sessionDir, {
+                id: opts.sessionId,
+            });
+        },
+        forkSessionManager: async (opts) => {
+            const sdk = (await loadSdk());
+            return sdk.SessionManager.forkFrom(opts.sourcePath, opts.targetCwd, opts.targetSessionDir, { id: opts.targetSessionId });
+        },
+        openSessionManager: async (opts) => {
+            const sdk = (await loadSdk());
+            try {
+                return sdk.SessionManager.open(opts.sessionFile);
+            }
+            catch {
+                // Missing/corrupt session file — caller fails closed rather than
+                // silently creating a fresh session and losing prior context.
+                return undefined;
+            }
+        },
+        resolveModel: (opts) => {
+            const rt = opts.modelRuntime;
+            if (typeof rt?.getModel !== "function")
+                return undefined;
+            try {
+                return rt.getModel(opts.provider, opts.modelId);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        listAvailableModels: (opts) => {
+            const rt = opts.modelRuntime;
+            const available = rt?.snapshot?.available ?? [];
+            const configured = rt?.snapshot?.configuredProviders;
+            const isConfigured = (provider) => configured instanceof Set ? configured.has(provider) : false;
+            return available.map((m) => ({
+                id: m.id,
+                name: m.name,
+                provider: m.provider,
+                hasCredentials: isConfigured(m.provider),
+            }));
+        },
+    };
+}
+/**
+ * Re-export the tool gate for the dispatcher layer so the per-tool-call gate
+ * (Gate 3) lives in exactly one place.
+ */
+export { authorizeOperatorChatTool, assertNoWriteToolInList, OPERATOR_CHAT_ALLOWED_TOOLS, };