@akagilnc/pi-workflow-roles 0.1.2471 → 0.1.2477

package/dist/engine-detour-tool.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC, ENGINE_DETOUR_TOOL_NAME, engineDetourFailureDiagnostic, engineNameFromEnv, isEngineDetourFailure, runEngineDetourOnce, } from "./engine-detour.js";
+import { ENGINE_DETOUR_TOOL_NAME, engineDetourFailureDiagnostic, engineNameFromEnv, isEngineDetourFailure, runEngineDetourOnce, } from "./engine-detour.js";
 const engineDetourArgsSchema = Type.Object({
     argv: Type.Array(Type.String({ minLength: 1 }), {
         minItems: 1,
@@ -18,26 +18,20 @@ function isCallerCancellation(error, signal) {
     return false;
 }
 /**
- * Build one once-latch detour tool definition for a configured engine name.
- * `latch` is shared so parent registration can reset between activations.
+ * Build one detour tool definition for a configured engine name.
  * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
  * Engine process failures (nonzero/empty/spawn) stop via `fail` with their cause.
  * Caller AbortSignal cancellation propagates unchanged.
  */
 export function createEngineDetourToolDefinition(input) {
-    const latch = input.latch ?? { used: false };
     const engineName = input.engineName;
     return {
         name: ENGINE_DETOUR_TOOL_NAME,
         label: "劳务引擎",
-        description: `运行一次劳务引擎子进程（engine=${engineName}），stdout 返回本 session；每次激活至多一次。`,
+        description: `运行一次劳务引擎子进程（engine=${engineName}），stdout 返回本 session。`,
         promptSnippet: "运行配置的劳务引擎一次并返回 stdout",
         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)) {
@@ -67,6 +61,7 @@ export function createEngineDetourToolDefinition(input) {
                 details: {
                     tool: ENGINE_DETOUR_TOOL_NAME,
                     code: result.code,
+                    stderr: result.stderr,
                 },
             };
         },
@@ -75,31 +70,18 @@ export function createEngineDetourToolDefinition(input) {
 /**
  * Register the engine-generic detour tool once for this process when any role 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 */
-            },
-        };
+        return false;
     }
-    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;
-        },
-    };
+    return true;
 }

package/dist/engine-detour.js

@@ -22,7 +22,6 @@ export function applyEngineChildEnv(childEnv, engine) {
     }
 }
 export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC = "劳务引擎 stdout 为空";
-export const ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC = "本激活内劳务引擎已使用";
 function abortReasonError(signal) {
     const reason = signal.reason;
     if (reason instanceof Error)

package/package.json

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

package/resources/engines/zcode.md

@@ -0,0 +1,46 @@
+# zcode engine method material
+
+This file is packaged technical material for the optional `zcode` labor engine
+(Z.AI ZCode agent runtime on the host, GLM Coding Plan models).
+
+Before invoking the engine, read `../engine-dispatch.md`, resolving that path
+relative to this note. This note only covers this engine's CLI technical
+parameters.
+
+## Invocation (host-verified 2026-08-29)
+
+The machine entrypoint is `zcode` (npm `zcode-app-cli`, wraps the official
+ZCode runtime; host has 3.10.1-17 / runtime 0.16.5). Non-interactive labor:
+
+```bash
+zcode --prompt 'YOUR_LABOR_PROMPT' --cwd /path/to/worktree
+```
+
+`--prompt` defaults to permission mode `yolo` (no TTY permission stalls).
+Useful extras measured from `zcode --help`: `--attach <path>` (repeatable),
+`--mode build|edit|plan|yolo`, `--resume <sess_...>`, `--json` where
+supported. Prefer `zcode --help` on the host over any remembered flag set.
+
+## Realm and model traps (host-verified 2026-08-29, all three hit in sequence)
+
+- Missing `~/.zcode/cli/config.json` → hard error `Model config is missing`.
+  The desktop app's login is NOT shared with the CLI.
+- `zcode login` signs into the **overseas Z.AI realm only**. An account on the
+  mainland BigModel realm then fails with
+  `[1113][Insufficient balance or no resource package]`.
+- The scaffolded config defaults `model.main` to `zai/glm-5.2`, which is not
+  in the coding plan — same 1113 failure even with a valid plan.
+
+Working mainland configuration (per official docs
+`docs.bigmodel.cn/cn/coding-plan/quick-start`): in
+`~/.zcode/cli/config.json`, provider kind `anthropic` with
+`baseURL: https://open.bigmodel.cn/api/anthropic`, `options.apiKey` = the
+coding-plan key (host keychain: service `glm-key`, account `akagilnc`), and
+`model.main: zai/glm-5.3`, `model.lite: zai/glm-5.3-flash`. With that config
+the smoke prompt returns normally.
+
+## Quota facts (owner-provided, 2026-08-28)
+
+Plan quotas are daily and per-model (GLM-5.3 3M/day, Flash 5M/day on the
+current plan; a weekend event granted a larger temporary pool). Whether cached
+tokens count toward quota is unverified.

package/src/engine-detour-tool.ts

@@ -14,7 +14,6 @@ import type {
 import { Type, type Static } from "typebox";
 
 import {
-  ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC,
   ENGINE_DETOUR_TOOL_NAME,
   engineDetourFailureDiagnostic,
   engineNameFromEnv,
@@ -42,13 +41,6 @@ export type EngineDetourHostActions = {
   ): never;
 };
 
-export type EngineDetourToolRegistration = {
-  /** True when the tool definition was installed on this ExtensionAPI. */
-  readonly registered: boolean;
-};
-
-type EngineDetourLatch = { used: boolean };
-
 /** Caller/upper-layer cancellation must propagate unchanged. */
 function isCallerCancellation(
   error: unknown,
@@ -66,24 +58,21 @@ function isCallerCancellation(
 }
 
 /**
- * Build one once-latch detour tool definition for a configured engine name.
- * `latch` is shared so parent registration can reset between activations.
+ * Build one detour tool definition for a configured engine name.
  * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
  * Engine process failures (nonzero/empty/spawn) stop via `fail` with their cause.
  * Caller AbortSignal cancellation propagates unchanged.
  */
 export function createEngineDetourToolDefinition(input: {
   engineName: string;
-  latch?: EngineDetourLatch;
   fail: (error: Error, toolCallId: string, ctx: ExtensionContext) => never;
 }): ToolDefinition {
-  const latch = input.latch ?? { used: false };
   const engineName = input.engineName;
   return {
     name: ENGINE_DETOUR_TOOL_NAME,
     label: "劳务引擎",
     description:
-      `运行一次劳务引擎子进程（engine=${engineName}），stdout 返回本 session；每次激活至多一次。`,
+      `运行一次劳务引擎子进程（engine=${engineName}），stdout 返回本 session。`,
     promptSnippet: "运行配置的劳务引擎一次并返回 stdout",
     parameters: engineDetourArgsSchema,
     async execute(
@@ -93,15 +82,6 @@ export function createEngineDetourToolDefinition(input: {
       _onUpdate,
       ctx,
     ): Promise<AgentToolResult<unknown>> {
-      if (latch.used) {
-        input.fail(
-          new Error(ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC),
-          toolCallId,
-          ctx,
-        );
-      }
-      latch.used = true;
-
       const args = params as EngineDetourArgs;
       const argv = Array.isArray(args.argv) ? args.argv : [];
       if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
@@ -140,6 +120,7 @@ export function createEngineDetourToolDefinition(input: {
         details: {
           tool: ENGINE_DETOUR_TOOL_NAME,
           code: result.code,
+          stderr: result.stderr,
         },
       };
     },
@@ -149,36 +130,23 @@ export function createEngineDetourToolDefinition(input: {
 /**
  * Register the engine-generic detour tool once for this process when any role has
  * an engine activation signal. Returns whether registration occurred.
- * Once-latch is activation-scoped via the returned reset handle.
  */
 export function registerEngineDetourTool(
   pi: ExtensionAPI,
   hostActions: EngineDetourHostActions,
-): EngineDetourToolRegistration & { resetLatch(): void } {
+): boolean {
   const engineName = engineNameFromEnv();
   if (engineName === undefined) {
-    return {
-      registered: false,
-      resetLatch() {
-        /* no-op when unregistered */
-      },
-    };
+    return false;
   }
 
-  const latch: EngineDetourLatch = { 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;
-    },
-  };
+  return true;
 }

package/src/engine-detour.ts

@@ -30,9 +30,6 @@ export function applyEngineChildEnv(
 export const ENGINE_DETOUR_EMPTY_STDOUT_DIAGNOSTIC =
   "劳务引擎 stdout 为空" as const;
 
-export const ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC =
-  "本激活内劳务引擎已使用" as const;
-
 export type EngineDetourResult = Readonly<{
   code: number;
   stdout: string;

package/src/role-runtime.ts

@@ -629,7 +629,7 @@ export function createRoleRuntimeExtension(
     const pendingInfrastructureFailures = new Map<string, PendingInfrastructureFailure>();
     // Envelope-owned execute→tool_result bridge for Gatekeeper non-pass (ADR 0018).
     const pendingGatekeeperNonPassByToolCallId = new Map<string, GatekeeperNonPassResult>();
-    let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
+    let engineDetourRegistered = false;
     // #288 primary-session thin adapter. The policy is the sole budget owner;
     // terminating-tool rejections and mechanical delivery requests share two turns.
     let receiptDelivery = createReceiptDeliveryPolicy();
@@ -1109,7 +1109,6 @@ export function createRoleRuntimeExtension(
       pendingNavigatorSettlement = undefined;
       pendingInfrastructureFailures.clear();
       pendingGatekeeperNonPassByToolCallId.clear();
-      engineDetourRegistration?.resetLatch();
       navigatorWorkContext = undefined;
       // #351: OAuth keepalive is orthogonal to --ak-role; start before role early-return
       // so role-less sessions (and reload after shutdown stop) still keep tokens alive.
@@ -1224,11 +1223,8 @@ export function createRoleRuntimeExtension(
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
         // #357 T2 / #378 / #380 / #391: any role+engine activation registers the package detour tool once.
         // Gate is env presence only — no per-engine execute branch; no role-module spawn.
-        if (engineDetourRegistration === undefined) {
-          engineDetourRegistration = registerEngineDetourTool(pi, hostActions);
-          if (!engineDetourRegistration.registered) {
-            engineDetourRegistration = undefined;
-          }
+        if (!engineDetourRegistered) {
+          engineDetourRegistered = registerEngineDetourTool(pi, hostActions);
         }
         // Worker gates ①②: arm records baseline and runs private one-shot hook uninstall (ADR 0070).
         // Parent session feeds #216 createRecordSession so baseline/bounce survive resume.