@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/runs/shared/claude-code.js

@@ -1,199 +1,162 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { splitKnownThinkingSuffix } from "../../shared/model-info.js";
-import { scanJournal } from "../../shared/journal-reader.js";
-import { writeAtomicJson } from "../../shared/atomic-json.js";
-const PREFIX = "claude-code/";
-const DEFAULT_CONTEXT = "300k";
-const CONTEXT_TOKENS = {
-    "300k": "300000",
-    "1m": "1000000",
-};
-const FAMILY_ALIASES = new Set(["fable", "opus", "sonnet", "haiku"]);
-const SESSION_EVENT_TYPE = "claude_code_session";
-export function isClaudeCodeModel(model) {
-    return Boolean(model?.startsWith(PREFIX));
-}
-function splitThinking(input) {
-    const { baseModel, thinkingSuffix } = splitKnownThinkingSuffix(input);
-    return thinkingSuffix ? { model: baseModel, thinking: thinkingSuffix.slice(1) } : { model: input };
-}
-export function parseClaudeCodeModel(model) {
-    if (!isClaudeCodeModel(model))
-        throw new Error(`Not a Claude Code model: ${model}`);
-    const { model: withoutThinking, thinking } = splitThinking(model);
-    const raw = withoutThinking.slice(PREFIX.length).trim().toLowerCase();
-    const [familyRaw, contextRaw] = raw.split("@", 2);
-    if (!FAMILY_ALIASES.has(familyRaw)) {
-        throw new Error(`Unsupported Claude Code model '${model}'. Use claude-code/fable, claude-code/opus, claude-code/sonnet, or claude-code/haiku.`);
+import { parseClaudeCodeModel } from "./claude-model.js";
+export { isClaudeCodeModel, parseClaudeCodeModel, } from "./claude-model.js";
+import { readClaudeCodeSessionMetadata, hasNonMetadataContent } from "./claude-session.js";
+export { readClaudeCodeSessionMetadata, writeClaudeCodeSessionMetadata, appendClaudeCodeMessage, } from "./claude-session.js";
+import { nonempty } from "./child-presence.js";
+function sessionArgs(input, parsed, sessionId, resuming) {
+    const args = [
+        "-p",
+        "--dangerously-skip-permissions",
+        "--model",
+        parsed.cliModel,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+    ];
+    if (nonempty(parsed.thinking) && parsed.thinking !== "minimal") {
+        args.push("--effort", parsed.thinking);
     }
-    const family = familyRaw;
-    const context = contextRaw ?? (family === "haiku" ? "native" : DEFAULT_CONTEXT);
-    if (context !== "300k" && context !== "1m" && context !== "native") {
-        throw new Error(`Unsupported Claude Code context '${context}' in '${model}'. Use @300k or @1m.`);
+    if (nonempty(input.sessionName)) {
+        args.push("--name", input.sessionName);
     }
-    if (family === "haiku" && context === "1m")
-        throw new Error("Claude Code haiku does not support @1m context.");
-    if (family === "haiku" && context === "300k")
-        throw new Error("Claude Code haiku does not support @300k context.");
-    const cliModel = context === "1m" && (family === "opus" || family === "sonnet") ? `${family}[1m]` : family;
-    return {
-        inputModel: model,
-        family,
-        context,
-        ...(thinking && thinking !== "off" ? { thinking } : {}),
-        cliModel,
-        ...(context === "300k" ? { autoCompactWindow: CONTEXT_TOKENS[context] } : {}),
-    };
+    args.push(resuming ? "--resume" : "--session-id", sessionId);
+    return args;
 }
-export function readClaudeCodeSessionMetadata(sessionFile) {
-    if (!sessionFile)
-        return;
-    const validate = (value) => {
-        if (!value || typeof value.sessionId !== "string" || !value.sessionId || typeof value.model !== "string" || typeof value.cliModel !== "string"
-            || !["fable", "opus", "sonnet", "haiku"].includes(value.family ?? "") || !["300k", "1m", "native"].includes(value.context ?? ""))
-            return;
-        return { ...value, updatedAt: Number(value.updatedAt) || 0 };
-    };
-    try {
-        return validate(JSON.parse(fs.readFileSync(`${sessionFile}.metadata.json`, "utf8")));
+function contextArgs(input) {
+    if (input.allowSubagents === true) {
+        throw new Error("Claude Code backend does not support nested subagent fanout. Use a Pi-backed model for allowSubagents.");
     }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
+    const inheritContext = input.inheritProjectContext ?? true;
+    const inheritSkills = input.inheritSkills ?? true;
+    if (!inheritContext && inheritSkills) {
+        throw new Error("Claude Code cannot disable project setting sources while preserving their skills. Set inheritSkills: false or use a Pi-backed model.");
     }
-    if (!fs.existsSync(sessionFile))
-        return;
-    let metadata;
-    // Legacy metadata is recovered read-only; new updates never rewrite its audit messages.
-    scanJournal(sessionFile, (path) => !path.length || ["type", "claudeCode"].includes(String(path[0])) ? 4096 : false, ({ value }) => {
-        if (value?.type === SESSION_EVENT_TYPE)
-            metadata ??= validate(value.claudeCode);
-    }, { policy: "inspect" });
-    return metadata;
-}
-export function writeClaudeCodeSessionMetadata(sessionFile, metadata) {
-    fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
-    writeAtomicJson(`${sessionFile}.metadata.json`, metadata);
-    fs.closeSync(fs.openSync(sessionFile, "a", 0o600));
+    return [
+        ...(inheritContext ? [] : ["--setting-sources", ""]),
+        ...(inheritSkills ? [] : ["--disable-slash-commands"]),
+        "--disallowedTools=Agent",
+    ];
 }
-export function appendClaudeCodeMessage(sessionFile, message, observation) {
-    if (!sessionFile)
-        return;
-    fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
-    fs.appendFileSync(sessionFile, `${JSON.stringify({ type: "message_end", message, ...(observation ? { claudeCodeResult: observation } : {}) })}\n`, { mode: 0o600 });
-}
-function hasNonMetadataContent(sessionFile) {
-    if (!fs.existsSync(sessionFile))
-        return false;
-    let content = false;
-    scanJournal(sessionFile, (path) => !path.length || path.length === 1 && path[0] === "type", ({ value }) => {
-        if (value?.type !== SESSION_EVENT_TYPE)
-            content = true;
-    }, { policy: "inspect", malformed: () => { content = true; } });
-    return content;
+function promptArgs(input) {
+    const args = [];
+    if (input.systemPrompt !== undefined && input.systemPrompt.trim().length > 0) {
+        args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", input.systemPrompt);
+    }
+    args.push(...contextArgs(input));
+    const mappedTools = mapClaudeCodeTools(input.tools, input.mcpDirectTools);
+    if (input.outputSchema) {
+        args.push("--json-schema", JSON.stringify(input.outputSchema));
+    }
+    args.push(input.task);
+    if (mappedTools !== undefined) {
+        args.push("--tools", mappedTools);
+    }
+    return args;
 }
 export function buildClaudeCodeInvocation(input) {
     const parsed = parseClaudeCodeModel(input.model);
     const existing = readClaudeCodeSessionMetadata(input.sessionFile);
-    if (input.sessionFile && !existing && hasNonMetadataContent(input.sessionFile)) {
+    if (nonempty(input.sessionFile) && !existing && hasNonMetadataContent(input.sessionFile)) {
         throw new Error(`Claude Code backend cannot resume non-Claude session file: ${input.sessionFile}. Use fresh context for claude-code/* subagents.`);
     }
     const sessionId = existing?.sessionId ?? randomUUID();
-    const args = ["-p", "--dangerously-skip-permissions", "--model", parsed.cliModel, "--output-format", "stream-json", "--verbose"];
-    if (parsed.thinking && parsed.thinking !== "minimal")
-        args.push("--effort", parsed.thinking);
-    if (input.sessionName)
-        args.push("--name", input.sessionName);
-    if (existing)
-        args.push("--resume", sessionId);
-    else
-        args.push("--session-id", sessionId);
-    if (input.systemPrompt?.trim()) {
-        args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", input.systemPrompt);
-    }
-    if (input.allowSubagents)
-        throw new Error("Claude Code backend does not support nested subagent fanout. Use a Pi-backed model for allowSubagents.");
-    const inheritProjectContext = input.inheritProjectContext ?? true;
-    const inheritSkills = input.inheritSkills ?? true;
-    if (!inheritProjectContext && inheritSkills) {
-        throw new Error("Claude Code cannot disable project setting sources while preserving their skills. Set inheritSkills: false or use a Pi-backed model.");
-    }
-    if (!inheritProjectContext)
-        args.push("--setting-sources", "");
-    if (!inheritSkills)
-        args.push("--disable-slash-commands");
-    args.push("--disallowedTools=Agent");
-    const mappedTools = mapClaudeCodeTools(input.tools, input.mcpDirectTools);
-    if (input.outputSchema)
-        args.push("--json-schema", JSON.stringify(input.outputSchema));
-    args.push(input.task);
-    if (mappedTools)
-        args.push("--tools", mappedTools);
     return {
         command: "claude",
-        args,
-        env: parsed.autoCompactWindow ? { CLAUDE_CODE_AUTO_COMPACT_WINDOW: parsed.autoCompactWindow } : {},
+        args: [...sessionArgs(input, parsed, sessionId, existing !== undefined), ...promptArgs(input)],
+        env: nonempty(parsed.autoCompactWindow)
+            ? { CLAUDE_CODE_AUTO_COMPACT_WINDOW: parsed.autoCompactWindow }
+            : {},
         sessionId,
-        resuming: Boolean(existing),
+        resuming: existing !== undefined,
         model: parsed,
     };
 }
-function mapClaudeCodeTools(tools, mcpDirectTools) {
-    if (mcpDirectTools?.length) {
-        throw new Error(`Claude Code backend does not support MCP direct tool allowlist entries: ${mcpDirectTools.join(", ")}. Use a Pi-backed model for MCP direct tools.`);
-    }
-    if (!tools || tools.length === 0)
-        return undefined;
-    const map = {
-        bash: "Bash",
-        read: "Read",
-        edit: "Edit",
-        write: "Write",
-        grep: "Grep",
-        glob: "Glob",
-        web_fetch: "WebFetch",
-        webfetch: "WebFetch",
-        web_search: "WebSearch",
-        websearch: "WebSearch",
-    };
+const TOOL_NAMES = {
+    bash: "Bash",
+    read: "Read",
+    edit: "Edit",
+    write: "Write",
+    grep: "Grep",
+    glob: "Glob",
+    web_fetch: "WebFetch",
+    webfetch: "WebFetch",
+    web_search: "WebSearch",
+    websearch: "WebSearch",
+};
+function mappedToolNames(tools) {
     const mapped = [];
     const unsupported = [];
     for (const tool of tools) {
         const name = tool.trim();
-        if (!name)
+        if (name.length === 0) {
             continue;
-        const mappedTool = map[name.toLowerCase()];
-        if (mappedTool)
+        }
+        const mappedTool = TOOL_NAMES[name.toLowerCase()];
+        if (typeof mappedTool === "string" && mappedTool.length > 0) {
             mapped.push(mappedTool);
-        else
+        }
+        else {
             unsupported.push(name);
+        }
     }
+    return { mapped, unsupported };
+}
+function mapClaudeCodeTools(tools, mcpDirectTools) {
+    if (mcpDirectTools !== undefined && mcpDirectTools.length > 0) {
+        throw new Error(`Claude Code backend does not support MCP direct tool allowlist entries: ${mcpDirectTools.join(", ")}. Use a Pi-backed model for MCP direct tools.`);
+    }
+    if (!tools || tools.length === 0) {
+        return;
+    }
+    const { mapped, unsupported } = mappedToolNames(tools);
     if (unsupported.length > 0 || mapped.length === 0) {
-        throw new Error(`Claude Code backend does not support tool allowlist entr${unsupported.length === 1 ? "y" : "ies"}: ${(unsupported.length ? unsupported : tools).join(", ")}. Supported tools: bash, read, edit, write, grep, glob, web_fetch, web_search.`);
+        throw new Error(`Claude Code backend does not support tool allowlist entr${unsupported.length === 1 ? "y" : "ies"}: ${(unsupported.length > 0 ? unsupported : tools).join(", ")}. Supported tools: bash, read, edit, write, grep, glob, web_fetch, web_search.`);
     }
     return [...new Set(mapped)].join(",");
 }
-export function claudeCodeMessageFromResult(event, fallbackModel) {
-    const resultText = event.result ?? "";
-    const isError = event.is_error === true || event.subtype === "error" || Boolean(event.api_error_status);
-    const counters = { input: event.usage?.input_tokens, output: event.usage?.output_tokens,
-        cacheRead: event.usage?.cache_read_input_tokens, cacheWrite: event.usage?.cache_creation_input_tokens };
+function observedClaudeUsage(event) {
+    const counters = {
+        input: event.usage?.input_tokens,
+        output: event.usage?.output_tokens,
+        cacheRead: event.usage?.cache_read_input_tokens,
+        cacheWrite: event.usage?.cache_creation_input_tokens,
+    };
+    const values = Object.values(counters);
+    if (values.every((value) => value === undefined) && event.total_cost_usd === undefined) {
+        return;
+    }
     const observed = Object.fromEntries(Object.entries(counters).filter(([, value]) => value !== undefined));
-    if (Object.values(counters).every((value) => typeof value === "number"))
-        observed.totalTokens = Object.values(counters).reduce((sum, value) => sum + value, 0);
+    return {
+        ...observed,
+        ...(values.every((value) => typeof value === "number")
+            ? { totalTokens: values.reduce((sum, value) => sum + value, 0) }
+            : {}),
+        ...(event.total_cost_usd !== undefined ? { cost: { total: event.total_cost_usd } } : {}),
+    };
+}
+function resultFailure(event) {
+    const status = event.api_error_status;
+    const hasStatus = status !== undefined && status !== null && status !== 0;
+    if (event.is_error !== true && event.subtype !== "error" && !hasStatus) {
+        return;
+    }
+    return nonempty(event.result)
+        ? event.result
+        : `Claude Code failed${hasStatus ? ` (${status})` : ""}.`;
+}
+export function claudeCodeMessageFromResult(event, fallbackModel) {
+    const errorMessage = resultFailure(event);
     return {
         role: "assistant",
-        content: [{ type: "text", text: resultText }],
+        content: [{ type: "text", text: event.result ?? "" }],
         model: resolveClaudeCodeResultModel(event) ?? fallbackModel,
-        stopReason: isError ? "error" : "stop",
-        ...(isError ? { errorMessage: resultText || `Claude Code failed${event.api_error_status ? ` (${event.api_error_status})` : ""}.` } : {}),
-        usage: Object.keys(observed).length || event.total_cost_usd !== undefined
-            ? { ...observed, ...(event.total_cost_usd !== undefined ? { cost: { total: event.total_cost_usd } } : {}) } : undefined,
+        stopReason: errorMessage !== undefined ? "error" : "stop",
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+        usage: observedClaudeUsage(event),
     };
 }
 export function resolveClaudeCodeResultModel(event) {
     const keys = Object.keys(event.modelUsage ?? {});
-    return keys.find((key) => !key.includes("haiku")) ?? keys[0];
+    return keys.find((key) => !key.includes("haiku")) ?? keys.at(0);
 }

package/dist/runs/shared/claude-model.js

@@ -0,0 +1,42 @@
+import { splitKnownThinkingSuffix } from "../../shared/model-info.js";
+import { nonempty } from "./child-presence.js";
+const PREFIX = "claude-code/";
+export function isClaudeCodeModel(model) {
+    return model?.startsWith(PREFIX) === true;
+}
+export function isClaudeFamily(family) {
+    return family === "fable" || family === "opus" || family === "sonnet" || family === "haiku";
+}
+export function isClaudeContext(context) {
+    return context === "300k" || context === "1m" || context === "native";
+}
+function resolveContext(family, contextRaw, model) {
+    const context = contextRaw ?? (family === "haiku" ? "native" : "300k");
+    if (!isClaudeContext(context)) {
+        throw new Error(`Unsupported Claude Code context '${context}' in '${model}'. Use @300k or @1m.`);
+    }
+    if (family === "haiku" && context !== "native") {
+        throw new Error(`Claude Code haiku does not support @${context} context.`);
+    }
+    return context;
+}
+export function parseClaudeCodeModel(model) {
+    if (!isClaudeCodeModel(model)) {
+        throw new Error(`Not a Claude Code model: ${model}`);
+    }
+    const { baseModel, thinkingSuffix } = splitKnownThinkingSuffix(model);
+    const [family, contextRaw] = baseModel.slice(PREFIX.length).trim().toLowerCase().split("@", 2);
+    if (!isClaudeFamily(family)) {
+        throw new Error(`Unsupported Claude Code model '${model}'. Use claude-code/fable, claude-code/opus, claude-code/sonnet, or claude-code/haiku.`);
+    }
+    const context = resolveContext(family, contextRaw, model);
+    const thinking = nonempty(thinkingSuffix) ? thinkingSuffix.slice(1) : undefined;
+    return {
+        inputModel: model,
+        family,
+        context,
+        ...(nonempty(thinking) && thinking !== "off" ? { thinking } : {}),
+        cliModel: context === "1m" && (family === "opus" || family === "sonnet") ? `${family}[1m]` : family,
+        ...(context === "300k" ? { autoCompactWindow: "300000" } : {}),
+    };
+}

package/dist/runs/shared/claude-session.js

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { scanJournal } from "../../shared/journal-reader.js";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { hasErrorCode, isRecord as isObject } from "../../shared/unknown.js";
+import { nonempty } from "./child-presence.js";
+import { isClaudeFamily, isClaudeContext } from "./claude-model.js";
+const SESSION_EVENT_TYPE = "claude_code_session";
+function validateMetadata(value) {
+    if (!isObject(value) ||
+        typeof value.sessionId !== "string" ||
+        !nonempty(value.sessionId) ||
+        typeof value.model !== "string" ||
+        typeof value.cliModel !== "string") {
+        return;
+    }
+    if (!isClaudeFamily(value.family) || !isClaudeContext(value.context)) {
+        return;
+    }
+    const updatedAt = Number(value.updatedAt);
+    return {
+        sessionId: value.sessionId,
+        model: value.model,
+        cliModel: value.cliModel,
+        family: value.family,
+        context: value.context,
+        updatedAt: Number.isNaN(updatedAt) ? 0 : updatedAt,
+    };
+}
+export function readClaudeCodeSessionMetadata(sessionFile) {
+    if (!nonempty(sessionFile)) {
+        return;
+    }
+    try {
+        const value = JSON.parse(fs.readFileSync(`${sessionFile}.metadata.json`, "utf8"));
+        return validateMetadata(value);
+    }
+    catch (error) {
+        if (!hasErrorCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+    if (!fs.existsSync(sessionFile)) {
+        return;
+    }
+    let metadata;
+    // Legacy metadata is recovered read-only; updates never rewrite its audit messages.
+    scanJournal(sessionFile, (keys) => keys.length === 0 || ["type", "claudeCode"].includes(String(keys[0])) ? 4096 : false, ({ value }) => {
+        if (value.type === SESSION_EVENT_TYPE) {
+            metadata ??= validateMetadata(value.claudeCode);
+        }
+    }, { policy: "inspect" });
+    return metadata;
+}
+export function writeClaudeCodeSessionMetadata(sessionFile, metadata) {
+    fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+    writeAtomicJson(`${sessionFile}.metadata.json`, metadata);
+    fs.closeSync(fs.openSync(sessionFile, "a", 0o600));
+}
+export function appendClaudeCodeMessage(sessionFile, message, observation) {
+    if (!nonempty(sessionFile)) {
+        return;
+    }
+    fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+    fs.appendFileSync(sessionFile, `${JSON.stringify({ type: "message_end", message, ...(observation ? { claudeCodeResult: observation } : {}) })}\n`, { mode: 0o600 });
+}
+export function hasNonMetadataContent(sessionFile) {
+    if (!fs.existsSync(sessionFile)) {
+        return false;
+    }
+    let content = false;
+    scanJournal(sessionFile, (keys) => keys.length === 0 || (keys.length === 1 && keys[0] === "type"), ({ value }) => {
+        if (value.type !== SESSION_EVENT_TYPE) {
+            content = true;
+        }
+    }, {
+        policy: "inspect",
+        malformed: () => {
+            content = true;
+        },
+    });
+    return content;
+}

package/dist/runs/shared/claude-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runs/shared/completion-guard.js

@@ -1,31 +1,31 @@
 import { createMutationCompletionTracker } from "./mutating-tool-guard.js";
 export function resolveCompletionPolicy(input) {
-    if (input.usesAcceptanceContract)
+    if (input.usesAcceptanceContract) {
         return "acceptance-contract";
+    }
     return input.completionGuardEnabled ? "mutation-guard" : "none";
 }
+function recordAssistantCalls(message, tracker) {
+    for (const part of message.content) {
+        if (part.type === "toolCall") {
+            tracker.recordToolStart({
+                id: part.id,
+                toolName: part.name,
+                args: part.arguments,
+            });
+        }
+    }
+}
 export function hasCompletedMutationToolCall(messages) {
-    const mutations = createMutationCompletionTracker();
+    const tracker = createMutationCompletionTracker();
     for (const message of messages) {
         if (message.role === "assistant") {
-            for (const part of message.content) {
-                if (part.type !== "toolCall")
-                    continue;
-                const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
-                    ? part.arguments
-                    : {};
-                mutations.recordToolStart({
-                    id: typeof part.id === "string" ? part.id : undefined,
-                    toolName: typeof part.name === "string" ? part.name : undefined,
-                    args,
-                });
-            }
-            continue;
+            recordAssistantCalls(message, tracker);
         }
-        if (message.role !== "toolResult")
-            continue;
-        if (mutations.recordToolResult(message)?.completedMutation)
+        else if (message.role === "toolResult" &&
+            tracker.recordToolResult(message)?.completedMutation === true) {
             return true;
+        }
     }
     return false;
 }

package/dist/runs/shared/control-event-policy.js

@@ -0,0 +1,8 @@
+export function shouldNotifyControlEvent(config, event) {
+    return config.enabled && config.notifyOn.includes(event.type);
+}
+export function controlNotificationKey(event, childIntercomTarget) {
+    const childKey = childIntercomTarget ??
+        (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+    return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+}

package/dist/runs/shared/control-notification-owner.js

@@ -0,0 +1,13 @@
+import { controlNotificationKey, shouldNotifyControlEvent } from "./control-event-policy.js";
+/** Explicit mutation contract: the caller owns seenKeys; a successful claim adds one key. */
+export function claimControlNotification(config, event, seenKeys, childIntercomTarget) {
+    if (!shouldNotifyControlEvent(config, event)) {
+        return false;
+    }
+    const key = controlNotificationKey(event, childIntercomTarget);
+    if (seenKeys.has(key)) {
+        return false;
+    }
+    seenKeys.add(key);
+    return true;
+}