@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/runs/shared/native-usage.ts

@@ -1,113 +1,396 @@
 import type { Usage as NativeUsage } from "@earendil-works/pi-ai";
 import { isDeepStrictEqual } from "node:util";
-import type { Usage, UsageContribution } from "../../shared/types.ts";
+import type {
+  ObservedUsage,
+  ReadonlyInput,
+  Usage,
+  UsageAccumulator,
+  UsageContribution,
+} from "../../shared/types.ts";
 import { scanJournal, nativeProjection } from "../../shared/journal-reader.ts";
+import { hasErrorCode, isRecord as isObject } from "../../shared/unknown.ts";
+import { nonempty } from "./child-presence.ts";
+import {
+  observedUsage,
+  optionalNumber,
+  optionalString,
+  requiredString,
+} from "./child-message-validation.ts";
 
-export function snapshotNativeBaseline(file: string | undefined): { ids: Set<string>; entryCount: number; legacy: boolean; sessionId?: string } {
-	const ids = new Set<string>();
-	let first = true, native = false, entryCount = 0, legacy = false, sessionId: string | undefined;
-	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 as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
-	return { ids, entryCount, legacy, sessionId };
+export interface NativeBaseline {
+  readonly ids: Readonly<ReadonlySet<string>>;
+  readonly entryCount: number;
+  readonly legacy: boolean;
+  readonly sessionId?: string;
 }
 
-export function snapshotNativeUsage(file: string | undefined): Set<string> { return snapshotNativeBaseline(file).ids; }
+export function snapshotNativeBaseline(
+  file: string | undefined,
+): NativeBaseline & { readonly ids: Set<string> } {
+  const ids = new Set<string>();
+  let first = true;
+  let native = false;
+  let entryCount = 0;
+  let legacy = false;
+  let sessionId: string | undefined;
+  if (nonempty(file)) {
+    try {
+      scanJournal(
+        file,
+        (path) =>
+          path.length === 0 ||
+          (path.length === 1 && ["id", "type", "version"].includes(String(path[0]))),
+        ({ value }) => {
+          if (first) {
+            first = false;
+            native = value.type === "session";
+            if (native) {
+              sessionId = requiredString(value.id, "native session identity");
+              if (sessionId.length === 0) {
+                throw new SyntaxError("Invalid native session identity");
+              }
+              legacy = value.version === 1;
+            }
+          } else if (native) {
+            entryCount++;
+          }
+          if (native && typeof value.id === "string") {
+            ids.add(value.id);
+          }
+        },
+        { requireNewline: true },
+      );
+    } catch (error) {
+      if (!hasErrorCode(error, "ENOENT")) {
+        throw error;
+      }
+    }
+  }
+  return { ids, entryCount, legacy, sessionId };
+}
+
+export function snapshotNativeUsage(file: string | undefined): Set<string> {
+  return snapshotNativeBaseline(file).ids;
+}
+
+function validateObservedCounters(value: ObservedUsage): void {
+  // This exported reducer may receive external observations; static types are not wire validation.
+  observedUsage(value);
+  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");
+      }
+    }
+  }
+}
 
-export function addUsage(usage: Usage, value: NativeUsage, attribution?: Omit<UsageContribution, "usage">): void {
-	for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "reasoning", "cacheWrite1h"] as const) {
-		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 });
+/** Mutating accounting boundary: the caller owns this accumulator, observations stay readonly. */
+export function addUsage(
+  usage: UsageAccumulator,
+  value: ObservedUsage,
+  attribution?: Omit<UsageContribution, "usage">,
+): void {
+  validateObservedCounters(value);
+  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: NativeUsage): void {
-	for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
-		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"] as const) {
-		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`);
-	}
+/** Complete native receipts are required for billing; partial observations remain audit-only. */
+export function validateNativeUsage(
+  value: ObservedUsage,
+): asserts value is ReadonlyInput<NativeUsage> {
+  for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+    const counter = value[key];
+    if (counter === undefined || !Number.isFinite(counter) || counter < 0) {
+      throw new Error(`Native usage ${key} is unavailable or invalid`);
+    }
+  }
+  for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+    const counter = value.cost?.[key];
+    if (counter === undefined || !Number.isFinite(counter) || counter < 0) {
+      throw new Error(`Native usage cost.${key} is unavailable or invalid`);
+    }
+  }
 }
 
 export interface NativeUsageMetadata {
-	type: string;
-	id: string;
-	checkpoint?: boolean;
-	provider?: string;
-	model?: string;
-	usage?: NativeUsage;
-	message?: { role: string; timestamp?: number; toolCallId?: string; provider?: string; model?: string; responseModel?: string; usage?: NativeUsage };
+  readonly type: string;
+  readonly id: string;
+  readonly checkpoint?: boolean;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly usage?: ObservedUsage;
+  readonly message?: {
+    readonly role: string;
+    readonly timestamp?: number;
+    readonly toolCallId?: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly responseModel?: string;
+    readonly usage?: ObservedUsage;
+  };
+}
+
+export function nativeUsageMetadata(value: unknown): NativeUsageMetadata {
+  if (!isObject(value)) {
+    throw new SyntaxError("Invalid native entry");
+  }
+  const message = isObject(value.message) ? value.message : undefined;
+  if (value.type === "message" && !message) {
+    throw new SyntaxError("Invalid native message");
+  }
+  if (value.checkpoint !== undefined && typeof value.checkpoint !== "boolean") {
+    throw new SyntaxError("Invalid native checkpoint");
+  }
+  return {
+    ...value,
+    type: requiredString(value.type, "native entry type"),
+    id: requiredString(value.id, "native entry identity"),
+    checkpoint: value.checkpoint,
+    provider: optionalString(value.provider, "provider"),
+    model: optionalString(value.model, "model"),
+    usage: observedUsage(value.usage),
+    message: message
+      ? {
+          role: requiredString(message.role, "native message role"),
+          timestamp: optionalNumber(message.timestamp, "timestamp"),
+          toolCallId: optionalString(message.toolCallId, "toolCallId"),
+          provider: optionalString(message.provider, "provider"),
+          model: optionalString(message.model, "model"),
+          responseModel: optionalString(message.responseModel, "responseModel"),
+          usage: observedUsage(message.usage),
+        }
+      : undefined,
+  };
+}
+
+interface EntryUsage {
+  readonly value?: ObservedUsage;
+  readonly provider?: string;
+  readonly model?: string;
+}
+function messageUsage(message: NativeUsageMetadata["message"]): EntryUsage {
+  if (message?.role === "assistant") {
+    return {
+      value: message.usage,
+      provider: message.provider,
+      model: message.responseModel ?? message.model,
+    };
+  }
+  return { value: message?.role === "toolResult" ? message.usage : undefined };
+}
+function entryUsage(entry: NativeUsageMetadata): EntryUsage {
+  if (entry.type === "usage") {
+    return { value: entry.usage, provider: entry.provider, model: entry.model };
+  }
+  if (entry.type === "compaction" || entry.type === "branch_summary") {
+    return { value: entry.usage };
+  }
+  return entry.type === "message" ? messageUsage(entry.message) : {};
+}
+function requiredReceipt(entry: NativeUsageMetadata): EntryUsage {
+  const receipt = entryUsage(entry);
+  const required =
+    entry.type === "usage" || (entry.type === "message" && entry.message?.role === "assistant");
+  if (!receipt.value && required) {
+    throw new Error(`Required native usage is unavailable: ${entry.id}`);
+  }
+  return receipt;
+}
+export interface NativeUsageCollector {
+  readonly totals: readonly Usage[];
+  readonly append: (entry: NativeUsageMetadata) => void;
 }
 
-/** One billing reducer for published journals and settled, once-audited in-memory sessions. */
-export function nativeUsageCollector(sessionId: string, baseline: ReadonlySet<string>, boundaries: Array<string | undefined> = []) {
-	const totals: Usage[] = 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<string, UsageContribution>(), turns = new Set<string>();
-	return { totals, append(entry: NativeUsageMetadata) {
-		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: NativeUsage | undefined, provider: string | undefined, model: string | undefined;
-			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++;
-	} };
+class UsageCollector implements NativeUsageCollector {
+  private readonly sessionId: string;
+  private readonly baseline: Readonly<ReadonlySet<string>>;
+  private readonly boundaries: readonly (string | undefined)[];
+  private readonly segments: UsageAccumulator[];
+  private readonly contributions = new Map<string, UsageContribution>();
+  private readonly turns = new Set<string>();
+  private segment = 0;
+  constructor(
+    sessionId: string,
+    baseline: Readonly<ReadonlySet<string>>,
+    boundaries: readonly (string | undefined)[],
+  ) {
+    this.sessionId = sessionId;
+    this.baseline = baseline;
+    this.boundaries = boundaries;
+    this.segments = Array.from({ length: Math.max(1, boundaries.length) }, () => ({
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      turns: 0,
+      contributions: [],
+    }));
+  }
+  get totals(): readonly Usage[] {
+    return this.segments;
+  }
+  private total(): UsageAccumulator {
+    const total = this.segments.at(this.segment);
+    if (!total) {
+      throw new Error("Missing native usage segment");
+    }
+    return total;
+  }
+  private countTurn(entry: NativeUsageMetadata): void {
+    if (
+      entry.type === "message" &&
+      entry.message?.role === "assistant" &&
+      !this.turns.has(entry.id)
+    ) {
+      this.total().turns++;
+      this.turns.add(entry.id);
+    }
+  }
+  private account(entry: NativeUsageMetadata): void {
+    const { value, provider, model } = requiredReceipt(entry);
+    this.countTurn(entry);
+    if (!value) {
+      return;
+    }
+    validateNativeUsage(value);
+    if (entry.id.length === 0) {
+      throw new Error("Native usage entry identity is unavailable");
+    }
+    const next = { id: `${this.sessionId}:${entry.id}`, provider, model, usage: value };
+    const previous = this.contributions.get(next.id);
+    if (previous && !isDeepStrictEqual(previous, next)) {
+      throw new Error(`Conflicting native usage contribution: ${next.id}`);
+    }
+    if (!previous) {
+      this.contributions.set(next.id, next);
+      addUsage(this.total(), value, { id: next.id, provider, model });
+    }
+  }
+  append(entry: NativeUsageMetadata): void {
+    if (!this.baseline.has(entry.id) && entry.checkpoint !== true) {
+      this.account(entry);
+    }
+    if (entry.id === this.boundaries.at(this.segment) && this.segment < this.segments.length - 1) {
+      this.segment++;
+    }
+  }
+}
+
+/** One reducer for published journals and settled, once-audited in-memory sessions. */
+export function nativeUsageCollector(
+  sessionId: string,
+  baseline: Readonly<ReadonlySet<string>>,
+  boundaries: readonly (string | undefined)[] = [],
+): NativeUsageCollector {
+  return new UsageCollector(sessionId, baseline, boundaries);
+}
+
+interface NativeUsageReadOptions {
+  readonly terminalEntryId?: string;
+  readonly onEntry?: (entry: NativeUsageMetadata) => void;
+  readonly onBoundary?: (boundary: {
+    readonly sessionId: string;
+    readonly lastEntryId?: string;
+  }) => void;
+}
+class UsageReader {
+  private readonly baseline: Readonly<ReadonlySet<string>>;
+  private readonly boundaries: readonly (string | undefined)[];
+  private readonly options: NativeUsageReadOptions;
+  private first = true;
+  private sessionId?: string;
+  private lastEntryId?: string;
+  private reached = false;
+  private collector?: NativeUsageCollector;
+  constructor(
+    baseline: Readonly<ReadonlySet<string>>,
+    boundaries: readonly (string | undefined)[],
+    options: NativeUsageReadOptions,
+  ) {
+    this.baseline = baseline;
+    this.boundaries = boundaries;
+    this.options = options;
+  }
+  observe(value: Readonly<Record<string, unknown>>): boolean {
+    if (this.first) {
+      this.first = false;
+      this.sessionId =
+        value.type === "session" ? requiredString(value.id, "native session identity") : undefined;
+      if (nonempty(this.sessionId)) {
+        this.collector = nativeUsageCollector(this.sessionId, this.baseline, this.boundaries);
+      }
+    }
+    if (!this.collector) {
+      return false;
+    }
+    const entry = nativeUsageMetadata(value);
+    this.options.onEntry?.(entry);
+    this.collector.append(entry);
+    if (entry.type !== "session") {
+      this.lastEntryId = entry.id;
+    }
+    if (entry.id === this.options.terminalEntryId) {
+      this.reached = true;
+      return true;
+    }
+    return false;
+  }
+  finish(): Usage[] | undefined {
+    if (nonempty(this.options.terminalEntryId) && !this.reached) {
+      throw new Error("Native accounting terminal entry is missing");
+    }
+    if (nonempty(this.sessionId)) {
+      this.options.onBoundary?.({ sessionId: this.sessionId, lastEntryId: this.lastEntryId });
+    }
+    return this.collector?.totals.slice();
+  }
 }
 
-/** Read native journals without opening a second writer or copying their transcripts. */
-export function readNativeUsage(file: string | undefined, baseline: ReadonlySet<string>, boundaries: Array<string | undefined> = [],
-	options: { terminalEntryId?: string; onEntry?: (entry: NativeUsageMetadata) => void; onBoundary?: (boundary: { sessionId: string; lastEntryId?: string }) => void } = {}): Usage[] | undefined {
-	if (!file) return;
-	let sessionId: string | undefined, first = true, lastEntryId: string | undefined, reached = false;
-	let collector: ReturnType<typeof nativeUsageCollector> | undefined;
-	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 as NativeUsageMetadata);
-		collector.append(entry as NativeUsageMetadata);
-		if (entry.type !== "session") lastEntryId = entry.id;
-		if (entry.id === options.terminalEntryId) { reached = true; throw boundaryReached; }
-	}, { requireNewline: true }); } catch (error) { if ((error as NodeJS.ErrnoException).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;
+/** Read journals without opening a second writer or copying their transcripts. */
+export function readNativeUsage(
+  file: string | undefined,
+  baseline: Readonly<ReadonlySet<string>>,
+  boundaries: readonly (string | undefined)[] = [],
+  options: NativeUsageReadOptions = {},
+): Usage[] | undefined {
+  if (!nonempty(file)) {
+    return;
+  }
+  const reader = new UsageReader(baseline, boundaries, options);
+  const boundaryReached = new Error("terminal entry reached");
+  try {
+    scanJournal(
+      file,
+      (keys, root) =>
+        keys[0] === "message" && keys[1] === "content" ? false : nativeProjection(keys, root),
+      ({ value }) => {
+        if (reader.observe(value)) {
+          throw boundaryReached;
+        }
+      },
+      { requireNewline: true },
+    );
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) {
+      return;
+    }
+    if (error !== boundaryReached) {
+      throw error;
+    }
+  }
+  return reader.finish();
 }

package/src/runs/shared/nested-control-records.ts

@@ -0,0 +1,178 @@
+import {
+  assertSafeNestedId as assertSafeId,
+  isSafeNestedId,
+  type NestedRoute,
+  type NestedEventRecord,
+  type NestedControlRequestRecord,
+  type NestedControlResultRecord,
+} from "./nested-protocol.ts";
+import { validateRouteShape, readRouteFiles, writeRouteRecord } from "./nested-route.ts";
+import { clampNumber, stringValue, parseRecord, parseRouteRecord } from "./nested-validation.ts";
+
+export function writeNestedEvent(
+  route: NestedRoute,
+  event: Omit<NestedEventRecord, "rootRunId" | "capabilityToken">,
+): void {
+  validateRouteShape(route);
+  const record: NestedEventRecord = {
+    ...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: Readonly<Record<string, unknown>>,
+): { readonly requestId: string; readonly targetRunId: string; readonly ts: number } | undefined {
+  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: unknown, safe: boolean): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  return (
+    typeof value === "number" &&
+    value >= 0 &&
+    (safe ? Number.isSafeInteger(value) : Number.isInteger(value))
+  );
+}
+
+function requestIndices(
+  raw: Readonly<Record<string, unknown>>,
+): Pick<NestedControlRequestRecord, "index" | "targetChildIndex"> | undefined {
+  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: string,
+  route: NestedRoute,
+): NestedControlRequestRecord | undefined {
+  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: string,
+  route: NestedRoute,
+): NestedControlResultRecord | undefined {
+  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: NestedRoute,
+  request: Omit<NestedControlRequestRecord, "type" | "rootRunId" | "capabilityToken">,
+): string {
+  validateRouteShape(route);
+  assertSafeId("requestId", request.requestId);
+  assertSafeId("targetRunId", request.targetRunId);
+  const record: NestedControlRequestRecord = {
+    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: NestedRoute,
+  skipFiles: Readonly<ReadonlySet<string>> = new Set(),
+): Array<NestedControlRequestRecord & { filePath: string }> {
+  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: NestedRoute,
+  result: Omit<NestedControlResultRecord, "type" | "rootRunId" | "capabilityToken">,
+): void {
+  validateRouteShape(route);
+  assertSafeId("requestId", result.requestId);
+  assertSafeId("targetRunId", result.targetRunId);
+  const record: NestedControlResultRecord = {
+    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: NestedRoute): NestedControlResultRecord[] {
+  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): result is NestedControlResultRecord => Boolean(result)),
+  );
+}