@tea-agent/loop-agent 0.22.0 → 0.23.1

package/dist/worker/console/chat/tool-adapter.js

@@ -0,0 +1,238 @@
+/**
+ * Operator Chat — operator action → Pi tool schema adapter (plan W5 / W12).
+ *
+ * Maps the FULL operator action surface (every action in the capabilities
+ * registry — read, mutation, and long-running — derived dynamically) into
+ * tool-schema descriptors the Pi model can invoke. Each descriptor carries:
+ *   - toolId (canonical action name)
+ *   - description (from capabilities registry)
+ *   - inputParams (the parameters the model may supply; MUST match the
+ *     dispatcher's paramsOf reads — see INPUT_PARAMS contract note)
+ *
+ * High-risk / long-running actions ARE mapped as tools (2026-07-25 widening).
+ * They still fail closed at dispatch time without their prepared receipt.
+ *
+ * The adapter does NOT register tools with the SDK directly — that is the
+ * session layer's job (chat/pi-runtime.ts). This keeps the adapter pure and
+ * unit-testable against the registry.
+ */
+import { buildOperatorCapabilitiesDocument } from "../../../shared/operator/capabilities.js";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, authorizeOperatorChatTool, } from "./tools.js";
+/**
+ * Minimal input parameter specs per action. Only the parameters the model is
+ * allowed to supply are listed; the dispatch layer fills the rest (repoRoot,
+ * operatorSessionId, request identity / clientRequestId — note the dispatcher
+ * reads `req.clientRequestId`, not `p.clientRequestId`, so the model MUST NOT
+ * be asked for it). Kept intentionally small to avoid over-permissive tool
+ * surfaces.
+ *
+ * CONTRACT SOURCE OF TRUTH: each entry here MUST match the fields the
+ * dispatcher in operator-actions.ts actually reads from `p` (paramsOf). The
+ * `verifyOperatorChatToolSurfaceMatchesDispatcher` test pins this. Adding a
+ * new operator action to the registry WITHOUT an entry here is a build-time
+ * failure (fail-closed dynamic discovery) — see buildOperatorChatToolSchemas.
+ */
+const INPUT_PARAMS = {
+    operatorCapabilities: [],
+    inspect: [],
+    doctor: [],
+    contractShow: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+    ],
+    // contractValidate / contractDiff: dispatcher reads draftJson/inputText
+    // (a JSON string staged to a file), NOT a `draft` object. The model may
+    // pass a stored-draft taskId with NO draftJson to validate the saved draft.
+    contractValidate: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        {
+            name: "draftJson",
+            type: "string",
+            required: false,
+            description: "TaskContractDraftV1 serialized as a JSON string. When omitted, the dispatcher validates the task's currently-saved Console draft.",
+        },
+    ],
+    contractDiff: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        {
+            name: "draftJson",
+            type: "string",
+            required: false,
+            description: "TaskContractDraftV1 serialized as a JSON string to diff against the saved draft. When omitted, diffs the saved draft.",
+        },
+    ],
+    sourceInstructions: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+    ],
+    prepareDagConfirmation: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+    ],
+    observeLink: [
+        {
+            name: "taskId",
+            type: "string",
+            required: false,
+            description: "task id (optional, one of taskId/dagRunId/featureId)",
+        },
+        {
+            name: "dagRunId",
+            type: "string",
+            required: false,
+            description: "dag run id",
+        },
+        {
+            name: "featureId",
+            type: "string",
+            required: false,
+            description: "feature id",
+        },
+    ],
+    statsContext: [],
+    dagReport: [
+        {
+            name: "runId",
+            type: "string",
+            required: true,
+            description: "dag run id",
+        },
+    ],
+    status: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+    ],
+    spineCheck: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+    ],
+    dagValidate: [
+        {
+            name: "dagPath",
+            type: "string",
+            required: true,
+            description: "path to DAG json",
+        },
+    ],
+    dagRerunPlan: [
+        {
+            name: "runId",
+            type: "string",
+            required: true,
+            description: "dag run id",
+        },
+        {
+            name: "fromNode",
+            type: "string",
+            required: true,
+            description: "node id to rerun from",
+        },
+    ],
+    // high-risk mutation — formerly human-confirmation-only
+    importPrd: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        { name: "content", type: "string", required: true, description: "PRD markdown content" },
+    ],
+    contractApply: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        { name: "assessmentId", type: "string", required: false, description: "assessment id binding (defaults to the draft's bound assessment)" },
+        { name: "expectedRevision", type: "string", required: false, description: "expected contract revision (defaults to live observed)" },
+        { name: "expectedObservedHash", type: "string", required: false, description: "expected observed hash (defaults to live observed)" },
+    ],
+    confirmDagConfirmation: [
+        { name: "confirmationId", type: "string", required: true, description: "confirmation id from prepareDagConfirmation" },
+        { name: "challenges", type: "array", required: true, itemsType: "string", description: "all challenge answers" },
+    ],
+    workerTaskRetry: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        { name: "featureId", type: "string", required: false, description: "feature id (canonical retry carries Feature identity; passed to the CLI as --feature-id when present)" },
+        { name: "reason", type: "string", required: true, description: "retry reason" },
+    ],
+    // long-running execution — formerly human-confirmation-only
+    dagRunTask: [
+        { name: "taskId", type: "string", required: true, description: "task id to run as a DAG" },
+        { name: "profile", type: "string", required: false, description: "DAG profile (defaults to auto)" },
+    ],
+    runDag: [
+        { name: "confirmationId", type: "string", required: true, description: "confirmation id (from prepareDagConfirmation) — raw dag path is never accepted from the model" },
+    ],
+    dagRerun: [
+        { name: "runId", type: "string", required: true, description: "dag run id" },
+        { name: "fromNode", type: "string", required: true, description: "node id to rerun from" },
+        { name: "planHash", type: "string", required: true, description: "rerun plan hash" },
+        { name: "reason", type: "string", required: true, description: "rerun reason" },
+    ],
+    standaloneTaskRerun: [
+        { name: "runId", type: "string", required: true, description: "dag run id" },
+        { name: "reason", type: "string", required: true, description: "rerun reason" },
+    ],
+    newTask: [
+        { name: "taskId", type: "string", required: true, description: "task id" },
+        { name: "title", type: "string", required: false, description: "task title (defaults to taskId)" },
+    ],
+    contractDraftSave: [
+        { name: "taskId", type: "string", required: false, description: "task id (defaults to draft.taskId)" },
+        {
+            name: "draft",
+            type: "object",
+            required: true,
+            description: "TaskContractDraftV1 object",
+        },
+    ],
+};
+/**
+ * Build the full Chat tool schema set from the capabilities registry.
+ *
+ * FAIL-CLOSED dynamic discovery: every whitelisted action MUST have an entry
+ * in INPUT_PARAMS. An action present in the registry (and thus allowed by the
+ * dynamic allowlist) but missing an INPUT_PARAMS entry is a CONTRACT GAP — it
+ * means we don't know which params its dispatcher reads, so exposing it as a
+ * zero-param tool would be a silent schema degradation (the model could call
+ * it but couldn't supply required fields). Instead we throw at boot so the
+ * gap is caught in tests and never ships. Diagnostics list the offending
+ * actions so adding a registry action is a one-line INPUT_PARAMS update.
+ */
+export function buildOperatorChatToolSchemas() {
+    const doc = buildOperatorCapabilitiesDocument();
+    const out = [];
+    const unschemaed = [];
+    for (const action of doc.actions) {
+        const decision = authorizeOperatorChatTool(action.action);
+        if (!decision.ok)
+            continue;
+        const params = INPUT_PARAMS[action.action];
+        if (!params) {
+            // Fail-closed: an allowed action without a schema entry is a contract
+            // gap, not a zero-param tool. Collect then throw so boot/red-team tests
+            // surface it loudly.
+            unschemaed.push(action.action);
+            continue;
+        }
+        out.push({
+            toolId: decision.toolId,
+            action: action.action,
+            description: action.description,
+            cli: action.cli,
+            kind: action.kind,
+            inputParams: params,
+        });
+    }
+    if (unschemaed.length > 0) {
+        throw new Error(`Operator Chat tool schema gap: allowed operator actions lack an INPUT_PARAMS entry: ${unschemaed.sort().join(", ")}. Add each to INPUT_PARAMS in tool-adapter.ts (must match the dispatcher's paramsOf reads).`);
+    }
+    return out;
+}
+/**
+ * Verify the adapter covers exactly the allowlist and nothing more.
+ * Used by boot/red-team checks (V15 — the surface equals the registry).
+ */
+export function verifyOperatorChatToolSurface() {
+    const schemas = buildOperatorChatToolSchemas();
+    const covered = schemas.map((s) => s.action).sort();
+    const expected = [...OPERATOR_CHAT_ALLOWED_TOOLS].sort();
+    const coveredSet = new Set(covered);
+    const expectedSet = new Set(expected);
+    const missing = expected.filter((a) => !coveredSet.has(a));
+    const extra = covered.filter((a) => !expectedSet.has(a));
+    return {
+        ok: missing.length === 0 && extra.length === 0,
+        covered,
+        missing,
+        extra,
+    };
+}

package/dist/worker/console/chat/tools.js

@@ -0,0 +1,171 @@
+/**
+ * Operator Chat — tool whitelist (design §7.5 / plan D3, widened 2026-07-25).
+ *
+ * The General Operator Chat exposes the loop-agent runtime's FULL structured
+ * operator surface as Pi tools, plus the built-in read/explore tools
+ * (bash / read / grep / find / ls) so the model can probe the repo. It still
+ * forbids file-WRITING coding tools (edit / write / apply_patch / full-tools /
+ * shell / coding-chat) — those can never be activated.
+ *
+ * DYNAMIC DISCOVERY: the allowed operator-action list is derived directly from
+ * the capabilities registry (`buildOperatorCapabilitiesDocument()`), NOT
+ * hard-coded. When runtime adds a new operator action to the registry, it
+ * appears here automatically — zero code sync, and the previous
+ * "whitelist/registry drift" risk (old plan D3 W5 constraint) is eliminated.
+ * The only hand-maintained list is the DENY list of file-writing tools.
+ *
+ * bash is ALLOWED but bare (no command filter). The residual risk that bash
+ * can still write files via `echo >` / `tee` / `sed -i` is accepted by the
+ * owner and documented in the exec-plan Open Questions Q9. A future
+ * command-filter layer can close that gap without changing this contract.
+ */
+import { buildOperatorCapabilitiesDocument } from "../../../shared/operator/capabilities.js";
+import { OFFICIAL_DENIED_TOOL_IDS } from "../resource-loader.js";
+/**
+ * All operator actions registered in the capabilities registry are exposed as
+ * Chat tools. Derived dynamically so new actions appear automatically.
+ */
+export const OPERATOR_CHAT_ALLOWED_TOOLS = Object.freeze(buildOperatorCapabilitiesDocument().actions.map((a) => a.action));
+/**
+ * Operator actions denied by the legacy MVP boundary. Kept EMPTY since the
+ * owner decided (2026-07-25) that the full operator surface is Chat-callable.
+ * Retained (empty) so downstream guards referencing it keep compiling and
+ * stay defensive against future additions.
+ */
+export const OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS = Object.freeze([]);
+// Coding / generic tool ids that must never appear in a Chat session.
+// File-WRITING coding tools are forbidden (edit/write/apply_patch/full-tools/
+// coding-chat/shell). bash / read / grep / find / ls are intentionally
+// ALLOWED (owner decision 2026-07-25 — the Chat must be able to probe the
+// repo and run read-only commands). We therefore build the deny list from
+// OFFICIAL_DENIED_TOOL_IDS and then explicitly UN-deny BOTH the explore
+// tools AND the high-risk operator actions (contractApply / runDag / dagRerun
+// / etc. are now Chat-callable per the widening — OFFICIAL_DENIED_TOOL_IDS
+// listed them as a defense against accidental activation in the Interview
+// flow, but the Chat deliberately exposes the full operator surface).
+const _EXPLORE_TOOLS = new Set(["bash", "read", "grep", "find", "ls"]);
+// Operator actions that OFFICIAL_DENIED_TOOL_IDS carries for Interview safety
+// but that the Chat now deliberately allows. We compare on a COMPACTED form
+// (strip - and _) because OFFICIAL lists both camelCase (`contractApply`) and
+// snake_case (`contract_apply`) variants, and authorize() also normalizes —
+// leaving any variant in would re-deny the action via normalization.
+const _ALLOWED_OPERATOR_ACTIONS_COMPACT = new Set(OPERATOR_CHAT_ALLOWED_TOOLS.map((t) => t.toLowerCase().replace(/[-_]/g, "")));
+export const OPERATOR_CHAT_DENIED_TOOLS = Object.freeze(OFFICIAL_DENIED_TOOL_IDS.filter((id) => {
+    const lower = id.toLowerCase();
+    if (_EXPLORE_TOOLS.has(lower))
+        return false;
+    if (_ALLOWED_OPERATOR_ACTIONS_COMPACT.has(lower.replace(/[-_]/g, "")))
+        return false;
+    return true;
+}));
+const ALLOWED = new Set(OPERATOR_CHAT_ALLOWED_TOOLS.map((t) => t.toLowerCase()));
+const DENIED_ACTIONS = new Set(OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS.map((a) => a.toLowerCase()));
+const DENIED_TOOLS = new Set(OPERATOR_CHAT_DENIED_TOOLS.map((t) => t.toLowerCase()));
+export function isOperatorChatToolAllowed(toolId) {
+    return ALLOWED.has(toolId.trim().toLowerCase());
+}
+export function isOperatorChatToolDenied(toolId) {
+    const id = toolId.trim().toLowerCase();
+    if (DENIED_TOOLS.has(id))
+        return true;
+    if (DENIED_ACTIONS.has(id))
+        return true;
+    // normalize snake/camel/kebab
+    const compact = id.replace(/[-_]/g, "");
+    for (const d of DENIED_TOOLS) {
+        if (d.replace(/[-_]/g, "") === compact)
+            return true;
+    }
+    for (const d of DENIED_ACTIONS) {
+        if (d.replace(/[-_]/g, "") === compact)
+            return true;
+    }
+    return false;
+}
+/**
+ * Three-gate authorization (design §7.5): session create / setActiveTools /
+ * per-tool-call. Server-side only — UI hiding is insufficient.
+ */
+export function authorizeOperatorChatTool(toolId) {
+    const id = toolId.trim();
+    if (!id) {
+        return {
+            ok: false,
+            code: "tool-unknown",
+            toolId: id,
+            message: "empty tool id is not allowed in General Operator Chat",
+        };
+    }
+    if (isOperatorChatToolDenied(id)) {
+        return {
+            ok: false,
+            code: "tool-denied",
+            toolId: id,
+            message: `tool "${id}" is denied in General Operator Chat (no edit/write/apply_patch/full-tools/shell/coding-chat)`,
+        };
+    }
+    if (!isOperatorChatToolAllowed(id)) {
+        return {
+            ok: false,
+            code: "tool-unknown",
+            toolId: id,
+            message: `tool "${id}" is not registered for General Operator Chat (new operator actions default to deny)`,
+        };
+    }
+    return { ok: true, toolId: id };
+}
+/**
+ * Filter a requested tool list against the Chat whitelist.
+ * Returns allowed + denied (for diagnostics / red-team evidence).
+ */
+export function filterOperatorChatTools(requested) {
+    const allowed = [];
+    const denied = [];
+    for (const toolId of requested) {
+        const decision = authorizeOperatorChatTool(toolId);
+        if (decision.ok)
+            allowed.push(decision.toolId);
+        else
+            denied.push(toolId);
+    }
+    return { allowed, denied };
+}
+/**
+ * Assert that a full requested tool set contains NO file-writing coding tool.
+ * Used by red-team / boot checks (V12 — closed coding surface). Note: bash is
+ * intentionally ALLOWED since the 2026-07-25 widening (owner decision); this
+ * guard now only blocks tools whose PRIMARY purpose is editing files
+ * (edit/write/apply_patch/full-tools/shell). The residual write-via-bash risk
+ * (`echo >` / `tee`) is documented in exec-plan Open Questions Q9.
+ */
+export function assertNoWriteToolInList(requested) {
+    const writeVariants = [
+        "edit",
+        "write",
+        "apply_patch",
+        "apply-patch",
+        "full-tools",
+        "full_tools",
+        "coding-chat",
+        "coding_chat",
+        "shell",
+    ];
+    const lower = new Set(requested.map((t) => t.trim().toLowerCase()));
+    for (const v of writeVariants) {
+        if (lower.has(v)) {
+            throw new Error(`file-writing tool "${v}" must not appear in Operator Chat tool list (V12 closed coding surface)`);
+        }
+    }
+}
+/**
+ * Back-compat alias kept for callers that still reference the old name. Now
+ * asserts absence of file-writing tools (bash is allowed post-widening).
+ * @deprecated use {@link assertNoWriteToolInList}.
+ */
+export function assertNoBashInToolList(requested) {
+    assertNoWriteToolInList(requested);
+}
+/** Canonical sorted tool list to hand to setActiveToolsByName. */
+export function canonicalOperatorChatToolList() {
+    return [...OPERATOR_CHAT_ALLOWED_TOOLS].sort();
+}

package/dist/worker/console/server.js

@@ -10,6 +10,9 @@ import { DraftStore } from "./draft-store.js";
 import { AssessmentStore } from "./interview/assessment.js";
 import { InterviewSessionStore } from "./interview/session.js";
 import { isLoopbackHost } from "./loopback.js";
+import { ChatSessionStore } from "./chat/session-store.js";
+import { ConsolePiRuntime } from "./chat/pi-runtime.js";
+import { handleChatRequest } from "./chat/routes.js";
 import { createOperationEventStore, } from "./operation-sse.js";
 import { OperationStore } from "./operation-store.js";
 import { probePiReadiness, } from "./pi-readiness.js";
@@ -99,6 +102,30 @@ export async function createConsoleServer(options) {
     let boundHost = host;
     let boundPort = port;
     const getConsoleOrigin = () => `http://${boundHost}:${boundPort}`;
+    // Phase 4: General Operator Chat runtime. The actionContext is forwarded so
+    // custom-tool execute() calls dispatch into the operator action layer (Gate 3).
+    // Chat session dir is dedicated (app-data/chat-sessions), NOT user default.
+    const chatStore = new ChatSessionStore(appData);
+    const skillsDir = resolveLoopAgentSkillsDir(repoRoot);
+    const chatRuntime = new ConsolePiRuntime({
+        cwd: repoRoot,
+        skillsDir,
+        sessionDir: appData.chatSessions,
+        actionContext,
+    });
+    // chatRouteDeps is a plain object literal — it cannot throw. The previous
+    // try/catch was dead code that created a false "handled failure" impression.
+    // If a future field can throw, scope it explicitly instead of wrapping the
+    // literal.
+    const chatRouteDeps = {
+        runtime: chatRuntime,
+        store: chatStore,
+        appData,
+        bootToken,
+        getConsoleOrigin,
+        allowNonLoopbackAccess: !loopbackBind,
+        skillsDir,
+    };
     const routeContext = {
         repoRoot,
         staticDir,
@@ -114,6 +141,7 @@ export async function createConsoleServer(options) {
             operations,
             events,
             getReadiness,
+            chat: chatRouteDeps,
         },
     };
     return new Promise((resolve, reject) => {
@@ -173,6 +201,11 @@ export async function createConsoleServer(options) {
             }
             if (pathname.startsWith("/api/operator/v1/") ||
                 pathname.startsWith("/api/session/")) {
+                // Phase 4: General Operator Chat routes (mounted under chat/).
+                if (pathname.startsWith("/api/operator/v1/chat/")) {
+                    await handleChatRequest(req, res, chatRouteDeps, pathname);
+                    return;
+                }
                 await handleConsoleOperatorRequest(req, res, routeContext);
                 return;
             }
@@ -221,12 +254,34 @@ export async function createConsoleServer(options) {
                 getReadiness,
                 operatorSessionId,
                 close: () => new Promise((closeResolve, closeReject) => {
+                    // Dispose all Chat Pi sessions BEFORE closing the HTTP server so
+                    // no prompt is left executing and no session/SDK state/file handle
+                    // leaks across Console restarts (regression: close() previously
+                    // only closed the socket, leaving ConsolePiRuntime sessions live).
+                    try {
+                        chatRuntime.disposeAll();
+                    }
+                    catch (error) {
+                        // Best-effort: surface but do not block the HTTP close.
+                        process.stderr.write(`[console] chatRuntime.disposeAll() failed during close: ${error instanceof Error ? error.message : String(error)}\n`);
+                    }
                     server.close((err) => (err ? closeReject(err) : closeResolve()));
                 }),
             });
         });
     });
 }
+/** Resolve the loop-agent repo skills/ directory (source repo or npm pack asset). */
+function resolveLoopAgentSkillsDir(repoRoot) {
+    // When running from dist (npm pack), skills/ is a sibling of dist/ at the
+    // package root. When running from source (tsx), it's the repo root.
+    const fromDist = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "skills");
+    const fromRepo = path.resolve(repoRoot, "skills");
+    // Prefer whichever exists; dist path wins if present (npm-installed runtime).
+    if (existsSync(fromDist))
+        return fromDist;
+    return fromRepo;
+}
 function requestSource(req) {
     const forwarded = req.headers["x-forwarded-for"];
     if (typeof forwarded === "string" && forwarded.trim()) {