@akagilnc/pi-workflow-roles 0.1.2096 → 0.1.2105

package/dist/public-cli/main.js

@@ -14449,7 +14449,7 @@ function setPersistentSeatEngine(config, seat, engine) {
   const previous = config.seats[seat];
   if (previous === void 0) {
     throw new Error(
-      `config seat ${seat} has no persistent model; set provider/model:thinking before engine`
+      `config seat ${seat} has no persistent model; set provider/model[:thinking] before engine`
     );
   }
   if (engine === void 0) {
@@ -14518,19 +14518,6 @@ function parseModelSpec(spec, fallbackThinking) {
   const model = modelPart.slice(slash + 1);
   return thinking === void 0 ? { provider, model } : { provider, model, thinking };
 }
-function parsePersistentModelSpec(spec) {
-  const parsed = parseModelSpec(spec);
-  if (parsed.thinking === void 0) {
-    throw new Error(
-      `model specification requires a thinking level (provider/model:thinking), got ${spec}`
-    );
-  }
-  return {
-    provider: parsed.provider,
-    model: parsed.model,
-    thinking: parsed.thinking
-  };
-}
 function formatModelSpec(selection) {
   const base = `${selection.provider}/${selection.model}`;
   return selection.thinking === void 0 ? base : `${base}:${selection.thinking}`;
@@ -14578,13 +14565,15 @@ function parseSeatModelConfig(value, seat) {
   if (typeof raw.model !== "string" || raw.model.trim() === "") {
     throw new Error(`config seat ${seat} requires model`);
   }
-  if (typeof raw.thinking !== "string" || !THINKING_LEVELS.has(raw.thinking)) {
-    throw new Error(`config seat ${seat} requires a valid thinking level`);
+  if (raw.thinking !== void 0) {
+    if (typeof raw.thinking !== "string" || !THINKING_LEVELS.has(raw.thinking)) {
+      throw new Error(`config seat ${seat} requires a valid thinking level`);
+    }
   }
   const parsed = {
     provider: raw.provider,
     model: raw.model,
-    thinking: raw.thinking
+    ...raw.thinking === void 0 ? {} : { thinking: raw.thinking }
   };
   if (raw.engine !== void 0) {
     if (typeof raw.engine !== "string") {
@@ -27117,7 +27106,7 @@ function renderHelp() {
   lines.push(
     "",
     "Role options: ak-role help <command>",
-    "Persistent config: ak-role config set <seat> <provider/model:thinking>",
+    "Persistent config: ak-role config set <seat> <provider/model[:thinking]>",
     "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles"
   );
@@ -27198,7 +27187,7 @@ async function runConfigCommand(args, home, packageRoot2, io) {
   if (args[0] === "set") {
     if (args.length < 3) {
       throw new CliUsageError(
-        "usage: ak-role config set <seat> <provider/model:thinking>"
+        "usage: ak-role config set <seat> <provider/model[:thinking]>"
       );
     }
     const pairs = args.slice(1);
@@ -27214,7 +27203,7 @@ async function runConfigCommand(args, home, packageRoot2, io) {
       if (!isPublicConfigurableSeat(seat)) {
         throw new CliUsageError(`unknown configurable seat: ${seat}`);
       }
-      config = setPersistentSeatConfig(config, seat, parsePersistentModelSpec(spec));
+      config = setPersistentSeatConfig(config, seat, parseModelSpec(spec));
     }
     await savePublicCliConfig(config, home);
     io.stdout(renderConfig(config));

package/package.json

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

package/resources/engines/codex.md

@@ -0,0 +1,55 @@
+# codex engine method material
+
+This file is packaged method material for the optional `codex` labor engine
+(Codex CLI on the host). 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)
+
+The machine entrypoint is `codex`. Run from the role project root. Non-interactive
+labor uses `codex exec` (alias `e`). Always pass `--skip-git-repo-check` so the
+labor subprocess can start outside a Git work tree when needed:
+
+```bash
+codex exec --skip-git-repo-check "YOUR_LABOR_PROMPT"
+```
+
+For concurrent or disposable labor turns, add `--ephemeral` so session files are
+not persisted to disk:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral "YOUR_LABOR_PROMPT"
+```
+
+Working-root override when the seat cwd is not the project root:
+
+```bash
+codex exec --skip-git-repo-check --ephemeral -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Default (non-`--json`) mode prints the session banner and progress on stderr
+(measured on this host). Collect the labor body from stdout so that stderr log
+noise is not mixed into the returned body; the package idle clock can still see
+activity on both streams. Use `--json` only when the seat itself needs
+machine-readable event rows (those rows land on stdout as JSONL; measured event
+types include `thread.started`, `turn.started`, `item.completed`, `error`,
+`turn.failed`):
+
+```bash
+codex exec --skip-git-repo-check --ephemeral --json "YOUR_LABOR_PROMPT"
+```
+
+Prefer `codex exec --help` on the host over any remembered flag set. Do not wrap
+this engine behind `ak-role` flags. Later host quota/auth failures are separate
+from argv acceptance — re-check the local CLI if a turn fails after session start.
+
+When the package detour tool is available, start exactly one subprocess per
+labor invocation through it with argv assembled from this material and the
+local CLI; return the stdout labor content to the same session for the existing
+typed submission path. One labor turn = one process (not one process for the
+whole role run). If the detour fails, continue labor in-session on the seat main
+road and still submit via the existing typed path.

package/resources/engines/kimi.md

@@ -0,0 +1,61 @@
+# kimi engine method material
+
+This file is packaged method material for the optional `kimi` labor engine
+(Kimi Code CLI on the host). 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)
+
+The machine entrypoint on this host is installed at `~/.kimi-code/bin/kimi`
+(put that directory on PATH, or pass the absolute path as argv[0]). Run from
+the role project root.
+
+Non-interactive labor uses `-p` / `--prompt` alone. On this host (kimi 0.36.1),
+`-p` cannot be combined with `--yolo` or `--auto` — both are rejected at parse
+time with `Cannot combine --prompt with --yolo.` / `... --auto.`. Do not add
+those flags to prompt-mode argv:
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT"
+```
+
+Pin a model alias configured in the host `config.toml` when the seat needs a
+known Kimi model id (example alias shape measured: `kimi-code/k3-256k`):
+
+```bash
+kimi -m <model-alias> -p "YOUR_LABOR_PROMPT"
+```
+
+Use `--output-format stream-json` (choices measured on this host: `text`,
+`stream-json`; default is `text`) so the package idle clock can see subprocess
+activity while the engine works. Take the labor body from
+`{"role":"assistant","content":...}` rows, not from `role:meta` rows:
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT" --output-format stream-json
+```
+
+Text / default mode when stream events are not needed. Measured on this host
+with separate fd redirects (`1>` / `2>`): stdout is the labor answer body;
+stderr carries the version line, thinking bullets, and the trailing
+`To resume this session:` hint. Collect the labor body from stdout only — do
+not treat resume lines as same-stream noise to strip from stdout (they are not
+on that stream; stripping bullet-shaped lines risks deleting answer content):
+
+```bash
+kimi -p "YOUR_LABOR_PROMPT" --output-format text
+```
+
+Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.
+
+When the package detour tool is available, start exactly one subprocess per
+labor invocation through it with argv assembled from this material and the
+local CLI; return the stdout labor content to the same session for the existing
+typed submission path. One labor turn = one process (not one process for the
+whole role run). If the detour fails, continue labor in-session on the seat main
+road and still submit via the existing typed path.

package/src/public-cli/cli.ts

@@ -13,7 +13,7 @@ import {
   formatModelSpec,
   loadCredentialProviders,
   loadPublicCliConfig,
-  parsePersistentModelSpec,
+  parseModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
   isEngineAxisSeat,
@@ -418,7 +418,7 @@ function renderHelp(): string {
   lines.push(
     "",
     "Role options: ak-role help <command>",
-    "Persistent config: ak-role config set <seat> <provider/model:thinking>",
+    "Persistent config: ak-role config set <seat> <provider/model[:thinking]>",
     "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles",
   );
@@ -507,7 +507,7 @@ async function runConfigCommand(
   if (args[0] === "set") {
     if (args.length < 3) {
       throw new CliUsageError(
-        "usage: ak-role config set <seat> <provider/model:thinking>",
+        "usage: ak-role config set <seat> <provider/model[:thinking]>",
       );
     }
     // Bulk: repeated seat spec pairs after `set`
@@ -524,7 +524,9 @@ async function runConfigCommand(
       if (!isPublicConfigurableSeat(seat)) {
         throw new CliUsageError(`unknown configurable seat: ${seat}`);
       }
-      config = setPersistentSeatConfig(config, seat, parsePersistentModelSpec(spec));
+      // #384: persistent seat config shares the invocation model grammar.
+      // Bare provider/model stores as-is; :thinking suffix still required only when colon present.
+      config = setPersistentSeatConfig(config, seat, parseModelSpec(spec));
     }
     await savePublicCliConfig(config, home);
     io.stdout(renderConfig(config));

package/src/public-cli/config.ts

@@ -23,7 +23,7 @@ export type CredentialProviders = {
 
 export type SeatModelConfig = ModelRef;
 
-/** Persistent seat row: required model triple + optional engine axis (#356). */
+/** Persistent seat row: provider/model[:thinking] + optional engine axis (#356/#384). */
 export type PersistentSeatConfig = SeatModelConfig & {
   engine?: string;
 };
@@ -123,7 +123,7 @@ export function isEngineAxisSeat(seat: string): seat is "judge" | "reviewer" {
 
 /**
  * Set or clear persistent engine on Judge or Reviewer (#356 / #378).
- * Engine-only seats are rejected — model triple remains required.
+ * Engine-only seats are rejected — provider/model[:thinking] remains required first.
  */
 export function setPersistentSeatEngine(
   config: PublicCliConfig,
@@ -136,7 +136,7 @@ export function setPersistentSeatEngine(
   const previous = config.seats[seat];
   if (previous === undefined) {
     throw new Error(
-      `config seat ${seat} has no persistent model; set provider/model:thinking before engine`,
+      `config seat ${seat} has no persistent model; set provider/model[:thinking] before engine`,
     );
   }
   if (engine === undefined) {
@@ -226,30 +226,12 @@ export function parseModelSpec(
   }
   const provider = modelPart.slice(0, slash);
   const model = modelPart.slice(slash + 1);
-  // #346: bare provider/model is legal on invocation — do not invent thinking.
-  // Persistent config set still requires thinking via parsePersistentModelSpec.
+  // #346/#384: bare provider/model is legal — do not invent thinking.
   return thinking === undefined
     ? { provider, model }
     : { provider, model, thinking };
 }
 
-/** Persistent seat config keeps the three-part provider/model:thinking grammar. */
-export function parsePersistentModelSpec(spec: string): SeatModelConfig & {
-  thinking: PublicThinkingLevel;
-} {
-  const parsed = parseModelSpec(spec);
-  if (parsed.thinking === undefined) {
-    throw new Error(
-      `model specification requires a thinking level (provider/model:thinking), got ${spec}`,
-    );
-  }
-  return {
-    provider: parsed.provider,
-    model: parsed.model,
-    thinking: parsed.thinking,
-  };
-}
-
 export function formatModelSpec(selection: SeatModelConfig): string {
   const base = `${selection.provider}/${selection.model}`;
   return selection.thinking === undefined ? base : `${base}:${selection.thinking}`;
@@ -308,16 +290,21 @@ function parseSeatModelConfig(value: unknown, seat: string): PersistentSeatConfi
   if (typeof raw.model !== "string" || raw.model.trim() === "") {
     throw new Error(`config seat ${seat} requires model`);
   }
-  if (
-    typeof raw.thinking !== "string" ||
-    !THINKING_LEVELS.has(raw.thinking as PublicThinkingLevel)
-  ) {
-    throw new Error(`config seat ${seat} requires a valid thinking level`);
+  // #384: thinking is optional on persistent seats; when present it must be typed.
+  if (raw.thinking !== undefined) {
+    if (
+      typeof raw.thinking !== "string" ||
+      !THINKING_LEVELS.has(raw.thinking as PublicThinkingLevel)
+    ) {
+      throw new Error(`config seat ${seat} requires a valid thinking level`);
+    }
   }
   const parsed: PersistentSeatConfig = {
     provider: raw.provider,
     model: raw.model,
-    thinking: raw.thinking as PublicThinkingLevel,
+    ...(raw.thinking === undefined
+      ? {}
+      : { thinking: raw.thinking as PublicThinkingLevel }),
   };
   if (raw.engine !== undefined) {
     // Shape only: engine must be a string field. Path-safety syntax is deferred to