@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/src/runs/background/stale-run-reconciler.ts

@@ -1,312 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import {
-  RESULTS_DIR,
-  type AsyncParallelGroupStatus,
-  type AsyncStatus,
-  type NestedRunSummary,
-  type SubagentRunMode,
-} from "../../shared/types.ts";
-import type { ReadonlyInput } from "../../shared/types/inputs.ts";
-import { normalizeParallelGroups } from "./parallel-groups.ts";
-import {
-  nestedSummaryFromAsyncStatus,
-  projectNestedEvents,
-  resolveNestedAsyncDir,
-  writeNestedEvent,
-  type NestedRoute,
-} from "../shared/nested-events.ts";
-import { isDurableRun } from "./async-result-file.ts";
-import { readRunJson } from "../shared/supervisor-questions.ts";
-import { readStatus } from "../../shared/utils.ts";
-import type { AsyncRunRecord } from "./async-run-record.ts";
-import {
-  buildFailedRepair,
-  terminalStatusFromResult,
-  writeFailedRepair,
-} from "./async-run-repair.ts";
-import { errorCode, hasText } from "./async-value.ts";
-
-export type PidLiveness = "alive" | "dead" | "unknown";
-type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
-interface StartedRunMetadata {
-  readonly runId: string;
-  readonly pid?: number;
-  readonly sessionId?: string;
-  readonly mode?: SubagentRunMode;
-  readonly agents?: readonly string[];
-  readonly chainStepCount?: number;
-  readonly parallelGroups?: readonly AsyncParallelGroupStatus[];
-  readonly startedAt?: number;
-  readonly sessionFile?: string;
-}
-interface ReconcileAsyncRunOptions {
-  readonly resultsDir?: string;
-  readonly kill?: KillFn;
-  readonly now?: () => number;
-  readonly startedRun?: StartedRunMetadata;
-  readonly missingStatusGraceMs?: number;
-  readonly staleAlivePidMs?: number;
-}
-interface ReconcileAsyncRunResult {
-  readonly status: ReadonlyInput<AsyncStatus> | null;
-  readonly repaired: boolean;
-  readonly resultPath?: string;
-  readonly message?: string;
-}
-interface Recovery {
-  readonly asyncDir: string;
-  readonly resultPath: string;
-  readonly now: number;
-  readonly options: ReadonlyInput<ReconcileAsyncRunOptions>;
-}
-
-function buildStartedStatus(
-  asyncDir: string,
-  startedRun: ReadonlyInput<StartedRunMetadata>,
-  now: number,
-): AsyncStatus {
-  const startedAt = startedRun.startedAt ?? now;
-  const agents = (startedRun.agents?.length ?? 0) > 0 ? (startedRun.agents ?? []) : ["subagent"];
-  const count = startedRun.chainStepCount;
-  const groups =
-    count === undefined
-      ? []
-      : normalizeParallelGroups(startedRun.parallelGroups, agents.length, count);
-  return {
-    runId: startedRun.runId.length > 0 ? startedRun.runId : path.basename(asyncDir),
-    sessionId: startedRun.sessionId,
-    mode: startedRun.mode ?? "single",
-    state: "running",
-    pid: startedRun.pid,
-    startedAt,
-    lastUpdate: now,
-    currentStep: 0,
-    chainStepCount: count,
-    ...(groups.length > 0 ? { parallelGroups: groups } : {}),
-    steps: agents.map((agent) => ({ agent, status: "running", startedAt })),
-    sessionFile: startedRun.sessionFile,
-  };
-}
-function terminal(state: AsyncStatus["state"]): boolean {
-  return state === "complete" || state === "failed" || state === "blocked" || state === "paused";
-}
-
-function publishNestedRepair(
-  result: ReadonlyInput<ReconcileAsyncRunResult>,
-  route: ReadonlyInput<NestedRoute>,
-  child: ReadonlyInput<NestedRunSummary>,
-  ts: number,
-): void {
-  if (
-    !result.status ||
-    isDurableRun(result.status) ||
-    (!result.repaired && !terminal(result.status.state))
-  ) {
-    return;
-  }
-  writeNestedEvent(route, {
-    type: terminal(result.status.state) ? "subagent.nested.completed" : "subagent.nested.updated",
-    ts,
-    parentRunId: child.parentRunId,
-    parentStepIndex: child.parentStepIndex,
-    child,
-  });
-}
-function projectedNestedChild(
-  run: ReadonlyInput<NestedRunSummary>,
-  status: ReadonlyInput<AsyncStatus>,
-  asyncDir: string,
-  ts: number,
-): NestedRunSummary {
-  const child = nestedSummaryFromAsyncStatus(status, asyncDir, {
-    id: run.id,
-    parentRunId: run.parentRunId,
-    parentStepIndex: run.parentStepIndex,
-    depth: run.depth,
-    path: run.path,
-    mode: run.mode,
-    ts,
-  });
-  const steps = child.steps?.map((step, index) => {
-    return { ...step, children: run.steps?.at(index)?.children };
-  });
-  return { ...child, steps };
-}
-function reconcileNestedRun(
-  run: ReadonlyInput<NestedRunSummary>,
-  route: ReadonlyInput<NestedRoute>,
-  options: ReadonlyInput<ReconcileAsyncRunOptions>,
-): NestedRunSummary {
-  if (run.state !== "running" && run.state !== "queued") {
-    return run;
-  }
-  const asyncDir = resolveNestedAsyncDir(route.rootRunId, run);
-  if (!hasText(asyncDir)) {
-    return run;
-  }
-  const result = reconcileAsyncRun(asyncDir, {
-    ...options,
-    resultsDir: path.join(options.resultsDir ?? RESULTS_DIR, "nested", route.rootRunId),
-  });
-  if (!result.status) {
-    return run;
-  }
-  const ts = options.now?.() ?? Date.now();
-  const child = projectedNestedChild(run, result.status, asyncDir, ts);
-  publishNestedRepair(result, route, child, ts);
-  return { ...run, ...child, ...(hasText(result.message) ? { error: result.message } : {}) };
-}
-function reconcileNestedTree(
-  run: ReadonlyInput<NestedRunSummary>,
-  route: ReadonlyInput<NestedRoute>,
-  options: ReadonlyInput<ReconcileAsyncRunOptions>,
-): NestedRunSummary {
-  const projected = reconcileNestedRun(run, route, options);
-  const children = projected.children?.map((child) => reconcileNestedTree(child, route, options));
-  const steps = projected.steps?.map((step) => {
-    return {
-      ...step,
-      children: step.children?.map((child) => reconcileNestedTree(child, route, options)),
-    };
-  });
-  return { ...projected, children, steps };
-}
-export function reconcileNestedAsyncDescendants(
-  route: ReadonlyInput<NestedRoute>,
-  options: ReadonlyInput<ReconcileAsyncRunOptions> = {},
-): NestedRunSummary[] {
-  return projectNestedEvents(route).children.map((run) => reconcileNestedTree(run, route, options));
-}
-export function checkPidLiveness(
-  pid: number,
-  kill: KillFn = (target, signal) => process.kill(target, signal),
-): PidLiveness {
-  try {
-    kill(pid, 0);
-    return "alive";
-  } catch (error) {
-    return errorCode(error) === "ESRCH" ? "dead" : "unknown";
-  }
-}
-
-function durableProjection(
-  status: ReadonlyInput<AsyncStatus>,
-  recovery: Recovery,
-): ReconcileAsyncRunResult {
-  const { asyncDir, resultPath, options, now } = recovery;
-  const final = terminalStatusFromResult(status, resultPath, status.endedAt ?? now);
-  if (final) {
-    return { status: final, repaired: false, resultPath };
-  }
-  if (typeof status.pid === "number" && checkPidLiveness(status.pid, options.kill) === "dead") {
-    const failure = buildFailedRepair(status, asyncDir, status.lastUpdate ?? status.startedAt);
-    return { status: failure.status, repaired: false, message: failure.message };
-  }
-  if (terminal(status.state)) {
-    return {
-      status: { ...status, state: "running" },
-      repaired: false,
-      message: "Waiting for the owner's final result. Completion is unconfirmed.",
-    };
-  }
-  return { status, repaired: false };
-}
-function legacyProjection(
-  status: ReadonlyInput<AsyncStatus> | null,
-  effective: ReadonlyInput<AsyncStatus>,
-  recovery: Recovery,
-): ReconcileAsyncRunResult {
-  const { asyncDir, resultPath, now } = recovery;
-  if (fs.existsSync(resultPath)) {
-    const final =
-      effective.state === "running" || effective.state === "queued"
-        ? terminalStatusFromResult(effective, resultPath, now)
-        : undefined;
-    if (final) {
-      writeAtomicJson(path.join(asyncDir, "status.json"), final);
-      return {
-        status: final,
-        repaired: true,
-        resultPath,
-        message: "Existing async result file was used to repair stale running status.",
-      };
-    }
-    return { status: effective, repaired: false, resultPath };
-  }
-  return legacyMissingResult(status, effective, recovery);
-}
-function awaitingInitialStatus(
-  status: ReadonlyInput<AsyncStatus> | null,
-  effective: ReadonlyInput<AsyncStatus>,
-  recovery: Recovery,
-): boolean {
-  const start = recovery.options.startedRun?.startedAt ?? effective.startedAt;
-  return status === null && recovery.now - start < (recovery.options.missingStatusGraceMs ?? 1000);
-}
-function legacyMissingResult(
-  status: ReadonlyInput<AsyncStatus> | null,
-  effective: ReadonlyInput<AsyncStatus>,
-  recovery: Recovery,
-): ReconcileAsyncRunResult {
-  const { options, now, asyncDir, resultPath } = recovery;
-  const unchanged = { status, repaired: false, resultPath };
-  if (
-    (effective.state !== "running" && effective.state !== "queued") ||
-    typeof effective.pid !== "number" ||
-    awaitingInitialStatus(status, effective, recovery)
-  ) {
-    return unchanged;
-  }
-  if (checkPidLiveness(effective.pid, options.kill) === "dead") {
-    return writeFailedRepair(asyncDir, effective, resultPath, { now });
-  }
-  const lastUpdate = effective.lastUpdate ?? effective.startedAt;
-  if (now - lastUpdate <= (options.staleAlivePidMs ?? 24 * 60 * 60 * 1000)) {
-    return unchanged;
-  }
-  const reason = `Async runner process ${effective.pid} still has a live PID, but status has not updated for ${now - lastUpdate}ms. Marked run failed by stale-run reconciliation because PID ownership cannot be verified.`;
-  return writeFailedRepair(asyncDir, effective, resultPath, { now, reason });
-}
-function resultLocation(
-  asyncDir: string,
-  status: ReadonlyInput<AsyncStatus>,
-  options: ReadonlyInput<ReconcileAsyncRunOptions>,
-  record: ReadonlyInput<Pick<AsyncRunRecord, "status" | "durable">> | undefined,
-): { readonly durable: boolean; readonly resultPath: string } {
-  const runId = status.runId.length > 0 ? status.runId : path.basename(asyncDir);
-  const durable =
-    isDurableRun(status) ||
-    (record === undefined
-      ? isDurableRun(readRunJson(path.join(asyncDir, "launch.json")))
-      : record.durable);
-  return {
-    durable,
-    resultPath: durable
-      ? path.join(asyncDir, "result.json")
-      : path.join(options.resultsDir ?? RESULTS_DIR, `${runId}.json`),
-  };
-}
-export function reconcileAsyncRun(
-  asyncDir: string,
-  options: ReadonlyInput<ReconcileAsyncRunOptions> = {},
-  record?: ReadonlyInput<Pick<AsyncRunRecord, "status" | "durable">>,
-): ReconcileAsyncRunResult {
-  const now = options.now?.() ?? Date.now();
-  const status = record === undefined ? readStatus(asyncDir) : record.status;
-  const effective =
-    status ??
-    (options.startedRun === undefined
-      ? undefined
-      : buildStartedStatus(asyncDir, options.startedRun, now));
-  if (!effective) {
-    return { status: null, repaired: false };
-  }
-  const location = resultLocation(asyncDir, effective, options, record);
-  const recovery = { asyncDir, resultPath: location.resultPath, options, now };
-  // The detached durable owner is the only execution writer. Inspection projects its evidence.
-  return location.durable
-    ? durableProjection(effective, recovery)
-    : legacyProjection(status, effective, recovery);
-}

package/src/runs/background/subagent-runner-launcher.ts

@@ -1,88 +0,0 @@
-import { spawn } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-
-const RETRY_WINDOW_MS = 30_000;
-const RETRY_DELAY_MS = 500;
-const MAX_STDERR_LENGTH = 64 * 1024;
-
-function run(
-  runnerPath: string,
-  configPath: string,
-  piPackageRoot?: string,
-): Promise<{ code: number; stderr: string }> {
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, [runnerPath, configPath], {
-      stdio: ["ignore", "inherit", "pipe"],
-      env:
-        piPackageRoot !== undefined && piPackageRoot.length > 0
-          ? { ...process.env, PI_PACKAGE_DIR: process.env.PI_PACKAGE_DIR ?? piPackageRoot }
-          : process.env,
-    });
-    let stderr = "";
-    child.stderr.on("data", (chunk: unknown) => {
-      if (!Buffer.isBuffer(chunk)) {
-        return;
-      }
-      process.stderr.write(chunk);
-      stderr = `${stderr}${chunk.toString()}`.slice(-MAX_STDERR_LENGTH);
-    });
-    child.once("error", (error) => {
-      const failure = error.stack ?? error.message;
-      process.stderr.write(`${failure}\n`);
-      resolve({ code: 1, stderr: failure });
-    });
-    child.once("close", (code) => resolve({ code: code ?? 1, stderr }));
-  });
-}
-
-const runnerPath = process.argv.at(2);
-const configPath = process.argv.at(3);
-if (runnerPath === undefined || configPath === undefined) {
-  throw new Error("Usage: subagent-runner-launcher <runner> <config>");
-}
-
-let statusPath: string | undefined;
-let piPackageRoot: string | undefined;
-try {
-  const config: unknown = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-  if (typeof config === "object" && config !== null) {
-    if ("piPackageRoot" in config && typeof config.piPackageRoot === "string") {
-      piPackageRoot = config.piPackageRoot;
-    }
-    if ("asyncDir" in config && typeof config.asyncDir === "string") {
-      statusPath = path.join(config.asyncDir, "status.json");
-    }
-  }
-} catch {
-  // The runner owns reporting malformed launch files; launcher discovery is best effort.
-}
-
-// ponytail: bridge short in-place extension updates; use shared update locking if longer gaps appear.
-const deadline = Date.now() + RETRY_WINDOW_MS;
-let announcedRetry = false;
-while (true) {
-  // Retrying before startup must finish before inspecting the next process outcome.
-  // oxlint-disable-next-line no-await-in-loop
-  const result = await run(runnerPath, configPath, piPackageRoot);
-  const failedBeforeStartup = statusPath === undefined || !fs.existsSync(statusPath);
-  if (
-    result.code === 0 ||
-    !failedBeforeStartup ||
-    !result.stderr.includes("ERR_MODULE_NOT_FOUND") ||
-    Date.now() >= deadline
-  ) {
-    process.exitCode = result.code;
-    break;
-  }
-  if (!announcedRetry) {
-    process.stderr.write(
-      "[pi-subagents] Runner dependencies are being updated; retrying startup.\n",
-    );
-    announcedRetry = true;
-  }
-  // Back off between dependency-update retries instead of launching concurrent runners.
-  // oxlint-disable-next-line no-await-in-loop
-  await delay(RETRY_DELAY_MS);
-}

package/src/runs/background/subagent-runner.ts

@@ -1,85 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ReadonlyDeep } from "type-fest";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { appendJsonl } from "../../shared/artifacts.ts";
-import { saveRunStatus } from "../shared/supervisor-questions.ts";
-import { parseSubagentRunConfig } from "./run-schemas.ts";
-import type { SubagentRunConfig } from "./runner-contract.ts";
-import { createRunnerStatus } from "./runner-initial-status.ts";
-import { RunnerMonitor } from "./runner-monitor.ts";
-import { RunnerLifecycle } from "./runner-lifecycle.ts";
-import { RunnerWorkflow } from "./runner-workflow.ts";
-import { completeRunner } from "./runner-completion.ts";
-
-async function runSubagent(config: ReadonlyDeep<SubagentRunConfig>): Promise<void> {
-  const startedAt = Date.now();
-  const status = createRunnerStatus(config, startedAt);
-  fs.mkdirSync(config.asyncDir, { recursive: true });
-  writeAtomicJson(path.join(config.asyncDir, "status.json"), status);
-  if (config.runtimeVersion !== 2) {
-    saveRunStatus(config.id, status);
-  }
-  const monitor = new RunnerMonitor(config, status, startedAt);
-  const lifecycle = new RunnerLifecycle(config, status, monitor);
-  lifecycle.start(startedAt);
-  appendJsonl(
-    path.join(config.asyncDir, "events.jsonl"),
-    JSON.stringify({
-      type: "subagent.run.started",
-      ts: startedAt,
-      runId: config.id,
-      mode: status.mode,
-      cwd: config.cwd,
-      pid: process.pid,
-    }),
-  );
-  try {
-    const evidence = await new RunnerWorkflow(config, monitor, lifecycle).run(startedAt);
-    await completeRunner(config, evidence, monitor, lifecycle);
-  } finally {
-    lifecycle.dispose();
-  }
-}
-
-function runnerError(error: unknown): void {
-  console.error("Subagent runner error:", error);
-  process.exit(1);
-}
-
-function launchConfig(text: string, file?: string): void {
-  const value: unknown = JSON.parse(text);
-  const config = parseSubagentRunConfig(value);
-  if (file !== undefined && config.runtimeVersion !== 2) {
-    try {
-      fs.unlinkSync(file);
-    } catch {
-      /* Legacy temporary configuration cleanup is best effort. */
-    }
-  }
-  runSubagent(config).catch(runnerError);
-}
-
-const configArg = process.argv.at(2);
-if (configArg !== undefined && configArg.length > 0) {
-  try {
-    launchConfig(fs.readFileSync(configArg, "utf-8"), configArg);
-  } catch (error) {
-    runnerError(error);
-  }
-} else {
-  let input = "";
-  process.stdin.setEncoding("utf-8");
-  process.stdin.on("data", (chunk: unknown) => {
-    if (typeof chunk === "string") {
-      input += chunk;
-    }
-  });
-  process.stdin.on("end", () => {
-    try {
-      launchConfig(input);
-    } catch (error) {
-      runnerError(error);
-    }
-  });
-}

package/src/runs/background/top-level-async.ts

@@ -1,15 +0,0 @@
-interface AsyncOverrideParams {
-  async?: boolean;
-  clarify?: boolean;
-}
-
-export function applyForceTopLevelAsyncOverride<T extends AsyncOverrideParams>(
-  params: T,
-  depth: number,
-  forceTopLevelAsync: boolean,
-): T {
-  if (!(depth === 0 && forceTopLevelAsync)) {
-    return params;
-  }
-  return { ...params, async: true, clarify: false };
-}