@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/runs/shared/run-history.ts

@@ -1,100 +1,221 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { historyDirectory, historyTransaction, openHistoryDatabase } from "../../history/database.ts";
-import { getAgentDir } from "../../shared/utils.ts";
+import {
+  historyDirectory,
+  historyTransaction,
+  openHistoryDatabase,
+} from "../../history/database.ts";
+import { isRecord } from "../../shared/unknown.ts";
+import { getAgentDir } from "../../shared/agent-dir.ts";
 
 export interface RunEntry {
-	agent: string;
-	task: string;
-	ts: number;
-	status: "ok" | "error";
-	duration: number;
-	exit?: number;
+  readonly agent: string;
+  readonly task: string;
+  readonly ts: number;
+  readonly status: "ok" | "error";
+  readonly duration: number;
+  readonly exit?: number;
 }
 
 const MAX_AGENT_SAMPLES = 1000;
 const MAX_LEGACY_BYTES = 1024 * 1024;
 const TIMING_DATABASE = "run-timing.sqlite";
 
+function validIdentity(entry: Readonly<Record<string, unknown>>): boolean {
+  return (
+    typeof entry.agent === "string" &&
+    entry.agent.length > 0 &&
+    entry.agent.length <= 256 &&
+    typeof entry.task === "string"
+  );
+}
+
+function validTiming(entry: Readonly<Record<string, unknown>>): boolean {
+  return (
+    typeof entry.ts === "number" &&
+    Number.isSafeInteger(entry.ts) &&
+    entry.ts >= 0 &&
+    typeof entry.duration === "number" &&
+    Number.isFinite(entry.duration) &&
+    entry.duration >= 0
+  );
+}
+
 function validEntry(value: unknown): value is RunEntry {
-	if (!value || typeof value !== "object") return false;
-	const entry = value as RunEntry;
-	return typeof entry.agent === "string" && entry.agent.length > 0 && entry.agent.length <= 256
-		&& typeof entry.task === "string" && Number.isSafeInteger(entry.ts) && entry.ts >= 0
-		&& (entry.status === "ok" || entry.status === "error") && Number.isFinite(entry.duration) && entry.duration >= 0
-		&& (entry.exit === undefined || Number.isSafeInteger(entry.exit));
+  if (!isRecord(value)) {
+    return false;
+  }
+  return (
+    validIdentity(value) &&
+    validTiming(value) &&
+    (value.status === "ok" || value.status === "error") &&
+    (value.exit === undefined ||
+      (typeof value.exit === "number" && Number.isSafeInteger(value.exit)))
+  );
 }
 
 /** Legacy samples are read-only, complete LF records from a bounded tail. */
 function legacySamples(agentDir: string, agent?: string): RunEntry[] {
-	let fd: number | undefined;
-	try {
-		fd = fs.openSync(path.join(agentDir, "run-history.jsonl"), "r");
-		const size = fs.fstatSync(fd).size, start = Math.max(0, size - MAX_LEGACY_BYTES);
-		const bytes = Buffer.alloc(size - start);
-		let count = 0;
-		while (count < bytes.length) {
-			const read = fs.readSync(fd, bytes, count, bytes.length - count, start + count);
-			if (!read) break;
-			count += read;
-		}
-		const complete = bytes.subarray(0, count), first = start ? complete.indexOf(10) + 1 : 0, last = complete.lastIndexOf(10);
-		if (last < first || start && !first) return [];
-		const samples: RunEntry[] = [], retained = new Map<string, number>();
-		for (const line of complete.subarray(first, last).toString("utf8").split("\n").reverse()) {
-			try {
-				const entry: unknown = JSON.parse(line);
-				if (!validEntry(entry) || agent !== undefined && entry.agent !== agent || (retained.get(entry.agent) ?? 0) >= MAX_AGENT_SAMPLES) continue;
-				samples.push({ ...entry, task: entry.task.slice(0, 200) });
-				retained.set(entry.agent, (retained.get(entry.agent) ?? 0) + 1);
-				if (agent !== undefined && samples.length === MAX_AGENT_SAMPLES) break;
-			} catch { /* Incomplete or invalid timing samples are not evidence. */ }
-		}
-		return samples;
-	} catch { return []; }
-	finally { if (fd !== undefined) fs.closeSync(fd); }
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(path.join(agentDir, "run-history.jsonl"), "r");
+    const size = fs.fstatSync(fd).size,
+      start = Math.max(0, size - MAX_LEGACY_BYTES);
+    const bytes = Buffer.alloc(size - start);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = fs.readSync(fd, bytes, count, bytes.length - count, start + count);
+      if (read === 0) {
+        break;
+      }
+      count += read;
+    }
+    const complete = bytes.subarray(0, count),
+      first = start > 0 ? complete.indexOf(10) + 1 : 0,
+      last = complete.lastIndexOf(10);
+    if (last < first || (start > 0 && first === 0)) {
+      return [];
+    }
+    return parseLegacyLines(
+      complete.subarray(first, last).toString("utf8").split("\n").reverse(),
+      agent,
+    );
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) {
+      fs.closeSync(fd);
+    }
+  }
+}
+
+function parseLegacySample(line: string, agent: string | undefined): RunEntry | undefined {
+  try {
+    const entry: unknown = JSON.parse(line);
+    if (!validEntry(entry) || (agent !== undefined && entry.agent !== agent)) {
+      return;
+    }
+    return entry;
+  } catch {
+    // Invalid timing samples are not evidence; valid neighboring LF records survive.
+    return;
+  }
+}
+
+function parseLegacyLines(lines: readonly string[], agent: string | undefined): RunEntry[] {
+  const samples: RunEntry[] = [];
+  const retained = new Map<string, number>();
+  for (const line of lines) {
+    const entry = parseLegacySample(line, agent);
+    if (!entry || (retained.get(entry.agent) ?? 0) >= MAX_AGENT_SAMPLES) {
+      continue;
+    }
+    samples.push({ ...entry, task: entry.task.slice(0, 200) });
+    retained.set(entry.agent, (retained.get(entry.agent) ?? 0) + 1);
+    if (agent !== undefined && samples.length === MAX_AGENT_SAMPLES) {
+      break;
+    }
+  }
+  return samples;
 }
 
 export function recordRun(agent: string, task: string, exitCode: number, durationMs: number): void {
-	const entry: RunEntry = { agent, task: task.slice(0, 200), ts: Math.floor(Date.now() / 1000), status: exitCode === 0 ? "ok" : "error", duration: durationMs, ...(exitCode !== 0 ? { exit: exitCode } : {}) };
-	if (!validEntry(entry)) return;
-	let db: ReturnType<typeof openHistoryDatabase> | undefined;
-	try {
-		const agentDir = getAgentDir(); fs.mkdirSync(agentDir, { recursive: true });
-		db = openHistoryDatabase(path.join(historyDirectory(agentDir), TIMING_DATABASE));
-		const connection = db;
-		const imported = connection.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='timing_meta'").get()
-			&& connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get();
-		// Filesystem reads and JSON parsing must not consume another writer's admission budget.
-		const legacy = imported ? [] : legacySamples(agentDir).reverse();
-		// Allow brief native writer overlap; three attempts still bound best-effort admission.
-		connection.exec("PRAGMA busy_timeout=1000");
-		historyTransaction(connection, () => {
-			connection.exec(`CREATE TABLE IF NOT EXISTS timing_meta(key TEXT PRIMARY KEY);
+  const entry: RunEntry = {
+    agent,
+    task: task.slice(0, 200),
+    ts: Math.floor(Date.now() / 1000),
+    status: exitCode === 0 ? "ok" : "error",
+    duration: durationMs,
+    ...(exitCode !== 0 ? { exit: exitCode } : {}),
+  };
+  if (
+    !validIdentity({ ...entry }) ||
+    !validTiming({ ...entry }) ||
+    !Number.isSafeInteger(exitCode)
+  ) {
+    return;
+  }
+  let db: ReturnType<typeof openHistoryDatabase> | undefined;
+  try {
+    const agentDir = getAgentDir();
+    fs.mkdirSync(agentDir, { recursive: true });
+    db = openHistoryDatabase(path.join(historyDirectory(agentDir), TIMING_DATABASE));
+    const connection = db;
+    const imported =
+      connection
+        .prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='timing_meta'")
+        .get() !== undefined &&
+      connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get() !==
+        undefined;
+    // Filesystem reads and JSON parsing must not consume another writer's admission budget.
+    const legacy = imported ? [] : legacySamples(agentDir).reverse();
+    // Allow brief native writer overlap; three attempts still bound best-effort admission.
+    connection.exec("PRAGMA busy_timeout=1000");
+    historyTransaction(connection, () => {
+      connection.exec(`CREATE TABLE IF NOT EXISTS timing_meta(key TEXT PRIMARY KEY);
 				CREATE TABLE IF NOT EXISTS samples(sequence INTEGER PRIMARY KEY,agent TEXT NOT NULL,task TEXT NOT NULL,ts INTEGER NOT NULL,status TEXT NOT NULL,duration REAL NOT NULL,exit INTEGER);
 				CREATE INDEX IF NOT EXISTS samples_agent ON samples(agent,sequence DESC);`);
-			const insert = connection.prepare("INSERT INTO samples(agent,task,ts,status,duration,exit) VALUES (?,?,?,?,?,?)");
-			const save = (sample: RunEntry) => insert.run(sample.agent, sample.task, sample.ts, sample.status, sample.duration, sample.exit ?? null);
-			if (!connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get()) {
-				// Another writer may have imported while this snapshot was being read.
-				for (const sample of legacy) save(sample);
-				connection.exec("INSERT INTO timing_meta VALUES ('legacy-imported')");
-			}
-			save(entry);
-			connection.prepare("DELETE FROM samples WHERE agent=? AND sequence NOT IN (SELECT sequence FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?)").run(agent, agent, MAX_AGENT_SAMPLES);
-		});
-	} catch { /* Best-effort timing metadata must never interrupt a run. */ }
-	finally { db?.close(); }
+      const insert = connection.prepare(
+        "INSERT INTO samples(agent,task,ts,status,duration,exit) VALUES (?,?,?,?,?,?)",
+      );
+      const save = (sample: RunEntry) =>
+        insert.run(
+          sample.agent,
+          sample.task,
+          sample.ts,
+          sample.status,
+          sample.duration,
+          sample.exit ?? null,
+        );
+      if (!connection.prepare("SELECT key FROM timing_meta WHERE key='legacy-imported'").get()) {
+        // Another writer may have imported while this snapshot was being read.
+        for (const sample of legacy) {
+          save(sample);
+        }
+        connection.exec("INSERT INTO timing_meta VALUES ('legacy-imported')");
+      }
+      save(entry);
+      connection
+        .prepare(
+          "DELETE FROM samples WHERE agent=? AND sequence NOT IN (SELECT sequence FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?)",
+        )
+        .run(agent, agent, MAX_AGENT_SAMPLES);
+    });
+  } catch {
+    /* Best-effort timing metadata must never interrupt a run. */
+  } finally {
+    db?.close();
+  }
 }
 
 export function loadRunsForAgent(agent: string): RunEntry[] {
-	const agentDir = getAgentDir(), file = path.join(agentDir, "history-index", TIMING_DATABASE);
-	if (!fs.existsSync(file)) return legacySamples(agentDir, agent);
-	let db: ReturnType<typeof openHistoryDatabase> | undefined;
-	try {
-		db = openHistoryDatabase(path.join(historyDirectory(agentDir, false), TIMING_DATABASE), true);
-		return db.prepare("SELECT agent,task,ts,status,duration,exit FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?").all(agent, MAX_AGENT_SAMPLES)
-			.map((row) => ({ agent: String(row.agent), task: String(row.task), ts: Number(row.ts), status: row.status as RunEntry["status"], duration: Number(row.duration), ...(row.exit === null ? {} : { exit: Number(row.exit) }) }));
-	} catch { return []; }
-	finally { db?.close(); }
+  const agentDir = getAgentDir(),
+    file = path.join(agentDir, "history-index", TIMING_DATABASE);
+  if (!fs.existsSync(file)) {
+    return legacySamples(agentDir, agent);
+  }
+  let db: ReturnType<typeof openHistoryDatabase> | undefined;
+  try {
+    db = openHistoryDatabase(path.join(historyDirectory(agentDir, false), TIMING_DATABASE), true);
+    return db
+      .prepare(
+        "SELECT agent,task,ts,status,duration,exit FROM samples WHERE agent=? ORDER BY sequence DESC LIMIT ?",
+      )
+      .all(agent, MAX_AGENT_SAMPLES)
+      .flatMap((row) => {
+        const entry = {
+          agent: row.agent,
+          task: row.task,
+          ts: row.ts,
+          status: row.status,
+          duration: row.duration,
+          ...(row.exit === null ? {} : { exit: row.exit }),
+        };
+        return validEntry(entry) ? [entry] : [];
+      });
+  } catch {
+    return [];
+  } finally {
+    db?.close();
+  }
 }

package/src/runs/shared/run-id-ambiguity.ts

@@ -1,4 +1,8 @@
-export function formatRunIdAmbiguity(kind: string, prefix: string, candidates: string[]): string {
-	const preview = candidates.slice(0, 5);
-	return `Ambiguous ${kind} run id prefix '${prefix}' matched: ${preview.join(", ")}. ${candidates.length} matches (showing ${preview.length}). Provide a longer prefix or full run id.`;
+export function formatRunIdAmbiguity(
+  kind: string,
+  prefix: string,
+  candidates: readonly string[],
+): string {
+  const preview = candidates.slice(0, 5);
+  return `Ambiguous ${kind} run id prefix '${prefix}' matched: ${preview.join(", ")}. ${candidates.length} matches (showing ${preview.length}). Provide a longer prefix or full run id.`;
 }

package/src/runs/shared/run-metadata-paths.ts

@@ -0,0 +1,17 @@
+import * as path from "node:path";
+import { getAgentDir } from "../../shared/agent-dir.ts";
+import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+
+export const LEGACY_QUESTIONS_DIR = path.join(TEMP_ROOT_DIR, "supervisor-questions");
+export const QUESTIONS_DIR = path.join(getAgentDir(), "sessions", "subagent-runs");
+
+export function safeId(value: string): string {
+  if (typeof value !== "string" || !/^[a-zA-Z0-9_-]+$/.test(value)) {
+    throw new Error("Invalid run or question ID.");
+  }
+  return value;
+}
+
+export function getRunMetadataDir(runId: string, root = QUESTIONS_DIR): string {
+  return path.join(root, safeId(runId));
+}

package/src/runs/shared/run-metadata.ts

@@ -0,0 +1,240 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { parseAsyncResult, parseSupervisorRunContract } from "../background/run-schemas.ts";
+import { hasErrorCode, isRecord } from "../../shared/unknown.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { NativeJournal, ownerProjection, readJsonProjection } from "../../shared/journal-reader.ts";
+import { runSynchronously } from "../../shared/cooperative.ts";
+import type {
+  AsyncStatus,
+  AsyncResultFile,
+  ReadonlyInput,
+  SupervisorRunContract,
+  SavedLaunchConfig,
+} from "../../shared/types.ts";
+
+import {
+  getRunMetadataDir,
+  safeId,
+  QUESTIONS_DIR,
+  LEGACY_QUESTIONS_DIR,
+} from "./run-metadata-paths.ts";
+export {
+  getRunMetadataDir,
+  safeId,
+  QUESTIONS_DIR,
+  LEGACY_QUESTIONS_DIR,
+} from "./run-metadata-paths.ts";
+import { compactOwnerResult } from "./owner-output.ts";
+export { compactOwnerResult } from "./owner-output.ts";
+
+function conflictingCompletion(
+  previous: string | undefined,
+  incoming: string | undefined,
+): boolean {
+  return (
+    previous !== undefined &&
+    previous !== "" &&
+    incoming !== undefined &&
+    incoming !== "" &&
+    previous !== incoming
+  );
+}
+export function saveAsyncRunResult(
+  runId: string,
+  result: ReadonlyInput<AsyncResultFile>,
+): ReadonlyInput<AsyncResultFile> {
+  const file = path.join(getRunMetadataDir(runId), "result.json");
+  const previous = readRunJson(file, parseAsyncResult);
+  if (conflictingCompletion(previous?.completionId, result.completionId)) {
+    throw new Error("Conflicting completion identity");
+  }
+  const saved: ReadonlyInput<AsyncResultFile> = {
+    ...result,
+    recordVersion: 3,
+    completionId: previous?.completionId ?? result.completionId ?? randomUUID(),
+    ...(preserveLegacyOwner(file, previous) ? { legacySource: `${file}.legacy` } : {}),
+    results: result.results?.map((child, index) => compactOwnerResult(runId, index, child)),
+  };
+  writeAtomicJson(file, saved);
+  return saved;
+}
+
+function preserveLegacyOwner(
+  file: string,
+  previous: { readonly recordVersion?: number } | undefined,
+): boolean {
+  if (!previous || previous.recordVersion === 3) {
+    return false;
+  }
+  try {
+    fs.copyFileSync(file, `${file}.legacy`, fs.constants.COPYFILE_EXCL);
+  } catch (error) {
+    if (!hasErrorCode(error, "EEXIST")) {
+      throw error;
+    }
+  }
+  return true;
+}
+
+export function saveRunStatus(runId: string, status: ReadonlyInput<AsyncStatus>): void {
+  writeAtomicJson(path.join(getRunMetadataDir(runId), "status.json"), status);
+}
+
+export function readRunJson(file: string): unknown;
+export function readRunJson<T>(
+  file: string,
+  // Plain callbacks have no mutable properties; T describes the projected result.
+  project: (value: unknown) => T,
+): T | undefined;
+export function readRunJson(file: string, project?: (value: unknown) => unknown): unknown {
+  try {
+    const value: unknown = readJsonProjection(file, ownerProjection);
+    return project === undefined ? value : project(value);
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) {
+      return;
+    }
+    throw error;
+  }
+}
+
+export function readQuestionOwner(
+  runId: string,
+  root = QUESTIONS_DIR,
+): { readonly sessionId?: string } | undefined {
+  const value = readRunJson(path.join(getRunMetadataDir(runId, root), "question-owner.json"));
+  return isRecord(value) && typeof value.sessionId === "string"
+    ? { sessionId: value.sessionId }
+    : undefined;
+}
+
+export function saveQuestionOwner(runId: string, sessionId: string, root = QUESTIONS_DIR): void {
+  writeAtomicJson(path.join(root, safeId(runId), "question-owner.json"), { sessionId });
+}
+
+function preservedAttemptBaseline(
+  previous: SupervisorRunContract | undefined,
+  incoming: ReadonlyInput<SupervisorRunContract>,
+): Pick<SupervisorRunContract, "attemptBaseline"> {
+  return previous?.attemptBaseline && incoming.baselineSource !== "native-migration"
+    ? { attemptBaseline: previous.attemptBaseline }
+    : {};
+}
+export function saveQuestionContract(
+  runId: string,
+  index: number,
+  contract: ReadonlyInput<SupervisorRunContract>,
+  root = QUESTIONS_DIR,
+): void {
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new Error("Child index must be a non-negative integer.");
+  }
+  const file = path.join(root, safeId(runId), "contracts", `${index}.json`);
+  const previous = readRunJson(file, parseSupervisorRunContract);
+  writeAtomicJson(file, {
+    ...previous,
+    ...contract,
+    recordVersion: 3,
+    ...(preserveLegacyOwner(file, previous) ? { legacySource: `${file}.legacy` } : {}),
+    ...preservedAttemptBaseline(previous, contract),
+    ...(contract.result ? { result: compactOwnerResult(runId, index, contract.result, root) } : {}),
+    ...(previous?.launch ? { launch: previous.launch } : {}),
+  });
+}
+
+function nativeConfigurationAllowed(contract: SupervisorRunContract): boolean {
+  return (
+    contract.recordVersion !== 3 &&
+    !contract.effectiveConfiguration &&
+    contract.launch?.model?.startsWith("claude-code/") !== true
+  );
+}
+function recoverNativeConfiguration(
+  contract: SupervisorRunContract,
+  sessionFile: string | undefined,
+  endedAt: number | undefined,
+): Pick<SupervisorRunContract, "effectiveConfiguration"> | undefined {
+  if (!nativeConfigurationAllowed(contract)) {
+    return;
+  }
+  if (sessionFile === undefined || sessionFile === "" || !fs.existsSync(sessionFile)) {
+    return;
+  }
+  const journal = new NativeJournal(sessionFile, "inspect", true);
+  return { effectiveConfiguration: journal.configuration(endedAt, contract.terminalLeafId) };
+}
+
+function withNativeConfiguration(
+  contract: SupervisorRunContract,
+  launch: SavedLaunchConfig,
+  effectiveConfiguration: SupervisorRunContract["effectiveConfiguration"],
+): SupervisorRunContract {
+  const native = effectiveConfiguration ?? {};
+  return { ...contract, effectiveConfiguration, launch: { ...launch, ...native } };
+}
+
+export function readQuestionContract(
+  runId: string,
+  index: number,
+  root = QUESTIONS_DIR,
+  projection: {
+    readonly sessionFile?: string;
+    readonly endedAt?: number;
+    readonly readConfiguration?: false;
+  } = {},
+): SupervisorRunContract | undefined {
+  const contract = readRunJson(
+    path.join(root, safeId(runId), "contracts", `${index}.json`),
+    parseSupervisorRunContract,
+  );
+  if (!contract?.launch || projection.readConfiguration === false) {
+    return contract;
+  }
+  const sessionFile = projection.sessionFile ?? contract.sessionFile;
+  // Read native selection once, without rewriting the frozen requested launch.
+  const recovery = recoverNativeConfiguration(contract, sessionFile, projection.endedAt);
+  if (recovery) {
+    saveQuestionContract(runId, index, recovery, root);
+  }
+  const effectiveConfiguration =
+    recovery?.effectiveConfiguration ?? contract.effectiveConfiguration;
+  return withNativeConfiguration(contract, contract.launch, effectiveConfiguration);
+}
+
+export function migrateSupervisorQuestions(ownerSessionId: string, runId?: string): void {
+  runSynchronously(migrateSupervisorQuestionSteps(ownerSessionId, runId));
+}
+
+export function* migrateSupervisorQuestionSteps(
+  ownerSessionId: string,
+  runId?: string,
+): Generator<void> {
+  if (!fs.existsSync(LEGACY_QUESTIONS_DIR)) {
+    return;
+  }
+  const runs =
+    runId === undefined
+      ? fs
+          .readdirSync(LEGACY_QUESTIONS_DIR, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => entry.name)
+      : [safeId(runId)];
+  for (const id of runs) {
+    yield;
+    try {
+      const source = getRunMetadataDir(id, LEGACY_QUESTIONS_DIR);
+      const owner = readQuestionOwner(id, LEGACY_QUESTIONS_DIR);
+      if (owner?.sessionId !== ownerSessionId) {
+        continue;
+      }
+      fs.cpSync(source, getRunMetadataDir(id), { recursive: true, force: false });
+    } catch (error) {
+      if (runId !== undefined) {
+        throw error;
+      }
+      console.error(`Could not recover legacy questions for ${id}:`, error);
+    }
+  }
+}