@fitchmultz/pi-subagents 0.49.0 → 0.50.0

package/src/runs/shared/acceptance-reports.ts

@@ -1,246 +0,0 @@
-import { isRecord, isUnknownArray, errorMessage } from "../../shared/unknown.ts";
-import type { AcceptanceReport, JsonSchemaObject } from "../../shared/types.ts";
-
-// Open finding objects are intentional: native strict conversion must fall back,
-// rather than discarding caller-defined review evidence.
-export const ACCEPTANCE_REPORT_SCHEMA: JsonSchemaObject = {
-  type: "object",
-  properties: {
-    criteriaSatisfied: {
-      type: "array",
-      items: {
-        type: "object",
-        properties: {
-          id: { type: "string" },
-          status: {
-            type: "string",
-            enum: ["satisfied", "not-satisfied", "not-applicable", "blocked"],
-          },
-          evidence: { type: "string", pattern: "\\S" },
-          humanAction: { type: "string" },
-        },
-        required: ["status", "evidence"],
-        if: { properties: { status: { const: "blocked" } } },
-        // JSON Schema's conditional vocabulary is noncallable data, not a Promise thenable.
-        // oxlint-disable-next-line unicorn/no-thenable
-        then: { required: ["humanAction"], properties: { humanAction: { pattern: "\\S" } } },
-      },
-    },
-    changedFiles: { type: "array", items: { type: "string" } },
-    testsAddedOrUpdated: { type: "array", items: { type: "string" } },
-    commandsRun: {
-      type: "array",
-      items: {
-        type: "object",
-        properties: {
-          command: { type: "string" },
-          result: { type: "string", enum: ["passed", "failed", "not-run"] },
-          summary: { type: "string" },
-        },
-        required: ["command", "result", "summary"],
-      },
-    },
-    validationOutput: { type: "array", items: { type: "string" } },
-    residualRisks: { type: "array", items: { type: "string" } },
-    noStagedFiles: { type: "boolean" },
-    diffSummary: { type: "string" },
-    reviewFindings: {
-      type: "array",
-      items: {
-        anyOf: [
-          { type: "string" },
-          { type: "object", minProperties: 1, additionalProperties: true },
-        ],
-      },
-    },
-    manualNotes: { type: "string" },
-    notes: { type: "string" },
-  },
-};
-
-export function formatAcceptanceReportExample(nativeReport = false): string {
-  const report: AcceptanceReport = {
-    criteriaSatisfied: [
-      { id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" },
-    ],
-    changedFiles: [],
-    testsAddedOrUpdated: [],
-    commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
-    validationOutput: [],
-    residualRisks: [],
-    noStagedFiles: true,
-    diffSummary: "concise summary of changed behavior and important files",
-    reviewFindings: [],
-    manualNotes: "manual notes or external evidence, if any",
-    notes: "self-review summary and remaining work",
-  };
-  return `\`\`\`${nativeReport ? "json" : "acceptance-report"}\n${JSON.stringify(nativeReport ? { value: { answer: "Complete standalone final answer with all requested handoff details", report } } : report, null, 2)}\n\`\`\``;
-}
-
-export function parseAcceptanceReport(output: string): {
-  report?: AcceptanceReport;
-  error?: string;
-} {
-  const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
-    .map((match) => match[1]?.trim())
-    .filter((value) => typeof value === "string" && value.length > 0);
-  const parseErrors: string[] = [];
-  for (const body of fenced) {
-    try {
-      const parsed = JSON.parse(body) as unknown;
-      const report =
-        parsed !== null && typeof parsed === "object" && "acceptance" in parsed
-          ? parsed.acceptance
-          : parsed;
-      const shapeError = validateAcceptanceReportShape(report);
-      if (isAcceptanceReport(report)) {
-        return { report };
-      }
-      parseErrors.push(
-        `acceptance-report block is invalid: ${shapeError ?? "unrecognized report"}`,
-      );
-    } catch (error) {
-      parseErrors.push(errorMessage(error));
-    }
-  }
-  if (parseErrors.length > 0) {
-    return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
-  }
-  return { error: "Structured acceptance report not found." };
-}
-
-export function stripAcceptanceReport(output: string): string {
-  return output.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "").trimEnd();
-}
-
-function isStringArray(value: unknown): boolean {
-  return isUnknownArray(value) && value.every((item) => typeof item === "string");
-}
-
-function isCriterionReport(value: unknown): boolean {
-  if (!isRecord(value)) {
-    return false;
-  }
-  const criterion = value;
-  if (criterion.id !== undefined && typeof criterion.id !== "string") {
-    return false;
-  }
-  if (
-    typeof criterion.status !== "string" ||
-    !["satisfied", "not-satisfied", "not-applicable", "blocked"].includes(criterion.status)
-  ) {
-    return false;
-  }
-  if (
-    criterion.status === "blocked" &&
-    (typeof criterion.humanAction !== "string" || criterion.humanAction.trim().length === 0)
-  ) {
-    return false;
-  }
-  return typeof criterion.evidence === "string" && criterion.evidence.trim().length > 0;
-}
-
-function isCommandReport(value: unknown): boolean {
-  if (!isRecord(value)) {
-    return false;
-  }
-  const command = value;
-  return (
-    typeof command.command === "string" &&
-    (command.result === "passed" || command.result === "failed" || command.result === "not-run") &&
-    typeof command.summary === "string"
-  );
-}
-
-function isReviewFinding(value: unknown): boolean {
-  if (typeof value === "string") {
-    return true;
-  }
-  if (!isRecord(value)) {
-    return false;
-  }
-  const values = Object.values(value);
-  return values.some((item) => typeof item === "string" && item.trim().length > 0);
-}
-
-export function isAcceptanceReport(value: unknown): value is AcceptanceReport {
-  return validateAcceptanceReportShape(value) === undefined;
-}
-
-interface ReportField {
-  readonly key: keyof AcceptanceReport;
-  readonly valid: (value: unknown) => boolean;
-  readonly error: string;
-}
-
-function everyArrayItem(value: unknown, valid: (item: unknown) => boolean): boolean {
-  return isUnknownArray(value) && value.every(valid);
-}
-
-const REPORT_FIELDS: readonly ReportField[] = [
-  {
-    key: "criteriaSatisfied",
-    valid: (value) => everyArrayItem(value, isCriterionReport),
-    error: "criteriaSatisfied must be an array of {id?, status, evidence} objects",
-  },
-  { key: "changedFiles", valid: isStringArray, error: "changedFiles must be an array of strings" },
-  {
-    key: "testsAddedOrUpdated",
-    valid: isStringArray,
-    error: "testsAddedOrUpdated must be an array of strings",
-  },
-  {
-    key: "commandsRun",
-    valid: (value) => everyArrayItem(value, isCommandReport),
-    error:
-      "commandsRun must be an array of {command, result, summary} objects with result passed, failed, or not-run",
-  },
-  {
-    key: "validationOutput",
-    valid: isStringArray,
-    error: "validationOutput must be an array of strings",
-  },
-  {
-    key: "residualRisks",
-    valid: isStringArray,
-    error: "residualRisks must be an array of strings",
-  },
-  {
-    key: "noStagedFiles",
-    valid: (value) => typeof value === "boolean",
-    error: "noStagedFiles must be a boolean",
-  },
-  {
-    key: "diffSummary",
-    valid: (value) => typeof value === "string",
-    error: "diffSummary must be a string",
-  },
-  {
-    key: "reviewFindings",
-    valid: (value) => everyArrayItem(value, isReviewFinding),
-    error:
-      "reviewFindings must be an array of strings or non-empty objects with at least one string value",
-  },
-  {
-    key: "manualNotes",
-    valid: (value) => typeof value === "string",
-    error: "manualNotes must be a string",
-  },
-  { key: "notes", valid: (value) => typeof value === "string", error: "notes must be a string" },
-];
-
-export function validateAcceptanceReportShape(value: unknown): string | undefined {
-  if (!isRecord(value)) {
-    return "acceptance report must be a JSON object";
-  }
-  for (const field of REPORT_FIELDS) {
-    const entry = value[field.key];
-    if (entry !== undefined && !field.valid(entry)) {
-      return field.error;
-    }
-  }
-  const hasReportField = REPORT_FIELDS.some(
-    (field) => field.key !== "notes" && value[field.key] !== undefined,
-  );
-  return hasReportField ? undefined : "acceptance report must include at least one report field";
-}

package/src/runs/shared/acceptance-submission.ts

@@ -1,251 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import {
-  createStructuredOutputRuntime,
-  readStructuredOutput,
-  validateStructuredOutputValue,
-  type StructuredOutputRuntime,
-} from "./structured-output.ts";
-import type {
-  AcceptanceReport,
-  JsonSchemaObject,
-  ReadonlyInput,
-  ObservedMessage,
-  ObservedContent,
-} from "../../shared/types.ts";
-import {
-  ACCEPTANCE_REPORT_SCHEMA,
-  isAcceptanceReport,
-  parseAcceptanceReport,
-} from "./acceptance-reports.ts";
-
-type ObservedAssistant = Extract<ObservedMessage, { readonly role: "assistant" }>;
-type ObservedToolCall = Extract<ObservedContent, { readonly type: "toolCall" }>;
-
-export type FinalizationReportRuntime = ReadonlyInput<StructuredOutputRuntime> & {
-  readonly publicOutputSchema?: JsonSchemaObject;
-};
-export interface FinalizationReportSubmission {
-  readonly output: string;
-  readonly structuredOutput?: unknown;
-  readonly report?: AcceptanceReport;
-  readonly reportSubmissionError?: string;
-  readonly unconfirmedOutput?: string;
-}
-
-export function createFinalizationReportRuntime(
-  publicOutputSchema?: JsonSchemaObject,
-): FinalizationReportRuntime {
-  const runtime = createStructuredOutputRuntime({
-    type: "object",
-    properties: {
-      // Resource-local references, including recursive '#', stay scoped to the public answer.
-      answer: publicOutputSchema
-        ? { $id: "urn:pi-subagents:public-output", ...publicOutputSchema }
-        : {
-            type: "string",
-            pattern: "\\S",
-            description:
-              "Complete standalone final answer, including every requested handoff detail.",
-          },
-      report: ACCEPTANCE_REPORT_SCHEMA,
-    },
-    required: ["answer", "report"],
-    additionalProperties: false,
-  });
-  return { ...runtime, publicOutputSchema };
-}
-
-function readReportValue(
-  value: unknown,
-  publicOutputSchema?: JsonSchemaObject,
-): (FinalizationReportSubmission & { report: AcceptanceReport }) | undefined {
-  if (value === null || typeof value !== "object") {
-    return undefined;
-  }
-  // Legacy runtimes retain their original string schema.
-  if (publicOutputSchema === undefined && "report" in value && typeof value.report === "string") {
-    const parsed = parseAcceptanceReport(value.report);
-    if (parsed.report) {
-      return { output: value.report, report: parsed.report };
-    }
-  }
-  if (!("answer" in value) || !("report" in value) || !isAcceptanceReport(value.report)) {
-    return undefined;
-  }
-  return readAnswer(value.answer, value.report, publicOutputSchema);
-}
-
-function readAnswer(
-  answer: unknown,
-  report: AcceptanceReport,
-  schema?: JsonSchemaObject,
-): (FinalizationReportSubmission & { report: AcceptanceReport }) | undefined {
-  if (schema) {
-    if (validateStructuredOutputValue(schema, answer).status === "invalid") {
-      return undefined;
-    }
-    return { output: JSON.stringify(answer), structuredOutput: answer, report };
-  }
-  if (typeof answer !== "string" || answer.trim().length === 0) {
-    return undefined;
-  }
-  return { output: answer, report };
-}
-
-export function reportAuditOutput(submission: {
-  readonly output: string;
-  readonly report?: AcceptanceReport;
-}): string {
-  return submission.report && !parseAcceptanceReport(submission.output).report
-    ? `${submission.output}\n\n\`\`\`acceptance-report\n${JSON.stringify(submission.report)}\n\`\`\``
-    : submission.output;
-}
-
-function toolResultSucceeded(result: { readonly isError?: unknown }): boolean {
-  return result.isError === false;
-}
-
-function successfulStructuredIds(messages: readonly ObservedMessage[]): Set<string> {
-  return new Set(
-    messages.flatMap((message) =>
-      message.role === "toolResult" &&
-      message.toolName === "structured_output" &&
-      toolResultSucceeded(message)
-        ? [message.toolCallId]
-        : [],
-    ),
-  );
-}
-
-function auditSubmission(value: unknown, runtime: FinalizationReportRuntime): string | undefined {
-  const previous = readReportValue(value, runtime.publicOutputSchema);
-  return previous && validateStructuredOutputValue(runtime.schema, value).status === "valid"
-    ? reportAuditOutput(previous)
-    : undefined;
-}
-
-function previousAuditOutput(
-  messages: readonly ObservedMessage[],
-  runtime: FinalizationReportRuntime,
-  submitted: FinalizationReportSubmission | undefined,
-): string | undefined {
-  const successfulIds = successfulStructuredIds(messages);
-  let retained = submitted ? reportAuditOutput(submitted) : undefined;
-  for (const message of messages) {
-    if (message.role !== "assistant") {
-      continue;
-    }
-    const content: readonly ObservedContent[] = message.content;
-    if (!Array.isArray(message.content)) {
-      continue;
-    }
-    for (const call of content) {
-      if (
-        call.type !== "toolCall" ||
-        call.name !== "structured_output" ||
-        !successfulIds.has(call.id)
-      ) {
-        continue;
-      }
-      const value: unknown = call.arguments.value;
-      retained = auditSubmission(value, runtime) ?? retained;
-    }
-  }
-  return retained;
-}
-
-function latestSubmissionError(
-  messages: readonly ObservedMessage[],
-  call: ObservedToolCall,
-  index: number,
-): string | undefined {
-  const result = messages
-    .slice(index + 1)
-    .findLast((message) => message.role === "toolResult" && message.toolCallId === call.id);
-  if (
-    result?.role !== "toolResult" ||
-    result.toolName !== "structured_output" ||
-    !toolResultSucceeded(result)
-  ) {
-    return "the latest structured_output call has no matching successful result.";
-  }
-  return undefined;
-}
-
-function latestAssistant(
-  messages: readonly ObservedMessage[],
-): { message: ObservedAssistant; index: number } | undefined {
-  const index = messages.findLastIndex((message) => message.role === "assistant");
-  const last = Object.hasOwn(messages, index) ? messages[index] : undefined;
-  if (
-    last?.role !== "assistant" ||
-    (last.errorMessage ?? "").length > 0 ||
-    (last.stopReason !== "stop" && last.stopReason !== "toolUse") ||
-    !Array.isArray(last.content)
-  ) {
-    return undefined;
-  }
-  return { message: last, index };
-}
-
-function currentToolSubmissionError(
-  last: ObservedAssistant,
-  messages: readonly ObservedMessage[],
-  index: number,
-  captured: { readonly value?: unknown; readonly error?: string },
-): string | undefined {
-  const calls = last.content.filter((part) => part.type === "toolCall");
-  const call = calls.length > 0 ? calls[0] : undefined;
-  if (calls.length !== 1 || call?.name !== "structured_output") {
-    return "the latest assistant turn must submit structured_output as its only tool call.";
-  }
-  const error = latestSubmissionError(messages, call, index);
-  if (error !== undefined) {
-    return error;
-  }
-  if (captured.error !== undefined) {
-    return captured.error;
-  }
-  if (!isDeepStrictEqual(captured.value, call.arguments.value)) {
-    return "the capture does not match the latest submission.";
-  }
-  return undefined;
-}
-
-/** The current attempt's terminal assistant and its actual successful tool result authorize publication. */
-export function readFinalizationReport(
-  messages: readonly ObservedMessage[],
-  runtime: FinalizationReportRuntime,
-  options: { readonly messageOffset?: number; readonly structuredResult?: boolean } = {},
-): FinalizationReportSubmission {
-  const currentMessages = messages.slice(options.messageOffset ?? 0);
-  const captured = readStructuredOutput(runtime);
-  const submitted = readReportValue(captured.value, runtime.publicOutputSchema);
-  const unconfirmedOutput = previousAuditOutput(currentMessages, runtime, submitted);
-  const rejected = (reason: string): FinalizationReportSubmission => ({
-    output: "",
-    reportSubmissionError: `No current finalization report: ${reason}`,
-    unconfirmedOutput,
-  });
-  const latest = latestAssistant(currentMessages);
-  if (!latest) {
-    return rejected("the latest assistant turn did not finish successfully.");
-  }
-  // Claude Code's terminal result is schema-constrained rather than a Pi tool call.
-  if (options.structuredResult === true) {
-    if (captured.error !== undefined) {
-      return rejected(captured.error);
-    }
-    return submitted
-      ? { ...submitted, unconfirmedOutput }
-      : rejected("the submission must contain a complete answer and a valid acceptance report.");
-  }
-  const error = currentToolSubmissionError(latest.message, currentMessages, latest.index, captured);
-  if (error !== undefined) {
-    return rejected(error);
-  }
-  if (!submitted) {
-    return rejected("the submission must contain a complete answer and a valid acceptance report.");
-  }
-  return { ...submitted, unconfirmedOutput };
-}

package/src/runs/shared/acceptance-verification.ts

@@ -1,118 +0,0 @@
-import { spawn } from "node:child_process";
-import { addAbortListener } from "node:events";
-import * as path from "node:path";
-import { attachChildProcessLifecycle } from "../../shared/post-exit-stdio-guard.ts";
-import type {
-  AcceptanceVerifyCommand,
-  AcceptanceVerifyResult,
-} from "../../shared/types/acceptance.ts";
-
-const MAX_VERIFY_OUTPUT_CHARS = 12_000;
-class VerifyOutput {
-  private value = "";
-  private truncated = false;
-  append(chunk: Buffer): void {
-    const text = chunk.toString();
-    const remaining = Math.max(0, MAX_VERIFY_OUTPUT_CHARS - this.value.length);
-    this.value += text.slice(0, remaining);
-    this.truncated ||= text.length > remaining;
-  }
-  read(): string | undefined {
-    const trimmed = this.value.trim();
-    if (trimmed.length === 0 && !this.truncated) {
-      return undefined;
-    }
-    return this.truncated ? `${trimmed}${trimmed.length > 0 ? "\n" : ""}...[truncated]` : trimmed;
-  }
-}
-
-function verifyStatus(
-  exitCode: number | null,
-  timedOut: boolean,
-  cancelled: boolean,
-  allowFailure: boolean,
-): AcceptanceVerifyResult["status"] {
-  if (cancelled) {
-    return "failed";
-  }
-  if (timedOut) {
-    return "timed-out";
-  }
-  if (exitCode === 0) {
-    return "passed";
-  }
-  return allowFailure ? "allowed-failure" : "failed";
-}
-
-/** Owns the verification child, tree termination, output bounds, listeners and timer through close. */
-export function runVerifyCommand(
-  command: AcceptanceVerifyCommand,
-  defaultCwd: string,
-  signal?: AbortSignal,
-): Promise<AcceptanceVerifyResult> {
-  return new Promise((resolve) => {
-    const startedAt = Date.now();
-    const cwd =
-      command.cwd !== undefined && command.cwd.length > 0
-        ? path.resolve(defaultCwd, command.cwd)
-        : defaultCwd;
-    const stdout = new VerifyOutput();
-    const stderr = new VerifyOutput();
-    let timedOut = false;
-    let cancelled = false;
-    const child = spawn(command.command, {
-      cwd,
-      env: { ...process.env, ...command.env },
-      shell: true,
-      stdio: ["ignore", "pipe", "pipe"],
-      detached: true,
-    });
-    const lifecycle = attachChildProcessLifecycle(child);
-    const abortListener =
-      signal &&
-      addAbortListener(signal, () => {
-        cancelled = true;
-        lifecycle.terminate();
-      });
-    const timeout = setTimeout(() => {
-      timedOut = true;
-      lifecycle.terminate();
-    }, command.timeoutMs ?? 120_000);
-    timeout.unref();
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout.append(chunk);
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr.append(chunk);
-    });
-    const cleanup = () => {
-      clearTimeout(timeout);
-      abortListener?.[Symbol.dispose]();
-    };
-    child.on("close", (exitCode) => {
-      cleanup();
-      resolve({
-        id: command.id,
-        command: command.command,
-        cwd,
-        exitCode,
-        status: verifyStatus(exitCode, timedOut, cancelled, command.allowFailure === true),
-        stdout: stdout.read(),
-        stderr: cancelled ? "Verification cancelled." : stderr.read(),
-        durationMs: Date.now() - startedAt,
-      });
-    });
-    child.on("error", (error) => {
-      cleanup();
-      resolve({
-        id: command.id,
-        command: command.command,
-        cwd,
-        exitCode: 1,
-        status: command.allowFailure === true ? "allowed-failure" : "failed",
-        stderr: error.message,
-        durationMs: Date.now() - startedAt,
-      });
-    });
-  });
-}

package/src/runs/shared/acceptance.ts

@@ -1,31 +0,0 @@
-export {
-  acceptanceInputFromResolved,
-  acceptanceSelfReviewConfig,
-  formatAcceptancePrompt,
-  resolveEffectiveAcceptance,
-  shouldRunAcceptanceFinalization,
-  validateAcceptanceInput,
-} from "./acceptance-contract.ts";
-export {
-  parseAcceptanceReport,
-  validateAcceptanceReportShape,
-  stripAcceptanceReport,
-} from "./acceptance-reports.ts";
-export {
-  acceptanceFailureMessage,
-  acceptanceHumanAction,
-  evaluateAcceptance,
-  evaluateAcceptanceReport,
-} from "./acceptance-evaluation.ts";
-export {
-  buildFinalizationProcessFailureLedger,
-  createFinalizationProcessFailureTurn,
-  createFinalizationReportRuntime,
-  type FinalizationReportSubmission,
-  readFinalizationReport,
-  formatUnconfirmedFinalizationOutput,
-  formatAcceptanceFinalizationPrompt,
-  evaluateRunAcceptance,
-  resolveExecutionOutcome,
-  resolveFinalizationOutput,
-} from "./acceptance-finalization.ts";