@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/runs/background/runner-step-record.ts

@@ -0,0 +1,76 @@
+import * as fs from "node:fs";
+import type { ReadonlyDeep } from "type-fest";
+import type { ArtifactPaths, ModelAttempt } from "../../shared/types.ts";
+import { saveQuestionContract } from "../shared/supervisor-questions.ts";
+import type { RunSingleStepResult } from "./runner-contract.ts";
+import type { StepAttempt } from "./runner-attempt-output.ts";
+
+export function nativeResultFields(
+  execution: ReadonlyDeep<StepAttempt>,
+  attempts: readonly ReadonlyDeep<ModelAttempt>[],
+): Pick<
+  RunSingleStepResult,
+  | "accounting"
+  | "nativeSessionId"
+  | "terminalLeafId"
+  | "terminalEntryId"
+  | "auditPath"
+  | "auditSaveError"
+  | "agentProcessExit"
+> {
+  return {
+    accounting:
+      attempts.find((attempt) => attempt.accounting?.state === "incomplete")?.accounting ??
+      execution.accounting,
+    nativeSessionId: execution.nativeSessionId,
+    terminalLeafId: execution.terminalLeafId,
+    terminalEntryId: execution.terminalEntryId,
+    auditPath: execution.auditPath,
+    auditSaveError: execution.auditSaveError,
+    agentProcessExit: execution.agentProcessExit,
+  };
+}
+
+/** Publishes immutable completed-step evidence after output preservation is finished. */
+export function saveStepRecord(
+  result: ReadonlyDeep<RunSingleStepResult>,
+  input: Readonly<{ runId: string; flatIndex: number; task: string; fullOutput: string }>,
+  paths: Readonly<ArtifactPaths> | undefined,
+): void {
+  if (result.task === undefined || result.usage === undefined) {
+    throw new Error("Completed step evidence requires task and usage.");
+  }
+  if (paths) {
+    fs.writeFileSync(paths.outputPath, input.fullOutput, "utf-8");
+    fs.writeFileSync(
+      paths.metadataPath,
+      JSON.stringify(
+        {
+          runId: input.runId,
+          agent: result.agent,
+          task: input.task,
+          exitCode: result.exitCode,
+          interrupted: result.interrupted,
+          agentProcessExit: result.agentProcessExit,
+          error: result.error,
+          acceptance: result.acceptance,
+          initialOutput: result.initialOutput,
+          usage: result.usage,
+          model: result.model,
+          attemptedModels: result.attemptedModels,
+          modelAttempts: result.modelAttempts,
+          resourceLimitExceeded: result.resourceLimitExceeded,
+          skills: result.skills,
+          timestamp: Date.now(),
+        },
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+  }
+  saveQuestionContract(input.runId, input.flatIndex, {
+    result: { ...result, task: result.task, usage: result.usage, finalOutput: result.finalOutput },
+    updatedAt: Date.now(),
+  });
+}

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

@@ -0,0 +1,150 @@
+import type { ReadonlyDeep } from "type-fest";
+import { findLatestSessionFile } from "../../shared/utils.ts";
+import { runModelAttempts, sumAttemptUsage } from "../shared/model-fallback.ts";
+import { recordRun } from "../shared/run-history.ts";
+import { resolveExecutionOutcome, type evaluateRunAcceptance } from "../shared/acceptance.ts";
+import type { RunnerSubagentStep } from "../../shared/types.ts";
+import { RunnerAttempt } from "./runner-attempt.ts";
+import { RunnerFinalization } from "./runner-finalization.ts";
+import type { StepAttempt } from "./runner-attempt-output.ts";
+import type { RunSingleStepResult, SingleStepContext } from "./runner-contract.ts";
+import { prepareRunnerStep, type PreparedRunnerStep } from "./runner-prepare-step.ts";
+import { publishStepOutput, stepOutputFields } from "./runner-step-output.ts";
+import { nativeResultFields, saveStepRecord } from "./runner-step-record.ts";
+
+interface StepExecution {
+  readonly runner: RunnerAttempt;
+  readonly finalization: RunnerFinalization;
+  readonly initial: StepAttempt;
+  readonly attemptedModels: readonly string[];
+  readonly attemptNotes: readonly string[];
+  readonly acceptance: Awaited<ReturnType<typeof evaluateRunAcceptance>> | undefined;
+  readonly outcome: ReturnType<typeof resolveExecutionOutcome>;
+  readonly sessionFile?: string;
+}
+
+async function executePreparedStep(
+  prepared: PreparedRunnerStep,
+  ctx: ReadonlyDeep<SingleStepContext>,
+): Promise<StepExecution> {
+  const {
+    step,
+    interruptSignal,
+    verificationSignal,
+    structuredRuntime,
+    sessionDir,
+    sessionEnabled,
+  } = prepared;
+  const runner = new RunnerAttempt(step, ctx, {
+    interruptSignal,
+    verificationSignal,
+    effectiveStructuredOutput: structuredRuntime,
+    sessionEnabled,
+    sessionDir,
+  });
+  const candidates = step.modelCandidates;
+  const series = await runModelAttempts({
+    candidates: candidates !== undefined && candidates.length > 0 ? candidates : [step.model],
+    signal: verificationSignal,
+    runAttempt: (model) => runner.run(prepared.task, model),
+  });
+  const sessionFile =
+    step.sessionFile ??
+    (sessionDir !== undefined && sessionDir.length > 0
+      ? (findLatestSessionFile(sessionDir) ?? undefined)
+      : undefined);
+  const finalization = new RunnerFinalization(step, runner, series.result, {
+    sessionFile,
+    cwd: step.cwd ?? ctx.cwd,
+    signal: verificationSignal,
+    structuredRuntime,
+    modelAttempts: series.modelAttempts,
+  });
+  const acceptance = await finalization.evaluate();
+  const outcome = finalization.includePreviousFailure(
+    resolveExecutionOutcome({
+      result: finalization.execution,
+      acceptance,
+      signal: ctx.signal,
+      interruptSignal,
+    }),
+  );
+  return {
+    runner,
+    finalization,
+    initial: series.result,
+    attemptedModels: series.attemptedModels,
+    attemptNotes: series.notes,
+    acceptance,
+    outcome,
+    sessionFile,
+  };
+}
+
+/** Runs fallback attempts, acceptance review and output preservation in that order. */
+export async function runSingleStep(
+  input: RunnerSubagentStep,
+  ctx: ReadonlyDeep<SingleStepContext>,
+): Promise<RunSingleStepResult> {
+  const startedAt = Date.now();
+  if (ctx.signal?.aborted === true) {
+    return { agent: input.agent, output: "", exitCode: 1, error: "Subagent cancelled." };
+  }
+  const prepared = prepareRunnerStep(input, ctx);
+  const execution = await executePreparedStep(prepared, ctx);
+  const { initial, finalization, runner, attemptedModels, outcome, acceptance, sessionFile } =
+    execution;
+  const { step } = prepared;
+  const published = publishStepOutput(step, ctx, {
+    output: finalization.output,
+    acceptance,
+    resolvedOutput: finalization.resolvedOutput,
+    outcome,
+    attemptNotes: execution.attemptNotes,
+  });
+  const exitCode = outcome.exitCode ?? 1;
+  const usage = sumAttemptUsage(finalization.modelAttempts);
+  const progressSummary = {
+    toolCount: runner.toolCount,
+    tokens: usage.input + usage.output,
+    durationMs: Date.now() - startedAt,
+  };
+  const result: RunSingleStepResult = {
+    ...nativeResultFields(finalization.execution, finalization.modelAttempts),
+    agent: step.agent,
+    output: published.displayOutput,
+    exitCode,
+    error: outcome.error,
+    usage,
+    timedOut: outcome.timedOut,
+    task: step.task,
+    skills: step.skills,
+    ...stepOutputFields(step, published, {
+      acceptance,
+      initialOutput: finalization.initialOutput,
+      saveError: finalization.resolvedOutput.saveError,
+    }),
+    toolCalls: runner.toolCalls.length > 0 ? runner.toolCalls : undefined,
+    progressSummary,
+    sessionFile,
+    intercomTarget: ctx.childIntercomTarget,
+    model: initial.model,
+    attemptedModels: attemptedModels.length > 0 ? [...attemptedModels] : undefined,
+    modelAttempts: finalization.modelAttempts,
+    artifactPaths: prepared.artifactPaths,
+    interrupted: outcome.interrupted,
+    completionGuardTriggered: initial.completionGuardTriggered,
+    structuredOutput: finalization.structuredOutput,
+    structuredOutputPath: prepared.structuredRuntime?.outputPath,
+    structuredOutputSchemaPath: prepared.structuredRuntime?.schemaPath,
+    acceptance,
+    resourceLimitExceeded: outcome.resourceLimitExceeded,
+  };
+  recordRun(step.agent, step.task, exitCode, progressSummary.durationMs);
+  saveStepRecord(
+    result,
+    { runId: ctx.id, flatIndex: ctx.flatIndex, task: prepared.task, fullOutput: published.output },
+    prepared.artifactPaths,
+  );
+  return result;
+}

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

@@ -0,0 +1,220 @@
+import * as fs from "node:fs";
+import type { ReadonlyDeep } from "type-fest";
+import { appendJsonl } from "../../shared/artifacts.ts";
+import { readChildProcessIdentity } from "../../shared/post-exit-stdio-guard.ts";
+import { extractToolArgsPreview } from "../../shared/utils.ts";
+import {
+  runChildAttempt,
+  type ChildAttemptResult,
+  type ChildEvent,
+} from "../shared/child-attempt.ts";
+import { FINALIZATION_EVENT } from "../shared/native-finalization.ts";
+import { saveQuestionContract } from "../shared/supervisor-questions.ts";
+
+interface ChildEventContext {
+  readonly eventsPath: string;
+  readonly runId: string;
+  readonly stepIndex: number;
+  readonly agent: string;
+}
+
+// Durable records omit repetitive progress deltas, but the live consumer sees every event.
+const TRANSIENT_CHILD_EVENT_TYPES = new Set(["message_update", "tool_execution_update"]);
+
+interface BoundaryMarker {
+  readonly type: string;
+  readonly nonce: string;
+  readonly turn: number;
+  readonly lastEntryId?: string;
+  readonly messageCount: number;
+  readonly at: number;
+}
+
+function hasBoundaryIdentity(
+  value: object,
+): value is Pick<BoundaryMarker, "type" | "nonce" | "lastEntryId"> {
+  return (
+    "type" in value &&
+    value.type === FINALIZATION_EVENT &&
+    "nonce" in value &&
+    typeof value.nonce === "string" &&
+    (!("lastEntryId" in value) || typeof value.lastEntryId === "string")
+  );
+}
+
+function hasBoundaryCounters(
+  value: object,
+): value is Pick<BoundaryMarker, "turn" | "messageCount" | "at"> {
+  return (
+    "turn" in value &&
+    typeof value.turn === "number" &&
+    "messageCount" in value &&
+    typeof value.messageCount === "number" &&
+    "at" in value &&
+    typeof value.at === "number"
+  );
+}
+
+function isBoundaryMarker(value: unknown): value is BoundaryMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    hasBoundaryIdentity(value) &&
+    hasBoundaryCounters(value)
+  );
+}
+
+class ChildAudit {
+  private readonly context: ChildEventContext;
+  private readonly outputFile: string;
+
+  constructor(context: ChildEventContext, outputFile: string) {
+    this.context = context;
+    this.outputFile = outputFile;
+  }
+
+  append(event: Readonly<object>): void {
+    appendJsonl(
+      this.context.eventsPath,
+      JSON.stringify({
+        ...event,
+        recordVersion: 3,
+        subagentSource: "child",
+        subagentRunId: this.context.runId,
+        subagentStepIndex: this.context.stepIndex,
+        subagentAgent: this.context.agent,
+        observedAt: Date.now(),
+      }),
+    );
+  }
+
+  record(event: ReadonlyDeep<ChildEvent>, result: ReadonlyDeep<ChildAttemptResult>): void {
+    if (TRANSIENT_CHILD_EVENT_TYPES.has(event.type ?? "")) {
+      return;
+    }
+    if (event.type === "subagent.native_baseline") {
+      this.append(event);
+      saveQuestionContract(this.context.runId, this.context.stepIndex, {
+        attemptBaseline: result.attemptBaseline,
+        baselineSource: "native-migration",
+      });
+      return;
+    }
+    if (event.type === "subagent.native") {
+      this.append(event);
+      saveQuestionContract(this.context.runId, this.context.stepIndex, {
+        nativeSessionId: result.nativeSessionId,
+        terminalLeafId: result.terminalLeafId,
+        effectiveConfiguration: result.effectiveConfiguration,
+        updatedAt: Date.now(),
+      });
+      return;
+    }
+    if (isBoundaryMarker(event)) {
+      const file = `${this.outputFile}.boundaries.jsonl`;
+      fs.appendFileSync(file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+      this.append({
+        type: event.type,
+        nonce: event.nonce,
+        turn: event.turn,
+        lastEntryId: event.lastEntryId,
+        messageCount: event.messageCount,
+        at: event.at,
+        boundaryFile: file,
+      });
+      return;
+    }
+    this.append({
+      type: event.type,
+      messageNumber: result.messageCount,
+      ...(event.message ? { role: event.message.role, timestamp: event.message.timestamp } : {}),
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      isError: event.isError,
+      ...(event.type === "tool_execution_start"
+        ? { argsPreview: extractToolArgsPreview(event.args ?? {}) }
+        : {}),
+      ...(event.type === "tool_execution_end" ? { auditPath: `${this.outputFile}.audit.log` } : {}),
+    });
+  }
+
+  finalized(result: ReadonlyDeep<ChildAttemptResult>): void {
+    this.append({
+      type: "subagent.child.finalized",
+      agentProcessExit: result.agentProcessExit,
+      exitCode: result.exitCode,
+      accounting: result.accounting,
+      nativeSessionId: result.nativeSessionId,
+      terminalLeafId: result.terminalLeafId,
+      terminalEntryId: result.terminalEntryId,
+      nativeReferences: result.nativeReferences,
+      auditPath: result.auditPath,
+      auditRecords: result.auditRecords,
+      auditSaveError: result.auditSaveError,
+      outputFile: this.outputFile,
+    });
+    saveQuestionContract(this.context.runId, this.context.stepIndex, {
+      nativeSessionId: result.nativeSessionId,
+      terminalLeafId: result.terminalLeafId,
+      terminalEntryId: result.terminalEntryId,
+      effectiveConfiguration: result.effectiveConfiguration,
+      accounting: result.accounting,
+      auditPath: result.auditPath,
+      updatedAt: Date.now(),
+    });
+  }
+}
+
+export async function runPiStreaming(
+  options: Parameters<typeof runChildAttempt>[0],
+  outputFile: string,
+  context: ChildEventContext,
+): Promise<ChildAttemptResult> {
+  const outputFd = fs.openSync(outputFile, "w", 0o600);
+  const audit = new ChildAudit(context, outputFile);
+  let outputWritten = false;
+  try {
+    const result = await runChildAttempt({
+      ...options,
+      auditPath: `${outputFile}.audit.log`,
+      onStart: (control, started) => {
+        if (control.pid !== undefined && control.pid !== 0) {
+          saveQuestionContract(context.runId, context.stepIndex, {
+            pid: control.pid,
+            processIdentity: readChildProcessIdentity(control.pid),
+            sessionFile: options.sessionFile,
+            attemptBaseline: started.attemptBaseline,
+            updatedAt: Date.now(),
+          });
+        }
+        options.onStart?.(control, started);
+      },
+      onOutput: (text) => {
+        fs.writeFileSync(outputFd, text);
+        outputWritten ||= text.length > 0;
+      },
+      onStderr: (text) => {
+        audit.append({
+          type: "subagent.child.stderr",
+          auditPath: `${outputFile}.audit.log`,
+          length: Buffer.byteLength(text),
+        });
+      },
+      onEvent: (event, observed, mutation) => {
+        // Preserve callback ordering: disk publication follows the live owner update.
+        options.onEvent?.(event, observed, mutation);
+        audit.record(event, observed);
+      },
+    });
+    // Native recovery and non-streaming providers can finalize text without publishing deltas.
+    // onOutput can change outputWritten while the child attempt is awaiting stream completion.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
+    if (!outputWritten && result.finalOutput.length > 0) {
+      fs.writeFileSync(outputFd, `${result.finalOutput}\n`);
+    }
+    audit.finalized(result);
+    return result;
+  } finally {
+    fs.closeSync(outputFd);
+  }
+}