@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/runs/shared/nested-path.js

@@ -0,0 +1,48 @@
+import * as path from "node:path";
+const MAX_NESTED_ID_LENGTH = 128;
+export const MAX_NESTED_PATH_ENTRIES = 4;
+export function isSafeNestedPathId(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= MAX_NESTED_ID_LENGTH
+        && !path.isAbsolute(value)
+        && !value.includes("/")
+        && !value.includes("\\")
+        && !value.includes("..");
+}
+function stepIndex(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function nonEmptyString(value, max) {
+    return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+}
+export function sanitizeNestedPath(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((part) => {
+        if (!part || typeof part !== "object")
+            return undefined;
+        const record = part;
+        if (!isSafeNestedPathId(record.runId))
+            return undefined;
+        return {
+            runId: record.runId,
+            ...(stepIndex(record.stepIndex) !== undefined ? { stepIndex: stepIndex(record.stepIndex) } : {}),
+            ...(nonEmptyString(record.agent, 128) ? { agent: nonEmptyString(record.agent, 128) } : {}),
+        };
+    }).filter((part) => Boolean(part)).slice(0, MAX_NESTED_PATH_ENTRIES);
+}
+export function parseNestedPathEnv(value) {
+    if (!value)
+        return [];
+    try {
+        return sanitizeNestedPath(JSON.parse(value));
+    }
+    catch {
+        return [];
+    }
+}
+export function encodeNestedPathEnv(value) {
+    const sanitized = sanitizeNestedPath(value);
+    return sanitized.length ? JSON.stringify(sanitized) : "";
+}

package/dist/runs/shared/nested-render.js

@@ -0,0 +1,108 @@
+import { formatDuration, formatTokens, shortenPath } from "../../shared/formatters.js";
+import { formatActivityLabel, formatRunAction } from "../../shared/status-format.js";
+export function countNestedRuns(children) {
+    const counts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, blocked: 0, queued: 0 };
+    for (const child of children ?? []) {
+        counts.total++;
+        counts[child.state]++;
+        const nested = countNestedRuns([...(child.children ?? []), ...(child.steps?.flatMap((step) => step.children ?? []) ?? [])]);
+        counts.total += nested.total;
+        counts.running += nested.running;
+        counts.paused += nested.paused;
+        counts.complete += nested.complete;
+        counts.failed += nested.failed;
+        counts.blocked += nested.blocked;
+        counts.queued += nested.queued;
+    }
+    return counts;
+}
+export function formatNestedAggregate(children) {
+    const counts = countNestedRuns(children);
+    if (counts.total === 0)
+        return undefined;
+    const parts = [
+        counts.running > 0 ? `${counts.running} running` : "",
+        counts.paused > 0 ? `${counts.paused} paused` : "",
+        counts.failed > 0 ? `${counts.failed} failed` : "",
+        counts.blocked > 0 ? `${counts.blocked} need human action` : "",
+        counts.complete > 0 ? `${counts.complete} complete` : "",
+        counts.queued > 0 ? `${counts.queued} queued` : "",
+    ].filter(Boolean);
+    return `+${counts.total} nested run${counts.total === 1 ? "" : "s"}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+}
+function nestedRunLabel(run) {
+    if (run.agent)
+        return run.agent;
+    if (run.agents?.length)
+        return run.agents.length === 1 ? run.agents[0] : `${run.agents.slice(0, 2).join(", ")}${run.agents.length > 2 ? ` +${run.agents.length - 2}` : ""}`;
+    return run.id;
+}
+function formatNestedActivity(input) {
+    const facts = [];
+    if (input.currentTool && input.currentToolStartedAt !== undefined)
+        facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
+    else if (input.currentTool)
+        facts.push(`tool ${input.currentTool}`);
+    if (input.currentPath)
+        facts.push(shortenPath(input.currentPath));
+    if (input.turnCount !== undefined)
+        facts.push(`${input.turnCount} turns`);
+    if (input.toolCount !== undefined)
+        facts.push(`${input.toolCount} tools`);
+    if (input.totalTokens)
+        facts.push(`${formatTokens(input.totalTokens.total)} tok`);
+    const activity = formatActivityLabel(input.lastActivityAt, input.activityState);
+    return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
+}
+function formatNestedRunLines(children, options) {
+    const lines = [];
+    const append = (items, depth, indent) => {
+        if (!items?.length || lines.length >= options.maxLines)
+            return;
+        if (depth > options.maxDepth) {
+            const aggregate = formatNestedAggregate(items);
+            if (aggregate && lines.length < options.maxLines)
+                lines.push(`${indent}↳ ${aggregate}`);
+            return;
+        }
+        for (let index = 0; index < items.length; index++) {
+            const child = items[index];
+            if (lines.length >= options.maxLines) {
+                const aggregate = formatNestedAggregate(items.slice(index));
+                if (aggregate)
+                    lines[lines.length - 1] = `${indent}↳ ${aggregate}`;
+                return;
+            }
+            const activity = child.state === "running" ? formatNestedActivity(child) : undefined;
+            const error = child.error ? ` | error: ${child.error}` : "";
+            lines.push(`${indent}↳ ${nestedRunLabel(child)} [${child.id}] ${child.state}${activity ? ` | ${activity}` : ""}${error}`);
+            if (options.commandHints && lines.length < options.maxLines)
+                lines.push(`${indent}  Status: ${formatRunAction("status", child.id, {}, options.childSafe)}`);
+            if (depth === options.maxDepth) {
+                const aggregate = formatNestedAggregate([...(child.steps?.flatMap((step) => step.children ?? []) ?? []), ...(child.children ?? [])]);
+                if (aggregate && lines.length < options.maxLines)
+                    lines.push(`${indent}  ↳ ${aggregate}`);
+                continue;
+            }
+            for (const [stepIndex, step] of (child.steps ?? []).entries()) {
+                if (lines.length >= options.maxLines)
+                    return;
+                const stepActivity = step.status === "running" ? formatNestedActivity(step) : undefined;
+                lines.push(`${indent}  ${stepIndex + 1}. ${step.agent} ${step.status}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
+                append(step.children, depth + 1, `${indent}    `);
+            }
+            append(child.children, depth + 1, `${indent}  `);
+        }
+    };
+    append(children, 0, options.indent);
+    return lines;
+}
+export function formatNestedRunStatusLines(children, options = {}) {
+    return formatNestedRunLines(children, {
+        indent: options.indent ?? "  ",
+        maxDepth: options.maxDepth ?? 2,
+        maxLines: options.maxLines ?? 40,
+        commandHints: options.commandHints ?? false,
+        childSafe: options.childSafe,
+    });
+}

package/dist/runs/shared/parallel-utils.js

@@ -0,0 +1,61 @@
+export function isParallelGroup(step) {
+    return "parallel" in step && Array.isArray(step.parallel);
+}
+export function isDynamicRunnerGroup(step) {
+    return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray(step.parallel);
+}
+export function flattenSteps(steps) {
+    const flat = [];
+    for (const step of steps) {
+        if (isParallelGroup(step)) {
+            for (const task of step.parallel)
+                flat.push(task);
+        }
+        else if (isDynamicRunnerGroup(step)) {
+            continue;
+        }
+        else {
+            flat.push(step);
+        }
+    }
+    return flat;
+}
+export async function mapConcurrent(items, limit, fn) {
+    const safeLimit = Math.max(1, Math.floor(limit) || 1);
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker(_workerIndex) {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(safeLimit, items.length) }, (_, wi) => worker(wi)));
+    return results;
+}
+export function aggregateParallelOutputs(results, headerFormat = (i, agent) => `=== Parallel Task ${i + 1} (${agent}) ===`) {
+    return results
+        .map((r, i) => {
+        const header = headerFormat(r.taskIndex ?? i, r.agent);
+        const hasOutput = Boolean(r.output?.trim());
+        const status = r.exitCode === -1
+            ? `SKIPPED${r.error ? `: ${r.error}` : ""}`
+            : r.exitCode !== 0 && r.exitCode !== null
+                ? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+                : r.error
+                    ? `WARNING: ${r.error}`
+                    : !hasOutput && r.outputTargetPath && r.outputTargetExists === false
+                        ? `EMPTY OUTPUT (expected output file missing: ${r.outputTargetPath})`
+                        : !hasOutput && !r.outputTargetPath
+                            ? "EMPTY OUTPUT (no textual response returned)"
+                            : "";
+        const body = status ? (hasOutput ? `${status}\n${r.output}` : status) : r.output;
+        return `${header}\n${body}`;
+    })
+        .join("\n\n");
+}
+export const FAIL_FAST_REASON = "subagent-fail-fast";
+export function isFailFastAbort(signal) {
+    return signal?.aborted === true && signal.reason === FAIL_FAST_REASON;
+}
+export const MAX_PARALLEL_CONCURRENCY = 4;

package/dist/runs/shared/parent-receipts.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { journalStamp, scanJournal } from "../../shared/journal-reader.js";
+function hashRange(fd, start, end, hash) {
+    const bytes = Buffer.allocUnsafe(64 * 1024);
+    while (start < end) {
+        const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, end - start), start);
+        if (!count)
+            throw new Error("Parent journal truncated during inspection");
+        hash.update(bytes.subarray(0, count));
+        start += count;
+    }
+}
+const receiptProjection = (path) => {
+    if (!path.length || ["type", "id", "timestamp", "customType"].includes(String(path[0])))
+        return true;
+    if (path[0] === "details")
+        return path.length === 1 || ["completion", "subagentCompletion", "result"].includes(String(path[1]))
+            && (path[1] !== "result" || path.length <= 3 || path[3] === "wait");
+    if (path[0] === "message")
+        return path.length === 1 || ["role", "toolName", "usage"].includes(String(path[1]))
+            || path[1] === "details" && (path.length === 2 || ["wait", "parentUsage"].includes(String(path[2])));
+    return false;
+};
+/** Cache only LF-published receipt fields, never transcripts or accepted-but-unsaved messages. */
+export function createParentReceiptReader(policy) {
+    let cache;
+    return {
+        clear() { cache = undefined; },
+        read(file) {
+            if (!file || !fs.existsSync(file)) {
+                cache = undefined;
+                return new Map();
+            }
+            const fd = fs.openSync(file, "r");
+            try {
+                const stat = fs.fstatSync(fd, { bigint: true }), stamp = journalStamp(stat), identity = `${stat.dev}:${stat.ino}`;
+                let hash = createHash("sha256");
+                let append = cache?.file === file && cache.identity === identity && Number(stat.size) >= cache.end;
+                if (append) {
+                    // Coarse timestamps can hide same-size edits; even a stat hit needs verified bytes.
+                    hashRange(fd, 0, cache.end, hash);
+                    append = hash.copy().digest("hex") === cache.digest;
+                }
+                if (append && Number(stat.size) === cache.end) {
+                    if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp)
+                        throw new Error("Parent journal changed during inspection");
+                    return cache.records;
+                }
+                if (!append)
+                    hash = createHash("sha256");
+                const start = append ? cache.end : 0, records = append ? new Map(cache.records) : new Map();
+                const end = scanJournal(fd, receiptProjection, ({ value }) => {
+                    if (value.type === "custom_message" || value.type === "message" && value.message?.role === "toolResult")
+                        records.set(value.id, value);
+                }, { policy, requireNewline: true, start, end: Number(stat.size) });
+                hashRange(fd, start, end, hash);
+                if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== stamp)
+                    throw new Error("Parent journal changed during inspection");
+                cache = { file, identity, end, digest: hash.digest("hex"), records };
+                return records;
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,121 @@
+import { isDeepStrictEqual } from "node:util";
+import { SessionEntryCursor } from "../../shared/session-entries.js";
+import { createParentReceiptReader } from "./parent-receipts.js";
+import { validateNativeUsage } from "./native-usage.js";
+const PREFIX = "subagent:";
+const UNATTRIBUTED = "unattributed";
+export function finalizedChildUsage(children, index) {
+    return children.flatMap((child) => (index === undefined || child.index === index) && child.state !== "live" && child.state !== "unknown" && !child.result?.detached && child.result?.accounting?.state !== "incomplete"
+        ? child.result?.usage.contributions ?? [] : []);
+}
+function sumUsage(contributions) {
+    const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+    for (const { usage } of contributions) {
+        for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"])
+            total[key] += usage[key];
+        for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"])
+            total.cost[key] += usage.cost[key];
+        // These are subsets of output/cacheWrite, never additional total tokens.
+        for (const key of ["reasoning", "cacheWrite1h"])
+            if (usage[key] !== undefined)
+                total[key] = (total[key] ?? 0) + usage[key];
+    }
+    return total;
+}
+function sameUsage(a, b) {
+    return isDeepStrictEqual({ ...a, reasoning: a.reasoning, cacheWrite1h: a.cacheWrite1h }, { ...b, reasoning: b.reasoning, cacheWrite1h: b.cacheWrite1h });
+}
+function checkContribution(previous, next) {
+    if (previous && ((previous.provider ?? UNATTRIBUTED) !== (next.provider ?? UNATTRIBUTED)
+        || (previous.model ?? UNATTRIBUTED) !== (next.model ?? UNATTRIBUTED) || !sameUsage(previous.usage, next.usage))) {
+        throw new Error(`Conflicting subagent usage contribution: ${next.id}`);
+    }
+}
+function uniqueContributions(contributions) {
+    const unique = new Map();
+    for (const contribution of contributions) {
+        if (!contribution.id.trim())
+            throw new Error("Subagent usage requires a stable native contribution ID");
+        validateNativeUsage(contribution.usage);
+        checkContribution(unique.get(contribution.id), contribution);
+        unique.set(contribution.id, contribution);
+    }
+    return [...unique.values()];
+}
+function createReceiptIndex(toolNames) {
+    const cursor = new SessionEntryCursor();
+    const received = new Map();
+    return (manager, saved) => {
+        const changes = cursor.read(manager);
+        if (changes.reset)
+            received.clear();
+        for (const metadata of changes.entries) {
+            if (metadata.type === "usage") {
+                const id = metadata.contributionId;
+                if (id?.startsWith(PREFIX))
+                    received.set(id.slice(PREFIX.length), { id: id.slice(PREFIX.length), provider: metadata.provider, model: metadata.model, usage: metadata.usage });
+                continue;
+            }
+            if (metadata.type !== "message" || metadata.message.role !== "toolResult" || !toolNames.includes(metadata.message.toolName))
+                continue;
+            const entry = saved.get(metadata.id) ?? (metadata.message.details !== undefined ? metadata : manager.getEntry(metadata.id) ?? metadata);
+            if (entry.type !== "message" || entry.message.role !== "toolResult")
+                continue;
+            const contributions = entry.message.details?.parentUsage?.contributions;
+            // Details/custom notifications alone are never evidence that native accounting ran.
+            if (Array.isArray(contributions) && entry.message.usage && sameUsage(entry.message.usage, sumUsage(contributions))) {
+                for (const contribution of contributions)
+                    received.set(contribution.id, contribution);
+            }
+        }
+        return received;
+    };
+}
+function unrecorded(contributions, received) {
+    return uniqueContributions(contributions).filter((contribution) => {
+        const previous = received.get(contribution.id);
+        checkContribution(previous, contribution);
+        return !previous;
+    });
+}
+/**
+ * Register once per extension instance. Attach only to finalized wait/execution
+ * results, never inspection or streaming updates. Legacy tool aliases and saved
+ * native usage entries still deduplicate old-session accounting.
+ */
+export function registerParentUsage(pi, toolNames) {
+    const toolReceipts = createParentReceiptReader("inspect");
+    const receipts = createReceiptIndex(toolNames);
+    pi.on("message_end", (event, ctx) => {
+        const message = event.message;
+        if (message.role !== "toolResult" || !toolNames.includes(message.toolName))
+            return;
+        const details = message.details;
+        if (!details?.parentUsage)
+            return;
+        const pending = unrecorded(details.parentUsage.contributions, receipts(ctx.sessionManager, toolReceipts.read(ctx.sessionManager.getSessionFile())));
+        const { usage: _usage, ...rest } = message;
+        const { parentUsage: _parentUsage, ...restDetails } = details;
+        // Public replacement hook: native emits/persists final tool messages serially,
+        // even for concurrent tools. No in-memory reservation can outlive an aborted result.
+        return { message: { ...rest, details: JSON.parse(JSON.stringify({ ...restDetails, ...(pending.length ? { parentUsage: { contributions: pending } } : {}) })),
+                ...(pending.length ? { usage: sumUsage(pending) } : {}) } };
+    });
+    return {
+        isRecorded(contributions, ctx, saved) {
+            return unrecorded(contributions, receipts(ctx.sessionManager, saved)).length === 0;
+        },
+        attach(result, contributions, ctx) {
+            const { usage: _usage, ...rest } = result;
+            const { parentUsage: _parentUsage, ...details } = result.details;
+            if (!contributions.length)
+                return { ...rest, details };
+            // Required identity/conflict rejection precedes any optional host I/O.
+            const saved = toolReceipts.read(ctx.sessionManager.getSessionFile());
+            const pending = unrecorded(contributions, receipts(ctx.sessionManager, saved));
+            // Intent only. Top-level usage is added at final message_end, immediately before native persistence.
+            return { ...rest, details: { ...details, ...(pending.length ? { parentUsage: { contributions: pending } } : {}) } };
+        },
+    };
+}