@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/pi/role-turn-host.js

@@ -0,0 +1,430 @@
+/**
+ * Pi adapter for the host-neutral main-session execution seam (#526 / S1b-2).
+ * Owns argv construction, spawn/SIGTERM/close, and session codec helpers.
+ * public-cli runners project RoleTurnRequest; this module is the sole argv owner.
+ */
+import { execFile, spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, appendFile, readFile, realpath } from "node:fs/promises";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { platform } from "node:process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { ExplicitInternalActivationError } from "../host-contracts.js";
+import { applyEngineChildEnv } from "../engine-detour.js";
+/** Package-relative Internal role entrypoint (ADR 0052; same path as public-cli registry). */
+const INTERNAL_ROLE_ENTRYPOINT_RELATIVE = "extensions/role-runtime.ts";
+export function resolveInternalRoleEntrypoint(packageRoot) {
+    return join(packageRoot, INTERNAL_ROLE_ENTRYPOINT_RELATIVE);
+}
+/** Non-dispatch args: load Internal once and exit via Pi help (no model turn). */
+export const EXPLICIT_INTERNAL_LOAD_PROBE_ARGS = [
+    "--no-skills",
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--no-session",
+    "--help",
+];
+export function buildExplicitInternalActivationArgs(selectedRoleEntry, extraArgs = []) {
+    return ["--no-extensions", "-e", selectedRoleEntry, ...extraArgs];
+}
+/**
+ * Pi argv for seat model. Host only passes through resolved values — no local
+ * thinking whitelist and no package default fill. Bare provider/model omits
+ * --thinking so Pi owns its own default (#346/#384). Explicit thinking only.
+ */
+function buildSeatModelCliArgs(model) {
+    if (model === undefined)
+        return [];
+    return [
+        "--provider",
+        model.provider,
+        "--model",
+        model.model,
+        ...(model.thinking === undefined ? [] : ["--thinking", model.thinking]),
+    ];
+}
+function buildActivationFlagArgs(activation) {
+    switch (activation.role) {
+        case "judge":
+            return ["--ak-role", "judge"];
+        case "coder":
+            return [
+                "--ak-role",
+                "coder",
+                "--ak-coder-phase",
+                activation.phase,
+                "--ak-coder-task",
+                activation.taskPath,
+            ];
+        case "fixer":
+            return [
+                "--ak-role",
+                "fixer",
+                "--ak-fixer-phase",
+                activation.phase,
+                "--ak-fix-packet",
+                activation.packetPath,
+                ...(activation.prerequisitesPath === undefined
+                    ? []
+                    : ["--ak-fixer-prerequisites", activation.prerequisitesPath]),
+            ];
+        case "reviewer":
+            return [
+                "--ak-role",
+                "reviewer",
+                "--ak-review-base",
+                activation.baseRevision,
+                ...(activation.authorityRefs.length === 0
+                    ? []
+                    : ["--ak-review-authority-refs", JSON.stringify([...activation.authorityRefs])]),
+                ...(activation.ticketNumber === undefined
+                    ? []
+                    : ["--ak-review-ticket-number", String(activation.ticketNumber)]),
+            ];
+        case "merger":
+            return ["--ak-role", "merger", "--ak-merger-input", activation.inputPath];
+        case "collector":
+            return [
+                "--ak-role",
+                "collector",
+                "--ak-collector-repo",
+                activation.repo,
+                "--ak-collector-pr",
+                activation.pr,
+                ...(activation.requestManifestPath === undefined
+                    ? []
+                    : ["--ak-collector-request-manifest", activation.requestManifestPath]),
+            ];
+        case "doctor":
+            return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];
+        case "notary":
+            return [
+                "--ak-role",
+                "notary",
+                "--ak-notary-source-run",
+                activation.sourceRun,
+                ...(activation.ticketNumber === undefined
+                    ? []
+                    : ["--ak-notary-ticket-number", String(activation.ticketNumber)]),
+            ];
+        case "countersign":
+            // ticketNumber rides activation/admission/invocation only (#632: no private flag).
+            return ["--ak-role", "countersign"];
+        case "gleaner-left":
+            return [
+                "--ak-role",
+                "gleaner-left",
+                "--ak-gleaner-left-base",
+                activation.baseRevision,
+            ];
+        case "inspector":
+            return ["--ak-role", "inspector"];
+        case "gatekeeper":
+            return ["--ak-role", "gatekeeper"];
+        case "navigator":
+            return ["--ak-role", "navigator"];
+        case "auditor":
+            return ["--ak-role", "auditor"];
+        case "evidence-child":
+            return ["--ak-role", "evidence-child"];
+        case "diarist":
+            return [
+                "--ak-role",
+                "diarist",
+                ...(activation.sourcesPath === undefined
+                    ? []
+                    : ["--ak-diarist-sources", activation.sourcesPath]),
+            ];
+        default: {
+            const _exhaustive = activation;
+            return _exhaustive;
+        }
+    }
+}
+function buildMethodArgs(methods) {
+    const skillArgs = [];
+    for (const method of methods) {
+        if (method.kind === "skill") {
+            skillArgs.push("--skill", method.path);
+        }
+    }
+    return skillArgs;
+}
+/**
+ * Translate a closed RoleTurnRequest into Pi argv after `--no-extensions -e entry`.
+ * Controlled session constants and session coordinates are adapter-internal.
+ */
+export function buildPiTurnExtraArgs(request, authority, extraPiArgs = []) {
+    const { sessionFile, sessionDirectory } = authority.decode(request.principal);
+    const prompt = request.continuation.kind === "initial" || request.continuation.kind === "resume"
+        ? request.continuation.prompt
+        : (() => {
+            const _exhaustive = request.continuation;
+            return _exhaustive;
+        })();
+    return [
+        "--no-skills",
+        ...buildMethodArgs(request.methods),
+        "--no-prompt-templates",
+        "--no-themes",
+        "--no-context-files",
+        "--session",
+        sessionFile,
+        "--session-dir",
+        sessionDirectory,
+        ...extraPiArgs,
+        ...buildActivationFlagArgs(request.activation),
+        "--mode",
+        "json",
+        ...buildSeatModelCliArgs(request.model),
+        prompt,
+    ];
+}
+const execFileAsync = promisify(execFile);
+async function resolveSelectedPi(command, cwd, env) {
+    const searchPath = env.PATH ?? (platform === "win32" ? (process.env.PATH ?? "") : "/usr/bin:/bin");
+    const candidates = isAbsolute(command) || command.includes("/")
+        ? [resolve(cwd, command)]
+        : searchPath.split(delimiter).map((dir) => resolve(cwd, dir, command));
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES")
+                continue;
+            throw new ExplicitInternalActivationError(`Pi executable resolution failed: ${String(error.message)}`, { knownCause: "activation", cause: error });
+        }
+        return await realpath(candidate);
+    }
+    throw new ExplicitInternalActivationError(`Pi executable not found: ${command}`, {
+        knownCause: "activation",
+    });
+}
+async function selectedPiIdentity(command, cwd, env) {
+    const executable = await resolveSelectedPi(command, cwd, env);
+    const { stdout } = await execFileAsync(executable, ["--version"], {
+        cwd,
+        env,
+        encoding: "utf8",
+    });
+    const version = stdout.trim();
+    if (version === "")
+        throw new Error(`Pi executable returned an empty version: ${executable}`);
+    return { executable, version };
+}
+/**
+ * Default child runner: canonically select `pi` on PATH (or PI_BINARY) and launch
+ * that exact file. Close settles exactly once for natural return / error / SIGTERM.
+ */
+export function createDefaultPiSpawnRunner(options) {
+    return async (args, spawnOptions) => {
+        const command = spawnOptions.env.PI_BINARY ?? "pi";
+        const piIdentity = await selectedPiIdentity(command, spawnOptions.cwd, spawnOptions.env);
+        return await new Promise((resolveResult, reject) => {
+            // Child stdout is discarded at the stdio seam (CLAUDE.md Role invocation
+            // evidence). Do not pipe or accumulate it. stderr stays piped for diagnostics.
+            const child = spawn(piIdentity.executable, [...args], {
+                cwd: spawnOptions.cwd,
+                env: spawnOptions.env,
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+            if (child.stderr === null) {
+                throw new Error("Pi child stderr pipe was not created");
+            }
+            let stderr = "";
+            let timedOut = false;
+            // No default wall clock. Only an explicit caller budget arms a timer (ADR 0010).
+            // SIGKILL is unconditionally forbidden — graceful SIGTERM only.
+            let timer;
+            let settled = false;
+            // `error` fires for pre-spawn failures (ENOENT after identity check is a
+            // true activation failure) or kill/dispatch errors. Retain it so `close`
+            // remains the SOLE settlement point (spec-B: child close once). Only
+            // fall back to rejecting on `error` if `close` never fires (e.g. spawn
+            // never succeeded so no `close` event will arrive).
+            let hasSpawned = false;
+            let executionError;
+            const armTimeoutAfterChildReady = () => {
+                if (spawnOptions.timeoutMs === undefined)
+                    return;
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                }, spawnOptions.timeoutMs);
+            };
+            // Parent cancellation reaches the nested activation: same graceful SIGTERM,
+            // same single close settlement. SIGKILL stays forbidden (#675 / ADR 0010).
+            const parentSignal = spawnOptions.signal;
+            const terminateForParentAbort = () => {
+                child.kill("SIGTERM");
+            };
+            parentSignal?.addEventListener("abort", terminateForParentAbort, { once: true });
+            let identityRecorded = Promise.resolve();
+            child.once("spawn", () => {
+                hasSpawned = true;
+                if (parentSignal?.aborted === true)
+                    terminateForParentAbort();
+                armTimeoutAfterChildReady();
+                const runDirectory = spawnOptions.env.AK_ROLE_RUN_DIR;
+                if (typeof runDirectory === "string" &&
+                    runDirectory !== "" &&
+                    options.recordLaunchedPiIdentity !== undefined) {
+                    identityRecorded = options.recordLaunchedPiIdentity(runDirectory, piIdentity);
+                }
+            });
+            child.stderr.setEncoding("utf8").on("data", (chunk) => {
+                stderr += chunk;
+            });
+            child.on("error", (error) => {
+                // A pre-spawn error has no child lifecycle to close. After spawn,
+                // retain the execution error and let the mandatory close event own
+                // cleanup and the single settlement.
+                if (settled || hasSpawned) {
+                    executionError = error;
+                    return;
+                }
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                parentSignal?.removeEventListener("abort", terminateForParentAbort);
+                settled = true;
+                reject(error);
+            });
+            child.on("close", (code) => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                parentSignal?.removeEventListener("abort", terminateForParentAbort);
+                void identityRecorded.then(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (executionError !== undefined) {
+                        reject(executionError);
+                        return;
+                    }
+                    resolveResult({
+                        code,
+                        stderr,
+                        timedOut,
+                    });
+                }, (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    reject(error);
+                });
+            });
+        });
+    };
+}
+/** Create the production Pi RoleTurnHost (composition-root assembly). */
+export function createPiRoleTurnHost(config) {
+    const spawnRunner = config.spawnRunner ??
+        createDefaultPiSpawnRunner({
+            ...(config.recordLaunchedPiIdentity === undefined
+                ? {}
+                : { recordLaunchedPiIdentity: config.recordLaunchedPiIdentity }),
+        });
+    return {
+        async executeTurn(request) {
+            // #617 DK-7: Pi argv gets projected native paths once; never record bytes.
+            // Pi already owns its own session file, so only sitian prior volume rides in.
+            let turnRequest = request;
+            const paths = request.hostTransition?.priorNativeKind === "sitian"
+                ? request.hostTransition.priorNativePaths
+                : undefined;
+            if (request.continuation.kind === "resume"
+                && paths !== undefined
+                && paths.length > 0) {
+                turnRequest = {
+                    ...request,
+                    continuation: {
+                        ...request.continuation,
+                        prompt: `${request.continuation.prompt}\n${paths.join("\n")}`,
+                    },
+                };
+            }
+            const roleEntry = await realpath(resolveInternalRoleEntrypoint(config.packageRoot));
+            const extraArgs = buildPiTurnExtraArgs(turnRequest, config.principalAuthority, config.extraPiArgs ?? []);
+            const args = buildExplicitInternalActivationArgs(roleEntry, extraArgs);
+            // Shared envelope isolates this call's court identity: omitting courtAttemptId
+            // must not inherit a parent process.env.AK_ROLE_COURT_ATTEMPT (#637).
+            const env = {
+                ...process.env,
+                HOME: request.home,
+                PI_CODING_AGENT_DIR: request.agentDir,
+                AK_ROLE_RUN_DIR: request.runDirectory,
+                // Nested public summons resolve package root without import.meta under jiti (#675).
+                // Child-process scoped only — not written back onto the parent process.env.
+                AK_ROLE_PACKAGE_ROOT: config.packageRoot,
+            };
+            if (request.courtAttemptId === undefined)
+                delete env.AK_ROLE_COURT_ATTEMPT;
+            else
+                env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
+            applyEngineChildEnv(env, request.engine);
+            // Nested auditor dossier tool binds the parent run pointer when published.
+            if (typeof process.env.AK_ROLE_AUDITOR_SOURCE_RUN === "string"
+                && process.env.AK_ROLE_AUDITOR_SOURCE_RUN.trim() !== "") {
+                env.AK_ROLE_AUDITOR_SOURCE_RUN = process.env.AK_ROLE_AUDITOR_SOURCE_RUN;
+            }
+            // Audited-subject input selects soul materials (same for nested and direct).
+            if (typeof process.env.AK_ROLE_AUDITOR_SUBJECT === "string"
+                && process.env.AK_ROLE_AUDITOR_SUBJECT.trim() !== "") {
+                env.AK_ROLE_AUDITOR_SUBJECT = process.env.AK_ROLE_AUDITOR_SUBJECT;
+            }
+            if (request.correlationId !== undefined && request.correlationId.trim() !== "") {
+                env.AK_CORRELATION_ID = request.correlationId;
+            }
+            if (config.recordLaunchedRolePackageIdentity !== undefined &&
+                config.observeLaunchedRolePackageIdentity !== undefined) {
+                await config.recordLaunchedRolePackageIdentity(request.runDirectory, await config.observeLaunchedRolePackageIdentity(config.packageRoot, roleEntry));
+            }
+            const timeoutMs = request.timeoutMs ?? config.timeoutMs;
+            return await spawnRunner(args, {
+                cwd: request.cwd,
+                env,
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+        },
+    };
+}
+import { sitianReport } from "../sitian-facade.js";
+/**
+ * Append one custom JSONL entry to the durable principal's session file.
+ * Pi session codec only — AK artifact O_EXCL retention stays in public-cli.
+ */
+export async function appendPiSessionCustomEntry(authority, principal, customType, data) {
+    const { sessionFile } = authority.decode(principal);
+    const text = await readFile(sessionFile, "utf8");
+    let parentId = null;
+    for (const line of text.trim().split("\n").filter(Boolean)) {
+        const entry = JSON.parse(line);
+        if (typeof entry.id === "string" && entry.type !== "session")
+            parentId = entry.id;
+    }
+    const timestamp = new Date().toISOString();
+    const pointerLine = `${JSON.stringify({
+        type: "custom",
+        customType,
+        data,
+        id: randomUUID(),
+        parentId,
+        timestamp,
+    })}\n`;
+    await appendFile(sessionFile, pointerLine, "utf8");
+    try {
+        sitianReport({
+            level: "event",
+            kind: "dispatch-error",
+            sessionParent: sessionFile,
+            payload: { customType, data },
+            source: "pi-role-turn-host",
+        });
+    }
+    catch { }
+}