@akagilnc/pi-workflow-roles 0.1.2086 → 0.1.2091

package/README.md

@@ -114,7 +114,7 @@ Generated from `src/public-cli/option-definitions.ts`. Prefer `ak-role help <com
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `--model` | — | `provider/model` | no | no | option | — | Override the effective seat model for this invocation (before or after the command). |
 | `--thinking` | — | `level` | no | no | option | — | Override thinking level: off\|minimal\|low\|medium\|high\|xhigh\|max. |
-| `--engine` | — | `name` | no | no | option | — | Optional Judge labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge-only). |
+| `--engine` | — | `name` | no | no | option | — | Optional Judge/Reviewer labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge+reviewer only). |
 | `--help` | `-h` | — | no | no | option | — | Show public CLI help and exit. |
 
 ### `judge`

package/README.zh-CN.md

@@ -143,7 +143,7 @@ Codex fast 档：开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `--model` | — | `provider/model` | 否 | 否 | option | — | 覆盖本调用有效席位模型（可置于子命令前或后）。 |
 | `--thinking` | — | `level` | 否 | 否 | option | — | 覆盖 thinking 档位：off\|minimal\|low\|medium\|high\|xhigh\|max。 |
-| `--engine` | — | `name` | 否 | 否 | option | — | 本调用可选 Judge 劳动引擎（池令名字；有包内调法笔记则附卷；仅 Judge）。 |
+| `--engine` | — | `name` | 否 | 否 | option | — | 本调用可选 Judge/Reviewer 劳动引擎（池令名字；有包内调法笔记则附卷；仅 Judge+Reviewer）。 |
 | `--help` | `-h` | — | 否 | 否 | option | — | 显示公开 CLI 帮助并退出。 |
 
 ### `judge`

package/dist/engine-detour-tool.js

@@ -0,0 +1,93 @@
+import { Type } from "typebox";
+import { ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC, ENGINE_DETOUR_TOOL_NAME, engineDetourFailureDiagnostic, engineNameFromEnv, isEngineDetourFailure, runEngineDetourOnce, } from "./engine-detour.js";
+import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.js";
+const engineDetourArgsSchema = Type.Object({
+    argv: Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        description: "Executable argv for one engine subprocess. First element is the command (PATH lookup); remaining elements are arguments. Build argv from the host CLI actual interface for the configured engine name; when optional packaged notes are present in the session prompt, follow those bytes. Do not invent package flags.",
+    }),
+}, { additionalProperties: false });
+/**
+ * Build one once-latch detour tool definition for a configured engine name.
+ * `latch` is shared so parent registration can reset between activations.
+ * `fail` owns host abort (parent) vs throw (evidence child).
+ */
+export function createEngineDetourToolDefinition(input) {
+    const latch = input.latch ?? { used: false };
+    const engineName = input.engineName;
+    return wrapPackageOwnedToolDefinition({
+        name: ENGINE_DETOUR_TOOL_NAME,
+        label: "Engine Detour",
+        description: `Run one labor-engine subprocess (engine=${engineName}) and return its stdout to this session. Call at most once per activation. Build argv from the host CLI actual interface for this engine name; when optional packaged notes are present in the session prompt, follow those bytes too.`,
+        promptSnippet: "Run the configured labor engine once and return its stdout",
+        promptGuidelines: [
+            `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once for the configured engine (${engineName}). Optional packaged notes are guidance when present; a bare engine name alone is also a valid call path.`,
+            "Pass argv for the host CLI of this engine name — first element is the executable name on PATH. Follow optional packaged notes when delivered; otherwise act from the engine name and the host CLI actual interface. Do not invent package flags.",
+            "On success, use the returned stdout as labor content for the existing typed submission / report path.",
+        ],
+        parameters: engineDetourArgsSchema,
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
+            if (latch.used) {
+                input.fail(new Error(ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC), toolCallId, ctx);
+            }
+            latch.used = true;
+            const args = params;
+            const argv = Array.isArray(args.argv) ? args.argv : [];
+            if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
+                input.fail(new Error("engine detour argv must be a non-empty string array"), toolCallId, ctx);
+            }
+            let result;
+            try {
+                result = await runEngineDetourOnce({
+                    argv,
+                    cwd: ctx.cwd,
+                    ...(signal === undefined ? {} : { signal }),
+                });
+            }
+            catch (error) {
+                input.fail(error instanceof Error ? error : new Error(String(error)), toolCallId, ctx);
+            }
+            if (isEngineDetourFailure(result)) {
+                input.fail(new Error(engineDetourFailureDiagnostic(result)), toolCallId, ctx);
+            }
+            return {
+                content: [{ type: "text", text: result.stdout }],
+                details: {
+                    tool: ENGINE_DETOUR_TOOL_NAME,
+                    code: result.code,
+                },
+            };
+        },
+    });
+}
+/**
+ * Register the engine-generic detour tool once for this process when Judge/Reviewer has
+ * an engine activation signal. Returns whether registration occurred.
+ * Once-latch is activation-scoped via the returned reset handle.
+ */
+export function registerEngineDetourTool(pi, hostActions) {
+    const engineName = engineNameFromEnv();
+    if (engineName === undefined) {
+        return {
+            registered: false,
+            resetLatch() {
+                /* no-op when unregistered */
+            },
+        };
+    }
+    const latch = { used: false };
+    const definition = createEngineDetourToolDefinition({
+        engineName,
+        latch,
+        fail(error, toolCallId, ctx) {
+            hostActions.failInfrastructure(error, ctx, toolCallId);
+        },
+    });
+    pi.registerTool(definition);
+    return {
+        registered: true,
+        resetLatch() {
+            latch.used = false;
+        },
+    };
+}

package/dist/engine-detour.js

@@ -0,0 +1,76 @@
+/**
+ * Engine-generic one-shot subprocess detour (#357 T2 / ADR 0069).
+ * Spawn once; no retry, hang surface, or per-engine branch.
+ * Material body is LLM data — this module only executes argv the model assembled.
+ */
+import { spawn } from "node:child_process";
+/** Package-owned detour tool name (settlement whitelist + session principal). */
+export const ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour";
+/** Env presence/name signal injected by public Judge run (registration gate only). */
+export const AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE";
+export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC = "engine detour produced empty stdout";
+export const ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC = "engine detour already used in this activation";
+/**
+ * Run one engine subprocess. First argv element is the executable (PATH lookup).
+ * stdio: ignore stdin, pipe stdout+stderr. No shell, no retry, no hang timer.
+ */
+export async function runEngineDetourOnce(input) {
+    if (input.argv.length === 0) {
+        throw new Error("engine detour argv must be non-empty");
+    }
+    const command = input.argv[0];
+    const args = input.argv.slice(1);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const child = spawn(command, args, {
+            cwd: input.cwd,
+            env: input.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8").on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        child.on("error", (error) => fail(error));
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+/** Failure predicate: nonzero exit OR stdout trim-empty (including whitespace-only). */
+export function isEngineDetourFailure(result) {
+    return result.code !== 0 || result.stdout.trim() === "";
+}
+/**
+ * Diagnostic string for shared settlement / Terminal Error Artifact.
+ * Prefer engine stderr 原样; whitespace-only/empty stderr is absent → stable fallback.
+ */
+export function engineDetourFailureDiagnostic(result) {
+    if (result.stderr.trim().length > 0)
+        return result.stderr;
+    if (result.stdout.trim() === "")
+        return ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC;
+    return `engine detour exited with code ${result.code}`;
+}
+/** Non-empty trimmed engine name from process.env, else undefined. */
+export function engineNameFromEnv() {
+    const raw = process.env[AK_ROLE_ENGINE_ENV];
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/evidence-child-executor.js

@@ -8,19 +8,23 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createAssistantMessageEventStream, InMemoryCredentialStore, } from "@earendil-works/pi-ai";
 import { AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE, AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE, prepareComplianceDispatch, } from "./compliance-transport.js";
+import { createEngineDetourToolDefinition } from "./engine-detour-tool.js";
+import { engineNameFromEnv } from "./engine-detour.js";
+import { appendEngineSessionMaterial, engineSessionMaterialFromOptions, } from "./package-resources/engine-material.js";
 import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.js";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.js";
 import { REVIEWER_VERIFICATION_BOUNDARY } from "./reviewer-construction.js";
 import { createStreamIdleGuard, isStreamIdleTimeoutError } from "./stream-idle-guard.js";
 import { hasUpstreamErrorTestimony, isNonSuccessHttpStatus, projectConfirmedRemotePayload, } from "./upstream-error-testimony.js";
 /** Package-owned system prompt for Reviewer Standards/Spec evidence children (private carrier). */
-function buildEvidenceChildSystemPrompt() {
-    return [
+function buildEvidenceChildSystemPrompt(engineMaterial) {
+    const lines = [
         "Work only in the supplied workspace.",
         "Use the available evidence tools to investigate. Do not commit, push, or mutate remotes.",
         REVIEWER_VERIFICATION_BOUNDARY,
         "Return one substantive non-blank report.",
-    ].join("\n");
+    ];
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 // ── shared constants / types ──────────────────────────────────────────────
 export const AUDITOR_TURN_LIMIT = 32;
@@ -456,6 +460,30 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
         catch (error) {
             throw classifiedError(error, "provider");
         }
+        // #378: when labor engine is configured, legs get the same detour tool + material
+        // dual-path as the parent seat (ADR 0069 detour-rejoins-main-road).
+        const engineName = engineNameFromEnv();
+        const engineMaterial = engineName === undefined
+            ? undefined
+            : options.packageRoot === undefined || options.packageRoot.trim() === ""
+                // Name-only when package root is unavailable (still a valid #376 path).
+                ? Object.freeze({ name: engineName })
+                : engineSessionMaterialFromOptions({
+                    engine: engineName,
+                    packageRoot: options.packageRoot,
+                });
+        // #378: detour failure is durable for this leg — later assistant reports cannot wash it.
+        let engineDetourFailure;
+        const engineDetourTool = engineName === undefined
+            ? undefined
+            : createEngineDetourToolDefinition({
+                engineName,
+                fail(error) {
+                    const failure = error instanceof Error ? error : new Error(String(error));
+                    engineDetourFailure = failure;
+                    throw failure;
+                },
+            });
         // No tools allowlist — Pi defaults + unrestricted evidence surface (ADR 0064).
         // Single createAgentSession owner: in-process-session.ts.
         const { session, dispose } = await openInProcessAgentSession({
@@ -464,7 +492,10 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
             model: inherited.model,
             thinkingLevel: context.thinkingLevel ?? "off",
             modelRuntime: inherited.runtime,
-            systemPrompt: buildEvidenceChildSystemPrompt(),
+            systemPrompt: buildEvidenceChildSystemPrompt(engineMaterial),
+            ...(engineDetourTool === undefined
+                ? {}
+                : { customTools: [engineDetourTool] }),
             sessionManager: createRecordSession({
                 cwd: workspace,
                 kind: "evidence-children",
@@ -489,8 +520,18 @@ export async function executeEvidenceChild(workspace, prompt, context, options =
                 await session.prompt(delivered);
             }
             catch (error) {
+                // Engine detour fail becomes isError toolResult and must outrank a later
+                // provider-shaped throw from the same prompt turn (#378).
+                if (engineDetourFailure !== undefined) {
+                    throw classifiedError(engineDetourFailure, "child");
+                }
                 throw classifiedError(error, "provider");
             }
+            // Launched-leg detour non-zero / empty stdout / spawn failure is infrastructure:
+            // reject the leg even when the model still emits a non-blank report afterward.
+            if (engineDetourFailure !== undefined) {
+                throw classifiedError(engineDetourFailure, "child");
+            }
             if (signal?.aborted)
                 throw new Error("Evidence child was cancelled");
             const lastAssistant = [...session.messages]

package/dist/package-resources/engine-material.js

@@ -0,0 +1,105 @@
+/**
+ * Packaged engine method-material seam (#356 T1 / ADR 0069 / #376).
+ * Engine names are owner pool-directive labels — not a closed material catalog.
+ * Material body is optional data for the LLM, not a code contract.
+ * Only path-safety syntax is checked at real I/O seams.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const ENGINE_MATERIAL_RELATIVE_ROOT = "resources/engines";
+/** Non-empty, trimmed; reject only real path hazards at the I/O seam. */
+export function isEngineNameSyntax(name) {
+    if (typeof name !== "string")
+        return false;
+    if (name.length === 0 || name.trim() !== name)
+        return false;
+    // Exact "." / ".." are directory aliases; consecutive dots inside a label are not.
+    if (name === "." || name === "..")
+        return false;
+    if (name.includes("/") || name.includes("\\") || name.includes("\0"))
+        return false;
+    return true;
+}
+export function engineMaterialRelativeDirectory() {
+    return ENGINE_MATERIAL_RELATIVE_ROOT;
+}
+export function resolveEngineMaterialDirectory(packageRoot) {
+    return join(packageRoot, ENGINE_MATERIAL_RELATIVE_ROOT);
+}
+/**
+ * Enumerate packaged engine notes stems (discovery only — not a legal-name gate).
+ * Only `*.md` stems that pass name syntax are listed.
+ */
+export function listEngineMaterialNames(packageRoot) {
+    const dir = resolveEngineMaterialDirectory(packageRoot);
+    if (!existsSync(dir))
+        return Object.freeze([]);
+    const names = readdirSync(dir)
+        .filter((entry) => entry.endsWith(".md"))
+        .map((entry) => entry.slice(0, -".md".length))
+        .filter((stem) => isEngineNameSyntax(stem))
+        .sort();
+    return Object.freeze([...names]);
+}
+/**
+ * Build the packaged notes path for a syntax-legal engine name.
+ * Does not require the file to exist (material is optional data).
+ */
+export function resolveEngineMaterialPath(packageRoot, name) {
+    const legal = assertLegalEngineName(name);
+    return join(resolveEngineMaterialDirectory(packageRoot), `${legal}.md`);
+}
+/**
+ * Path-safety syntax gate for engine labels at real I/O seams.
+ * Returns the canonical name on success; throws Error on illegal syntax.
+ * Does not consult any material catalog (ADR 0069 pool-directive axis).
+ */
+export function assertLegalEngineName(name) {
+    if (!isEngineNameSyntax(name)) {
+        throw new Error(`illegal engine name: ${name}`);
+    }
+    return name;
+}
+/**
+ * Resolve optional engine options into session material coordinates.
+ * No engine → undefined (caller keeps default prompt bytes).
+ * Engine with packaged notes → name + absolute material path.
+ * Engine without notes → name only (pass-through; no warning).
+ */
+export function engineSessionMaterialFromOptions(options) {
+    if (options.engine === undefined)
+        return undefined;
+    if (options.packageRoot === undefined || options.packageRoot.trim() === "") {
+        throw new Error("packageRoot is required when engine is configured");
+    }
+    const name = assertLegalEngineName(options.engine);
+    const materialPath = resolveEngineMaterialPath(options.packageRoot, name);
+    if (existsSync(materialPath)) {
+        return Object.freeze({ name, materialPath });
+    }
+    return Object.freeze({ name });
+}
+/**
+ * Append engine method-material delivery to session initial material lines.
+ * No engine → identity copy (byte-stable when joined the same way).
+ * With notes → read-these-bytes header + engine name + absolute material path.
+ * Name only → engine name coordinate only (no read-these-bytes header, no path, no warning).
+ * Never delivers material body.
+ */
+export function appendEngineSessionMaterial(lines, engineMaterial) {
+    if (engineMaterial === undefined) {
+        return [...lines];
+    }
+    const out = [...lines];
+    out.push("");
+    if (engineMaterial.materialPath !== undefined) {
+        out.push("Engine method material (read these bytes and follow them):");
+        out.push(`- engine: ${engineMaterial.name}`);
+        out.push(`- ${engineMaterial.materialPath}`);
+    }
+    else {
+        // Name-only pass-through: no packaged bytes to read.
+        out.push(`- engine: ${engineMaterial.name}`);
+    }
+    return out;
+}