@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/runs/background/async-run-discovery.ts

@@ -0,0 +1,270 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { RESULTS_DIR } from "../../shared/types.ts";
+import type { ReadonlyInput } from "../../shared/types/inputs.ts";
+import { runSynchronously } from "../../shared/cooperative.ts";
+import { asyncRunRoots, readAsyncRunRecord } from "./async-resume.ts";
+import type { AsyncRunRecord } from "./async-run-record.ts";
+import type { AsyncRunSummary } from "./async-run-summary.ts";
+import { getRunMetadataDir, readRunJson } from "../shared/supervisor-questions.ts";
+import { findNestedRouteForRootId } from "../shared/nested-events.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { validateStatusForSummary } from "./async-status-validation.ts";
+import { asyncStatusToSummary } from "./async-status-projection.ts";
+import { errorCode, errorMessage, hasText, isRecord } from "./async-value.ts";
+
+interface AsyncRunListOptions {
+  readonly states?: readonly AsyncRunSummary["state"][];
+  readonly sessionId?: string;
+  readonly limit?: number;
+  readonly resultsDir?: string;
+  readonly kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+  readonly now?: () => number;
+  readonly reconcile?: boolean;
+  readonly skipInvalid?: boolean;
+  readonly records?: readonly AsyncRunRecord[];
+}
+interface AsyncRunDiscoveryOptions extends Omit<
+  AsyncRunListOptions,
+  "states" | "limit" | "records"
+> {
+  readonly ownerSessionId?: string;
+  readonly receiptRunIds?: () => Iterable<string>;
+}
+
+function directory(root: string, entry: string): boolean {
+  const entryPath = path.join(root, entry);
+  try {
+    return fs.statSync(entryPath).isDirectory();
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      return false;
+    }
+    throw new Error(`Failed to inspect async run path '${entryPath}': ${errorMessage(error)}`, {
+      cause: error,
+    });
+  }
+}
+
+class AsyncRunDiscovery {
+  private readonly owners = new Map<string, string>();
+  private readonly discovered = new Set<string>();
+  private readonly sessionIds: ReadonlySet<string>;
+  private readonly ownerSessionId: string | undefined;
+
+  private readonly root: string;
+  private readonly options: ReadonlyInput<AsyncRunDiscoveryOptions>;
+  constructor(root: string, options: ReadonlyInput<AsyncRunDiscoveryOptions>) {
+    this.root = root;
+    this.options = options;
+    this.sessionIds = new Set([options.sessionId, options.ownerSessionId].filter(hasText));
+    // A legacy file-path-only query cannot classify native UUID owners as foreign.
+    this.ownerSessionId =
+      options.ownerSessionId ??
+      (hasText(options.sessionId) && !path.isAbsolute(options.sessionId)
+        ? options.sessionId
+        : undefined);
+  }
+
+  private *scanRoot(root: string): Generator<void, string[]> {
+    const entries: string[] = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      yield;
+      try {
+        if (entry.isDirectory() || (entry.isSymbolicLink() && directory(root, entry.name))) {
+          entries.push(entry.name);
+        }
+      } catch (error) {
+        if (this.options.skipInvalid !== true) {
+          throw error;
+        }
+        this.invalidEntry(path.join(root, entry.name), error);
+      }
+    }
+    return entries;
+  }
+
+  private *candidates(receipts: readonly string[]): Generator<void, Set<string>> {
+    const entries = new Set(receipts);
+    for (const root of asyncRunRoots(this.root)) {
+      try {
+        const scanned = yield* this.scanRoot(root);
+        for (const entry of scanned) {
+          entries.add(entry);
+        }
+      } catch (error) {
+        if (errorCode(error) === "ENOENT") {
+          continue;
+        }
+        throw new Error(`Failed to list async runs in '${this.root}': ${errorMessage(error)}`, {
+          cause: error,
+        });
+      }
+    }
+    return entries;
+  }
+
+  private invalidEntry(entry: string, error: unknown): void {
+    console.error(`Skipping invalid async run '${entry}':`, error);
+  }
+
+  private owner(entry: string): string | undefined {
+    let owner = this.owners.get(entry);
+    if (!hasText(owner) && hasText(this.ownerSessionId)) {
+      try {
+        const saved: unknown = readRunJson(
+          path.join(getRunMetadataDir(entry), "question-owner.json"),
+        );
+        if (
+          isRecord(saved) &&
+          typeof saved.sessionId === "string" &&
+          saved.sessionId.trim().length > 0
+        ) {
+          owner = saved.sessionId;
+          this.owners.set(entry, owner);
+        }
+      } catch {
+        // Missing/unusable identity metadata retains the legacy status fallback.
+      }
+    }
+    return owner;
+  }
+
+  private foreignOwner(owner: string | undefined, receipt: boolean): boolean {
+    return hasText(owner) && owner !== this.ownerSessionId && !receipt;
+  }
+  private authorizedRecord(
+    record: ReadonlyInput<AsyncRunRecord>,
+    owner: string | undefined,
+    receipt: boolean,
+  ): boolean {
+    const matching = owner !== undefined && owner === this.ownerSessionId;
+    return (
+      this.sessionIds.size === 0 ||
+      receipt ||
+      matching ||
+      this.sessionIds.has(record.status?.sessionId ?? "")
+    );
+  }
+
+  private readEntry(entry: string, receipt: boolean): AsyncRunRecord | undefined {
+    if (this.discovered.has(entry)) {
+      return undefined;
+    }
+    const owner = this.owner(entry);
+    if (this.foreignOwner(owner, receipt)) {
+      return undefined;
+    }
+    const record = readAsyncRunRecord(entry, this.root, this.options.resultsDir ?? RESULTS_DIR);
+    const { asyncDir } = record.location;
+    if (!hasText(asyncDir)) {
+      return undefined;
+    }
+    if (!this.authorizedRecord(record, owner, receipt)) {
+      return undefined;
+    }
+    if (this.options.reconcile !== false) {
+      record.status = reconcileAsyncRun(asyncDir, this.options, record).status;
+    }
+    if (record.status) {
+      validateStatusForSummary(record.status, path.join(asyncDir, "status.json"));
+      this.discovered.add(entry);
+    }
+    return record;
+  }
+
+  *steps(): Generator<void, AsyncRunRecord[]> {
+    const receipts = new Set(this.options.receiptRunIds?.());
+    const entries = yield* this.candidates([...receipts]);
+    const records: AsyncRunRecord[] = [];
+    for (const entry of entries) {
+      yield;
+      try {
+        const record = this.readEntry(entry, receipts.has(entry));
+        if (record) {
+          records.push(record);
+        }
+      } catch (error) {
+        if (this.options.skipInvalid !== true) {
+          throw error;
+        }
+        this.invalidEntry(entry, error);
+      }
+    }
+    return records;
+  }
+}
+
+/** Retry new/unpublished runs without retaining payloads or negative ownership facts. */
+export function createAsyncRunDiscovery(
+  asyncDirRoot: string,
+  options: ReadonlyInput<AsyncRunDiscoveryOptions> = {},
+): (() => AsyncRunRecord[]) & { readonly steps: () => Generator<void, AsyncRunRecord[]> } {
+  const discovery = new AsyncRunDiscovery(asyncDirRoot, options);
+  return Object.assign(() => runSynchronously(discovery.steps()), {
+    steps: () => discovery.steps(),
+  });
+}
+
+const STATE_RANK = { running: 0, queued: 1, failed: 2, blocked: 2, paused: 2, complete: 3 };
+
+function summary(
+  record: ReadonlyInput<AsyncRunRecord>,
+  options: ReadonlyInput<AsyncRunListOptions>,
+): AsyncRunSummary | undefined {
+  const { asyncDir } = record.location;
+  const { status } = record;
+  if (!hasText(asyncDir) || !status) {
+    return undefined;
+  }
+  const warnings: string[] = [];
+  let children;
+  try {
+    const route = findNestedRouteForRootId(
+      status.runId.length > 0 ? status.runId : path.basename(asyncDir),
+    );
+    if (route) {
+      children = reconcileNestedAsyncDescendants(route, options);
+    }
+  } catch (error) {
+    warnings.push(`Nested status unavailable: ${errorMessage(error)}`);
+  }
+  return asyncStatusToSummary(asyncDir, status, warnings, children);
+}
+
+function allowState(
+  run: ReadonlyInput<AsyncRunSummary>,
+  states: readonly AsyncRunSummary["state"][] | undefined,
+): boolean {
+  return states === undefined || states.includes(run.state);
+}
+
+export function listAsyncRuns(
+  asyncDirRoot: string,
+  options: ReadonlyInput<AsyncRunListOptions> = {},
+): AsyncRunSummary[] {
+  const runs: AsyncRunSummary[] = [];
+  for (const record of options.records ?? createAsyncRunDiscovery(asyncDirRoot, options)()) {
+    try {
+      const run = summary(record, options);
+      if (run && allowState(run, options.states)) {
+        runs.push(run);
+      }
+    } catch (error) {
+      if (options.skipInvalid !== true) {
+        throw error;
+      }
+      console.error(
+        `Skipping invalid async run '${record.location.resolvedId ?? "unknown"}':`,
+        error,
+      );
+    }
+  }
+  runs.sort((a, b) => {
+    const rank = STATE_RANK[a.state] - STATE_RANK[b.state];
+    return rank !== 0
+      ? rank
+      : (b.lastUpdate ?? b.endedAt ?? b.startedAt) - (a.lastUpdate ?? a.endedAt ?? a.startedAt);
+  });
+  return options.limit === undefined ? runs : runs.slice(0, options.limit);
+}

package/src/runs/background/async-run-location.ts

@@ -0,0 +1,194 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatRunIdAmbiguity } from "../shared/run-id-ambiguity.ts";
+import type { ReadonlyInput } from "../../shared/types/inputs.ts";
+import { QUESTIONS_DIR, readRunJson } from "../shared/supervisor-questions.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { isDurableRun } from "./async-result-file.ts";
+import type { AsyncRunLocation, AsyncRunRecord } from "./async-run-record.ts";
+import { hasText } from "./async-value.ts";
+
+export interface AsyncResumeParams {
+  readonly id?: string;
+  readonly runId?: string;
+  readonly dir?: string;
+  readonly index?: number;
+}
+
+function assertRunId(value: string | undefined, field: "id" | "runId"): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value.trim().length === 0) {
+    throw new Error(`${field} must not be empty.`);
+  }
+  if (path.isAbsolute(value) || /[\\/]/.test(value) || value.includes("..")) {
+    throw new Error(`${field} must be an async run id or prefix, not a path.`);
+  }
+  return value;
+}
+
+function insideRoot(root: string, target: string): boolean {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative.length === 0 || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function prefixedRunIds(dir: string, prefix: string, suffix = ""): string[] {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(dir)
+    .filter((entry) => entry.startsWith(prefix) && (suffix.length === 0 || entry.endsWith(suffix)))
+    .map((entry) => (suffix.length > 0 ? entry.slice(0, -suffix.length) : entry))
+    .sort();
+}
+
+export function asyncRunRoots(asyncDirRoot: string): string[] {
+  return [...new Set([path.resolve(asyncDirRoot), path.resolve(QUESTIONS_DIR)])];
+}
+
+function exactResultPath(resultsDir: string, runId: string): string | null {
+  const resultPath = path.join(resultsDir, `${runId}.json`);
+  if (!insideRoot(resultsDir, resultPath)) {
+    throw new Error(`Async result file must be inside ${path.resolve(resultsDir)}.`);
+  }
+  return fs.existsSync(resultPath) ? resultPath : null;
+}
+
+function preferredResult(durableResult: string, resultsDir: string, runId: string): string | null {
+  return fs.existsSync(durableResult) ? durableResult : exactResultPath(resultsDir, runId);
+}
+
+function resolveAsyncRunRecord(
+  runId: string,
+  asyncDirRoot: string,
+  resultsDir: string,
+  readLegacyStatus: boolean,
+): AsyncRunRecord {
+  assertRunId(runId, "id");
+  const durableDir = path.join(QUESTIONS_DIR, runId);
+  const legacyDir = path.join(asyncDirRoot, runId);
+  const durableStatus = readStatus(durableDir);
+  const durableResult = path.join(durableDir, "result.json");
+  const durable =
+    isDurableRun(durableStatus) || isDurableRun(readRunJson(path.join(durableDir, "launch.json")));
+  let asyncDir: string | null = null;
+  if (durable) {
+    asyncDir = durableDir;
+  } else if (fs.existsSync(legacyDir)) {
+    asyncDir = legacyDir;
+  } else if (durableStatus) {
+    asyncDir = durableDir;
+  }
+  let status = asyncDir === durableDir ? durableStatus : null;
+  if (asyncDir !== durableDir && asyncDir !== null && readLegacyStatus) {
+    status = readStatus(asyncDir);
+  }
+  return {
+    location: {
+      asyncDir,
+      resultPath: preferredResult(durableResult, resultsDir, runId),
+      resolvedId: runId,
+    },
+    status,
+    durable: durable || isDurableRun(status),
+  };
+}
+
+export function exactAsyncRunLocation(
+  runId: string,
+  asyncDirRoot: string,
+  resultsDir: string,
+): AsyncRunLocation {
+  return resolveAsyncRunRecord(runId, asyncDirRoot, resultsDir, false).location;
+}
+
+/** Resolve canonical precedence and decode each candidate status once for this pass. */
+export function readAsyncRunRecord(
+  runId: string,
+  asyncDirRoot: string,
+  resultsDir: string,
+): AsyncRunRecord {
+  return resolveAsyncRunRecord(runId, asyncDirRoot, resultsDir, true);
+}
+
+export function findAsyncRunPrefixMatches(
+  prefix: string,
+  asyncDirRoot: string,
+  resultsDir: string,
+): { readonly id: string; readonly location: AsyncRunLocation }[] {
+  const requestedId = assertRunId(prefix, "id");
+  if (!hasText(requestedId)) {
+    return [];
+  }
+  const asyncRoot = path.resolve(asyncDirRoot);
+  const resultRoot = path.resolve(resultsDir);
+  const durableIds = prefixedRunIds(QUESTIONS_DIR, requestedId).filter((id) =>
+    ["status.json", "result.json", "launch.json"].some((file) =>
+      fs.existsSync(path.join(QUESTIONS_DIR, id, file)),
+    ),
+  );
+  const ids = [
+    ...new Set([
+      ...prefixedRunIds(asyncRoot, requestedId),
+      ...durableIds,
+      ...prefixedRunIds(resultRoot, requestedId, ".json"),
+    ]),
+  ].sort();
+  return ids.map((id) => ({ id, location: exactAsyncRunLocation(id, asyncRoot, resultRoot) }));
+}
+
+function directoryLocation(
+  params: ReadonlyInput<AsyncResumeParams>,
+  roots: { readonly asyncRoot: string; readonly resultRoot: string; readonly requestedId?: string },
+): AsyncRunLocation {
+  const asyncDir = path.resolve(params.dir ?? "");
+  if (!asyncRunRoots(roots.asyncRoot).some((root) => insideRoot(root, asyncDir))) {
+    throw new Error(
+      `Async run directory must be inside ${asyncRunRoots(roots.asyncRoot).join(" or ")}.`,
+    );
+  }
+  const resolvedId = roots.requestedId ?? path.basename(asyncDir);
+  if (hasText(roots.requestedId) && roots.requestedId !== path.basename(asyncDir)) {
+    throw new Error(
+      `Async run id '${roots.requestedId}' does not match directory '${path.basename(asyncDir)}'.`,
+    );
+  }
+  const location = exactAsyncRunLocation(resolvedId, roots.asyncRoot, roots.resultRoot);
+  const canonical =
+    location.asyncDir !== null &&
+    isDurableRun(readRunJson(path.join(location.asyncDir, "launch.json")));
+  return { ...location, asyncDir: canonical ? location.asyncDir : asyncDir };
+}
+
+export function resolveAsyncRunLocation(
+  params: ReadonlyInput<AsyncResumeParams>,
+  asyncDirRoot: string,
+  resultsDir: string,
+): AsyncRunLocation {
+  const asyncRoot = path.resolve(asyncDirRoot);
+  const resultRoot = path.resolve(resultsDir);
+  const requestedId = assertRunId(params.id, "id") ?? assertRunId(params.runId, "runId");
+  if (hasText(params.dir)) {
+    return directoryLocation(params, { asyncRoot, resultRoot, requestedId });
+  }
+  if (!hasText(requestedId)) {
+    return { asyncDir: null, resultPath: null };
+  }
+  const direct = exactAsyncRunLocation(requestedId, asyncRoot, resultRoot);
+  if (direct.asyncDir !== null || direct.resultPath !== null) {
+    return direct;
+  }
+  const matches = findAsyncRunPrefixMatches(requestedId, asyncRoot, resultRoot);
+  if (matches.length > 1) {
+    throw new Error(
+      formatRunIdAmbiguity(
+        "async",
+        requestedId,
+        matches.map((match) => match.id),
+      ),
+    );
+  }
+  return matches[0]?.location ?? { asyncDir: null, resultPath: null, resolvedId: requestedId };
+}

package/src/runs/background/async-run-record.ts

@@ -0,0 +1,14 @@
+import type { AsyncStatus, ReadonlyInput } from "../../shared/types.ts";
+
+export interface AsyncRunLocation {
+  readonly asyncDir: string | null;
+  readonly resultPath: string | null;
+  readonly resolvedId?: string;
+}
+
+/** A discovery pass owns this decoded status and may replace its projection. */
+export interface AsyncRunRecord {
+  readonly location: AsyncRunLocation;
+  status: ReadonlyInput<AsyncStatus> | null;
+  readonly durable: boolean;
+}