@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

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

@@ -0,0 +1,185 @@
+export function splitThinkingSuffix(model) {
+    const colonIdx = model.lastIndexOf(":");
+    if (colonIdx === -1)
+        return { baseModel: model, thinkingSuffix: "" };
+    return {
+        baseModel: model.substring(0, colonIdx),
+        thinkingSuffix: model.substring(colonIdx),
+    };
+}
+export function resolveModelCandidate(model, availableModels, preferredProvider) {
+    if (!model)
+        return undefined;
+    if (model.includes("/"))
+        return model;
+    if (!availableModels || availableModels.length === 0)
+        return model;
+    const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+    const matches = availableModels.filter((entry) => entry.id === baseModel);
+    if (preferredProvider) {
+        const preferredMatch = matches.find((entry) => entry.provider === preferredProvider);
+        if (preferredMatch)
+            return `${preferredMatch.fullId}${thinkingSuffix}`;
+    }
+    if (matches.length !== 1)
+        return model;
+    return `${matches[0].fullId}${thinkingSuffix}`;
+}
+export function buildModelCandidates(primaryModel, fallbackModels, availableModels, preferredProvider) {
+    const seen = new Set();
+    const candidates = [];
+    for (const raw of [primaryModel, ...(fallbackModels ?? [])]) {
+        if (!raw)
+            continue;
+        const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        candidates.push(normalized);
+    }
+    return candidates;
+}
+const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+    /rate\s*limit/i,
+    /usage\s*limit/i,
+    /too many requests/i,
+    /\b429\b/,
+    /quota/i,
+    /billing/i,
+    /credit/i,
+    /auth(?:entication)?/i,
+    /unauthori[sz]ed/i,
+    /forbidden/i,
+    /api key/i,
+    /token expired/i,
+    /invalid key/i,
+    /provider.*unavailable/i,
+    /model.*unavailable/i,
+    /model.*disabled/i,
+    /model.*not found/i,
+    /unknown model/i,
+    /overloaded/i,
+    /service unavailable/i,
+    /temporar(?:ily)? unavailable/i,
+    /connection refused/i,
+    /database is locked/i,
+    /\bsqlite_busy\b/i,
+    /fetch failed/i,
+    /network error/i,
+    /socket hang up/i,
+    /upstream/i,
+    /timed? out/i,
+    /timeout/i,
+    /\b502\b/,
+    /\b503\b/,
+    /\b504\b/,
+];
+export function isRetryableModelFailure(error) {
+    if (!error)
+        return false;
+    return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
+}
+const NON_RECOVERABLE_SAME_MODEL_PATTERNS = [
+    /usage\s*limit/i,
+    /quota/i,
+    /billing/i,
+    /credit/i,
+    /auth(?:entication)?/i,
+    /unauthori[sz]ed/i,
+    /forbidden/i,
+    /api key/i,
+    /token expired/i,
+    /invalid key/i,
+    /model.*disabled/i,
+    /model.*not found/i,
+    /unknown model/i,
+];
+const SAME_MODEL_RECOVERY_PATTERNS = [
+    /web\s*socket/i,
+    /websocket/i,
+    /transport/i,
+    /stream/i,
+    /socket/i,
+    /connection/i,
+    /fetch failed/i,
+    /network/i,
+    /http idle/i,
+    /timed? out/i,
+    /timeout/i,
+    /overloaded/i,
+    /service unavailable/i,
+    /temporar(?:ily)? unavailable/i,
+    /connection refused/i,
+    /database is locked/i,
+    /\bsqlite_busy\b/i,
+    /econnreset/i,
+    /etimedout/i,
+    /\b502\b/,
+    /\b503\b/,
+    /\b504\b/,
+];
+export function isRecoverableSameModelFailure(error, exitCode) {
+    if (exitCode === 143)
+        return true;
+    if (!error)
+        return false;
+    if (NON_RECOVERABLE_SAME_MODEL_PATTERNS.some((pattern) => pattern.test(error)))
+        return false;
+    return SAME_MODEL_RECOVERY_PATTERNS.some((pattern) => pattern.test(error));
+}
+export function formatModelAttemptNote(attempt, nextModel) {
+    const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
+    return nextModel
+        ? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
+        : `[fallback] ${attempt.model} failed: ${failure}.`;
+}
+export function formatModelRecoveryAttemptNote(attempt, retryNumber, maxRetries) {
+    const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
+    return `[retry] ${attempt.model} failed: ${failure}. Retrying same model (${retryNumber}/${maxRetries}).`;
+}
+export function sumAttemptUsage(attempts) {
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    for (const attempt of attempts) {
+        for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"])
+            usage[key] += attempt.usage?.[key] ?? 0;
+        if (attempt.usage?.contributions?.length)
+            (usage.contributions ??= []).push(...attempt.usage.contributions);
+    }
+    return usage;
+}
+export async function runModelAttempts(input) {
+    const candidates = input.candidates.length ? input.candidates : [undefined];
+    const modelAttempts = [];
+    const attemptedModels = [];
+    const notes = [];
+    let result;
+    modelLoop: for (let index = 0; index < candidates.length; index++) {
+        const model = candidates[index];
+        for (let recovery = 0;; recovery++) {
+            result = await input.runAttempt(model, notes);
+            if (model)
+                attemptedModels.push(model);
+            const attempt = {
+                model: model ?? result.model ?? "default",
+                success: result.exitCode === 0 && !result.error && !result.interrupted,
+                exitCode: result.exitCode,
+                error: result.error,
+                accounting: result.accounting,
+                usage: { ...result.usage },
+            };
+            modelAttempts.push(attempt);
+            if (attempt.success || input.signal?.aborted || result.interrupted || result.timedOut || result.resourceLimitExceeded || result.terminalFailure)
+                break modelLoop;
+            const recoverable = isRecoverableSameModelFailure(result.error, result.exitCode);
+            if (recoverable && recovery === 0) {
+                notes.push(formatModelRecoveryAttemptNote(attempt, 1, 1));
+                continue;
+            }
+            if ((!recoverable && !isRetryableModelFailure(result.error)) || index === candidates.length - 1)
+                break modelLoop;
+            notes.push(formatModelAttemptNote(attempt, candidates[index + 1]));
+            break;
+        }
+    }
+    return { result, modelAttempts, attemptedModels, notes, usage: sumAttemptUsage(modelAttempts) };
+}

package/dist/runs/shared/mutating-tool-guard.js

@@ -0,0 +1,170 @@
+const MUTATING_BASH_PATTERNS = [
+    /(^|[;&|()\s])rm\s+/,
+    /(^|[;&|()\s])mv\s+/,
+    /(^|[;&|()\s])cp\s+/,
+    /(^|[;&|()\s])mkdir\s+/,
+    /(^|[;&|()\s])touch\s+/,
+    /(^|[;&|()\s])git\s+apply\b/,
+    /(^|[;&|()\s])patch\s+/,
+    /(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
+    /(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
+    /(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
+    /\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
+    /\bwrite_text\s*\(/,
+    /\bopen\s*\([^)]*,\s*["'][wa]/,
+];
+export function resolveCurrentPath(toolName, args) {
+    if (!toolName || !args)
+        return undefined;
+    const direct = ["path", "file", "filename", "target", "cwd"];
+    for (const key of direct) {
+        const value = args[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    if (toolName === "bash") {
+        const command = typeof args.command === "string" ? args.command : undefined;
+        if (!command)
+            return undefined;
+        const redirect = command.match(/(?:>>?|tee\s+)\s*([^&>\s][^\s;&|]*)/);
+        if (redirect?.[1])
+            return redirect[1];
+    }
+    return undefined;
+}
+function hasUnquotedFileRedirection(command) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (char === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (inSingle || inDouble)
+            continue;
+        if (char !== ">")
+            continue;
+        if (command[i - 1] === "-")
+            continue;
+        const isDouble = command[i + 1] === ">";
+        let cursor = i + (isDouble ? 2 : 1);
+        while (cursor < command.length && /\s/.test(command[cursor]))
+            cursor++;
+        if (cursor >= command.length)
+            continue;
+        const targetStart = command[cursor];
+        if (targetStart === "&" || targetStart === "|" || targetStart === ";")
+            continue;
+        if (targetStart === "(" || targetStart === ")")
+            continue;
+        return true;
+    }
+    return false;
+}
+export function isMutatingBashCommand(command) {
+    return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+}
+export function isMutatingTool(toolName, args) {
+    if (!toolName || args?.preview === true)
+        return false;
+    if (["edit", "write", "apply_edits", "apply_patch", "replace_text", "write_files"].includes(toolName))
+        return true;
+    if (toolName !== "bash")
+        return false;
+    const command = typeof args?.command === "string" ? args.command : "";
+    if (!command.trim())
+        return false;
+    return isMutatingBashCommand(command);
+}
+export function createMutationCompletionTracker() {
+    const pending = [];
+    const take = (input) => {
+        const id = typeof input?.toolCallId === "string" ? input.toolCallId : undefined;
+        if (id) {
+            const index = pending.findIndex((tool) => tool.id === id);
+            if (index >= 0)
+                return pending.splice(index, 1)[0];
+        }
+        const name = typeof input?.toolName === "string" ? input.toolName : undefined;
+        if (name) {
+            const index = pending.findIndex((tool) => tool.tool === name);
+            if (index >= 0)
+                return pending.splice(index, 1)[0];
+        }
+        return pending.shift();
+    };
+    return {
+        recordToolStart(input) {
+            const tool = input.toolName ?? "tool";
+            const entry = {
+                id: input.id,
+                tool,
+                path: input.path,
+                mutates: input.mutates ?? isMutatingTool(input.toolName, input.args),
+                startedAt: input.startedAt,
+            };
+            pending.push(entry);
+            return entry;
+        },
+        recordToolResult(input) {
+            const entry = take(input);
+            if (!entry)
+                return undefined;
+            const errored = input?.isError === true;
+            const details = input?.details && typeof input.details === "object" ? input.details : undefined;
+            const committed = Array.isArray(details?.modifiedFiles)
+                ? details.modifiedFiles.some((file) => typeof file === "string" && file.trim().length > 0)
+                : !errored && !["apply_patch", "replace_text", "write_files"].includes(entry.tool);
+            return { ...entry, errored, completedMutation: entry.mutates && details?.preview !== true && committed };
+        },
+    };
+}
+export function resetMutatingFailureState(state) {
+    state.consecutiveFailures = 0;
+    state.lastFailureAt = undefined;
+    state.recentFailures = [];
+    state.lastMutatingPath = undefined;
+    state.repeatedPathFailures = 0;
+}
+export function createMutatingFailureState() {
+    return {
+        consecutiveFailures: 0,
+        recentFailures: [],
+        repeatedPathFailures: 0,
+    };
+}
+export function recordMutatingFailure(state, input, windowMs) {
+    if (state.lastFailureAt === undefined || input.ts - state.lastFailureAt > windowMs) {
+        state.consecutiveFailures = 0;
+        state.recentFailures = [];
+        state.repeatedPathFailures = 0;
+        state.lastMutatingPath = undefined;
+    }
+    state.lastFailureAt = input.ts;
+    state.consecutiveFailures += 1;
+    if (input.path && state.lastMutatingPath === input.path) {
+        state.repeatedPathFailures += 1;
+    }
+    else if (input.path) {
+        state.lastMutatingPath = input.path;
+        state.repeatedPathFailures = 1;
+    }
+    state.recentFailures.push(input);
+    if (state.recentFailures.length > 3)
+        state.recentFailures.shift();
+}
+export function shouldEscalateMutatingFailures(state, threshold) {
+    return state.consecutiveFailures >= threshold || state.repeatedPathFailures >= threshold;
+}
+export function summarizeRecentMutatingFailures(state) {
+    if (state.recentFailures.length === 0)
+        return undefined;
+    return state.recentFailures
+        .map((entry) => `${entry.tool}${entry.path ? `(${entry.path})` : ""}: ${entry.error}`)
+        .join(" | ");
+}

package/dist/runs/shared/native-finalization.js

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Type } from "../../shared/native-typebox.js";
+import { setPromptSection } from "../../shared/prompt-sections.js";
+import { detectSubagentError, getFinalOutput } from "../../shared/utils.js";
+import { acceptanceFailureMessage, acceptanceSelfReviewConfig, createFinalizationReportRuntime, evaluateAcceptance, formatAcceptanceFinalizationPrompt, readFinalizationReport, resolveFinalizationOutput, stripAcceptanceReport, } from "./acceptance.js";
+import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.js";
+import { readStructuredOutput, validateStructuredOutputValue } from "./structured-output.js";
+import { compactObservedMessage } from "./child-observations.js";
+const CONFIG_ENV = "PI_SUBAGENT_FINALIZATION_CONFIG";
+export const FINALIZATION_EVENT = "subagent.finalization";
+export function createNativeFinalization(acceptance, publicOutput, outputPath) {
+    return { nonce: randomUUID(), acceptance, reportRuntime: createFinalizationReportRuntime(publicOutput?.schema), publicOutput,
+        outputPath, outputSnapshot: captureSingleOutputSnapshot(outputPath) };
+}
+export function nativeFinalizationLaunch(config) {
+    const configPath = path.join(path.dirname(config.reportRuntime.schemaPath), "finalization.json");
+    fs.writeFileSync(configPath, JSON.stringify(config), { mode: 0o600 });
+    return { extension: fileURLToPath(new URL(`native-finalization${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`, import.meta.url)), env: { [CONFIG_ENV]: configPath } };
+}
+/** Self-review includes structural and workspace checks; configured verification stays owner-run. */
+export default function registerNativeFinalization(pi) {
+    const configPath = process.env[CONFIG_ENV];
+    if (!configPath)
+        return;
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const { acceptance, reportRuntime } = config;
+    const selfReview = acceptanceSelfReviewConfig(acceptance);
+    const messages = [];
+    let messageOffset = 0;
+    let turn = 0;
+    let initialOutput = "";
+    let latestOutput = "";
+    let initialLedger;
+    let resolvedOutput = { fullOutput: "" };
+    const registerOutput = (runtime) => pi.registerTool({
+        name: "structured_output", label: "Structured Output", description: "Submit the complete output matching the current schema.",
+        parameters: Type.Object({ value: Type.Unsafe(runtime.schema) }, { additionalProperties: false }),
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
+        execute: async (_id, args) => {
+            const validation = validateStructuredOutputValue(runtime.schema, args.value);
+            if (validation.status === "invalid")
+                throw new Error(validation.message);
+            fs.writeFileSync(runtime.outputPath, JSON.stringify(args.value), { mode: 0o600 });
+            return { content: [{ type: "text", text: "Structured output captured." }], details: {}, terminate: true };
+        },
+    });
+    if (config.publicOutput) {
+        registerOutput(config.publicOutput);
+        pi.on("before_agent_start", (event) => setPromptSection(event.systemPromptOptions, "subagent_output", "Your final action must call structured_output with JSON matching the current schema. Prose alone does not complete this output contract."));
+    }
+    pi.on("message_end", (event) => {
+        if (["assistant", "user", "toolResult"].includes(event.message.role)) {
+            latestOutput = getFinalOutput([event.message]) || latestOutput;
+            messages.push(compactObservedMessage(event.message));
+        }
+    });
+    pi.on("agent_before_settle", async (event, ctx) => {
+        if (event.outcome !== "completed")
+            return;
+        const submission = turn === 0
+            ? { output: latestOutput }
+            : readFinalizationReport(messages, reportRuntime, { messageOffset });
+        if (turn === 0) {
+            initialOutput = submission.output;
+            const hiddenError = detectSubagentError(messages);
+            if (hiddenError.hasError)
+                submission.error = hiddenError.details ?? `${hiddenError.errorType} failed`;
+            if (config.publicOutput)
+                submission.error ??= readStructuredOutput(config.publicOutput).error;
+        }
+        const ledger = await evaluateAcceptance({ acceptance: selfReview, governing: acceptance, cwd: ctx.cwd,
+            output: submission.reportSubmissionError ? "" : submission.output, report: submission.reportSubmissionError ? undefined : submission.report });
+        initialLedger ??= ledger;
+        if (!submission.error && !submission.reportSubmissionError) {
+            const output = turn === 0 ? stripAcceptanceReport(submission.output) : resolveFinalizationOutput(submission.output, resolvedOutput.fullOutput);
+            resolvedOutput = resolveSingleOutput(config.outputPath, output, turn === 0 ? config.outputSnapshot : resolvedOutput.writtenSnapshot);
+            if (resolvedOutput.saveError)
+                submission.error = `Failed to save output file '${config.outputPath}': ${resolvedOutput.saveError}`;
+        }
+        const continueReview = !submission.error && ledger.status !== "blocked" && turn < acceptance.finalization.maxTurns
+            && (turn === 0 || Boolean(submission.reportSubmissionError) || ledger.status === "rejected");
+        const nextPrompt = continueReview ? formatAcceptanceFinalizationPrompt({ acceptance, initialOutput, initialLedger,
+            turn: turn + 1, maxTurns: acceptance.finalization.maxTurns,
+            previousFailure: submission.reportSubmissionError ?? acceptanceFailureMessage(ledger), nativeReport: true, outputSchema: config.publicOutput?.schema }) : undefined;
+        const marker = { type: FINALIZATION_EVENT, nonce: config.nonce, turn, lastEntryId: ctx.sessionManager.getLeafId() ?? undefined, messageCount: messages.length, at: Date.now(), submission, acceptance: ledger, resolvedOutput, nextPrompt };
+        fs.appendFileSync(path.join(path.dirname(reportRuntime.schemaPath), "boundaries.jsonl"), `${JSON.stringify(marker)}\n`, { mode: 0o600 });
+        if (!nextPrompt)
+            return;
+        if (turn === 0) {
+            // Native registration refreshes the active schema after the public payload is captured.
+            registerOutput(reportRuntime);
+            pi.setActiveTools([...new Set([...pi.getActiveTools(), "structured_output"])]);
+        }
+        turn++;
+        messageOffset = messages.length;
+        return { entries: [...event.entries, { type: "custom_message", customType: "subagent-self-review", content: nextPrompt, display: false }], continue: true };
+    });
+}

package/dist/runs/shared/native-usage.js

@@ -0,0 +1,153 @@
+import { isDeepStrictEqual } from "node:util";
+import { scanJournal, nativeProjection } from "../../shared/journal-reader.js";
+export function snapshotNativeBaseline(file) {
+    const ids = new Set();
+    let first = true, native = false, entryCount = 0, legacy = false, sessionId;
+    if (file)
+        try {
+            scanJournal(file, (path) => !path.length || path.length === 1 && ["id", "type", "version"].includes(String(path[0])), ({ value }) => {
+                if (first) {
+                    first = false;
+                    native = value?.type === "session";
+                    if (native) {
+                        if (typeof value.id !== "string" || !value.id)
+                            throw new SyntaxError("Invalid native session identity");
+                        sessionId = value.id;
+                        legacy = value.version === 1;
+                    }
+                }
+                else if (native)
+                    entryCount++;
+                if (native && typeof value?.id === "string")
+                    ids.add(value.id);
+            }, { requireNewline: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    return { ids, entryCount, legacy, sessionId };
+}
+export function snapshotNativeUsage(file) { return snapshotNativeBaseline(file).ids; }
+export function addUsage(usage, value, attribution) {
+    for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "reasoning", "cacheWrite1h"]) {
+        if (value[key] !== undefined && typeof value[key] !== "number")
+            throw new Error(`Invalid native usage counter: ${key}`);
+    }
+    for (const [key, counter] of Object.entries(value)) {
+        if (typeof counter === "number" && (!Number.isFinite(counter) || counter < 0))
+            throw new Error(`Invalid native usage counter: ${key}`);
+    }
+    if (value.cost)
+        for (const counter of Object.values(value.cost))
+            if (!Number.isFinite(counter) || counter < 0)
+                throw new Error("Invalid native usage cost");
+    usage.input += value.input ?? 0;
+    usage.output += value.output ?? 0;
+    usage.cacheRead += value.cacheRead ?? 0;
+    usage.cacheWrite += value.cacheWrite ?? 0;
+    usage.cost += value.cost?.total ?? 0;
+    if (attribution)
+        (usage.contributions ??= []).push({ ...attribution, usage: value });
+}
+export function validateNativeUsage(value) {
+    for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]) {
+        if (typeof value[key] !== "number" || !Number.isFinite(value[key]) || value[key] < 0)
+            throw new Error(`Native usage ${key} is unavailable or invalid`);
+    }
+    for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"]) {
+        if (!value.cost || typeof value.cost[key] !== "number" || !Number.isFinite(value.cost[key]) || value.cost[key] < 0)
+            throw new Error(`Native usage cost.${key} is unavailable or invalid`);
+    }
+}
+/** One billing reducer for published journals and settled, once-audited in-memory sessions. */
+export function nativeUsageCollector(sessionId, baseline, boundaries = []) {
+    const totals = Array.from({ length: Math.max(1, boundaries.length) }, () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0, contributions: [] }));
+    let segment = 0;
+    const contributions = new Map(), turns = new Set();
+    return { totals, append(entry) {
+            if (!entry || typeof entry !== "object")
+                throw new SyntaxError("Invalid native entry");
+            if (entry.type === "message" && (!entry.message || typeof entry.message.role !== "string"))
+                throw new SyntaxError("Invalid native message");
+            if (!baseline.has(entry.id) && entry.checkpoint !== true) {
+                let value, provider, model;
+                if (entry.type === "usage") {
+                    value = entry.usage;
+                    provider = entry.provider;
+                    model = entry.model;
+                }
+                else if (entry.type === "compaction" || entry.type === "branch_summary")
+                    value = entry.usage;
+                else if (entry.type === "message") {
+                    if (entry.message?.role === "assistant") {
+                        value = entry.message.usage;
+                        provider = entry.message.provider;
+                        model = entry.message.responseModel ?? entry.message.model;
+                        if (!turns.has(entry.id)) {
+                            totals[segment].turns++;
+                            turns.add(entry.id);
+                        }
+                    }
+                    else if (entry.message?.role === "toolResult")
+                        value = entry.message.usage;
+                }
+                if (!value && (entry.type === "usage" || entry.type === "message" && entry.message?.role === "assistant"))
+                    throw new Error(`Required native usage is unavailable: ${entry.id}`);
+                if (value) {
+                    validateNativeUsage(value);
+                    if (typeof entry.id !== "string" || !entry.id)
+                        throw new Error("Native usage entry identity is unavailable");
+                    const next = { id: `${sessionId}:${entry.id}`, provider, model, usage: value };
+                    const previous = contributions.get(next.id);
+                    if (previous && !isDeepStrictEqual(previous, next))
+                        throw new Error(`Conflicting native usage contribution: ${next.id}`);
+                    if (!previous) {
+                        contributions.set(next.id, next);
+                        addUsage(totals[segment], value, { id: next.id, provider, model });
+                    }
+                }
+            }
+            if (entry.id === boundaries[segment] && segment < totals.length - 1)
+                segment++;
+        } };
+}
+/** Read native journals without opening a second writer or copying their transcripts. */
+export function readNativeUsage(file, baseline, boundaries = [], options = {}) {
+    if (!file)
+        return;
+    let sessionId, first = true, lastEntryId, reached = false;
+    let collector;
+    const boundaryReached = Symbol("terminal entry");
+    try {
+        scanJournal(file, (path, root) => path[0] === "message" && path[1] === "content" ? false : nativeProjection(path, root), ({ value: entry }) => {
+            if (first) {
+                first = false;
+                sessionId = entry?.type === "session" ? entry.id : undefined;
+                if (sessionId)
+                    collector = nativeUsageCollector(sessionId, baseline, boundaries);
+            }
+            if (!collector)
+                return;
+            options.onEntry?.(entry);
+            collector.append(entry);
+            if (entry.type !== "session")
+                lastEntryId = entry.id;
+            if (entry.id === options.terminalEntryId) {
+                reached = true;
+                throw boundaryReached;
+            }
+        }, { requireNewline: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        if (error !== boundaryReached)
+            throw error;
+    }
+    if (options.terminalEntryId && !reached)
+        throw new Error("Native accounting terminal entry is missing");
+    if (sessionId)
+        options.onBoundary?.({ sessionId, lastEntryId });
+    return collector?.totals;
+}