@akagilnc/pi-workflow-roles 0.1.1751

package/dist/package-contracts/terminating-tools.js

@@ -0,0 +1,173 @@
+/**
+ * Package-owned terminating tool registry.
+ * Package roles share these terminating leaves.
+ */
+import { COLLECTOR_ACCEPTED_TEXT, COLLECTOR_OUTPUT_TOOL, validateAcceptedCollectorReceipt, } from "./collector-output.js";
+import { JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, validateAcceptedJudgeDetails, } from "./judge-output.js";
+import { REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, projectReviewerIntentToReceipt, validateReviewerIntent, validateRuntimeReviewerReceipt, } from "./reviewer-output.js";
+import { isAuditEscalationResult } from "../audit-escalation.js";
+import { DOCTOR_OUTPUT_TOOL_NAME, validateDoctorSubmissionShape, validateRecordedDoctorOutput } from "../doctor-contracts.js";
+import { MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateMergerOutput } from "../merger-contracts.js";
+import { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, validateAcceptedWorkerDetails, } from "./worker-output.js";
+export { CODER_ACCEPTED_TEXT, CODER_OUTPUT_TOOL_NAME, COLLECTOR_ACCEPTED_TEXT, COLLECTOR_OUTPUT_TOOL, FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, JUDGE_ACCEPTED_TEXT, JUDGE_OUTPUT_TOOL_NAME, REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, MERGER_ACCEPTED_TEXT, MERGER_OUTPUT_TOOL_NAME, validateAcceptedCollectorReceipt, validateAcceptedJudgeDetails, projectReviewerIntentToReceipt, validateReviewerIntent, validateRuntimeReviewerReceipt, validateAcceptedWorkerDetails, validateDoctorSubmissionShape, validateRecordedDoctorOutput, validateMergerOutput, };
+export const TERMINATING_TOOL_NAMES = [
+    CODER_OUTPUT_TOOL_NAME,
+    FIXER_OUTPUT_TOOL_NAME,
+    REVIEWER_OUTPUT_TOOL_NAME,
+    JUDGE_OUTPUT_TOOL_NAME,
+    COLLECTOR_OUTPUT_TOOL,
+    DOCTOR_OUTPUT_TOOL_NAME,
+    MERGER_OUTPUT_TOOL_NAME,
+];
+export function isTerminatingToolName(name) {
+    return TERMINATING_TOOL_NAMES.includes(name);
+}
+export function acceptedTextFor(toolName) {
+    switch (toolName) {
+        case CODER_OUTPUT_TOOL_NAME:
+            return CODER_ACCEPTED_TEXT;
+        case FIXER_OUTPUT_TOOL_NAME:
+            return FIXER_ACCEPTED_TEXT;
+        case REVIEWER_OUTPUT_TOOL_NAME:
+            return REVIEWER_ACCEPTED_TEXT;
+        case JUDGE_OUTPUT_TOOL_NAME:
+            return JUDGE_ACCEPTED_TEXT;
+        case COLLECTOR_OUTPUT_TOOL:
+            return COLLECTOR_ACCEPTED_TEXT;
+        case DOCTOR_OUTPUT_TOOL_NAME:
+            return "Doctor output accepted";
+        case MERGER_OUTPUT_TOOL_NAME:
+            return MERGER_ACCEPTED_TEXT;
+    }
+}
+export class AcceptedDetailsContractError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AcceptedDetailsContractError";
+    }
+}
+function safeProperty(candidate, property) {
+    try {
+        return candidate?.[property];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function validateAcceptedDetails(toolName, details) {
+    const candidate = details !== null && typeof details === "object" && !Array.isArray(details)
+        ? details
+        : undefined;
+    let auditEscalation = false;
+    try {
+        auditEscalation = isAuditEscalationResult(details);
+    }
+    catch {
+        // Hostile getters are not recognizable audit escalation evidence.
+    }
+    if (auditEscalation || safeProperty(candidate, "kind") === "audit_escalation") {
+        throw new AcceptedDetailsContractError("audit escalation is not an accepted role receipt");
+    }
+    const discriminator = safeProperty(candidate, toolName === JUDGE_OUTPUT_TOOL_NAME ? "judgeStatus" : "status");
+    const lawfulStatuses = {
+        [CODER_OUTPUT_TOOL_NAME]: ["planned", "completed", "refused", "unfinished"],
+        [FIXER_OUTPUT_TOOL_NAME]: ["planned", "completed", "refused", "partially_completed", "unfinished"],
+        [REVIEWER_OUTPUT_TOOL_NAME]: ["completed", "refused"],
+        [JUDGE_OUTPUT_TOOL_NAME]: ["converged", "continue", "escalate"],
+        [COLLECTOR_OUTPUT_TOOL]: [],
+        [DOCTOR_OUTPUT_TOOL_NAME]: ["completed", "refused"],
+        [MERGER_OUTPUT_TOOL_NAME]: ["completed", "escalate"],
+    };
+    const collectorDiscriminator = toolName === COLLECTOR_OUTPUT_TOOL && Array.isArray(candidate?.groups);
+    const runtimeBindingMissing = (toolName === DOCTOR_OUTPUT_TOOL_NAME && discriminator === "completed" && !(candidate?.cost !== null && typeof candidate?.cost === "object")) ||
+        (toolName === REVIEWER_OUTPUT_TOOL_NAME && candidate?.version !== 2);
+    if (runtimeBindingMissing || (!collectorDiscriminator && (typeof discriminator !== "string" || !lawfulStatuses[toolName].includes(discriminator)))) {
+        throw new AcceptedDetailsContractError("terminating receipt has no recognized execution discriminator");
+    }
+    try {
+        switch (toolName) {
+            case CODER_OUTPUT_TOOL_NAME:
+                return validateAcceptedWorkerDetails(details, "Coder");
+            case FIXER_OUTPUT_TOOL_NAME:
+                return validateAcceptedWorkerDetails(details, "Fixer");
+            case REVIEWER_OUTPUT_TOOL_NAME:
+                return validateRuntimeReviewerReceipt(details);
+            case JUDGE_OUTPUT_TOOL_NAME:
+                return validateAcceptedJudgeDetails(details);
+            case COLLECTOR_OUTPUT_TOOL:
+                return validateAcceptedCollectorReceipt(details);
+            case DOCTOR_OUTPUT_TOOL_NAME:
+                return validateRecordedDoctorOutput(details);
+            case MERGER_OUTPUT_TOOL_NAME:
+                return validateMergerOutput(details);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.constructor === Error)
+            throw new AcceptedDetailsContractError(error.message, { cause: error });
+        throw error;
+    }
+}
+export function validateAcceptedLifecycle(toolName, argumentsValue, detailsValue) {
+    const details = validateAcceptedDetails(toolName, detailsValue);
+    if (toolName === DOCTOR_OUTPUT_TOOL_NAME) {
+        const testimony = validateDoctorSubmissionShape(argumentsValue);
+        if (testimony.status === "refused") {
+            if (!deepEqual(testimony, details))
+                throw new Error("accepted tool lifecycle details mismatch");
+            return details;
+        }
+        const receipt = details;
+        if (receipt.status !== "completed")
+            throw new Error("accepted tool lifecycle details mismatch");
+        const { cost: _runtimeCost, ...projected } = receipt;
+        if (!deepEqual(testimony, projected))
+            throw new Error("accepted tool lifecycle details mismatch");
+        return details;
+    }
+    const argumentsDetails = validateAcceptedDetails(toolName, argumentsValue);
+    if (!deepEqual(argumentsDetails, details))
+        throw new Error("accepted tool lifecycle details mismatch");
+    return details;
+}
+export function acceptedFacts(toolName, details) {
+    switch (toolName) {
+        case CODER_OUTPUT_TOOL_NAME:
+        case FIXER_OUTPUT_TOOL_NAME:
+        case REVIEWER_OUTPUT_TOOL_NAME:
+        case DOCTOR_OUTPUT_TOOL_NAME: return { status: details.status };
+        case JUDGE_OUTPUT_TOOL_NAME: return { status: details.judgeStatus };
+        case MERGER_OUTPUT_TOOL_NAME: {
+            const output = details;
+            return { status: output.status, ...(output.status === "completed" && typeof output.mergeCommitId === "string" ? { commit: output.mergeCommitId } : {}) };
+        }
+        case COLLECTOR_OUTPUT_TOOL:
+            return { status: "collected" };
+    }
+}
+/** Deep structural equality for lifecycle agreement checks. */
+export function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (typeof a === "object") {
+        if (typeof b !== "object" || b === null || Array.isArray(b))
+            return false;
+        const aKeys = Object.keys(a).sort();
+        const bKeys = Object.keys(b).sort();
+        if (aKeys.length !== bKeys.length)
+            return false;
+        if (!aKeys.every((key, index) => key === bKeys[index]))
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

package/dist/package-contracts/worker-output.js

@@ -0,0 +1,13 @@
+/** Package-owned independent Coder and Fixer output leaves. */
+export { FIXER_ACCEPTED_TEXT, FIXER_OUTPUT_TOOL_NAME, fixerOutputSchema, validateFixerOutput, validateFixerOutputForPacket, } from "./fixer-output.js";
+export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisites, validateFixerPrerequisites } from "./fixer-packet.js";
+import { validateFixerOutput } from "./fixer-output.js";
+export const CODER_OUTPUT_TOOL_NAME = "ak_coder_output";
+export const CODER_ACCEPTED_TEXT = "Coder report accepted";
+export function validateAcceptedCoderDetails(output) {
+    return output;
+}
+/** Structural production validator for an accepted current leaf. */
+export function validateAcceptedWorkerDetails(output, roleLabel = "Coder") {
+    return roleLabel === "Fixer" ? validateFixerOutput(output) : validateAcceptedCoderDetails(output);
+}

package/dist/package-owned-tool-idle.js

@@ -0,0 +1,104 @@
+import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, createStreamIdleGuard, } from "./stream-idle-guard.js";
+import { isProducingToolUpdate } from "./tool-execution-observation.js";
+export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS = DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE = "AK_PACKAGE_OWNED_TOOL_IDLE_TIMEOUT";
+const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
+export class PackageOwnedToolIdleTimeoutError extends Error {
+    code = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE;
+    idleTimeoutMs = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS;
+    constructor() {
+        super(`package-owned tool idle timeout after ${PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS}ms`);
+        this.name = "PackageOwnedToolIdleTimeoutError";
+    }
+}
+/**
+ * Package-tool activity includes content production and host-only details
+ * progress. Keep the observation-plane oracle separate: its stderr heartbeat
+ * contract remains content-driven. Pi's known execute-entry placeholder
+ * (`content: [], details: undefined`) is not activity.
+ */
+function isPackageOwnedToolActivityUpdate(partialResult) {
+    if (isProducingToolUpdate(partialResult))
+        return true;
+    if (typeof partialResult !== "object" || partialResult === null)
+        return false;
+    const details = partialResult.details;
+    if (details === undefined || details === null)
+        return false;
+    if (typeof details === "string")
+        return details.length > 0;
+    if (Array.isArray(details))
+        return details.length > 0;
+    if (typeof details === "object")
+        return Reflect.ownKeys(details).length > 0;
+    return true;
+}
+/**
+ * Single shared execute wrapper for package-owned tool definitions.
+ * Idempotent: wrapping twice returns the same protected definition.
+ */
+export function wrapPackageOwnedToolDefinition(tool) {
+    // Mark the execute function, not the tool object — callers may spread tool fields
+    // onto a new definition with a different execute (e.g. auditor customTools).
+    if (tool.execute[WRAPPED] === true)
+        return tool;
+    const originalExecute = tool.execute.bind(tool);
+    const wrappedExecute = function packageOwnedToolIdleExecute(...args) {
+        const signal = args[2];
+        const onUpdate = args[3];
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const idle = createStreamIdleGuard({
+                idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
+            });
+            const settle = (deliver) => {
+                if (settled)
+                    return;
+                settled = true;
+                idle.signal.removeEventListener("abort", onIdle);
+                idle.dispose();
+                deliver();
+            };
+            const onIdle = () => {
+                settle(() => reject(new PackageOwnedToolIdleTimeoutError()));
+            };
+            idle.signal.addEventListener("abort", onIdle, { once: true });
+            const guardedOnUpdate = onUpdate === undefined
+                ? undefined
+                : (partialResult) => {
+                    if (settled)
+                        return;
+                    if (isPackageOwnedToolActivityUpdate(partialResult))
+                        idle.poke();
+                    onUpdate(partialResult);
+                };
+            const callArgs = args.slice();
+            // Preserve the original signal at args[2]; timeout must not abort it.
+            callArgs[2] = signal;
+            callArgs[3] = guardedOnUpdate;
+            void Promise.resolve()
+                .then(() => originalExecute(...callArgs))
+                .then((result) => settle(() => resolve(result)), (error) => settle(() => reject(error)));
+        });
+    };
+    wrappedExecute[WRAPPED] = true;
+    return {
+        ...tool,
+        execute: wrappedExecute,
+    };
+}
+/**
+ * Install the shared registration surface on an ExtensionAPI once.
+ * All subsequent pi.registerTool calls for package-owned tools are wrapped.
+ */
+export function installPackageOwnedToolRegistration(pi) {
+    const current = pi.registerTool;
+    if (current[WRAPPED] === true)
+        return;
+    const original = current.bind(pi);
+    const installed = ((tool) => {
+        original(wrapPackageOwnedToolDefinition(tool));
+    });
+    installed[WRAPPED] = true;
+    pi.registerTool = installed;
+}

package/dist/packaged-role-registry.js

@@ -0,0 +1,34 @@
+import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.js";
+import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.js";
+import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.js";
+import { CODER_OUTPUT_TOOL_NAME, FIXER_OUTPUT_TOOL_NAME } from "./package-contracts/worker-output.js";
+import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.js";
+import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.js";
+const PACKAGED_ROLE_REGISTRY = [
+  { role: "judge", phases: [null], outputTool: JUDGE_OUTPUT_TOOL_NAME, inputFlag: void 0, phaseFlag: void 0, activationStage: "load-and-install" },
+  { role: "fixer", phases: ["plan", "apply"], outputTool: FIXER_OUTPUT_TOOL_NAME, inputFlag: "ak-fix-packet", phaseFlag: "ak-fixer-phase", activationStage: "load-and-install" },
+  { role: "coder", phases: ["plan", "apply"], outputTool: CODER_OUTPUT_TOOL_NAME, inputFlag: "ak-coder-task", phaseFlag: "ak-coder-phase", activationStage: "load-and-install" },
+  { role: "reviewer", phases: [null], outputTool: REVIEWER_OUTPUT_TOOL_NAME, inputFlag: void 0, phaseFlag: void 0, activationStage: "load-and-install" },
+  { role: "collector", phases: [null], outputTool: COLLECTOR_OUTPUT_TOOL, inputFlag: "ak-collector-repo", phaseFlag: void 0, activationStage: "load-and-install" },
+  { role: "doctor", phases: [null], outputTool: DOCTOR_OUTPUT_TOOL_NAME, inputFlag: "ak-doctor-case", phaseFlag: void 0, activationStage: "load-and-install" },
+  { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: void 0, activationStage: "prepare-git-and-install" }
+];
+function packagedRoleMetadata(role) {
+  return PACKAGED_ROLE_REGISTRY.find((entry) => entry.role === role);
+}
+function packagedRoleInputFlag(role) {
+  return packagedRoleMetadata(role)?.inputFlag;
+}
+function packagedRolePhaseFlag(role) {
+  return packagedRoleMetadata(role)?.phaseFlag;
+}
+function packagedRoleOutputTool(role) {
+  return packagedRoleMetadata(role)?.outputTool;
+}
+export {
+  PACKAGED_ROLE_REGISTRY,
+  packagedRoleInputFlag,
+  packagedRoleMetadata,
+  packagedRoleOutputTool,
+  packagedRolePhaseFlag
+};