@tea-agent/loop-agent 0.21.0 → 0.23.1

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

@@ -0,0 +1,605 @@
+/**
+ * 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 path from "node:path";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, authorizeOperatorChatTool, assertNoWriteToolInList, } from "./tools.js";
+import { createOperatorChatResourceLoader, } from "./resource-loader.js";
+import { loadOperatorChatInstructionSkills, composeInstructionSkillsPrompt, } from "./instruction-skills.js";
+import { buildOperatorChatToolSchemas } from "./tool-adapter.js";
+import { resolveDefaultChatModel, } from "./model-resolver.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 the built-in read/explore tools (bash, read, grep, find, ls) to probe the repo, AND the full set of operator_* tools (all registered operator actions, including high-risk mutations such as contractApply / runDag / dagRerun / standaloneTaskRerun / workerTaskRetry / importPrd / confirmDagConfirmation / dagRunTask).",
+    "You do NOT have edit / write / apply_patch / full-tools / shell / coding-chat — file-WRITING is still gated behind the DAG path. All canonical writes still go through DAG implement-pi / repair-pi, never via this chat. The residual write-via-bash-redirect risk (`echo >` / `tee`) is an accepted documented residual.",
+    "High-risk mutations are now callable as tools, but each still requires its prepared receipt (e.g. contractApply needs a fresh complete assessment; runDag needs a confirmationId from prepareDagConfirmation; dagRerun needs a planHash). When a high-risk action fails on missing prepared state, use read-only tools (status, doctor, dagReport, inspect, contractShow) to diagnose, then tell the user to prepare the receipt via the human-confirmation page if needed.",
+    "Prefer read-only tools (status, doctor, dagReport, inspect, contractShow) to diagnose before acting.",
+].join("\n");
+/**
+ * Built-in SDK read/explore tool names registered for every Chat session.
+ *
+ * These MUST be passed as `tools:` to createSessionFromServices (Gate 1) so the
+ * SDK actually registers grep/find/ls — its default builtin set is only
+ * read/bash/edit/write. Excluding edit/write via excludeTools then leaves
+ * exactly bash/read/grep/find/ls as the builtin surface.
+ */
+export const OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS = Object.freeze([
+    "bash",
+    "read",
+    "grep",
+    "find",
+    "ls",
+]);
+/**
+ * Canonical active tool-set handed to setActiveToolsByName at every gate:
+ * every operator action (dynamic, from the registry) PLUS the built-in
+ * explore tools. File-WRITING coding tools (edit/write/...) are never here —
+ * they are excluded at the registry level and thus cannot be activated.
+ */
+export function OPERATOR_CHAT_ACTIVE_TOOL_NAMES() {
+    return [...OPERATOR_CHAT_ALLOWED_TOOLS, ...OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS];
+}
+/**
+ * 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 = buildOperatorChatToolSchemas();
+    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,
+                };
+            },
+        });
+    });
+}
+/**
+ * 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();
+    bindings;
+    constructor(options) {
+        this.options = options;
+        this.loader = createOperatorChatResourceLoader();
+        this.bindings =
+            options.bindings ?? createDefaultPiSdkBindings();
+    }
+    get sessionDir() {
+        return this.options.sessionDir;
+    }
+    /** 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);
+            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 customTools;
+        if (this.options.actionContext) {
+            try {
+                customTools = 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`);
+            }
+        }
+        // Tool surface (2026-07-25 widening):
+        //   - ALL operator actions are registered as customTools (full runtime
+        //     capability surface — derived dynamically from the registry).
+        //   - Built-in read/explore tools (bash/read/grep/find/ls) are registered
+        //     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
+        //     later setActiveToolsByName(["grep","find","ls"]) would silently
+        //     no-op because those tools would not exist in the registry.
+        //   - We then exclude edit/write so the only file-WRITING path is gone.
+        //   - bash is bare (no command filter); the residual write-via-redirect
+        //     risk is accepted (exec-plan Q9).
+        const { session } = await this.bindings.createSessionFromServices({
+            services,
+            sessionManager,
+            // Explicitly register the explore-tool builtin set (Gate 1). This is
+            // what makes grep/find/ls actually available — the SDK default builtin
+            // set is only read/bash/edit/write. Combined with excludeTools below,
+            // the effective registry = explore tools + customTools (operator actions).
+            tools: [...OPERATOR_CHAT_BUILTIN_EXPLORE_TOOLS],
+            excludeTools: [
+                "edit",
+                "write",
+                "apply_patch",
+                "apply-patch",
+                "full-tools",
+                "full_tools",
+                "coding-chat",
+                "coding_chat",
+                "shell",
+            ],
+            ...(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);
+        return {
+            sessionId,
+            sessionFile: session.sessionFile,
+            createdAt: new Date().toISOString(),
+            model,
+            activeTools: session.getActiveToolNames(),
+        };
+    }
+    /** 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): defend against any mid-session drift.
+        session.setActiveToolsByName(OPERATOR_CHAT_ACTIVE_TOOL_NAMES());
+        const unsub = session.subscribe((event) => {
+            const mapped = mapSdkEvent(sessionId, event);
+            if (mapped)
+                onEvent(mapped);
+        });
+        const onAbort = () => {
+            try {
+                session.dispose();
+            }
+            catch {
+                // ignore
+            }
+        };
+        options?.signal?.addEventListener("abort", onAbort);
+        try {
+            await session.prompt(text);
+            // 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();
+        }
+    }
+    dispose(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            try {
+                session.dispose();
+            }
+            catch {
+                // ignore
+            }
+            this.sessions.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 "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,
+            });
+        },
+        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, };

package/dist/worker/console/chat/resource-loader.js

@@ -0,0 +1,66 @@
+/**
+ * Operator Chat — closed ResourceLoader contract (design §7.5 / V12 / plan W3).
+ *
+ * The Chat session does NOT discover user-level / project-level extensions or
+ * skills (its tool surface is fixed: the operator-action registry + the
+ * built-in explore tools). This module is the typed contract describing the
+ * DECLARED Chat tool surface — it mirrors what pi-runtime.ts actually wires
+ * into the SDK session, so that capabilities/doctor/red-team can report a
+ * single source of truth. It is deliberately framework-agnostic (does not
+ * import the Pi SDK at module top-level so it stays unit-testable).
+ *
+ * Current contract (2026-07-25 widening): bash/read/grep/find/ls are ALLOWED
+ * explore tools; the full operator action set is allowed; the ONLY denied
+ * tools are file-WRITING coding tools (edit/write/apply_patch/full-tools/
+ * shell/coding-chat). hasBash therefore reflects reality: true.
+ *
+ * Note: this adapter is NOT the SDK's own ResourceLoader (that is
+ * DefaultResourceLoader, created inside createAgentSessionServices with
+ * noContextFiles/noSkills/noExtensions). This adapter is the operator-chat
+ * declarative surface used for capabilities reporting and red-team checks.
+ * The three-gate authorization (authorizeOperatorChatTool) is the actual
+ * enforcement; this adapter describes what that gate admits.
+ */
+import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, authorizeOperatorChatTool, filterOperatorChatTools, assertNoWriteToolInList, } from "./tools.js";
+/** Built-in explore tool names that are ALLOWED in every Chat session. */
+export const OPERATOR_CHAT_BUILTIN_EXPLORE_TOOL_IDS = Object.freeze([
+    "bash",
+    "read",
+    "grep",
+    "find",
+    "ls",
+]);
+export function createOperatorChatResourceLoader() {
+    let active = new Set();
+    return {
+        mode: "operator-chat-closed",
+        allowedToolIds: OPERATOR_CHAT_ALLOWED_TOOLS,
+        deniedToolIds: OPERATOR_CHAT_DENIED_TOOLS,
+        deniedOperatorActions: OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS,
+        builtinExploreToolIds: OPERATOR_CHAT_BUILTIN_EXPLORE_TOOL_IDS,
+        listTools: () => OPERATOR_CHAT_ALLOWED_TOOLS,
+        tryActivateTool: (toolId) => {
+            // Explore tools (bash/read/grep/find/ls) are run by the SDK's built-in
+            // tool registry, not by the operator dispatcher. tryActivateTool only
+            // classifies operator actions here, but it must NOT deny an explore
+            // tool — that would contradict the real session. Deny only write tools
+            // and report unknowns.
+            const explore = OPERATOR_CHAT_BUILTIN_EXPLORE_TOOL_IDS.includes(toolId);
+            if (explore) {
+                return { ok: true, toolId };
+            }
+            const decision = authorizeOperatorChatTool(toolId);
+            if (decision.ok)
+                active.add(decision.toolId);
+            return decision;
+        },
+        setActiveToolsByName: (names) => {
+            assertNoWriteToolInList(names);
+            const { allowed, denied } = filterOperatorChatTools(names);
+            active = new Set(allowed);
+            return { active: [...active], denied };
+        },
+        allowsEnvToolRestore: false,
+        hasBash: true,
+    };
+}