@akagilnc/pi-workflow-roles 0.1.4243 → 0.1.4274

package/dist/public-role-summons.js

@@ -77,11 +77,17 @@ function hostSelectionFailureFromUnknown(error) {
   const failure = error.failure;
   return failure;
 }
-async function createSummonEnv(options) {
-  const [{ piDurablePrincipalAuthority }, { appendPiSessionCustomEntry }, { resolveRoleTurnHost }] = await Promise.all([
+async function createSummonEnv(options, afterHost) {
+  const [
+    { piDurablePrincipalAuthority },
+    { appendPiSessionCustomEntry },
+    { resolveRoleTurnHost },
+    { missingResolvedSeatModelMessage, resolvedSeatWithModel }
+  ] = await Promise.all([
     import("./pi/durable-principal.js"),
     import("./pi/role-turn-host.js"),
-    import("./public-cli/role-turn-host-resolution.js")
+    import("./public-cli/role-turn-host-resolution.js"),
+    import("./public-cli/config.js")
   ]);
   const principalAuthority = piDurablePrincipalAuthority;
   const roleTurnHost = resolveRoleTurnHost(
@@ -93,26 +99,37 @@ async function createSummonEnv(options) {
     },
     { role: options.role, seat: options.seat, principalAuthority }
   );
-  const hostName = options.seat.host ?? "pi";
+  afterHost?.();
+  const seatWithModel = resolvedSeatWithModel(options.seat);
+  if (seatWithModel === void 0) {
+    return {
+      ok: false,
+      missingModelMessage: missingResolvedSeatModelMessage(options.role)
+    };
+  }
+  const hostName = seatWithModel.host ?? "pi";
   const { loadHostProvidersTable, projectHostFacingProvider } = await import("./public-cli/host-providers.js");
-  const hostFacingSelection = options.seat.selection === void 0 ? void 0 : projectHostFacingProvider(
-    options.seat.selection,
+  const hostFacingSelection = projectHostFacingProvider(
+    seatWithModel.selection,
     hostName,
     loadHostProvidersTable(options.home),
     options.home
   );
   return {
-    home: options.home,
-    principalAuthority,
-    agentDir: options.agentDir,
-    sessionAppender: appendPiSessionCustomEntry,
-    packageRoot: options.packageRoot,
-    roleTurnHost,
-    cwd: options.cwd,
-    credentials: options.credentials,
-    ...hostFacingSelection === void 0 ? {} : { model: hostFacingSelection },
-    ...projectSeatEngine(options.seat),
-    ...projectSeatHost(options.seat)
+    ok: true,
+    env: {
+      home: options.home,
+      principalAuthority,
+      agentDir: options.agentDir,
+      sessionAppender: appendPiSessionCustomEntry,
+      packageRoot: options.packageRoot,
+      roleTurnHost,
+      cwd: options.cwd,
+      credentials: options.credentials,
+      ...hostFacingSelection === void 0 ? {} : { model: hostFacingSelection },
+      ...projectSeatEngine(seatWithModel),
+      ...projectSeatHost(seatWithModel)
+    }
   };
 }
 async function summonPublicRole(options) {
@@ -127,46 +144,72 @@ async function summonPublicRole(options) {
   const credentials = options.credentials ?? await loadCredentialProviders(agentDir);
   const config = await loadPublicCliConfig(home);
   const seat = resolveEffectiveSeat(config, options.role, credentials);
-  let summonEnv;
-  try {
-    summonEnv = await createSummonEnv({
-      role: options.role,
-      home,
-      agentDir,
-      cwd: options.cwd,
-      packageRoot,
-      credentials,
-      seat,
-      ...options.extraPiArgs === void 0 ? {} : { extraPiArgs: options.extraPiArgs },
-      ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
-      ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters }
-    });
-  } catch (error) {
-    const failure = hostSelectionFailureFromUnknown(error);
-    if (failure !== void 0) {
-      const { formatHostSelectionFailure } = await import("./public-cli/role-turn-host-resolution.js");
-      return { exitCode: 1, stderr: formatHostSelectionFailure(failure) };
-    }
-    throw error;
-  }
-  const env = {
-    ...summonEnv,
-    // Station child role run (#840): omit automatic navigator attendance.
-    stationChild: true,
-    // Host config passthrough only — same face as public CLI (#422 / #675).
-    ...config.autoResumeLimit === void 0 ? {} : { autoResumeLimit: config.autoResumeLimit },
-    // Parent cancellation reaches the nested activation's own turn dispatch.
-    ...options.signal === void 0 ? {} : { signal: options.signal },
-    // #753: reask rides the existing notary same-ticket resume summons.instruction.
-    ...options.reviewReask === void 0 ? {} : { reviewReask: options.reviewReask },
-    // #879: verbatim submission body on officer dialogue content channel.
-    ...options.gateReviewInstruction === void 0 ? {} : { gateReviewInstruction: options.gateReviewInstruction },
-    ...options.boundTicketNumber === void 0 ? {} : { boundTicketNumber: options.boundTicketNumber },
-    // createRunId is the only remaining env overlay — host is seat-selected above.
-    ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId }
-  };
   const captured = options.io === void 0 ? createCapturingIo() : void 0;
   const io = options.io ?? captured.io;
+  const summonEnvInput = {
+    role: options.role,
+    home,
+    agentDir,
+    cwd: options.cwd,
+    packageRoot,
+    credentials,
+    seat,
+    ...options.extraPiArgs === void 0 ? {} : { extraPiArgs: options.extraPiArgs },
+    ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
+    ...options.hostAdapters === void 0 ? {} : { hostAdapters: options.hostAdapters }
+  };
+  async function prepareSummonEnv(afterHost) {
+    try {
+      const built = await createSummonEnv(summonEnvInput, afterHost);
+      if (!built.ok) {
+        return { ok: false, exitCode: 1, stderr: built.missingModelMessage };
+      }
+      return {
+        ok: true,
+        env: {
+          ...built.env,
+          stationChild: true,
+          ...config.autoResumeLimit === void 0 ? {} : { autoResumeLimit: config.autoResumeLimit },
+          ...options.signal === void 0 ? {} : { signal: options.signal },
+          ...options.reviewReask === void 0 ? {} : { reviewReask: options.reviewReask },
+          ...options.gateReviewInstruction === void 0 ? {} : { gateReviewInstruction: options.gateReviewInstruction },
+          ...options.boundTicketNumber === void 0 ? {} : { boundTicketNumber: options.boundTicketNumber },
+          ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId }
+        }
+      };
+    } catch (error) {
+      const failure = hostSelectionFailureFromUnknown(error);
+      if (failure !== void 0) {
+        const { formatHostSelectionFailure } = await import("./public-cli/role-turn-host-resolution.js");
+        return { ok: false, exitCode: 1, stderr: formatHostSelectionFailure(failure) };
+      }
+      const { CliUsageError } = await import("./public-cli/cli-errors.js");
+      if (error instanceof CliUsageError) {
+        const { presentStructuralRejection } = await import("./public-cli/settlement.js");
+        presentStructuralRejection(error, io);
+        return { ok: false, exitCode: 2 };
+      }
+      throw error;
+    }
+  }
+  function projectPrepareFailure(prepared) {
+    const parts = [prepared.stderr, captured?.stderrText()].filter(
+      (s) => typeof s === "string" && s !== ""
+    );
+    const stderr2 = parts.length === 0 ? void 0 : parts.join("");
+    return {
+      exitCode: prepared.exitCode,
+      ...stderr2 === void 0 ? {} : { stderr: stderr2 }
+    };
+  }
+  async function runPrepared(parse, run) {
+    let parsedArgv;
+    const prepared = await prepareSummonEnv(() => {
+      parsedArgv = parse(options.argv);
+    });
+    if (!prepared.ok) return { fail: projectPrepareFailure(prepared) };
+    return { ok: await run(prepared.env, () => parsedArgv) };
+  }
   let result;
   switch (options.role) {
     case "notary": {
@@ -174,7 +217,9 @@ async function summonPublicRole(options) {
         import("./public-cli/notary-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicNotary(options.argv, env, io, parseNotaryArgv);
+      const stepped = await runPrepared(parseNotaryArgv, (env, once) => runPublicNotary(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
     case "inspector": {
@@ -182,49 +227,23 @@ async function summonPublicRole(options) {
         import("./public-cli/inspector-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicInspector(options.argv, env, io, parseInspectorArgv);
-      break;
-    }
-    case "auditor": {
-      const [{ runPublicInstructionSeat }, { parseAuditorArgv }] = await Promise.all([
-        import("./public-cli/instruction-seat-run.js"),
-        import("./public-cli/invocation.js")
-      ]);
-      result = await runPublicInstructionSeat(
-        options.argv,
-        env,
-        io,
-        "auditor",
-        parseAuditorArgv
-      );
-      break;
-    }
-    case "navigator": {
-      const [{ runPublicInstructionSeat }, { parseNavigatorArgv }] = await Promise.all([
-        import("./public-cli/instruction-seat-run.js"),
-        import("./public-cli/invocation.js")
-      ]);
-      result = await runPublicInstructionSeat(
-        options.argv,
-        env,
-        io,
-        "navigator",
-        parseNavigatorArgv
-      );
+      const stepped = await runPrepared(parseInspectorArgv, (env, once) => runPublicInspector(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
+    case "auditor":
+    case "navigator":
     case "gatekeeper": {
-      const [{ runPublicInstructionSeat }, { parseGatekeeperArgv }] = await Promise.all([
+      const seat2 = options.role;
+      const [{ runPublicInstructionSeat }, invocation] = await Promise.all([
         import("./public-cli/instruction-seat-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicInstructionSeat(
-        options.argv,
-        env,
-        io,
-        "gatekeeper",
-        parseGatekeeperArgv
-      );
+      const parse = seat2 === "auditor" ? invocation.parseAuditorArgv : seat2 === "navigator" ? invocation.parseNavigatorArgv : invocation.parseGatekeeperArgv;
+      const stepped = await runPrepared(parse, (env, once) => runPublicInstructionSeat(options.argv, env, io, seat2, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
     case "judge": {
@@ -232,7 +251,9 @@ async function summonPublicRole(options) {
         import("./public-cli/judge-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicJudge(options.argv, env, io, parseJudgeArgv);
+      const stepped = await runPrepared(parseJudgeArgv, (env, once) => runPublicJudge(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
     case "doctor": {
@@ -240,7 +261,9 @@ async function summonPublicRole(options) {
         import("./public-cli/doctor-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicDoctor(options.argv, env, io, parseDoctorArgv);
+      const stepped = await runPrepared(parseDoctorArgv, (env, once) => runPublicDoctor(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
     case "diarist": {
@@ -248,7 +271,9 @@ async function summonPublicRole(options) {
         import("./public-cli/diarist-run.js"),
         import("./public-cli/invocation.js")
       ]);
-      result = await runPublicDiarist(options.argv, env, io, parseDiaristArgv);
+      const stepped = await runPrepared(parseDiaristArgv, (env, once) => runPublicDiarist(options.argv, env, io, once));
+      if ("fail" in stepped) return stepped.fail;
+      result = stepped.ok;
       break;
     }
   }

package/package.json

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

package/src/engine-detour-tool.ts

@@ -5,6 +5,7 @@
  * Engine process failures stop through the host infrastructure-failure seam.
  * Caller AbortSignal cancellation propagates unchanged.
  */
+import { basename } from "node:path";
 import { Type, type Static } from "typebox";
 import type { HostContext, HostToolDefinition, HostToolResult, RoleHost } from "./host-contracts.ts";
 
@@ -16,6 +17,18 @@ import {
   resolveEngineName,
   runEngineDetourOnce,
 } from "./engine-detour.ts";
+import {
+  engineDetourStdoutByteLength,
+  reportEngineDetourCall,
+} from "./engine-detour-usage.ts";
+
+/** runDirectory leaf is `<runId>@<role>`; subject is optional. */
+function basenameRunId(runDirectory: string): string | undefined {
+  const leaf = basename(runDirectory);
+  const at = leaf.indexOf("@");
+  if (at <= 0) return undefined;
+  return leaf.slice(0, at);
+}
 
 // #836 r16 class 3: argv required/minItems/element-minLength stay — execute()
 // must obtain the first item as the executable and spawn it (below; #82-98).
@@ -32,7 +45,14 @@ const engineDetourArgsSchema = Type.Object(
 
 type EngineDetourArgs = Static<typeof engineDetourArgsSchema>;
 
-type EngineDetourContext = Pick<HostContext, "cwd" | "mode" | "abort">;
+type EngineDetourContext = Pick<HostContext, "cwd" | "mode" | "abort"> & {
+  sessionManager?: Pick<HostContext["sessionManager"], "getSessionFile">;
+  runDirectory?: string;
+  /** Public-invocation scope from the shared Host envelope (#537). */
+  invocationScopeId?: string;
+  /** Selected host from the shared Host envelope (#537 / ADR 0082). */
+  host?: string;
+};
 
 export type EngineDetourHostActions = {
   failInfrastructure(
@@ -58,6 +78,12 @@ function isCallerCancellation(
   return false;
 }
 
+function asError(error: unknown, fallback: string): Error {
+  return error instanceof Error
+    ? error
+    : new Error(String(error).trim() || fallback);
+}
+
 /**
  * Build one detour tool definition for a configured engine name.
  * `fail` owns host abort (parent) vs throw (evidence child) for tool misuse only.
@@ -100,6 +126,68 @@ export function createEngineDetourToolDefinition(input: {
         );
       }
 
+      const sessionParent = ctx.sessionManager?.getSessionFile?.();
+      const startedAt = Date.now();
+      const runDirectory = typeof ctx.runDirectory === "string" && ctx.runDirectory.length > 0
+        ? ctx.runDirectory
+        : undefined;
+      const runId = runDirectory === undefined ? undefined : basenameRunId(runDirectory);
+      // Public-invocation scope + selected host from Host envelope only — never
+      // courtAttemptId, never sidecar file, never pre-spawn invocation.json I/O.
+      const invocationScopeId =
+        typeof ctx.invocationScopeId === "string" && ctx.invocationScopeId.trim() !== ""
+          ? ctx.invocationScopeId.trim()
+          : undefined;
+      const host =
+        typeof ctx.host === "string" && ctx.host.trim() !== ""
+          ? ctx.host.trim()
+          : undefined;
+
+      const recordCall = (observed: {
+        code?: number;
+        stdoutByteLength?: number;
+      }): void => {
+        if (typeof sessionParent !== "string" || sessionParent.length === 0) return;
+        reportEngineDetourCall({
+          toolCallId,
+          durationMs: Math.max(0, Date.now() - startedAt),
+          cwd: ctx.cwd,
+          sessionParent,
+          ...(runId === undefined ? {} : { runId }),
+          ...(invocationScopeId === undefined ? {} : { invocationScopeId }),
+          ...(host === undefined ? {} : { host }),
+          ...(observed.code === undefined ? {} : { code: observed.code }),
+          ...(observed.stdoutByteLength === undefined
+            ? {}
+            : { stdoutByteLength: observed.stdoutByteLength }),
+        });
+      };
+
+      /** Preserve engine cause; if ledger write also fails, keep both (失败诚实). */
+      const failAfterLedger = (
+        engineCause: Error,
+        observed: { code?: number; stdoutByteLength?: number },
+        aggregateMessage: string,
+      ): never => {
+        try {
+          recordCall(observed);
+        } catch (recordError) {
+          input.fail(
+            new AggregateError(
+              [
+                engineCause,
+                asError(recordError, "engine detour usage ledger write failed"),
+              ],
+              aggregateMessage,
+              { cause: engineCause },
+            ),
+            toolCallId,
+            ctx,
+          );
+        }
+        input.fail(engineCause, toolCallId, ctx);
+      };
+
       let result: Awaited<ReturnType<typeof runEngineDetourOnce>>;
       try {
         result = await runEngineDetourOnce({
@@ -109,20 +197,30 @@ export function createEngineDetourToolDefinition(input: {
         });
       } catch (error) {
         if (isCallerCancellation(error, signal)) throw error;
-        const cause = error instanceof Error
-          ? error
-          : new Error(String(error).trim() || "劳务引擎 spawn 失败");
-        input.fail(cause, toolCallId, ctx);
+        // Spawn path: duration only — code/stdout bytes absent (not forged 0).
+        return failAfterLedger(
+          asError(error, "劳务引擎 spawn 失败"),
+          {},
+          "engine detour spawn and usage ledger both failed",
+        );
       }
 
+      const stdoutByteLength = engineDetourStdoutByteLength(result.stdout);
+      const observed = { code: result.code, stdoutByteLength };
+
+      // Classify closed-child failure before ledger write so a sitian failure
+      // cannot erase nonzero/empty engine facts.
       if (isEngineDetourFailure(result)) {
-        input.fail(
+        return failAfterLedger(
           new Error(engineDetourFailureDiagnostic(result)),
-          toolCallId,
-          ctx,
+          observed,
+          "engine detour child-close and usage ledger both failed",
         );
       }
 
+      recordCall(observed);
+
+      // Usage ledger lives in sitian + decisiveFacts only (#537) — not tool details.
       return {
         content: [{ type: "text" as const, text: result.stdout }],
         details: {