@akagilnc/pi-workflow-roles 0.1.2048 → 0.1.2052

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2048",
+  "version": "0.1.2052",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/engines/codex.md

@@ -0,0 +1,32 @@
+# codex engine method material
+
+This file is packaged method material for the optional `codex` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Codex CLI)
+
+Non-interactive labor prompt (working root = role project):
+
+```bash
+codex exec -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Write the last agent message to a file, then bring that text back into the role
+session:
+
+```bash
+codex exec -C "$PROJECT_ROOT" -o /tmp/codex-labor-last.txt "YOUR_LABOR_PROMPT"
+```
+
+JSON event stream when the host needs machine-readable progress:
+
+```bash
+codex exec --json -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Prefer the installed `codex` binary's own `--help` / `codex exec --help` over
+any remembered flag set. Do not wrap this engine behind `ak-role` flags.

package/resources/engines/cursor.md

@@ -0,0 +1,32 @@
+# cursor engine method material
+
+This file is packaged method material for the optional `cursor` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Cursor Agent CLI)
+
+The machine entrypoint is `agent` (also exposed as `cursor-agent`). Run from the
+role project root. Non-interactive print mode:
+
+```bash
+agent -p --force --output-format text "YOUR_LABOR_PROMPT"
+```
+
+Choose a model explicitly when the seat needs a known Cursor model id:
+
+```bash
+agent -p --force --model grok-4.5 --output-format text "YOUR_LABOR_PROMPT"
+```
+
+Stream JSON events for long labor:
+
+```bash
+agent -p --force --output-format stream-json "YOUR_LABOR_PROMPT"
+```
+
+Prefer `agent --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.

package/resources/engines/kimi.md

@@ -0,0 +1,31 @@
+# kimi engine method material
+
+This file is packaged method material for the optional `kimi` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Kimi Code CLI)
+
+One-shot non-interactive prompt from the role project root:
+
+```bash
+kimi --yolo -p "YOUR_LABOR_PROMPT"
+```
+
+Pin a model alias when needed:
+
+```bash
+kimi --yolo -m <model-alias> -p "YOUR_LABOR_PROMPT"
+```
+
+Machine-readable prompt mode:
+
+```bash
+kimi --yolo --output-format text -p "YOUR_LABOR_PROMPT"
+```
+
+Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.

package/src/package-resources/engine-material.ts

@@ -0,0 +1,111 @@
+/**
+ * Packaged engine method-material seam (#356 T1 / ADR 0069).
+ * Legal engine names = directory stems under resources/engines/ — no code whitelist.
+ * Material body is data for the LLM, not a code contract.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const ENGINE_MATERIAL_RELATIVE_ROOT = "resources/engines" as const;
+
+export type EngineSessionMaterial = Readonly<{
+  name: string;
+  materialPath: string;
+}>;
+
+/** Non-empty, trimmed, no path separators or traversal. */
+export function isEngineNameSyntax(name: string): boolean {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.trim() !== name) return false;
+  if (name === "." || name === "..") return false;
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) return false;
+  if (name.includes("..")) return false;
+  return true;
+}
+
+export function engineMaterialRelativeDirectory(): string {
+  return ENGINE_MATERIAL_RELATIVE_ROOT;
+}
+
+export function resolveEngineMaterialDirectory(packageRoot: string): string {
+  return join(packageRoot, ENGINE_MATERIAL_RELATIVE_ROOT);
+}
+
+/**
+ * Enumerate legal engine names from packaged material files.
+ * Only `*.md` stems that pass name syntax are legal.
+ */
+export function listEngineMaterialNames(packageRoot: string): readonly string[] {
+  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]);
+}
+
+export function resolveEngineMaterialPath(
+  packageRoot: string,
+  name: string,
+): string {
+  const legal = assertLegalEngineName(packageRoot, name);
+  return join(resolveEngineMaterialDirectory(packageRoot), `${legal}.md`);
+}
+
+/**
+ * Assert `name` is a legal engine material stem under packageRoot.
+ * Returns the canonical name on success; throws Error on illegal.
+ */
+export function assertLegalEngineName(packageRoot: string, name: string): string {
+  if (!isEngineNameSyntax(name)) {
+    throw new Error(`illegal engine name: ${name}`);
+  }
+  const legal = listEngineMaterialNames(packageRoot);
+  if (!legal.includes(name)) {
+    throw new Error(
+      `unknown engine: ${name} (known: ${legal.length === 0 ? "(none)" : legal.join(", ")})`,
+    );
+  }
+  return name;
+}
+
+/**
+ * Resolve optional engine options into session material coordinates.
+ * No engine → undefined (caller keeps default prompt bytes).
+ */
+export function engineSessionMaterialFromOptions(options: {
+  engine?: string;
+  packageRoot?: string;
+}): EngineSessionMaterial | undefined {
+  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.packageRoot, options.engine);
+  return Object.freeze({
+    name,
+    materialPath: resolveEngineMaterialPath(options.packageRoot, name),
+  });
+}
+
+/**
+ * Append engine method-material path delivery to session initial material lines.
+ * No material → identity copy (byte-stable when joined the same way).
+ * Delivers engine name + absolute material path only — never material body.
+ */
+export function appendEngineSessionMaterial(
+  lines: readonly string[],
+  engineMaterial?: EngineSessionMaterial,
+): string[] {
+  if (engineMaterial === undefined) {
+    return [...lines];
+  }
+  const out = [...lines];
+  out.push("");
+  out.push("Engine method material (read these bytes and follow them):");
+  out.push(`- engine: ${engineMaterial.name}`);
+  out.push(`- ${engineMaterial.materialPath}`);
+  return out;
+}

package/src/public-cli/cli.ts

@@ -5,6 +5,9 @@ import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import {
+  assertLegalEngineName,
+} from "../package-resources/engine-material.ts";
 import {
   effectiveSeatConfigurations,
   formatModelSpec,
@@ -14,6 +17,8 @@ import {
   resolveEffectiveSeat,
   savePublicCliConfig,
   setPersistentSeatConfig,
+  setPersistentSeatEngine,
+  validatePublicCliConfigEngines,
   type CredentialProviders,
   type EffectiveSeat,
   type InvocationModelOverride,
@@ -94,7 +99,8 @@ export const PUBLIC_GLOBAL_OPTIONS: readonly PublicOptionDefinition[] =
 type TakenPublicGlobalFlag =
   | { flag: "help"; consume: 1 }
   | { flag: "model"; consume: 1 | 2; value: string | undefined }
-  | { flag: "thinking"; consume: 1 | 2; raw: string | undefined };
+  | { flag: "thinking"; consume: 1 | 2; raw: string | undefined }
+  | { flag: "engine"; consume: 1 | 2; value: string | undefined };
 
 /**
  * If `argv[index]` is a public global flag, describe its span and payload.
@@ -127,6 +133,13 @@ function takePublicGlobalFlag(
       raw: taken.value,
     };
   }
+  if (taken.def.id === "engine") {
+    return {
+      flag: "engine",
+      consume: consumed as 1 | 2,
+      value: taken.value,
+    };
+  }
   return undefined;
 }
 
@@ -217,6 +230,7 @@ type ParsedGlobal = {
   args: string[];
   model?: string;
   thinking?: PublicThinkingLevel;
+  engine?: string;
   help: boolean;
 };
 
@@ -231,6 +245,7 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
   const args = [...argv];
   let model: string | undefined;
   let thinking: PublicThinkingLevel | undefined;
+  let engine: string | undefined;
   let help = false;
   const positional: string[] = [];
   const globalOptions = createTypedOptionConsumer(PUBLIC_GLOBAL_OPTIONS);
@@ -259,12 +274,24 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
         args.splice(0, taken.consume);
         continue;
       }
-      if (taken.raw === undefined) {
-        throw new CliUsageError("--thinking requires a value");
+      if (taken.flag === "thinking") {
+        if (taken.raw === undefined) {
+          throw new CliUsageError("--thinking requires a value");
+        }
+        thinking = parseThinking(taken.raw);
+        args.splice(0, taken.consume);
+        continue;
+      }
+      if (taken.flag === "engine") {
+        if (taken.value === undefined) {
+          throw new CliUsageError("--engine requires a value");
+        }
+        engine = taken.value;
+        args.splice(0, taken.consume);
+        continue;
       }
-      thinking = parseThinking(taken.raw);
-      args.splice(0, taken.consume);
-      continue;
+      // Exhaustive for known global flags; unknown id is a table bug.
+      throw new CliUsageError(`unhandled global option: ${String((taken as { flag: string }).flag)}`);
     }
     // Subcommands may own additional flags later; unknown dashed tokens stay
     // positional here (same as pre-unification parseArgv).
@@ -277,18 +304,54 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
     args: rest,
     ...(model === undefined ? {} : { model }),
     ...(thinking === undefined ? {} : { thinking }),
+    ...(engine === undefined ? {} : { engine }),
     help,
   };
 }
 
 function invocationFromParsed(parsed: ParsedGlobal): InvocationModelOverride | undefined {
-  if (parsed.model === undefined && parsed.thinking === undefined) return undefined;
+  if (
+    parsed.model === undefined &&
+    parsed.thinking === undefined &&
+    parsed.engine === undefined
+  ) {
+    return undefined;
+  }
   return {
     ...(parsed.model === undefined ? {} : { model: parsed.model }),
     ...(parsed.thinking === undefined ? {} : { thinking: parsed.thinking }),
+    ...(parsed.engine === undefined ? {} : { engine: parsed.engine }),
   };
 }
 
+function requireLegalEngineName(packageRoot: string, name: string): string {
+  try {
+    return assertLegalEngineName(packageRoot, name);
+  } catch (error) {
+    throw new CliUsageError(
+      error instanceof Error ? error.message : String(error),
+      { cause: error },
+    );
+  }
+}
+
+function loadAndValidateConfig(
+  home: string,
+  packageRoot: string,
+): Promise<PublicCliConfig> {
+  return loadPublicCliConfig(home).then((config) => {
+    try {
+      validatePublicCliConfigEngines(config, packageRoot);
+    } catch (error) {
+      throw new CliUsageError(
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      );
+    }
+    return config;
+  });
+}
+
 /** Typed facts used by help presentation — not layout. */
 export function helpDocument() {
   return {
@@ -355,6 +418,7 @@ function renderHelp(): string {
     "",
     "Role options: ak-role help <command>",
     "Persistent config: ak-role config set <seat> <provider/model:thinking>",
+    "Persistent engine (judge only): ak-role config set-engine judge <name> | unset-engine judge",
     "Effective seats: ak-role roles",
   );
   return `${lines.join("\n")}\n`;
@@ -398,7 +462,7 @@ function renderRoles(seats: readonly EffectiveSeat[]): string {
 }
 
 function renderConfig(config: PublicCliConfig): string {
-  const lines: string[] = ["seat\tmodel"];
+  const lines: string[] = ["seat\tmodel\tengine"];
   const keys = Object.keys(config.seats) as (keyof typeof config.seats)[];
   if (keys.length === 0) {
     lines.push("(empty)");
@@ -406,7 +470,8 @@ function renderConfig(config: PublicCliConfig): string {
     for (const seat of keys.sort()) {
       const selection = config.seats[seat];
       if (selection === undefined) continue;
-      lines.push(`${seat}\t${formatModelSpec(selection)}`);
+      const engine = selection.engine === undefined ? "-" : selection.engine;
+      lines.push(`${seat}\t${formatModelSpec(selection)}\t${engine}`);
     }
   }
   return `${lines.join("\n")}\n`;
@@ -415,10 +480,11 @@ function renderConfig(config: PublicCliConfig): string {
 async function runConfigCommand(
   args: readonly string[],
   home: string,
+  packageRoot: string,
   io: CliIo,
 ): Promise<number> {
   if (args.length === 0 || args[0] === "get" || args[0] === "list" || args[0] === "show") {
-    const config = await loadPublicCliConfig(home);
+    const config = await loadAndValidateConfig(home, packageRoot);
     if (args[0] === "get" && args[1] !== undefined) {
       if (!isPublicConfigurableSeat(args[1])) {
         throw new CliUsageError(`unknown configurable seat: ${args[1]}`);
@@ -427,7 +493,9 @@ async function runConfigCommand(
       if (selection === undefined) {
         io.stdout(`${args[1]}\t(unconfigured)\n`);
       } else {
-        io.stdout(`${args[1]}\t${formatModelSpec(selection)}\n`);
+        const engine =
+          selection.engine === undefined ? "-" : selection.engine;
+        io.stdout(`${args[1]}\t${formatModelSpec(selection)}\t${engine}\n`);
       }
       return 0;
     }
@@ -448,7 +516,7 @@ async function runConfigCommand(
         "config set requires seat/spec pairs: ak-role config set <seat> <spec> [<seat> <spec> ...]",
       );
     }
-    let config = await loadPublicCliConfig(home);
+    let config = await loadAndValidateConfig(home, packageRoot);
     for (let i = 0; i < pairs.length; i += 2) {
       const seat = pairs[i]!;
       const spec = pairs[i + 1]!;
@@ -462,6 +530,66 @@ async function runConfigCommand(
     return 0;
   }
 
+  if (args[0] === "set-engine") {
+    if (args.length !== 3) {
+      throw new CliUsageError(
+        "usage: ak-role config set-engine judge <name>",
+      );
+    }
+    const seat = args[1]!;
+    const name = args[2]!;
+    if (!isPublicConfigurableSeat(seat)) {
+      throw new CliUsageError(`unknown configurable seat: ${seat}`);
+    }
+    if (seat !== "judge") {
+      throw new CliUsageError(
+        `engine axis is judge-only; refused seat ${seat}`,
+      );
+    }
+    requireLegalEngineName(packageRoot, name);
+    let config = await loadAndValidateConfig(home, packageRoot);
+    try {
+      config = setPersistentSeatEngine(config, seat, name);
+    } catch (error) {
+      throw new CliUsageError(
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      );
+    }
+    await savePublicCliConfig(config, home);
+    io.stdout(renderConfig(config));
+    return 0;
+  }
+
+  if (args[0] === "unset-engine") {
+    if (args.length !== 2) {
+      throw new CliUsageError(
+        "usage: ak-role config unset-engine judge",
+      );
+    }
+    const seat = args[1]!;
+    if (!isPublicConfigurableSeat(seat)) {
+      throw new CliUsageError(`unknown configurable seat: ${seat}`);
+    }
+    if (seat !== "judge") {
+      throw new CliUsageError(
+        `engine axis is judge-only; refused seat ${seat}`,
+      );
+    }
+    let config = await loadAndValidateConfig(home, packageRoot);
+    try {
+      config = setPersistentSeatEngine(config, seat, undefined);
+    } catch (error) {
+      throw new CliUsageError(
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      );
+    }
+    await savePublicCliConfig(config, home);
+    io.stdout(renderConfig(config));
+    return 0;
+  }
+
   throw new CliUsageError(`unknown config subcommand: ${args[0]}`);
 }
 
@@ -477,6 +605,21 @@ export async function runAkRole(
     // runtime entry, activation argv, or invocation provenance is derived.
     env = { ...env, packageRoot: await realpath(env.packageRoot) };
     const parsed = parseArgv(argv);
+    // Invocation --engine rejects at the call-request seam (not role submission).
+    // #356 MVP: engine axis is Judge-only (not resume / non-Judge seats).
+    if (parsed.engine !== undefined) {
+      requireLegalEngineName(env.packageRoot, parsed.engine);
+      if (
+        !parsed.help &&
+        parsed.command !== undefined &&
+        parsed.command !== "help" &&
+        parsed.command !== "judge"
+      ) {
+        throw new CliUsageError(
+          `engine axis is judge-only; refused command ${parsed.command}`,
+        );
+      }
+    }
 
     if (
       parsed.help ||
@@ -501,7 +644,7 @@ export async function runAkRole(
       if (parsed.args.length > 0) {
         throw new CliUsageError("roles takes no arguments");
       }
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ??
         (await loadCredentialProviders(resolveAgentDir(env, home)));
@@ -515,7 +658,9 @@ export async function runAkRole(
     }
 
     if (parsed.command === "config") {
-      return { exitCode: await runConfigCommand(parsed.args, home, io) };
+      return {
+        exitCode: await runConfigCommand(parsed.args, home, env.packageRoot, io),
+      };
     }
 
     // Resume reopens an exact Role run after a typed HTTP 429 (#108/#109).
@@ -523,7 +668,7 @@ export async function runAkRole(
     if (parsed.command === "resume") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const resumeRunId = parsed.args[0];
@@ -706,7 +851,7 @@ export async function runAkRole(
     if (parsed.command === "judge") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -728,6 +873,7 @@ export async function runAkRole(
             : { correlationId: env.correlationId }),
           ...(env.piRunner === undefined ? {} : { piRunner: env.piRunner }),
           ...(seat.selection === undefined ? {} : { model: seat.selection }),
+          ...(seat.engine === undefined ? {} : { engine: seat.engine }),
           ...(env.judgeExtraPiArgs === undefined
             ? {}
             : { extraPiArgs: env.judgeExtraPiArgs }),
@@ -749,7 +895,7 @@ export async function runAkRole(
     if (parsed.command === "coder") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -792,7 +938,7 @@ export async function runAkRole(
     if (parsed.command === "fixer") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -835,7 +981,7 @@ export async function runAkRole(
     if (parsed.command === "collector") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -878,7 +1024,7 @@ export async function runAkRole(
     if (parsed.command === "reviewer") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -921,7 +1067,7 @@ export async function runAkRole(
     if (parsed.command === "doctor") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(
@@ -964,7 +1110,7 @@ export async function runAkRole(
     if (parsed.command === "merger") {
       const agentDir = resolveAgentDir(env, home);
       const cwd = env.cwd ?? process.cwd();
-      const config = await loadPublicCliConfig(home);
+      const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ?? (await loadCredentialProviders(agentDir));
       const seat = resolveEffectiveSeat(