@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/dist/runs/shared/acceptance-reports.js

@@ -1,36 +1,65 @@
+import { isRecord, isUnknownArray, errorMessage } from "../../shared/unknown.js";
 // Open finding objects are intentional: native strict conversion must fall back,
 // rather than discarding caller-defined review evidence.
 export const ACCEPTANCE_REPORT_SCHEMA = {
     type: "object",
     properties: {
-        criteriaSatisfied: { type: "array", items: {
-                type: "object", properties: {
+        criteriaSatisfied: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
                     id: { type: "string" },
-                    status: { type: "string", enum: ["satisfied", "not-satisfied", "not-applicable", "blocked"] },
+                    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" } } }, then: { required: ["humanAction"], properties: { humanAction: { pattern: "\\S" } } },
-            } },
+                },
+                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"],
-            } },
+        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 }] } },
+        reviewFindings: {
+            type: "array",
+            items: {
+                anyOf: [
+                    { type: "string" },
+                    { type: "object", minProperties: 1, additionalProperties: true },
+                ],
+            },
+        },
         manualNotes: { type: "string" },
         notes: { type: "string" },
     },
 };
 export function formatAcceptanceReportExample(nativeReport = false) {
     const report = {
-        criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" }],
+        criteriaSatisfied: [
+            { id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" },
+        ],
         changedFiles: [],
         testsAddedOrUpdated: [],
         commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
@@ -47,101 +76,137 @@ export function formatAcceptanceReportExample(nativeReport = false) {
 export function parseAcceptanceReport(output) {
     const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
         .map((match) => match[1]?.trim())
-        .filter((value) => Boolean(value));
+        .filter((value) => typeof value === "string" && value.length > 0);
     const parseErrors = [];
     for (const body of fenced) {
         try {
             const parsed = JSON.parse(body);
-            const report = (parsed && typeof parsed === "object" && "acceptance" in parsed)
+            const report = parsed !== null && typeof parsed === "object" && "acceptance" in parsed
                 ? parsed.acceptance
                 : parsed;
             const shapeError = validateAcceptanceReportShape(report);
-            if (!shapeError)
-                return { report: report };
-            parseErrors.push(`acceptance-report block is invalid: ${shapeError}`);
+            if (isAcceptanceReport(report)) {
+                return { report };
+            }
+            parseErrors.push(`acceptance-report block is invalid: ${shapeError ?? "unrecognized report"}`);
         }
         catch (error) {
-            parseErrors.push(error instanceof Error ? error.message : String(error));
+            parseErrors.push(errorMessage(error));
         }
     }
-    if (parseErrors.length > 0)
+    if (parseErrors.length > 0) {
         return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+    }
     return { error: "Structured acceptance report not found." };
 }
 export function stripAcceptanceReport(output) {
-    return output
-        .replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
-        .trimEnd();
+    return output.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "").trimEnd();
 }
 function isStringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+    return isUnknownArray(value) && value.every((item) => typeof item === "string");
 }
 function isCriterionReport(value) {
-    if (!isPlainObject(value))
+    if (!isRecord(value)) {
         return false;
+    }
     const criterion = value;
-    if (criterion.id !== undefined && typeof criterion.id !== "string")
+    if (criterion.id !== undefined && typeof criterion.id !== "string") {
         return false;
-    if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable" && criterion.status !== "blocked")
+    }
+    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()))
+    }
+    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) {
-    if (!isPlainObject(value))
+    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";
+    return (typeof command.command === "string" &&
+        (command.result === "passed" || command.result === "failed" || command.result === "not-run") &&
+        typeof command.summary === "string");
 }
 function isReviewFinding(value) {
-    if (typeof value === "string")
+    if (typeof value === "string") {
         return true;
-    if (!isPlainObject(value))
+    }
+    if (!isRecord(value)) {
         return false;
+    }
     const values = Object.values(value);
-    return values.length > 0 && values.some((item) => typeof item === "string" && item.trim().length > 0);
+    return values.some((item) => typeof item === "string" && item.trim().length > 0);
 }
+export function isAcceptanceReport(value) {
+    return validateAcceptanceReportShape(value) === undefined;
+}
+function everyArrayItem(value, valid) {
+    return isUnknownArray(value) && value.every(valid);
+}
+const REPORT_FIELDS = [
+    {
+        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) {
-    if (!isPlainObject(value))
+    if (!isRecord(value)) {
         return "acceptance report must be a JSON object";
-    const report = value;
-    if (report.criteriaSatisfied !== undefined && (!Array.isArray(report.criteriaSatisfied) || !report.criteriaSatisfied.every(isCriterionReport)))
-        return "criteriaSatisfied must be an array of {id?, status, evidence} objects";
-    if (report.changedFiles !== undefined && !isStringArray(report.changedFiles))
-        return "changedFiles must be an array of strings";
-    if (report.testsAddedOrUpdated !== undefined && !isStringArray(report.testsAddedOrUpdated))
-        return "testsAddedOrUpdated must be an array of strings";
-    if (report.commandsRun !== undefined && (!Array.isArray(report.commandsRun) || !report.commandsRun.every(isCommandReport)))
-        return "commandsRun must be an array of {command, result, summary} objects with result passed, failed, or not-run";
-    if (report.validationOutput !== undefined && !isStringArray(report.validationOutput))
-        return "validationOutput must be an array of strings";
-    if (report.residualRisks !== undefined && !isStringArray(report.residualRisks))
-        return "residualRisks must be an array of strings";
-    if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean")
-        return "noStagedFiles must be a boolean";
-    if (report.diffSummary !== undefined && typeof report.diffSummary !== "string")
-        return "diffSummary must be a string";
-    if (report.reviewFindings !== undefined && (!Array.isArray(report.reviewFindings) || !report.reviewFindings.every(isReviewFinding)))
-        return "reviewFindings must be an array of strings or non-empty objects with at least one string value";
-    if (report.manualNotes !== undefined && typeof report.manualNotes !== "string")
-        return "manualNotes must be a string";
-    if (report.notes !== undefined && typeof report.notes !== "string")
-        return "notes must be a string";
-    const hasReportField = report.criteriaSatisfied !== undefined
-        || report.changedFiles !== undefined
-        || report.testsAddedOrUpdated !== undefined
-        || report.commandsRun !== undefined
-        || report.validationOutput !== undefined
-        || report.residualRisks !== undefined
-        || report.noStagedFiles !== undefined
-        || report.diffSummary !== undefined
-        || report.manualNotes !== undefined
-        || report.reviewFindings !== undefined;
+    }
+    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/dist/runs/shared/acceptance-submission.js

@@ -0,0 +1,167 @@
+import { isDeepStrictEqual } from "node:util";
+import { createStructuredOutputRuntime, readStructuredOutput, validateStructuredOutputValue, } from "./structured-output.js";
+import { ACCEPTANCE_REPORT_SCHEMA, isAcceptanceReport, parseAcceptanceReport, } from "./acceptance-reports.js";
+export function createFinalizationReportRuntime(publicOutputSchema) {
+    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, publicOutputSchema) {
+    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, report, schema) {
+    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) {
+    return submission.report && !parseAcceptanceReport(submission.output).report
+        ? `${submission.output}\n\n\`\`\`acceptance-report\n${JSON.stringify(submission.report)}\n\`\`\``
+        : submission.output;
+}
+function toolResultSucceeded(result) {
+    return result.isError === false;
+}
+function successfulStructuredIds(messages) {
+    return new Set(messages.flatMap((message) => message.role === "toolResult" &&
+        message.toolName === "structured_output" &&
+        toolResultSucceeded(message)
+        ? [message.toolCallId]
+        : []));
+}
+function auditSubmission(value, runtime) {
+    const previous = readReportValue(value, runtime.publicOutputSchema);
+    return previous && validateStructuredOutputValue(runtime.schema, value).status === "valid"
+        ? reportAuditOutput(previous)
+        : undefined;
+}
+function previousAuditOutput(messages, runtime, submitted) {
+    const successfulIds = successfulStructuredIds(messages);
+    let retained = submitted ? reportAuditOutput(submitted) : undefined;
+    for (const message of messages) {
+        if (message.role !== "assistant") {
+            continue;
+        }
+        const content = 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 = call.arguments.value;
+            retained = auditSubmission(value, runtime) ?? retained;
+        }
+    }
+    return retained;
+}
+function latestSubmissionError(messages, call, index) {
+    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) {
+    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, messages, index, captured) {
+    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, runtime, options = {}) {
+    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) => ({
+        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/dist/runs/shared/acceptance-verification.js

@@ -0,0 +1,100 @@
+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.js";
+const MAX_VERIFY_OUTPUT_CHARS = 12_000;
+class VerifyOutput {
+    value = "";
+    truncated = false;
+    append(chunk) {
+        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() {
+        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, timedOut, cancelled, allowFailure) {
+    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, defaultCwd, signal) {
+    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) => {
+            stdout.append(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            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,
+            });
+        });
+    });
+}