@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/public-cli/instruction-seat-run.js

@@ -0,0 +1,256 @@
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.js";
+import { readRunTicketNumber } from "../run-ticket-number.js";
+import { CliUsageError } from "./cli-errors.js";
+import { admitAuditorInvocation, admitEvidenceChildInvocation, admitGatekeeperInvocation, admitNavigatorInvocation, bindAdmittedTicketNumber, buildInstructionTransportPrompt, } from "./invocation.js";
+import { prepareSummonsResumeMaterials, runPostAdmissionOneShot, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { loadResumableInstructionSeatRun, markRunAdmitted, } from "./run-lifecycle.js";
+import { applyInstructionTicketProbe, probeInstructionTicket, ticketNumberFromProbe, tryResumeSameTicketSeatRun, } from "./seat-ticket-binding.js";
+import { presentStructuralRejection, readEngineDetourInfrastructureFailure, trySettleAuditorTerminalResult, trySettleEvidenceChildTerminalResult, trySettleGatekeeperTerminalResult, trySettleNavigatorTerminalResult, } from "./settlement.js";
+import { projectRoleTurnRequest, } from "./turn-request.js";
+/** Project an admitted instruction-seat invocation onto the host-neutral turn request. */
+export function buildInstructionSeatTurnRequest(admitted, options) {
+    return projectRoleTurnRequest(admitted, {
+        activation: {
+            role: admitted.role,
+        },
+    }, options);
+}
+function instructionSeatAdapters(options) {
+    return {
+        trySettle: (admitted, authority, scope) => {
+            switch (admitted.role) {
+                case "gatekeeper":
+                    return trySettleGatekeeperTerminalResult(admitted, authority, scope);
+                case "navigator":
+                    return trySettleNavigatorTerminalResult(admitted, authority, scope);
+                case "auditor":
+                    return trySettleAuditorTerminalResult(admitted, authority, scope);
+                case "evidence-child":
+                    return trySettleEvidenceChildTerminalResult(admitted, authority, scope);
+            }
+        },
+        // Accepted receipts and failure terminals both present via shared path.
+        shouldPresentSettled: () => true,
+        // #675 / #357 T2: failInfrastructure abort after engine-detour tool failure must not
+        // wash the durable toolResult diagnostic (same seam as reviewer-run / judge-run).
+        resolveRunnerKnownFailure: async ({ result, sessionFile, }) => {
+            const infrastructureFailure = await readEngineDetourInfrastructureFailure(sessionFile);
+            return infrastructureFailure === undefined
+                ? result.knownFailure
+                : {
+                    cause: infrastructureFailure.cause,
+                    diagnostic: infrastructureFailure.diagnostic,
+                    ...(infrastructureFailure.identity === undefined
+                        ? {}
+                        : { identity: infrastructureFailure.identity }),
+                };
+        },
+        ...(options?.beforeDispatch === undefined
+            ? {}
+            : { beforeDispatch: options.beforeDispatch }),
+    };
+}
+async function admitInstructionSeat(role, options) {
+    switch (role) {
+        case "gatekeeper":
+            return admitGatekeeperInvocation(options);
+        case "navigator":
+            return admitNavigatorInvocation(options);
+        case "auditor":
+            return admitAuditorInvocation(options);
+        case "evidence-child":
+            return admitEvidenceChildInvocation(options);
+    }
+}
+export async function runPublicInstructionSeatResume(request, env, io) {
+    return await runPostAdmissionSeatResume({
+        request,
+        env,
+        io,
+        load: (effective) => loadResumableInstructionSeatRun(env.home, effective.runId, env.principalAuthority),
+        buildTurnRequest: async (admitted, effective) => {
+            const summonsPrepared = await prepareSummonsResumeMaterials(admitted.runDirectory, effective.summons);
+            return buildInstructionSeatTurnRequest(admitted, resumeTurnRequestProjectionOptions(admitted, effective, env, summonsPrepared));
+        },
+        adapters: instructionSeatAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}
+/** Scope auditor subject/source-run env for the duration of one seat turn. */
+async function withAuditorSoulEnv(options) {
+    if (options.subject === undefined && options.sourceRunDirectory === undefined) {
+        return options.run();
+    }
+    const { AK_ROLE_AUDITOR_SUBJECT_ENV, AK_ROLE_AUDITOR_SOURCE_RUN_ENV } = await import("../auditor-soul.js");
+    const priorSubject = process.env[AK_ROLE_AUDITOR_SUBJECT_ENV];
+    const priorSource = process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV];
+    if (options.subject !== undefined) {
+        process.env[AK_ROLE_AUDITOR_SUBJECT_ENV] = options.subject;
+    }
+    if (options.sourceRunDirectory !== undefined) {
+        process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] = options.sourceRunDirectory;
+    }
+    try {
+        return await options.run();
+    }
+    finally {
+        if (options.subject !== undefined) {
+            if (priorSubject === undefined)
+                delete process.env[AK_ROLE_AUDITOR_SUBJECT_ENV];
+            else
+                process.env[AK_ROLE_AUDITOR_SUBJECT_ENV] = priorSubject;
+        }
+        if (options.sourceRunDirectory !== undefined) {
+            if (priorSource === undefined)
+                delete process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV];
+            else
+                process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] = priorSource;
+        }
+    }
+}
+export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
+    let parsed;
+    try {
+        parsed = parseArgv(argv);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    let auditorSubject;
+    let auditorSourceRun;
+    let auditorSourceTicket;
+    let ticketProbe;
+    // #637: same ticket → resume prior seat run with this summons' materials.
+    // Auditor inherits ticket from source-run (notary face); other instruction seats
+    // probe instruction (inspector face). No bare catch→fresh: lookup/resume failures
+    // surface; only true absence of a prior run mints new.
+    const projectRoot = parsed.project ?? env.cwd;
+    if (role === "auditor") {
+        if (parsed.subject !== "judge" && parsed.subject !== "doctor") {
+            presentStructuralRejection(new CliUsageError("auditor --subject requires judge|doctor"), io);
+            return { exitCode: 2 };
+        }
+        auditorSubject = parsed.subject;
+        const source = typeof parsed.sourceRun === "string" ? parsed.sourceRun.trim() : "";
+        if (source === "") {
+            presentStructuralRejection(new CliUsageError("auditor --source-run requires a run locator"), io);
+            return { exitCode: 2 };
+        }
+        try {
+            const { resolveNotarySourceRunLocator } = await import("../notary-source-run.js");
+            const resolved = await resolveNotarySourceRunLocator({
+                projectRoot,
+                sourceRun: source,
+                home: env.home,
+            });
+            auditorSourceRun = resolved.runDirectory;
+            auditorSourceTicket = await readRunTicketNumber(resolved.runDirectory);
+        }
+        catch (error) {
+            presentStructuralRejection(new CliUsageError(error instanceof Error ? error.message : String(error)), io);
+            return { exitCode: 2 };
+        }
+    }
+    else {
+        // Inspector face: unconditional probe (same seam as inspector-run.ts).
+        ticketProbe = await probeInstructionTicket(parsed.instruction, projectRoot, env);
+    }
+    const probedTicketNumber = auditorSourceTicket
+        ?? (ticketProbe === undefined ? undefined : ticketNumberFromProbe(ticketProbe));
+    if (probedTicketNumber !== undefined) {
+        const summons = {
+            instruction: parsed.instruction,
+            instructionEmpty: parsed.instruction.trim() === "",
+            attachmentPaths: parsed.attachmentPaths,
+        };
+        const resumed = await withAuditorSoulEnv({
+            ...(auditorSubject === undefined ? {} : { subject: auditorSubject }),
+            ...(auditorSourceRun === undefined
+                ? {}
+                : { sourceRunDirectory: auditorSourceRun }),
+            run: () => tryResumeSameTicketSeatRun({
+                home: env.home,
+                projectRoot,
+                role,
+                ticketNumber: probedTicketNumber,
+                freshSummons: env.freshSummons,
+                summons,
+                resume: (runId, materials) => runPublicInstructionSeatResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
+            }),
+        });
+        if (resumed !== undefined)
+            return resumed;
+    }
+    let admitted;
+    try {
+        admitted = await admitInstructionSeat(role, {
+            home: env.home,
+            principalAuthority: env.principalAuthority,
+            cwd: env.cwd,
+            instruction: parsed.instruction,
+            attachmentPaths: parsed.attachmentPaths,
+            ...(parsed.project === undefined ? {} : { project: parsed.project }),
+            ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+            ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    return await withAuditorSoulEnv({
+        ...(auditorSubject === undefined ? {} : { subject: auditorSubject }),
+        ...(auditorSourceRun === undefined
+            ? {}
+            : { sourceRunDirectory: auditorSourceRun }),
+        run: async () => {
+            await markRunAdmitted(admitted, env.principalAuthority);
+            const turnRequest = buildInstructionSeatTurnRequest(admitted, {
+                packageRoot: env.packageRoot,
+                home: env.home,
+                agentDir: env.agentDir,
+                ...(env.model === undefined ? {} : { model: env.model }),
+                ...(env.engine === undefined ? {} : { engine: env.engine }),
+                ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+                ...(env.correlationId === undefined || env.correlationId.trim() === ""
+                    ? {}
+                    : { correlationId: env.correlationId }),
+                continuation: {
+                    kind: "initial",
+                    prompt: buildInstructionTransportPrompt(admitted, engineSessionMaterialFromOptions({
+                        ...(env.engine === undefined ? {} : { engine: env.engine }),
+                        packageRoot: env.packageRoot,
+                    })),
+                },
+            });
+            return await runPostAdmissionOneShot({
+                admitted,
+                env,
+                io,
+                request: turnRequest,
+                adapters: instructionSeatAdapters({
+                    beforeDispatch: async (admittedSeat) => {
+                        // #635/#637: ticket bind inside controlled-failure boundary.
+                        // Auditor inherits source-run ticket (notary face).
+                        // Other seats: same applyInstructionTicketProbe as inspector-run.
+                        if (auditorSourceTicket !== undefined) {
+                            await bindAdmittedTicketNumber(admittedSeat, auditorSourceTicket);
+                        }
+                        else if (ticketProbe !== undefined) {
+                            await applyInstructionTicketProbe(admittedSeat, ticketProbe);
+                        }
+                    },
+                }),
+                ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+            });
+        },
+    });
+}