@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/runs/shared/nested-path.ts

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

package/src/runs/shared/nested-projection.ts

@@ -0,0 +1,230 @@
+import * as path from "node:path";
+import {
+  RESULTS_DIR,
+  type AsyncJobState,
+  type ReadonlyAsyncStatus,
+  type NestedStepSummary,
+  type NestedRunSummary,
+  type SubagentRunMode,
+} from "../../shared/types.ts";
+import { assertSafeNestedId as assertSafeId, MAX_CHILDREN, MAX_STEPS } from "./nested-protocol.ts";
+import { projectNestedEvents, terminal } from "./nested-registry.ts";
+import type { NestedPathEntry } from "./nested-path.ts";
+import { acceptanceHumanAction } from "./acceptance-evaluation.ts";
+
+/** Caller-owned projection slots; attachment replaces only their children. */
+export interface MutableStepProjection {
+  children?: readonly NestedRunSummary[];
+  readonly index?: number;
+}
+
+export function attachRootChildrenToSteps(
+  rootRunId: string,
+  steps: readonly MutableStepProjection[] | undefined,
+  children: readonly NestedRunSummary[] | undefined,
+): void {
+  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: AsyncJobState): void {
+  if (!job.nestedRoute) {
+    return;
+  }
+  const registry = projectNestedEvents(job.nestedRoute);
+  job.nestedChildren = registry.children;
+  attachRootChildrenToSteps(job.asyncId, job.steps, registry.children);
+}
+
+export function hasLiveNestedDescendants(
+  children: readonly NestedRunSummary[] | undefined,
+): boolean {
+  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;
+}
+
+type NestedStatusObservation = Pick<ReadonlyAsyncStatus, "runId" | "state"> &
+  Partial<ReadonlyAsyncStatus>;
+interface NestedStatusIdentity {
+  readonly id: string;
+  readonly parentRunId: string;
+  readonly parentStepIndex?: number;
+  readonly depth: number;
+  readonly path?: readonly NestedPathEntry[];
+  readonly mode?: SubagentRunMode;
+  readonly ts: number;
+}
+function parentPath(identity: NestedStatusIdentity): readonly NestedPathEntry[] {
+  return (
+    identity.path ?? [
+      {
+        runId: identity.parentRunId,
+        ...(identity.parentStepIndex !== undefined ? { stepIndex: identity.parentStepIndex } : {}),
+      },
+    ]
+  );
+}
+function summaryIdentity(
+  status: NestedStatusObservation,
+  asyncDir: string,
+  identity: NestedStatusIdentity,
+) {
+  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: Pick<
+    ReadonlyAsyncStatus,
+    "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath"
+  >,
+): Pick<
+  NestedRunSummary,
+  "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath"
+> {
+  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: NestedStatusObservation,
+): Pick<
+  NestedRunSummary,
+  "currentStep" | "chainStepCount" | "turnCount" | "toolCount" | "totalTokens"
+> {
+  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: NestedStatusObservation,
+  identity: NestedStatusIdentity,
+): Pick<
+  NestedRunSummary,
+  | "currentStep"
+  | "chainStepCount"
+  | "turnCount"
+  | "toolCount"
+  | "totalTokens"
+  | "startedAt"
+  | "endedAt"
+  | "lastUpdate"
+  | "sessionFile"
+> {
+  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: NonNullable<ReadonlyAsyncStatus["steps"]>[number]): NestedStepSummary {
+  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: NestedStatusObservation): string | undefined {
+  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: NestedStatusObservation,
+  asyncDir: string,
+  identity: NestedStatusIdentity,
+): NestedRunSummary {
+  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: string, id: string): string {
+  assertSafeId("rootRunId", rootRunId);
+  assertSafeId("id", id);
+  return path.join(RESULTS_DIR, "nested", rootRunId, `${id}.json`);
+}

package/src/runs/shared/nested-protocol.ts

@@ -0,0 +1,67 @@
+import * as path from "node:path";
+import { TEMP_ROOT_DIR, type NestedRouteInfo, type NestedRunSummary } from "../../shared/types.ts";
+import { isSafeNestedPathId } from "./nested-path.ts";
+
+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 type NestedRoute = NestedRouteInfo;
+
+export interface NestedEventRecord {
+  readonly type:
+    | "subagent.nested.started"
+    | "subagent.nested.updated"
+    | "subagent.nested.completed";
+  readonly ts: number;
+  readonly rootRunId: string;
+  readonly parentRunId: string;
+  readonly parentStepIndex?: number;
+  readonly capabilityToken: string;
+  readonly child: NestedRunSummary;
+}
+
+export interface NestedControlResultRecord {
+  readonly type: "subagent.nested.control-result";
+  readonly ts: number;
+  readonly rootRunId: string;
+  readonly capabilityToken: string;
+  readonly requestId: string;
+  readonly targetRunId: string;
+  readonly ok: boolean;
+  readonly message: string;
+}
+
+export interface NestedControlRequestRecord {
+  readonly type: "subagent.nested.control-request";
+  readonly ts: number;
+  readonly rootRunId: string;
+  readonly capabilityToken: string;
+  readonly requestId: string;
+  readonly targetRunId: string;
+  readonly targetChildIndex?: number;
+  /** Child inside the target run; targetChildIndex selects the outer owner. */
+  readonly index?: number;
+  readonly action: "interrupt" | "resume";
+  readonly message?: string;
+}
+
+export interface NestedRegistry {
+  readonly rootRunId: string;
+  readonly updatedAt: number;
+  readonly children: readonly NestedRunSummary[];
+  readonly processedEvents: readonly string[];
+}
+
+export function isSafeNestedId(value: unknown): value is string {
+  return isSafeNestedPathId(value);
+}
+
+export function assertSafeNestedId(label: string, value: unknown): void {
+  if (!isSafeNestedId(value)) {
+    throw new Error(`${label} must be a non-empty safe id token.`);
+  }
+}

package/src/runs/shared/nested-registry.ts

@@ -0,0 +1,273 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { NestedRunSummary, NestedRunState } from "../../shared/types.ts";
+import { isRecord, isUnknownArray, hasErrorCode } from "../../shared/unknown.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import {
+  assertSafeNestedId as assertSafeId,
+  type NestedRoute,
+  type NestedRegistry,
+  type NestedEventRecord,
+  MAX_CHILDREN,
+  REGISTRY_FILE,
+} from "./nested-protocol.ts";
+import {
+  commonRouteRoot,
+  validateRouteShape,
+  listNestedRoutes,
+  readRouteFiles,
+} from "./nested-route.ts";
+import { parseNestedEventRecords, sanitizeSummary } from "./nested-validation.ts";
+
+export function terminal(state: NestedRunState): boolean {
+  return state === "complete" || state === "failed" || state === "blocked" || state === "paused";
+}
+
+function rejectsSummaryUpdate(existing: NestedRunSummary, incoming: NestedRunSummary): boolean {
+  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: NestedRunSummary | undefined,
+  event: NestedEventRecord,
+): NestedRunSummary {
+  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: readonly NestedRunSummary[],
+  event: NestedEventRecord,
+): NestedRunSummary[] {
+  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 {
+  private matched = false;
+  private readonly event: NestedEventRecord;
+  constructor(event: NestedEventRecord) {
+    this.event = event;
+  }
+  attach(children: readonly NestedRunSummary[]): NestedRunSummary[] {
+    const next = this.walk(children);
+    return this.matched ? next : mergeChild(next, this.event);
+  }
+  private walk(items: readonly NestedRunSummary[]): NestedRunSummary[] {
+    return items.map((item) => this.attachItem(item));
+  }
+  private attachItem(item: NestedRunSummary): NestedRunSummary {
+    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: NestedRegistry,
+  event: NestedEventRecord,
+): NestedRegistry {
+  return {
+    ...registry,
+    updatedAt: Math.max(registry.updatedAt, event.ts),
+    children: new NestedEventAttachment(event).attach(registry.children),
+  };
+}
+
+function registryPath(route: NestedRoute): string {
+  return path.join(commonRouteRoot(route), REGISTRY_FILE);
+}
+
+export function findNestedRouteForRootId(rootRunId: string): NestedRoute | undefined {
+  assertSafeId("rootRunId", rootRunId);
+  return listNestedRoutes(rootRunId)[0];
+}
+
+export function projectNestedRegistryForRoot(rootRunId: string): NestedRegistry | undefined {
+  const route = findNestedRouteForRootId(rootRunId);
+  return route ? projectNestedEvents(route) : undefined;
+}
+
+export function findNestedRun(
+  children: readonly NestedRunSummary[] | undefined,
+  id: string,
+): NestedRunSummary | undefined {
+  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;
+}
+
+export interface NestedRunMatch {
+  readonly rootRunId: string;
+  readonly route: NestedRoute;
+  readonly run: NestedRunSummary;
+}
+
+export interface NestedRunResolutionScope {
+  readonly routes: readonly NestedRoute[];
+  readonly descendantOf?: { readonly parentRunId: string; readonly parentStepIndex?: number };
+}
+
+function collectNestedRuns(children: readonly NestedRunSummary[] | undefined): NestedRunSummary[] {
+  return (children ?? []).flatMap((child) =>
+    [child].concat(
+      collectNestedRuns(child.children),
+      collectNestedRuns(child.steps?.flatMap((step) => step.children ?? [])),
+    ),
+  );
+}
+function collectScopedNestedRuns(
+  children: readonly NestedRunSummary[] | undefined,
+  scope: NestedRunResolutionScope["descendantOf"],
+): NestedRunSummary[] {
+  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: NestedRoute,
+  id: string,
+  options: { readonly prefix?: boolean; readonly scope?: NestedRunResolutionScope },
+): NestedRunMatch[] {
+  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: string,
+  options: { readonly prefix?: boolean; readonly scope?: NestedRunResolutionScope } = {},
+): NestedRunMatch[] {
+  assertSafeId("id", id);
+  return (options.scope?.routes ?? listNestedRoutes()).flatMap((route) =>
+    routeMatches(route, id, options),
+  );
+}
+
+export function readNestedRegistry(route: NestedRoute): NestedRegistry {
+  validateRouteShape(route);
+  try {
+    const parsed: unknown = 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): child is NestedRunSummary => Boolean(child))
+        : [],
+      processedEvents: isUnknownArray(parsed.processedEvents)
+        ? parsed.processedEvents.filter((item): item is string => typeof item === "string")
+        : [],
+    };
+  } catch (error) {
+    if (!hasErrorCode(error, "ENOENT")) {
+      throw error;
+    }
+    return { rootRunId: route.rootRunId, updatedAt: 0, children: [], processedEvents: [] };
+  }
+}
+
+export function projectNestedEvents(route: NestedRoute): NestedRegistry {
+  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;
+}