@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/dist/runs/shared/nested-control-records.js

@@ -1,128 +0,0 @@
-import { assertSafeNestedId as assertSafeId, isSafeNestedId, } from "./nested-protocol.js";
-import { validateRouteShape, readRouteFiles, writeRouteRecord } from "./nested-route.js";
-import { clampNumber, stringValue, parseRecord, parseRouteRecord } from "./nested-validation.js";
-export function writeNestedEvent(route, event) {
-    validateRouteShape(route);
-    const record = {
-        ...event,
-        rootRunId: route.rootRunId,
-        capabilityToken: route.capabilityToken,
-    };
-    const sanitized = parseRecord(JSON.stringify(record), route);
-    if (!sanitized) {
-        throw new Error("Nested event record failed validation.");
-    }
-    writeRouteRecord(route.eventSink, sanitized.ts, sanitized);
-}
-function controlAddress(raw) {
-    const ts = clampNumber(raw.ts);
-    if (!isSafeNestedId(raw.requestId) || !isSafeNestedId(raw.targetRunId) || ts === undefined) {
-        return;
-    }
-    return { requestId: raw.requestId, targetRunId: raw.targetRunId, ts };
-}
-function validIndex(value, safe) {
-    if (value === undefined) {
-        return true;
-    }
-    return (typeof value === "number" &&
-        value >= 0 &&
-        (safe ? Number.isSafeInteger(value) : Number.isInteger(value)));
-}
-function requestIndices(raw) {
-    if (!validIndex(raw.targetChildIndex, false) || !validIndex(raw.index, true)) {
-        return;
-    }
-    return {
-        ...(typeof raw.targetChildIndex === "number" ? { targetChildIndex: raw.targetChildIndex } : {}),
-        ...(typeof raw.index === "number" ? { index: raw.index } : {}),
-    };
-}
-function parseControlRequest(content, route) {
-    const raw = parseRouteRecord(content, route);
-    if (!raw || raw.type !== "subagent.nested.control-request") {
-        return;
-    }
-    const address = controlAddress(raw);
-    const indices = requestIndices(raw);
-    if (!address || !indices) {
-        return;
-    }
-    if (raw.action !== "interrupt" && raw.action !== "resume") {
-        return;
-    }
-    const message = stringValue(raw.message, 16_000);
-    return {
-        type: "subagent.nested.control-request",
-        ...address,
-        ...indices,
-        rootRunId: route.rootRunId,
-        capabilityToken: route.capabilityToken,
-        action: raw.action,
-        ...(message !== undefined ? { message } : {}),
-    };
-}
-function parseControlResult(content, route) {
-    const raw = parseRouteRecord(content, route);
-    if (!raw || raw.type !== "subagent.nested.control-result") {
-        return;
-    }
-    const address = controlAddress(raw);
-    if (!address || typeof raw.ok !== "boolean") {
-        return;
-    }
-    return {
-        type: "subagent.nested.control-result",
-        ...address,
-        rootRunId: route.rootRunId,
-        capabilityToken: route.capabilityToken,
-        ok: raw.ok,
-        message: stringValue(raw.message, 16_000) ??
-            (raw.ok ? "Control request completed." : "Control request failed."),
-    };
-}
-export function writeNestedControlRequest(route, request) {
-    validateRouteShape(route);
-    assertSafeId("requestId", request.requestId);
-    assertSafeId("targetRunId", request.targetRunId);
-    const record = {
-        type: "subagent.nested.control-request",
-        ...request,
-        rootRunId: route.rootRunId,
-        capabilityToken: route.capabilityToken,
-    };
-    const sanitized = parseControlRequest(JSON.stringify(record), route);
-    if (!sanitized) {
-        throw new Error("Nested control request failed validation.");
-    }
-    return writeRouteRecord(route.controlInbox, sanitized.ts, sanitized);
-}
-export function readNestedControlRequests(route, skipFiles = new Set()) {
-    validateRouteShape(route);
-    return readRouteFiles(route.controlInbox, (entry) => entry.endsWith(".json") && !skipFiles.has(entry)).flatMap(({ filePath, content }) => {
-        const request = parseControlRequest(content, route);
-        return request ? [{ ...request, filePath }] : [];
-    });
-}
-export function writeNestedControlResult(route, result) {
-    validateRouteShape(route);
-    assertSafeId("requestId", result.requestId);
-    assertSafeId("targetRunId", result.targetRunId);
-    const record = {
-        type: "subagent.nested.control-result",
-        ...result,
-        rootRunId: route.rootRunId,
-        capabilityToken: route.capabilityToken,
-    };
-    const sanitized = parseControlResult(JSON.stringify(record), route);
-    if (!sanitized) {
-        throw new Error("Nested control result failed validation.");
-    }
-    writeRouteRecord(route.eventSink, sanitized.ts, sanitized);
-}
-export function readNestedControlResults(route) {
-    validateRouteShape(route);
-    return readRouteFiles(route.eventSink, (entry) => entry.endsWith(".json") || entry.endsWith(".jsonl")).flatMap(({ content }) => (content.includes("\n") ? content.split("\n").filter((line) => line.trim() !== "") : [content])
-        .map((line) => parseControlResult(line, route))
-        .filter((result) => Boolean(result)));
-}

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

@@ -1,8 +0,0 @@
-// Immutable wire records, capability routes, registry projection and mutable job
-// projection have separate owners. This file preserves the public API.
-export { NESTED_EVENTS_DIR, isSafeNestedId, assertSafeNestedId, } from "./nested-protocol.js";
-export { createNestedRoute, resolveNestedRouteFromEnv, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, resolveNestedAsyncDir, } from "./nested-route.js";
-export { sanitizeSummary } from "./nested-validation.js";
-export { applyNestedEvent, findNestedRouteForRootId, projectNestedRegistryForRoot, findNestedRun, findNestedRunMatchesById, readNestedRegistry, projectNestedEvents, } from "./nested-registry.js";
-export { writeNestedEvent, writeNestedControlRequest, readNestedControlRequests, writeNestedControlResult, readNestedControlResults, } from "./nested-control-records.js";
-export { attachRootChildrenToSteps, updateAsyncJobNestedProjection, hasLiveNestedDescendants, nestedSummaryFromAsyncStatus, nestedResultsPath, } from "./nested-projection.js";

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

@@ -1,52 +0,0 @@
-import * as path from "node:path";
-import { isRecord } from "../../shared/unknown.js";
-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 pathEntry(value) {
-    if (!isRecord(value) || !isSafeNestedPathId(value.runId)) {
-        return;
-    }
-    const stepIndex = value.stepIndex;
-    const agent = value.agent;
-    return {
-        runId: value.runId,
-        ...(typeof stepIndex === "number" && Number.isInteger(stepIndex) && stepIndex >= 0
-            ? { stepIndex }
-            : {}),
-        ...(typeof agent === "string" && agent.length > 0 ? { agent: agent.slice(0, 128) } : {}),
-    };
-}
-export function sanitizeNestedPath(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map(pathEntry)
-        .filter((part) => part !== undefined)
-        .slice(0, MAX_NESTED_PATH_ENTRIES);
-}
-export function parseNestedPathEnv(value) {
-    if (value === undefined || value.length === 0) {
-        return [];
-    }
-    try {
-        const parsed = JSON.parse(value);
-        return sanitizeNestedPath(parsed);
-    }
-    catch {
-        return [];
-    }
-}
-export function encodeNestedPathEnv(value) {
-    const sanitized = sanitizeNestedPath(value);
-    return sanitized.length > 0 ? JSON.stringify(sanitized) : "";
-}

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

@@ -1,155 +0,0 @@
-import * as path from "node:path";
-import { RESULTS_DIR, } from "../../shared/types.js";
-import { assertSafeNestedId as assertSafeId, MAX_CHILDREN, MAX_STEPS } from "./nested-protocol.js";
-import { projectNestedEvents, terminal } from "./nested-registry.js";
-import { acceptanceHumanAction } from "./acceptance-evaluation.js";
-export function attachRootChildrenToSteps(rootRunId, steps, children) {
-    if (steps === undefined || steps.length === 0) {
-        return;
-    }
-    for (const step of steps) {
-        step.children = undefined;
-    }
-    for (const child of children ?? []) {
-        if (child.parentRunId !== rootRunId || child.parentStepIndex === undefined) {
-            continue;
-        }
-        const step = steps.find((candidate, index) => (candidate.index ?? index) === child.parentStepIndex);
-        if (!step) {
-            continue;
-        }
-        step.children = [
-            ...(step.children ?? []).filter((existing) => existing.id !== child.id),
-            child,
-        ].slice(0, MAX_CHILDREN);
-    }
-}
-export function updateAsyncJobNestedProjection(job) {
-    if (!job.nestedRoute) {
-        return;
-    }
-    const registry = projectNestedEvents(job.nestedRoute);
-    job.nestedChildren = registry.children;
-    attachRootChildrenToSteps(job.asyncId, job.steps, registry.children);
-}
-export function hasLiveNestedDescendants(children) {
-    if (children === undefined || children.length === 0) {
-        return false;
-    }
-    for (const child of children) {
-        if (!terminal(child.state)) {
-            return true;
-        }
-        if (hasLiveNestedDescendants(child.children)) {
-            return true;
-        }
-        if (hasLiveNestedDescendants(child.steps?.flatMap((step) => step.children ?? []))) {
-            return true;
-        }
-    }
-    return false;
-}
-function parentPath(identity) {
-    return (identity.path ?? [
-        {
-            runId: identity.parentRunId,
-            ...(identity.parentStepIndex !== undefined ? { stepIndex: identity.parentStepIndex } : {}),
-        },
-    ]);
-}
-function summaryIdentity(status, asyncDir, identity) {
-    return {
-        id: status.runId === "" ? identity.id : status.runId,
-        indexedControl: status.indexedControl,
-        parentRunId: identity.parentRunId,
-        ...(identity.parentStepIndex !== undefined
-            ? { parentStepIndex: identity.parentStepIndex }
-            : {}),
-        depth: identity.depth,
-        path: parentPath(identity),
-        asyncDir,
-        ...(status.pid !== undefined && status.pid !== 0 ? { pid: status.pid } : {}),
-        ...(status.sessionId !== undefined && status.sessionId !== ""
-            ? { sessionId: status.sessionId }
-            : {}),
-        mode: status.mode ?? identity.mode,
-    };
-}
-function summaryActivity(status) {
-    return {
-        ...(status.activityState !== undefined ? { activityState: status.activityState } : {}),
-        ...(status.lastActivityAt !== undefined ? { lastActivityAt: status.lastActivityAt } : {}),
-        ...(status.currentTool !== undefined && status.currentTool !== ""
-            ? { currentTool: status.currentTool }
-            : {}),
-        ...(status.currentToolStartedAt !== undefined
-            ? { currentToolStartedAt: status.currentToolStartedAt }
-            : {}),
-        ...(status.currentPath !== undefined && status.currentPath !== ""
-            ? { currentPath: status.currentPath }
-            : {}),
-    };
-}
-function summaryCounters(status) {
-    return {
-        ...(status.currentStep !== undefined ? { currentStep: status.currentStep } : {}),
-        ...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
-        ...(status.turnCount !== undefined ? { turnCount: status.turnCount } : {}),
-        ...(status.toolCount !== undefined ? { toolCount: status.toolCount } : {}),
-        ...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
-    };
-}
-function summaryTiming(status, identity) {
-    return {
-        ...summaryCounters(status),
-        startedAt: status.startedAt ?? identity.ts,
-        ...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
-        lastUpdate: status.lastUpdate ?? identity.ts,
-        ...(status.sessionFile !== undefined && status.sessionFile !== ""
-            ? { sessionFile: status.sessionFile }
-            : {}),
-    };
-}
-function summaryStep(step) {
-    return {
-        agent: step.agent,
-        status: step.status,
-        ...(step.sessionFile !== undefined && step.sessionFile !== ""
-            ? { sessionFile: step.sessionFile }
-            : {}),
-        ...summaryActivity(step),
-        ...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
-        ...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
-        ...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
-        ...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
-        error: step.error ?? acceptanceHumanAction(step.acceptance),
-    };
-}
-function summaryError(status) {
-    if (status.error !== undefined) {
-        return status.error;
-    }
-    if (status.state !== "blocked") {
-        return;
-    }
-    return status.steps
-        ?.map((step) => acceptanceHumanAction(step.acceptance))
-        .filter(Boolean)
-        .join("\n");
-}
-export function nestedSummaryFromAsyncStatus(status, asyncDir, identity) {
-    const steps = status.steps;
-    return {
-        ...summaryIdentity(status, asyncDir, identity),
-        state: status.state,
-        error: summaryError(status),
-        ...summaryActivity(status),
-        ...summaryTiming(status, identity),
-        ...(steps && steps.length > 0 ? { steps: steps.map(summaryStep).slice(0, MAX_STEPS) } : {}),
-    };
-}
-export function nestedResultsPath(rootRunId, id) {
-    assertSafeId("rootRunId", rootRunId);
-    assertSafeId("id", id);
-    return path.join(RESULTS_DIR, "nested", rootRunId, `${id}.json`);
-}

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

@@ -1,18 +0,0 @@
-import * as path from "node:path";
-import { TEMP_ROOT_DIR } from "../../shared/types.js";
-import { isSafeNestedPathId } from "./nested-path.js";
-export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
-export const ROUTE_FILE = "route.json";
-export const REGISTRY_FILE = "registry.json";
-export const MAX_EVENT_BYTES = 64 * 1024;
-export const MAX_STEPS = 12;
-export const MAX_CHILDREN = 16;
-export const MAX_DEPTH = 3;
-export function isSafeNestedId(value) {
-    return isSafeNestedPathId(value);
-}
-export function assertSafeNestedId(label, value) {
-    if (!isSafeNestedId(value)) {
-        throw new Error(`${label} must be a non-empty safe id token.`);
-    }
-}

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

@@ -1,191 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { isRecord, isUnknownArray, hasErrorCode } from "../../shared/unknown.js";
-import { writeAtomicJson } from "../../shared/atomic-json.js";
-import { assertSafeNestedId as assertSafeId, MAX_CHILDREN, REGISTRY_FILE, } from "./nested-protocol.js";
-import { commonRouteRoot, validateRouteShape, listNestedRoutes, readRouteFiles, } from "./nested-route.js";
-import { parseNestedEventRecords, sanitizeSummary } from "./nested-validation.js";
-export function terminal(state) {
-    return state === "complete" || state === "failed" || state === "blocked" || state === "paused";
-}
-function rejectsSummaryUpdate(existing, incoming) {
-    const previous = existing.lastUpdate ?? 0;
-    const next = incoming.lastUpdate ?? 0;
-    return (next < previous ||
-        (terminal(existing.state) && !terminal(incoming.state)) ||
-        (terminal(existing.state) && terminal(incoming.state) && next === previous));
-}
-function mergeSummary(existing, event) {
-    const incomingState = event.type === "subagent.nested.completed" && event.child.state === "running"
-        ? "complete"
-        : event.child.state;
-    const incoming = {
-        ...event.child,
-        state: incomingState,
-        lastUpdate: event.child.lastUpdate ?? event.ts,
-    };
-    if (!existing) {
-        return incoming;
-    }
-    if (rejectsSummaryUpdate(existing, incoming)) {
-        return existing;
-    }
-    return {
-        ...existing,
-        ...incoming,
-        state: incoming.state,
-        lastUpdate: Math.max(existing.lastUpdate ?? 0, incoming.lastUpdate),
-    };
-}
-function mergeChild(items, event) {
-    const index = items.findIndex((child) => child.id === event.child.id);
-    const child = mergeSummary(index < 0 ? undefined : items.at(index), event);
-    return index < 0
-        ? [...items, child].slice(0, MAX_CHILDREN)
-        : items.map((existing, position) => (position === index ? child : existing));
-}
-/** An event owns one tree traversal and the fact that its parent was found. */
-class NestedEventAttachment {
-    matched = false;
-    event;
-    constructor(event) {
-        this.event = event;
-    }
-    attach(children) {
-        const next = this.walk(children);
-        return this.matched ? next : mergeChild(next, this.event);
-    }
-    walk(items) {
-        return items.map((item) => this.attachItem(item));
-    }
-    attachItem(item) {
-        if (item.id === this.event.parentRunId) {
-            this.matched = true;
-            return {
-                ...item,
-                children: mergeChild(item.children ?? [], this.event).slice(0, MAX_CHILDREN),
-                lastUpdate: Math.max(item.lastUpdate ?? 0, this.event.ts),
-            };
-        }
-        if ((item.children?.length ?? 0) === 0) {
-            return item;
-        }
-        return { ...item, children: this.walk(item.children ?? []) };
-    }
-}
-export function applyNestedEvent(registry, event) {
-    return {
-        ...registry,
-        updatedAt: Math.max(registry.updatedAt, event.ts),
-        children: new NestedEventAttachment(event).attach(registry.children),
-    };
-}
-function registryPath(route) {
-    return path.join(commonRouteRoot(route), REGISTRY_FILE);
-}
-export function findNestedRouteForRootId(rootRunId) {
-    assertSafeId("rootRunId", rootRunId);
-    return listNestedRoutes(rootRunId)[0];
-}
-export function projectNestedRegistryForRoot(rootRunId) {
-    const route = findNestedRouteForRootId(rootRunId);
-    return route ? projectNestedEvents(route) : undefined;
-}
-export function findNestedRun(children, id) {
-    if (children === undefined || children.length === 0) {
-        return undefined;
-    }
-    for (const child of children) {
-        if (child.id === id) {
-            return child;
-        }
-        const nested = findNestedRun(child.children, id) ??
-            findNestedRun(child.steps?.flatMap((step) => step.children ?? []), id);
-        if (nested) {
-            return nested;
-        }
-    }
-    return undefined;
-}
-function collectNestedRuns(children) {
-    return (children ?? []).flatMap((child) => [child].concat(collectNestedRuns(child.children), collectNestedRuns(child.steps?.flatMap((step) => step.children ?? []))));
-}
-function collectScopedNestedRuns(children, scope) {
-    if (!scope) {
-        return collectNestedRuns(children);
-    }
-    return (children ?? []).flatMap((child) => {
-        if (child.parentRunId === scope.parentRunId &&
-            (scope.parentStepIndex === undefined || child.parentStepIndex === scope.parentStepIndex)) {
-            return collectNestedRuns([child]);
-        }
-        return collectScopedNestedRuns(child.children, scope).concat(collectScopedNestedRuns(child.steps?.flatMap((step) => step.children ?? []), scope));
-    });
-}
-function routeMatches(route, id, options) {
-    try {
-        const registry = projectNestedEvents(route);
-        return collectScopedNestedRuns(registry.children, options.scope?.descendantOf)
-            .filter((run) => (options.prefix === true ? run.id.startsWith(id) : run.id === id))
-            .map((run) => ({ rootRunId: route.rootRunId, route, run }));
-    }
-    catch {
-        // An invalid route never authorizes an indexed control target.
-        return [];
-    }
-}
-export function findNestedRunMatchesById(id, options = {}) {
-    assertSafeId("id", id);
-    return (options.scope?.routes ?? listNestedRoutes()).flatMap((route) => routeMatches(route, id, options));
-}
-export function readNestedRegistry(route) {
-    validateRouteShape(route);
-    try {
-        const parsed = JSON.parse(fs.readFileSync(registryPath(route), "utf-8"));
-        if (!isRecord(parsed)) {
-            throw new Error("Invalid nested registry.");
-        }
-        return {
-            rootRunId: route.rootRunId,
-            updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0,
-            children: isUnknownArray(parsed.children)
-                ? parsed.children
-                    .map((child) => sanitizeSummary(child))
-                    .filter((child) => Boolean(child))
-                : [],
-            processedEvents: isUnknownArray(parsed.processedEvents)
-                ? parsed.processedEvents.filter((item) => typeof item === "string")
-                : [],
-        };
-    }
-    catch (error) {
-        if (!hasErrorCode(error, "ENOENT")) {
-            throw error;
-        }
-        return { rootRunId: route.rootRunId, updatedAt: 0, children: [], processedEvents: [] };
-    }
-}
-export function projectNestedEvents(route) {
-    validateRouteShape(route);
-    let registry = readNestedRegistry(route);
-    const seen = new Set(registry.processedEvents);
-    let changed = false;
-    for (const { entry, content } of readRouteFiles(route.eventSink, (name) => !seen.has(name) && (name.endsWith(".json") || name.endsWith(".jsonl")))) {
-        for (const event of parseNestedEventRecords(content, route)) {
-            registry = applyNestedEvent(registry, event);
-            changed = true;
-        }
-        seen.add(entry);
-        changed = true;
-    }
-    if (changed) {
-        // ponytail: directory enumeration and durable IDs still grow with route history.
-        // Archive immutable files with an atomic registry checkpoint if that becomes costly.
-        registry = { ...registry, processedEvents: [...seen] };
-        // Parent projection is the only writer to this sidecar registry. Child and
-        // runner processes only create immutable event files, so parent status.json
-        // remains owned by the existing runner writer and is never rewritten here.
-        writeAtomicJson(registryPath(route), registry);
-    }
-    return registry;
-}