@fitchmultz/pi-subagents 0.44.7 → 0.45.0

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

@@ -1,7 +1,8 @@
+import { isRecord, isUnknownArray, recordAt } from "../../shared/unknown.js";
 import { Compile } from "../../shared/native-typebox.js";
 import { AcceptanceOverride } from "../../extension/schemas.js";
 import { formatAcceptanceReportExample } from "./acceptance-reports.js";
-const DEFAULT_FINALIZATION_MAX_TURNS = 3;
+import { DEFAULT_FINALIZATION_MAX_TURNS } from "./acceptance-defaults.js";
 const MAX_FINALIZATION_TURNS = 10;
 const VALID_EVIDENCE = new Set([
     "changed-files",
@@ -14,7 +15,7 @@ const VALID_EVIDENCE = new Set([
     "review-findings",
     "manual-notes",
 ]);
-const ACCEPTANCE_KEYS = new Set(Object.keys(AcceptanceOverride.properties));
+const ACCEPTANCE_KEYS = new Set(Object.keys(recordAt(AcceptanceOverride, "properties") ?? {}));
 const REMOVED_ACCEPTANCE_KEYS = new Set(["level", "finalization", "reason", "review"]);
 const ACCEPTANCE_VALIDATOR = Compile(AcceptanceOverride);
 const EVIDENCE_REPORT_FIELDS = {
@@ -32,123 +33,188 @@ export function formatEvidenceReportFieldMapping(evidence) {
     return evidence.map((kind) => `- ${kind} -> ${EVIDENCE_REPORT_FIELDS[kind]}`);
 }
 function hasArrayItems(value) {
-    return Array.isArray(value) && value.length > 0;
+    return isUnknownArray(value) && value.length > 0;
 }
 function acceptanceErrorPath(pathLabel, instancePath) {
-    return instancePath.split("/").slice(1).reduce((result, part) => {
+    return instancePath
+        .split("/")
+        .slice(1)
+        .reduce((result, part) => {
         const decoded = part.replaceAll("~1", "/").replaceAll("~0", "~");
         return /^\d+$/.test(decoded) ? `${result}[${decoded}]` : `${result}.${decoded}`;
     }, pathLabel);
 }
-export function validateAcceptanceInput(input, pathLabel = "acceptance") {
-    if (input === undefined)
-        return [];
-    if (input === false || typeof input === "string") {
-        return [`${pathLabel} must be an object. Public acceptance levels and false disables are no longer supported.`];
-    }
-    if (!input || typeof input !== "object" || Array.isArray(input))
-        return [`${pathLabel} must be an object.`];
-    const value = input;
+function unsupportedAcceptanceFields(value, pathLabel) {
     const errors = [];
-    if (Object.hasOwn(value, "level"))
+    if (Object.hasOwn(value, "level")) {
         errors.push(`${pathLabel}.level is no longer supported; configure criteria, evidence, and verify directly.`);
-    if (Object.hasOwn(value, "review"))
+    }
+    if (Object.hasOwn(value, "review")) {
         errors.push(`${pathLabel}.review is not supported; launch a separate parent-controlled reviewer after the worker completes.`);
-    if (Object.hasOwn(value, "finalization"))
+    }
+    if (Object.hasOwn(value, "finalization")) {
         errors.push(`${pathLabel}.finalization is not supported; acceptance contracts always run the self-review loop.`);
-    if (Object.hasOwn(value, "reason"))
+    }
+    if (Object.hasOwn(value, "reason")) {
         errors.push(`${pathLabel}.reason is not supported because acceptance is disabled by omitting the field.`);
+    }
     for (const key of Object.keys(value)) {
-        if (!ACCEPTANCE_KEYS.has(key) && !REMOVED_ACCEPTANCE_KEYS.has(key))
+        if (!ACCEPTANCE_KEYS.has(key) && !REMOVED_ACCEPTANCE_KEYS.has(key)) {
             errors.push(`${pathLabel}.${key} is not supported.`);
+        }
     }
-    const structuralValue = Object.fromEntries(Object.entries(value).filter(([key]) => ACCEPTANCE_KEYS.has(key)));
-    const schemaErrors = [...ACCEPTANCE_VALIDATOR.Errors(structuralValue)];
-    for (const error of schemaErrors) {
-        const criterionMatch = error.instancePath.match(/^\/criteria\/(\d+)$/);
-        if (criterionMatch) {
-            const criterion = Array.isArray(value.criteria) ? value.criteria[Number(criterionMatch[1])] : undefined;
-            if (criterion && typeof criterion === "object" && !Array.isArray(criterion)) {
-                if (error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/0"))
-                    continue;
-            }
-            else if (typeof criterion === "string") {
-                if (error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/1"))
-                    continue;
-            }
-            else if (error.keyword !== "anyOf") {
-                continue;
+    return errors;
+}
+function ignoreCriterionAlternative(error, criteria) {
+    const match = error.instancePath.match(/^\/criteria\/(\d+)$/);
+    if (!match) {
+        return false;
+    }
+    const criterion = isUnknownArray(criteria) ? criteria[Number(match[1])] : undefined;
+    if (isRecord(criterion)) {
+        return error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/0");
+    }
+    if (typeof criterion === "string") {
+        return error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/1");
+    }
+    return error.keyword !== "anyOf";
+}
+function schemaTypeSuffix(expected, instancePath) {
+    if (/^\/stopRules\/\d+$/.test(instancePath)) {
+        return "a non-empty string";
+    }
+    return expected === "array" || expected === "object" ? `an ${expected}` : `a ${expected}`;
+}
+function schemaErrorProperties(params, key) {
+    if (!isRecord(params) || !isUnknownArray(params[key])) {
+        return [];
+    }
+    return params[key].filter((property) => typeof property === "string");
+}
+function schemaErrorDetail(error, pathLabel) {
+    const errorPath = acceptanceErrorPath(pathLabel, error.instancePath);
+    if (error.instancePath.endsWith("/timeoutMs")) {
+        return [`${errorPath} must be a positive integer.`];
+    }
+    if (error.instancePath === "/maxFinalizationTurns") {
+        return [`${errorPath} must be an integer from 1 to ${MAX_FINALIZATION_TURNS}.`];
+    }
+    switch (error.keyword) {
+        case "anyOf":
+            return [`${errorPath} must be a string or object.`];
+        case "required":
+            return schemaErrorProperties(error.params, "requiredProperties").map((property) => `${errorPath}.${property} is required.`);
+        case "additionalProperties":
+            return schemaErrorProperties(error.params, "additionalProperties").map((property) => error.instancePath.endsWith("/env")
+                ? `${errorPath}.${property} must be a string.`
+                : `${errorPath}.${property} is not supported.`);
+        case "enum":
+            if (error.instancePath.includes("/evidence/")) {
+                return [`${errorPath} is not a supported evidence kind.`];
             }
-        }
-        if (error.keyword === "minLength")
-            continue;
-        const errorPath = acceptanceErrorPath(pathLabel, error.instancePath);
-        if (error.keyword === "anyOf" && criterionMatch) {
-            errors.push(`${errorPath} must be a string or object.`);
-        }
-        else if (error.keyword === "required") {
-            for (const property of error.params.requiredProperties)
-                errors.push(`${errorPath}.${property} is required.`);
-        }
-        else if (error.keyword === "enum" && error.instancePath.includes("/evidence/")) {
-            errors.push(`${errorPath} is not a supported evidence kind.`);
-        }
-        else if (error.keyword === "enum" && error.instancePath.endsWith("/severity")) {
-            errors.push(`${errorPath} must be required or recommended.`);
-        }
-        else if (error.instancePath.endsWith("/timeoutMs")) {
-            errors.push(`${errorPath} must be a positive integer.`);
-        }
-        else if (error.instancePath === "/maxFinalizationTurns") {
-            errors.push(`${errorPath} must be an integer from 1 to ${MAX_FINALIZATION_TURNS}.`);
-        }
-        else if (error.keyword === "additionalProperties") {
-            for (const property of error.params.additionalProperties) {
-                errors.push(error.instancePath.endsWith("/env") ? `${errorPath}.${property} must be a string.` : `${errorPath}.${property} is not supported.`);
+            if (error.instancePath.endsWith("/severity")) {
+                return [`${errorPath} must be required or recommended.`];
             }
+            return [`${errorPath} ${error.message}.`];
+        case "type": {
+            const type = recordAt(error, "params")?.type;
+            const expected = typeof type === "string" ? type : "unknown";
+            return [`${errorPath} must be ${schemaTypeSuffix(expected, error.instancePath)}.`];
         }
-        else if (error.keyword === "type") {
-            const expected = String(error.params.type);
-            const suffix = error.instancePath.match(/^\/stopRules\/\d+$/) ? "a non-empty string" : expected === "array" || expected === "object" ? `an ${expected}` : `a ${expected}`;
-            errors.push(`${errorPath} must be ${suffix}.`);
-        }
-        else {
-            errors.push(`${errorPath} ${error.message}.`);
-        }
+        default:
+            return [`${errorPath} ${error.message}.`];
     }
-    for (const [index, criterion] of Array.isArray(value.criteria) ? value.criteria.entries() : []) {
-        if (typeof criterion === "string" && !criterion.trim())
+}
+function acceptanceSchemaErrors(value, pathLabel) {
+    const structuralValue = Object.fromEntries(Object.entries(value).filter(([key]) => ACCEPTANCE_KEYS.has(key)));
+    return ACCEPTANCE_VALIDATOR.Errors(structuralValue).flatMap((error) => {
+        if (error.keyword === "minLength" || ignoreCriterionAlternative(error, value.criteria)) {
+            return [];
+        }
+        return schemaErrorDetail(error, pathLabel);
+    });
+}
+function emptyCriteriaFields(value, pathLabel) {
+    const errors = [];
+    for (const [index, criterion] of isUnknownArray(value) ? value.entries() : []) {
+        if (typeof criterion === "string" && criterion.trim().length === 0) {
             errors.push(`${pathLabel}.criteria[${index}] must not be empty.`);
-        if (criterion && typeof criterion === "object" && !Array.isArray(criterion)) {
+        }
+        if (isRecord(criterion)) {
             const item = criterion;
-            if (typeof item.id === "string" && !item.id.trim())
+            if (typeof item.id === "string" && item.id.trim().length === 0) {
                 errors.push(`${pathLabel}.criteria[${index}].id is required.`);
-            if (typeof item.must === "string" && !item.must.trim())
+            }
+            if (typeof item.must === "string" && item.must.trim().length === 0) {
                 errors.push(`${pathLabel}.criteria[${index}].must is required.`);
+            }
         }
     }
-    for (const [index, command] of Array.isArray(value.verify) ? value.verify.entries() : []) {
-        if (!command || typeof command !== "object" || Array.isArray(command))
+    return errors;
+}
+function emptyVerificationFields(value, pathLabel) {
+    const errors = [];
+    for (const [index, command] of isUnknownArray(value) ? value.entries() : []) {
+        if (!isRecord(command)) {
             continue;
+        }
         const item = command;
-        if (typeof item.id === "string" && !item.id.trim())
+        if (typeof item.id === "string" && item.id.trim().length === 0) {
             errors.push(`${pathLabel}.verify[${index}].id is required.`);
-        if (typeof item.command === "string" && !item.command.trim())
+        }
+        if (typeof item.command === "string" && item.command.trim().length === 0) {
             errors.push(`${pathLabel}.verify[${index}].command is required.`);
+        }
     }
-    for (const [index, rule] of Array.isArray(value.stopRules) ? value.stopRules.entries() : []) {
-        if (typeof rule === "string" && !rule.trim())
+    return errors;
+}
+function emptyStopRules(value, pathLabel) {
+    const errors = [];
+    for (const [index, rule] of isUnknownArray(value) ? value.entries() : []) {
+        if (typeof rule === "string" && rule.trim().length === 0) {
             errors.push(`${pathLabel}.stopRules[${index}] must be a non-empty string.`);
+        }
     }
-    if (!hasArrayItems(value.criteria) && !hasArrayItems(value.evidence) && !hasArrayItems(value.verify) && !hasArrayItems(value.stopRules)) {
+    return errors;
+}
+export function validateAcceptanceInput(input, pathLabel = "acceptance") {
+    if (input === undefined) {
+        return [];
+    }
+    if (input === false || typeof input === "string") {
+        return [
+            `${pathLabel} must be an object. Public acceptance levels and false disables are no longer supported.`,
+        ];
+    }
+    if (!isRecord(input)) {
+        return [`${pathLabel} must be an object.`];
+    }
+    const value = input;
+    const errors = [
+        ...unsupportedAcceptanceFields(value, pathLabel),
+        ...acceptanceSchemaErrors(value, pathLabel),
+        ...emptyCriteriaFields(value.criteria, pathLabel),
+        ...emptyVerificationFields(value.verify, pathLabel),
+        ...emptyStopRules(value.stopRules, pathLabel),
+    ];
+    if (!hasArrayItems(value.criteria) &&
+        !hasArrayItems(value.evidence) &&
+        !hasArrayItems(value.verify) &&
+        !hasArrayItems(value.stopRules)) {
         errors.push(`${pathLabel} must include at least one of criteria, evidence, verify, or stopRules.`);
     }
     return [...new Set(errors)];
 }
 function normalizeCriteria(criteria, evidence) {
-    return (criteria ?? []).map((criterion, index) => {
+    return (criteria ?? [])
+        .map((criterion, index) => {
         if (typeof criterion === "string") {
-            return { id: `criterion-${index + 1}`, must: criterion, evidence, severity: "required" };
+            return {
+                id: `criterion-${index + 1}`,
+                must: criterion,
+                evidence,
+                severity: "required",
+            };
         }
         return {
             id: criterion.id.trim(),
@@ -156,11 +222,13 @@ function normalizeCriteria(criteria, evidence) {
             evidence: criterion.evidence?.filter((item) => VALID_EVIDENCE.has(item)) ?? evidence,
             severity: criterion.severity ?? "required",
         };
-    }).filter((criterion) => criterion.must.trim());
+    })
+        .filter((criterion) => criterion.must.trim().length > 0);
 }
 function deriveAcceptanceLevel(config) {
-    if ((config.verify?.length ?? 0) > 0)
+    if ((config.verify?.length ?? 0) > 0) {
         return "verified";
+    }
     return "checked";
 }
 export function resolveEffectiveAcceptance(input) {
@@ -177,8 +245,9 @@ export function resolveEffectiveAcceptance(input) {
         };
     }
     const validationErrors = validateAcceptanceInput(input.explicit);
-    if (validationErrors.length > 0)
+    if (validationErrors.length > 0) {
         throw new Error(validationErrors.join(" "));
+    }
     const explicit = input.explicit;
     const evidence = [...new Set(explicit.evidence ?? [])];
     const criteria = normalizeCriteria(explicit.criteria, evidence);
@@ -192,37 +261,61 @@ export function resolveEffectiveAcceptance(input) {
         evidence,
         verify,
         stopRules,
-        finalization: { mode: "self-review-loop", maxTurns: explicit.maxFinalizationTurns ?? DEFAULT_FINALIZATION_MAX_TURNS },
+        finalization: {
+            mode: "self-review-loop",
+            maxTurns: explicit.maxFinalizationTurns ?? DEFAULT_FINALIZATION_MAX_TURNS,
+        },
     };
 }
 export function acceptanceInputFromResolved(acceptance) {
-    if (!acceptance?.explicit)
+    if (acceptance?.explicit !== true) {
         return undefined;
-    const maxTurns = acceptance.finalization?.maxTurns;
+    }
+    const maxTurns = acceptance.finalization.maxTurns;
     return {
         criteria: acceptance.criteria,
         evidence: acceptance.evidence,
         verify: acceptance.verify,
         stopRules: acceptance.stopRules,
-        ...(maxTurns !== undefined ? { maxFinalizationTurns: maxTurns } : {}),
+        maxFinalizationTurns: maxTurns,
     };
 }
 export function shouldRunAcceptanceFinalization(acceptance) {
-    return acceptance.explicit && acceptance.finalization.mode === "self-review-loop" && acceptance.finalization.maxTurns > 0;
+    return (acceptance.explicit &&
+        acceptance.finalization.mode === "self-review-loop" &&
+        acceptance.finalization.maxTurns > 0);
 }
 export function acceptanceSelfReviewConfig(acceptance) {
-    if (acceptance.verify.length === 0)
+    if (acceptance.verify.length === 0) {
         return acceptance;
+    }
     return {
         ...acceptance,
         level: "checked",
         verify: [],
     };
 }
+export function formatAcceptanceRequirements(criteria, evidence, emptyCriteria) {
+    const criteriaLines = criteria.length > 0
+        ? criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}${criterion.evidence.length > 0 ? ` (evidence: ${criterion.evidence.join(", ")})` : ""}`)
+        : [emptyCriteria];
+    return [
+        "Criteria:",
+        ...criteriaLines,
+        "",
+        `Required evidence: ${evidence.length > 0 ? evidence.join(", ") : "none explicitly requested"}`,
+    ];
+}
 export function formatAcceptancePrompt(acceptance, nativeReport = false) {
-    if (acceptance.level === "none")
+    if (acceptance.level === "none") {
         return "";
-    const evidence = [...new Set([...acceptance.evidence, ...acceptance.criteria.flatMap((criterion) => criterion.evidence)])];
+    }
+    const evidence = [
+        ...new Set([
+            ...acceptance.evidence,
+            ...acceptance.criteria.flatMap((criterion) => criterion.evidence),
+        ]),
+    ];
     const lines = [
         "",
         "## Acceptance Contract",
@@ -231,23 +324,24 @@ export function formatAcceptancePrompt(acceptance, nativeReport = false) {
             : "Completion is not accepted from prose alone. End the initial response with a structured acceptance report.",
         "After the initial response, the runtime will continue this same session for a bounded self-review/repair loop before accepting the run.",
         "For an observed human-only boundary (such as Touch ID or an unavailable MFA code), report the affected criterion as blocked with concrete evidence and a nonempty humanAction stating the exact user action. Retain completed evidence. This leaves acceptance incomplete and stops finalization/verification until explicit Continue. Do not use blocked for ordinary errors, missing unrelated evidence, or work you can fix.",
+        "Check early whether you can verify each criterion here. Apart from the human-only boundary above, if one needs a service, credential, device, network, or tool you cannot reach, say so right away (send a contact_supervisor progress_update when available), finish the verifiable work, and report that criterion not-satisfied with the missing prerequisite in residualRisks instead of spending turns on workarounds.",
         "",
-        "Criteria:",
-        ...(acceptance.criteria.length ? acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}${criterion.evidence.length ? ` (evidence: ${criterion.evidence.join(", ")})` : ""}`) : ["- No explicit criteria were configured; satisfy the requested task and the required evidence/checks below."]),
-        "",
-        `Required evidence: ${evidence.join(", ") || "none explicitly requested"}`,
+        ...formatAcceptanceRequirements(acceptance.criteria, evidence, "- No explicit criteria were configured; satisfy the requested task and the required evidence/checks below."),
     ];
     if (evidence.length > 0) {
         lines.push("", `Structured evidence must be present in the ${nativeReport ? "typed report object" : "`acceptance-report` JSON fields"}. Markdown sections in your visible answer do not satisfy required evidence by themselves. If you already described evidence in prose, copy or summarize it into the matching JSON field.`, "Evidence field mapping:", ...formatEvidenceReportFieldMapping(evidence));
     }
     if (acceptance.verify.length > 0) {
         lines.push("", "Runtime verification commands configured by parent:");
-        for (const command of acceptance.verify)
+        for (const command of acceptance.verify) {
             lines.push(`- ${command.id}: ${command.command}`);
+        }
     }
     if (acceptance.stopRules.length > 0) {
         lines.push("", "Stop rules:", ...acceptance.stopRules.map((rule) => `- ${rule}`));
     }
-    lines.push("", nativeReport ? "Submit this shape through structured_output; do not emit a fenced acceptance-report:" : "Finish with a fenced JSON block tagged `acceptance-report` in this shape:", formatAcceptanceReportExample(nativeReport));
+    lines.push("", nativeReport
+        ? "Submit this shape through structured_output; do not emit a fenced acceptance-report:"
+        : "Finish with a fenced JSON block tagged `acceptance-report` in this shape:", formatAcceptanceReportExample(nativeReport));
     return lines.join("\n");
 }

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

@@ -0,0 +1 @@
+export const DEFAULT_FINALIZATION_MAX_TURNS = 3;