@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/dist/runs/shared/child-boundaries.js

@@ -0,0 +1,173 @@
+import * as path from "node:path";
+import { scanJournal } from "../../shared/journal-reader.js";
+import { FINALIZATION_EVENT, } from "./native-finalization-types.js";
+import { parseNativeFinalizationEvent } from "../background/run-schemas.js";
+import { readFinalizationReport } from "./acceptance.js";
+import { addUsage } from "./native-usage.js";
+import { hasErrorCode } from "../../shared/unknown.js";
+import { nonempty } from "./child-presence.js";
+function segmentUsage(messages) {
+    const usage = {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: 0,
+        turns: 0,
+    };
+    let assistantTokens = 0;
+    for (const message of messages) {
+        if (message.role === "assistant") {
+            usage.turns++;
+            assistantTokens += (message.usage?.input ?? 0) + (message.usage?.output ?? 0);
+        }
+        if ((message.role === "assistant" || message.role === "toolResult") && message.usage) {
+            addUsage(usage, message.usage);
+        }
+    }
+    return { usage, assistantTokens };
+}
+/** Native markers reset per-review limits only after all their messages have been observed. */
+export class ChildBoundaries {
+    options;
+    cursor = 0;
+    pending = new Error("pending native boundary");
+    segments = [];
+    priorUsage = {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: 0,
+        turns: 0,
+    };
+    messageOffset = 0;
+    assistantTokens = 0;
+    startedAt;
+    constructor(options, startedAt) {
+        this.options = options;
+        this.startedAt = startedAt;
+    }
+    snapshot() {
+        return this.segments;
+    }
+    sync(messages, nativeMessageCount) {
+        const config = this.options.config;
+        if (!config) {
+            return;
+        }
+        const file = path.join(path.dirname(config.reportRuntime.schemaPath), "boundaries.jsonl");
+        try {
+            scanJournal(file, () => true, ({ value, end }) => {
+                const marker = parseNativeFinalizationEvent(value);
+                if (marker.nonce !== config.nonce) {
+                    throw new Error("Unexpected finalization nonce");
+                }
+                if (marker.messageCount > nativeMessageCount) {
+                    throw this.pending;
+                }
+                this.accept(marker, messages);
+                this.cursor = end;
+            }, { policy: "live", start: this.cursor });
+        }
+        catch (error) {
+            if (error !== this.pending && !hasErrorCode(error, "ENOENT")) {
+                throw error;
+            }
+        }
+        return this.segments;
+    }
+    accept(marker, messages) {
+        const selected = messages
+            .filter((message) => ["assistant", "user", "toolResult"].includes(message.role))
+            .slice(this.messageOffset, marker.messageCount);
+        const { usage, assistantTokens } = segmentUsage(selected);
+        this.segments.push({
+            event: { ...marker, submission: { ...marker.submission } },
+            messages: selected,
+            usage,
+            durationMs: marker.at - this.startedAt,
+        });
+        this.enforceLimits(marker.at, assistantTokens);
+        if (nonempty(marker.nextPrompt)) {
+            this.messageOffset = marker.messageCount;
+            this.assistantTokens += assistantTokens;
+            for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"]) {
+                this.priorUsage[key] += usage[key];
+            }
+            this.startedAt = marker.at;
+            this.options.onReset();
+        }
+        this.options.onMarker(marker);
+    }
+    enforceLimits(at, tokens) {
+        if (this.options.maxTokens !== undefined && tokens >= this.options.maxTokens) {
+            this.options.onLimit("maxTokens", this.options.maxTokens, tokens);
+        }
+        if (this.options.maxExecutionTimeMs !== undefined &&
+            at - this.startedAt >= this.options.maxExecutionTimeMs) {
+            this.options.onLimit("maxExecutionTimeMs", this.options.maxExecutionTimeMs);
+        }
+    }
+    finish(result) {
+        const config = this.options.config;
+        if (!config) {
+            return { missing: false };
+        }
+        const previous = this.segments.at(-1);
+        if (nonempty(previous?.event.nextPrompt)) {
+            this.appendInterruptedReview(result);
+        }
+        const final = this.segments.at(-1);
+        if (!final) {
+            return {
+                missing: result.exitCode === 0 && !nonempty(result.error) && result.interrupted !== true,
+            };
+        }
+        if (final.event.turn > 0) {
+            final.event.submission = {
+                ...readFinalizationReport([...result.messages], config.reportRuntime, {
+                    messageOffset: this.messageOffset,
+                }),
+                error: final.event.submission.error,
+            };
+        }
+        final.execution = {
+            exitCode: result.exitCode,
+            error: result.error,
+            interrupted: result.interrupted,
+            timedOut: result.timedOut,
+            resourceLimitExceeded: result.resourceLimitExceeded,
+            terminalFailure: result.terminalFailure,
+        };
+        return { finalization: this.segments, missing: false };
+    }
+    appendInterruptedReview(result) {
+        const previous = this.segments.at(-1);
+        const config = this.options.config;
+        if (!previous || !config) {
+            return;
+        }
+        const usage = {
+            ...result.usage,
+            contributions: result.usage.contributions?.slice(this.priorUsage.contributions?.length ?? 0),
+        };
+        for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"]) {
+            usage[key] -= this.priorUsage[key];
+        }
+        this.segments.push({
+            event: {
+                type: FINALIZATION_EVENT,
+                nonce: config.nonce,
+                turn: previous.event.turn + 1,
+                messageCount: result.messages.length,
+                at: Date.now(),
+                submission: { output: "" },
+                resolvedOutput: previous.event.resolvedOutput,
+            },
+            messages: result.messages.slice(this.messageOffset),
+            usage,
+            durationMs: Date.now() - this.startedAt,
+        });
+    }
+}

package/dist/runs/shared/child-context-filter.js

@@ -0,0 +1,44 @@
+const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
+    "subagent-orchestration-instructions",
+    "subagent-slash-result",
+    "subagent-notify",
+    "subagent_control_notice",
+    "subagent-control",
+    "subagent-control-notice",
+]);
+const ORCHESTRATION_TOOLS = new Set(["subagent", "delegate", "agent_runs", "load_subagent"]);
+function parentOnlyMessage(message, fanoutChild) {
+    if (message.role === "custom") {
+        return PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(message.customType);
+    }
+    return !fanoutChild && message.role === "toolResult" && ORCHESTRATION_TOOLS.has(message.toolName);
+}
+function stripParentToolCalls(message) {
+    if (message.role !== "assistant") {
+        return message;
+    }
+    const content = message.content.filter((block) => block.type !== "toolCall" || !ORCHESTRATION_TOOLS.has(block.name));
+    if (content.length === message.content.length) {
+        return message;
+    }
+    return content.length === 0 ? undefined : { ...message, content };
+}
+/** Only the request-local context changes. Native saved history is never rewritten. */
+export function stripParentOnlySubagentMessages(messages, fanoutChild = false) {
+    let changed = false;
+    const filtered = [];
+    for (const message of messages) {
+        if (parentOnlyMessage(message, fanoutChild)) {
+            changed = true;
+            continue;
+        }
+        const stripped = fanoutChild ? message : stripParentToolCalls(message);
+        if (stripped === undefined) {
+            changed = true;
+            continue;
+        }
+        changed ||= stripped !== message;
+        filtered.push(stripped);
+    }
+    return changed ? filtered : undefined;
+}

package/dist/runs/shared/child-event-observer.js

@@ -0,0 +1,390 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { providerQualifiedModelId } from "../../shared/model-info.js";
+import { extractTextFromContent, extractToolArgsPreview, getFinalOutput, } from "../../shared/utils.js";
+import { appendClaudeCodeMessage, claudeCodeMessageFromResult, writeClaudeCodeSessionMetadata, } from "./claude-code.js";
+import { ChildBoundaries } from "./child-boundaries.js";
+import { addUsage, nativeUsageMetadata, validateNativeUsage, } from "./native-usage.js";
+import { compactObservedMessage } from "./child-observations.js";
+import { observedMessage, optionalBoolean, optionalNumber, optionalString, requiredString, } from "./child-message-validation.js";
+import { errorMessage as errorText, isRecord as isObject } from "../../shared/unknown.js";
+import { nonempty } from "./child-presence.js";
+import { createMutationCompletionTracker, resolveCurrentPath, } from "./mutating-tool-guard.js";
+import { createRepeatedSubagentCallGuardState, recordToolEndForSubagentLoopGuard, recordToolStartForSubagentLoopGuard, } from "./subagent-tool-loop-guard.js";
+function childEvent(value) {
+    const update = isObject(value.assistantMessageEvent) ? value.assistantMessageEvent : undefined;
+    if (value.args !== undefined && !isObject(value.args)) {
+        throw new SyntaxError("Invalid child tool arguments");
+    }
+    const type = optionalString(value.type, "child event type");
+    const fields = {
+        ...value,
+        type,
+        message: undefined,
+        toolCallId: optionalString(value.toolCallId, "toolCallId"),
+        toolName: optionalString(value.toolName, "toolName"),
+        args: value.args,
+        isError: optionalBoolean(value.isError, "isError"),
+        assistantMessageEvent: update
+            ? {
+                ...update,
+                type: requiredString(update.type, "assistant update type"),
+                delta: optionalString(update.delta, "delta"),
+                contentIndex: optionalNumber(update.contentIndex, "contentIndex"),
+            }
+            : undefined,
+    };
+    if (type === "message_end") {
+        return {
+            ...fields,
+            type,
+            message: value.message === undefined ? undefined : observedMessage(value.message),
+        };
+    }
+    if (type === "message_start" || type === "message_update") {
+        return {
+            ...fields,
+            type,
+            message: value.message === undefined ? undefined : messageHeader(value.message),
+        };
+    }
+    return fields;
+}
+function messageHeader(value) {
+    if (!isObject(value)) {
+        throw new SyntaxError("Invalid native message header");
+    }
+    return {
+        ...value,
+        role: requiredString(value.role, "message role"),
+        timestamp: optionalNumber(value.timestamp, "timestamp"),
+    };
+}
+function claudeResult(value) {
+    const usage = isObject(value.usage) ? value.usage : undefined;
+    const models = isObject(value.modelUsage) ? value.modelUsage : undefined;
+    const modelUsage = {};
+    for (const [name, metadata] of Object.entries(models ?? {})) {
+        if (!isObject(metadata)) {
+            throw new SyntaxError("Invalid Claude model usage");
+        }
+        modelUsage[name] = {
+            contextWindow: optionalNumber(metadata.contextWindow, "contextWindow"),
+            maxOutputTokens: optionalNumber(metadata.maxOutputTokens, "maxOutputTokens"),
+        };
+    }
+    return {
+        ...value,
+        type: optionalString(value.type, "type"),
+        subtype: optionalString(value.subtype, "subtype"),
+        is_error: optionalBoolean(value.is_error, "is_error"),
+        api_error_status: value.api_error_status === null
+            ? null
+            : optionalNumber(value.api_error_status, "api_error_status"),
+        result: optionalString(value.result, "result"),
+        stop_reason: optionalString(value.stop_reason, "stop_reason"),
+        session_id: optionalString(value.session_id, "session_id"),
+        total_cost_usd: optionalNumber(value.total_cost_usd, "total_cost_usd"),
+        usage: usage
+            ? {
+                input_tokens: optionalNumber(usage.input_tokens, "input_tokens"),
+                output_tokens: optionalNumber(usage.output_tokens, "output_tokens"),
+                cache_read_input_tokens: optionalNumber(usage.cache_read_input_tokens, "cache_read_input_tokens"),
+                cache_creation_input_tokens: optionalNumber(usage.cache_creation_input_tokens, "cache_creation_input_tokens"),
+            }
+            : undefined,
+        modelUsage: models ? modelUsage : undefined,
+    };
+}
+function assistantStoppedCleanly(message) {
+    return (message.stopReason === "stop" &&
+        !nonempty(message.errorMessage) &&
+        !message.content.some((part) => part.type === "toolCall"));
+}
+/** Owns live message facts and provisional accounting; native publication is verified at finish. */
+export class ChildEventObserver {
+    result;
+    baseline;
+    acceptedEntries = new Map();
+    boundaries;
+    options;
+    controls;
+    baselineSnapshot;
+    startedAt;
+    streamId = randomUUID();
+    mutations = createMutationCompletionTracker();
+    toolLoop = createRepeatedSubagentCallGuardState();
+    nativeMessageCount = 0;
+    assistantTokens = 0;
+    assistantError;
+    cleanAssistantStop = false;
+    lastOutput = "";
+    constructor(options, baseline, controls, startedAt) {
+        this.options = options;
+        this.controls = controls;
+        this.baselineSnapshot = baseline;
+        this.baseline = new Set(baseline.ids);
+        this.startedAt = startedAt;
+        this.result = {
+            stderr: "",
+            exitCode: 0,
+            messages: [],
+            model: options.model,
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+            finalOutput: "",
+            observedCompletedMutation: false,
+            durationMs: 0,
+            attemptBaseline: [...this.baseline],
+        };
+        this.boundaries = new ChildBoundaries({
+            config: options.nativeFinalization,
+            maxTokens: options.maxTokens,
+            maxExecutionTimeMs: options.maxExecutionTimeMs,
+            onLimit: controls.resourceLimit,
+            onReset: controls.resetTimer,
+            onMarker: (marker) => {
+                this.result.finalization = this.boundaries.snapshot();
+                options.onEvent?.(marker, this.result);
+            },
+        }, startedAt);
+    }
+    sync() {
+        this.result.finalization = this.boundaries.sync(this.result.messages, this.nativeMessageCount);
+    }
+    prepare(raw) {
+        let event = childEvent(raw);
+        if (event.type === "message_end" && !event.message) {
+            throw new Error("Child message_end event is missing its message");
+        }
+        if (event.type !== "message_update") {
+            this.sync();
+        }
+        if (event.type === "subagent.native_baseline") {
+            this.reconcileBaseline(raw);
+        }
+        if (event.type === "subagent.native") {
+            event = { ...event, ...this.observeNative(raw) };
+        }
+        return this.observeLifecycleAndClaude(event, raw);
+    }
+    observeLifecycleAndClaude(event, raw) {
+        const isClaudeResult = this.options.claudeCodeInvocation !== undefined && event.type === "result";
+        this.controls.observeLifecycle(isClaudeResult ? "agent_settled" : event.type);
+        return isClaudeResult
+            ? { type: "message_end", message: this.observeClaude(claudeResult(raw)) }
+            : event;
+    }
+    process(raw, textWritten) {
+        const event = this.prepare(raw);
+        const loopFailure = this.observeTool(event);
+        let mutation;
+        if (event.type === "message_end" && event.message) {
+            this.observeMessage(event.message, textWritten);
+            if (event.message.role === "toolResult") {
+                mutation = this.observeMutation(event.message);
+            }
+        }
+        this.result.durationMs = Date.now() - this.startedAt;
+        this.options.onEvent?.(event, this.result, mutation);
+        if (nonempty(loopFailure) && !this.controls.stopping()) {
+            this.result.terminalFailure = true;
+            this.controls.stop({ error: loopFailure });
+        }
+        if (event.type === "message_end") {
+            this.sync();
+        }
+        this.enforceTokenLimit();
+        return { messageCount: this.nativeMessageCount, message: this.result.messages.at(-1) };
+    }
+    enforceTokenLimit() {
+        const tokens = this.assistantTokens - this.boundaries.assistantTokens;
+        if (this.options.maxTokens !== undefined && tokens >= this.options.maxTokens) {
+            this.controls.resourceLimit("maxTokens", this.options.maxTokens, tokens);
+        }
+    }
+    reconcileBaseline(value) {
+        const ids = value.entryIds;
+        if (!this.baselineSnapshot.legacy ||
+            value.sessionId !== this.baselineSnapshot.sessionId ||
+            !Array.isArray(ids)) {
+            throw new Error("Cannot reconcile native legacy baseline");
+        }
+        const entryIds = ids.map((id) => requiredString(id, "baseline entry ID"));
+        if (new Set(entryIds).size !== this.baselineSnapshot.entryCount ||
+            entryIds.some((id) => id.length === 0)) {
+            throw new Error("Cannot reconcile native legacy baseline");
+        }
+        this.baseline.clear();
+        this.baseline.add(requiredString(value.sessionId, "baseline session ID"));
+        for (const id of entryIds) {
+            this.baseline.add(id);
+        }
+        this.result.attemptBaseline = [...this.baseline];
+    }
+    observeNative(value) {
+        if (!Array.isArray(value.entries)) {
+            throw new SyntaxError("Invalid native entries observation");
+        }
+        const entries = value.entries.map((entry) => nativeUsageMetadata(entry));
+        this.result.nativeSessionId = requiredString(value.sessionId, "native session ID");
+        this.result.terminalLeafId =
+            value.leafId === null ? null : optionalString(value.leafId, "leafId");
+        this.result.terminalEntryId = entries.at(-1)?.id ?? this.result.terminalEntryId;
+        this.result.effectiveConfiguration = this.configuration(value.configuration);
+        const nativeReferences = [];
+        for (const entry of entries) {
+            if (value.persisted !== true) {
+                this.acceptedEntries.set(entry.id, entry);
+            }
+            else if (entry.message && !this.baseline.has(entry.id)) {
+                const observation = this.controls.reference(entry);
+                if (observation) {
+                    nativeReferences.push({ messageNumber: observation.number, entryId: entry.id });
+                }
+            }
+        }
+        return { nativeReferences, referenceState: "observed" };
+    }
+    configuration(value) {
+        if (value === undefined) {
+            return;
+        }
+        if (!isObject(value)) {
+            throw new SyntaxError("Invalid native configuration");
+        }
+        return {
+            model: optionalString(value.model, "configuration.model"),
+            thinking: optionalString(value.thinking, "configuration.thinking"),
+            modelRecordedAt: optionalNumber(value.modelRecordedAt, "configuration.modelRecordedAt"),
+        };
+    }
+    observeClaude(event) {
+        const invocation = this.options.claudeCodeInvocation;
+        if (!invocation) {
+            throw new Error("Missing Claude invocation");
+        }
+        this.result.accounting = {
+            state: "incomplete",
+            error: "Claude Code did not provide the complete native usage/cost receipt. Reported totals and its audit were retained.",
+        };
+        if (this.options.structuredOutput && event.structured_output !== undefined) {
+            fs.mkdirSync(path.dirname(this.options.structuredOutput.outputPath), { recursive: true });
+            fs.writeFileSync(this.options.structuredOutput.outputPath, `${JSON.stringify(event.structured_output)}\n`, "utf8");
+        }
+        const message = claudeCodeMessageFromResult(event, invocation.model.inputModel);
+        if (nonempty(this.options.sessionFile)) {
+            writeClaudeCodeSessionMetadata(this.options.sessionFile, {
+                sessionId: nonempty(event.session_id) ? event.session_id : invocation.sessionId,
+                model: invocation.model.inputModel,
+                cliModel: invocation.model.cliModel,
+                family: invocation.model.family,
+                context: invocation.model.context,
+                updatedAt: Date.now(),
+            });
+            const { result: _result, structured_output: _structured, ...observation } = event;
+            appendClaudeCodeMessage(this.options.sessionFile, message, observation);
+        }
+        return message;
+    }
+    observeTool(event) {
+        let loopFailure;
+        if (event.type === "tool_execution_start") {
+            loopFailure = recordToolStartForSubagentLoopGuard({
+                state: this.toolLoop,
+                ...event,
+                toolName: event.toolName,
+                args: event.args,
+            });
+            this.mutations.recordToolStart({
+                id: event.toolCallId,
+                toolName: event.toolName,
+                args: event.args,
+                path: resolveCurrentPath(event.toolName, event.args),
+                startedAt: Date.now(),
+            });
+            const args = extractToolArgsPreview(event.args ?? {});
+            if (nonempty(event.toolName)) {
+                this.options.onOutput?.(`${event.toolName}${args.length > 0 ? `: ${args}` : ""}\n`);
+            }
+        }
+        else if (event.type === "tool_execution_end") {
+            loopFailure = recordToolEndForSubagentLoopGuard({
+                state: this.toolLoop,
+                ...event,
+                toolName: event.toolName,
+                isError: event.isError,
+            });
+        }
+        return loopFailure;
+    }
+    observeMutation(message) {
+        const mutation = this.mutations.recordToolResult(message);
+        if (mutation?.completedMutation === true) {
+            this.result.observedCompletedMutation = true;
+        }
+        return mutation;
+    }
+    observeMessage(message, textWritten) {
+        if (message.role === "assistant" && !message.usage) {
+            this.result.accounting = {
+                state: "incomplete",
+                error: "Required assistant usage is unavailable; execution was not repeated.",
+            };
+        }
+        const final = getFinalOutput([message]);
+        if (final.length > 0) {
+            this.lastOutput = final;
+        }
+        this.result.messages.push(compactObservedMessage(message));
+        if (["assistant", "user", "toolResult"].includes(message.role)) {
+            this.nativeMessageCount++;
+        }
+        this.result.messageCount = this.nativeMessageCount;
+        const text = this.emitMessageText(message, textWritten);
+        if ((message.role === "assistant" || message.role === "toolResult") && message.usage) {
+            this.observeUsage(message);
+        }
+        if (message.role === "assistant") {
+            this.observeAssistant(message, text);
+        }
+    }
+    emitMessageText(message, textWritten) {
+        const text = extractTextFromContent(message.content);
+        if (textWritten) {
+            this.options.onOutput?.("\n");
+        }
+        else if (this.options.claudeCodeInvocation && text.length > 0) {
+            this.options.onOutput?.(`${text}\n`);
+        }
+        return text;
+    }
+    observeUsage(message) {
+        if (!message.usage) {
+            return;
+        }
+        try {
+            addUsage(this.result.usage, message.usage, {
+                id: `stream:${this.streamId}:${this.result.messages.length}`,
+                provider: message.role === "assistant" ? message.provider : undefined,
+                model: message.role === "assistant" ? (message.responseModel ?? message.model) : undefined,
+            });
+            validateNativeUsage(message.usage);
+        }
+        catch (error) {
+            this.result.accounting = { state: "incomplete", error: errorText(error) };
+        }
+    }
+    observeAssistant(message, text) {
+        this.result.model ??= providerQualifiedModelId(message.provider, message.model);
+        this.result.usage.turns++;
+        this.assistantTokens += (message.usage?.input ?? 0) + (message.usage?.output ?? 0);
+        if (nonempty(message.errorMessage)) {
+            this.assistantError = message.errorMessage;
+        }
+        this.cleanAssistantStop = assistantStoppedCleanly(message);
+        if (this.cleanAssistantStop && text.trim().length > 0) {
+            this.assistantError = undefined;
+        }
+    }
+}