@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/src/role-runtime.ts

@@ -92,6 +92,16 @@ import {
   NAVIGATOR_TOOL_SPEC,
   type NavigatorRuntimeDependencies,
 } from "./navigator-role.ts";
+import {
+  AUDITOR_TOOL_SPEC,
+  type AuditorRuntimeDependencies,
+} from "./auditor-role.ts";
+import { AUDITOR_ACCEPTED_TEXT } from "./package-contracts/auditor-output.ts";
+import {
+  EVIDENCE_CHILD_TOOL_SPEC,
+  type EvidenceChildRuntimeDependencies,
+} from "./evidence-child-role.ts";
+import { EVIDENCE_CHILD_ACCEPTED_TEXT } from "./package-contracts/evidence-child-output.ts";
 import { GATEKEEPER_ACCEPTED_TEXT } from "./package-contracts/gatekeeper-output.ts";
 import { NAVIGATOR_ACCEPTED_TEXT } from "./package-contracts/navigator-output.ts";
 import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorTargetRole, type NavigatorWorkContext } from "./navigator-attendance.ts";
@@ -349,14 +359,11 @@ export {
   writeToolExecutionObservationRecord,
 } from "./tool-execution-observation.ts";
 export type { ToolExecutionObservationRecord, ToolExecutionObservationWriter } from "./tool-execution-observation.ts";
-export { executeAuditorChild } from "./evidence-child-executor.ts";
-export type { AuditorDecisionTool } from "./evidence-child-executor.ts";
 export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
   createGatekeeperOutputTool,
-  createOfficerDecisionTool,
   runGatekeeper,
 } from "./gatekeeper-role.ts";
 export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, RunGatekeeperOptions } from "./gatekeeper-role.ts";
@@ -397,7 +404,13 @@ export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisi
 export type { FixerInvocationInput, FixerPrerequisite } from "./package-contracts/fixer-packet.ts";
 export { AUDIT_ESCALATION_KIND, buildAuditEscalationResult, disposeComplianceDecision, isAuditEscalationResult, projectAuditEscalation } from "./audit-escalation.ts";
 export type { AuditEscalationResult, AuditEscalationToolResult, ComplianceDecisionHandlers } from "./audit-escalation.ts";
-export { AUDITOR_SOUL_ROLES, loadAuditorSoul } from "./auditor-soul.ts";
+export {
+  AUDITOR_SOUL_ROLES,
+  AK_ROLE_AUDITOR_SUBJECT_ENV,
+  loadAuditorSoul,
+  loadAuditorSoulFromSubjectInput,
+  resolveAuditorSubject,
+} from "./auditor-soul.ts";
 export type { AuditorSoulRole } from "./auditor-soul.ts";
 export { JUDGE_AUDIT_TOOL_NAME, SOUL_AUDIT_TOOL_NAME, createPiJudgeAuditor } from "./judge-auditor.ts";
 export { DOCTOR_AUDIT_TOOL_NAME, createPiDoctorAuditor } from "./doctor-auditor.ts";
@@ -461,6 +474,8 @@ type ActivationRuntime = {
   inspector: { activate(): Promise<void> };
   gatekeeper: { activate(): Promise<void> };
   navigator: { activate(): Promise<void> };
+  auditor: { activate(): Promise<void> };
+  evidenceChild: { activate(): Promise<void> };
   diarist: { activate(): Promise<void> };
   merger(): Promise<void>;
 };
@@ -510,6 +525,8 @@ function activationStage(role: PackagedRole, runtime: ActivationRuntime): { id:
     case "inspector": return { id: "load-and-install", run: async () => runtime.inspector.activate() };
     case "gatekeeper": return { id: "load-and-install", run: async () => runtime.gatekeeper.activate() };
     case "navigator": return { id: "load-and-install", run: async () => runtime.navigator.activate() };
+    case "auditor": return { id: "load-and-install", run: async () => runtime.auditor.activate() };
+    case "evidence-child": return { id: "load-and-install", run: async () => runtime.evidenceChild.activate() };
     case "diarist": return { id: "load-and-install", run: async () => runtime.diarist.activate() };
     case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
   }
@@ -618,6 +635,8 @@ export type RoleRuntimeDependencies = {
   loadInspectorSoul?(): Promise<string>;
   loadGatekeeperSoul?(): Promise<string>;
   loadNavigatorSoul?(): Promise<string>;
+  loadAuditorSoul?(): Promise<string>;
+  loadEvidenceChildSoul?(): Promise<string>;
   loadDiaristSoul?(): Promise<string>;
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
@@ -879,6 +898,41 @@ export function createNavigatorRoleRuntime(
   );
 }
 
+/** #675: public 审刑院 seat on the shared filed-officer envelope. */
+export function createAuditorRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: AuditorRuntimeDependencies,
+) {
+  const base = createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "auditor",
+      tool: AUDITOR_TOOL_SPEC,
+      acceptedText: AUDITOR_ACCEPTED_TEXT,
+      soulTag: "auditor",
+    },
+    dependencies,
+  );
+  return {
+    async activate() {
+      await base.activate();
+      // Same tools whether nested or direct (#675): dossier tool always registered.
+      // Source run: only the shared --source-run input face (never own-run fallback).
+      const { createAuditorDossierTool, AUDITOR_DOSSIER_TOOL_NAME } =
+        await import("./auditor-dossier-tool.ts");
+      const { AK_ROLE_AUDITOR_SOURCE_RUN_ENV } = await import("./auditor-soul.ts");
+      const already = roleHost.getAllTools().some((tool) => tool.name === AUDITOR_DOSSIER_TOOL_NAME);
+      if (already) return;
+      const sourceRun =
+        typeof process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV] === "string"
+        && process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim() !== ""
+          ? process.env[AK_ROLE_AUDITOR_SOURCE_RUN_ENV].trim()
+          : undefined;
+      roleHost.registerTool(createAuditorDossierTool(sourceRun) as never);
+    },
+  };
+}
+
 /**
  * #708: 起居郎 public seat on the shared filed-officer envelope.
  * Semantic collection happened in this role's own turn; the accept hook runs the
@@ -946,6 +1000,23 @@ function loadFrozenDiaristCatalog(
   return loadDiaristSourceCatalog(raw);
 }
 
+/** #675: public evidence-child seat on the shared filed-officer envelope. */
+export function createEvidenceChildRoleRuntime(
+  roleHost: RoleHost,
+  dependencies: EvidenceChildRuntimeDependencies,
+) {
+  return createFiledOfficerRuntime(
+    roleHost,
+    {
+      role: "evidence-child",
+      tool: EVIDENCE_CHILD_TOOL_SPEC,
+      acceptedText: EVIDENCE_CHILD_ACCEPTED_TEXT,
+      soulTag: "evidence-child",
+    },
+    dependencies,
+  );
+}
+
 export function createCountersignRoleRuntime(
   roleHost: RoleHost,
   dependencies: CountersignRuntimeDependencies,
@@ -1027,6 +1098,9 @@ export function createRoleRuntimeExtension(
     // terminating-tool rejections and mechanical delivery requests share two turns.
     let receiptDelivery = createReceiptDeliveryPolicy();
     let noReceiptRecorded = false;
+    // Public-run fetch observation (in-process-session statusAwareFetch face).
+    let priorFetch: typeof globalThis.fetch | undefined;
+    let fetchWrapped = false;
     const settleNavigatorProjection = async (settlement: NavigatorSettlement | undefined) => {
       const attendance = navigatorAttendance;
       if (settlement === undefined || attendance === undefined) return;
@@ -1037,6 +1111,9 @@ export function createRoleRuntimeExtension(
           return;
         }
         const settlePromise = attendance.settle(settlement);
+        // Attach catch immediately so a late rejection after grace timeout cannot
+        // surface as unhandledRejection / stale-ctx after session dispose (#675).
+        void settlePromise.catch(() => undefined);
         const raced = await raceNavigatorGrace(settlePromise, NAVIGATOR_POST_ROLE_GRACE_MS);
         if (raced.status !== "timeout") return;
         if (pendingNavigatorPresentation === undefined) {
@@ -1063,7 +1140,6 @@ export function createRoleRuntimeExtension(
           pendingNavigatorPresentation = { event, report };
         }
         await attendance.dispose();
-        void settlePromise.catch(() => undefined);
       })();
       pendingNavigatorSettlement = pending;
       await pending;
@@ -1290,6 +1366,11 @@ export function createRoleRuntimeExtension(
     roleHost.on("session_shutdown", async () => {
       // #351: stop OAuth keepalive first so shutdown yields zero further ticks.
       envelopeHost.stopKeepalive();
+      if (fetchWrapped && priorFetch !== undefined) {
+        globalThis.fetch = priorFetch;
+        priorFetch = undefined;
+        fetchWrapped = false;
+      }
       // Flush any still-pending affirmative attendance before teardown. Accepted
       // grace-timeout paths normally emit on agent_settled; abort can skip that hook.
       const presentation = pendingNavigatorPresentation;
@@ -1458,6 +1539,18 @@ export function createRoleRuntimeExtension(
         return dependencies.loadNavigatorSoul();
       },
     });
+    const auditor = createAuditorRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadAuditorSoul) throw new Error("Auditor runtime dependencies are not configured");
+        return dependencies.loadAuditorSoul();
+      },
+    });
+    const evidenceChild = createEvidenceChildRoleRuntime(roleHost, {
+      async loadSoul() {
+        if (!dependencies.loadEvidenceChildSoul) throw new Error("Evidence-child runtime dependencies are not configured");
+        return dependencies.loadEvidenceChildSoul();
+      },
+    });
     const diarist = createDiaristRoleRuntime(
       roleHost,
       {
@@ -1553,20 +1646,19 @@ export function createRoleRuntimeExtension(
     });
 
     // Public Role run: record typed non-success HTTP for error evidence + v1 resume.
-    // 2xx clears prior observation (see recordTypedProviderHttpStatus). Non-success
-    // write failure must surface — never silently drop authorized error evidence.
-    roleHost.on("after_provider_response", async (event, ctx) => {
+    // Same observation owner as in-process-session statusAwareFetch → typed-provider-http
+    // sidecar (settlement already merges observation.httpStatus into knownFailure).
+    // after_provider_response covers the success-path onResponse face; fetch wrap covers
+    // non-2xx Responses where openai-completions throws before onResponse (#675).
+    const recordHttpObservation = async (
+      status: number,
+      provider: string,
+      ctx: HostContext,
+    ): Promise<void> => {
       const runDir = process.env.AK_ROLE_RUN_DIR;
       if (typeof runDir !== "string" || runDir.trim() === "") return;
-      const provider = ctx.model?.provider;
-      if (typeof provider !== "string" || provider.trim() === "") return;
-      const status = event.status;
-      if (typeof status !== "number") return;
       try {
-        await recordTypedProviderHttpStatus(runDir, {
-          httpStatus: status,
-          provider,
-        });
+        await recordTypedProviderHttpStatus(runDir, { httpStatus: status, provider });
       } catch (error) {
         if (
           status >= 200 &&
@@ -1579,9 +1671,49 @@ export function createRoleRuntimeExtension(
         }
         failInfrastructure(error, ctx);
       }
+    };
+    roleHost.on("after_provider_response", async (event, ctx) => {
+      const status = event.status;
+      if (typeof status !== "number") return;
+      const fromCtx = ctx.model?.provider;
+      const provider =
+        typeof fromCtx === "string" && fromCtx.trim() !== ""
+          ? fromCtx
+          : "unknown";
+      await recordHttpObservation(status, provider, ctx);
     });
 
     roleHost.on("session_start", async (event, ctx) => {
+      // Scope fetch observation to this public run (in-process-session statusAwareFetch face).
+      if (!fetchWrapped && typeof globalThis.fetch === "function") {
+        priorFetch = globalThis.fetch.bind(globalThis);
+        const underlying = priorFetch;
+        globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+          const response = await underlying(input, init);
+          const runDir = process.env.AK_ROLE_RUN_DIR;
+          if (
+            typeof runDir === "string"
+            && runDir.trim() !== ""
+            && typeof response?.status === "number"
+            && (response.status < 200 || response.status >= 300)
+          ) {
+            const provider =
+              typeof ctx.model?.provider === "string" && ctx.model.provider.trim() !== ""
+                ? ctx.model.provider
+                : "unknown";
+            try {
+              await recordTypedProviderHttpStatus(runDir, {
+                httpStatus: response.status,
+                provider,
+              });
+            } catch {
+              // Observation must not break the provider stream (same as in-process-session).
+            }
+          }
+          return response;
+        }) as typeof globalThis.fetch;
+        fetchWrapped = true;
+      }
       admitted = false;
       selectedRole = undefined;
       activeReviewerParent = undefined;
@@ -1634,6 +1766,8 @@ export function createRoleRuntimeExtension(
         inspector,
         gatekeeper,
         navigator,
+        auditor,
+        evidenceChild,
         diarist,
         merger: async () => {
           if (dependencies.mergerGitState === undefined) {
@@ -1653,7 +1787,14 @@ export function createRoleRuntimeExtension(
         const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
         const session = durableSessionPointer(ctx.sessionManager);
 
-        if (dependencies.createNavigatorAttendance !== undefined) {
+        // Same public activation face for every role (#675 / owner 09-06): no nested-env
+        // skip, no work-role whitelist. Attendance attaches when the envelope supplies it.
+        // Navigator seat never re-attaches itself — prepare turns already ARE the navigator
+        // public activation (prevents summonPublicRole navigator ↔ attendance recursion).
+        if (
+          dependencies.createNavigatorAttendance !== undefined
+          && entry.role !== "navigator"
+        ) {
           let work: NavigatorWorkContext;
           let contextError: unknown;
           if (dependencies.loadNavigatorWorkContext === undefined) {

package/src/session-assistant-usage.ts

@@ -0,0 +1,119 @@
+/**
+ * Sum assistant-message usage rows from a session.jsonl (nested public summons).
+ * Accumulates real cost when rows carry it; never invents cost zeros (#675).
+ */
+import type { Usage } from "@earendil-works/pi-ai";
+import { join } from "node:path";
+
+import type { PublicSummonResult } from "./public-role-summons.ts";
+
+export async function readAssistantUsageFromSessionFile(
+  sessionFile: string,
+): Promise<Usage | undefined> {
+  const { readFile } = await import("node:fs/promises");
+  let text: string;
+  try {
+    text = await readFile(sessionFile, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  let rows: Array<{ type?: string; message?: { role?: string; usage?: Usage } }>;
+  try {
+    rows = text
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as {
+        type?: string;
+        message?: { role?: string; usage?: Usage };
+      });
+  } catch (error) {
+    throw new Error(
+      `session usage parse failed (${sessionFile}): ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  let total = 0;
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  let costInput = 0;
+  let costOutput = 0;
+  let costCacheRead = 0;
+  let costCacheWrite = 0;
+  let costTotal = 0;
+  let sawCost = false;
+  for (const row of rows) {
+    if (row.type !== "message" || row.message?.role !== "assistant") continue;
+    const usage = row.message.usage;
+    if (usage === undefined) continue;
+    total += usage.totalTokens ?? 0;
+    input += usage.input ?? 0;
+    output += usage.output ?? 0;
+    cacheRead += usage.cacheRead ?? 0;
+    cacheWrite += usage.cacheWrite ?? 0;
+    if (usage.cost !== undefined) {
+      sawCost = true;
+      costInput += usage.cost.input ?? 0;
+      costOutput += usage.cost.output ?? 0;
+      costCacheRead += usage.cost.cacheRead ?? 0;
+      costCacheWrite += usage.cost.cacheWrite ?? 0;
+      costTotal += usage.cost.total ?? 0;
+    }
+  }
+  if (total <= 0 && input <= 0 && output <= 0) return undefined;
+  const base = {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens: total > 0 ? total : input + output + cacheRead + cacheWrite,
+  };
+  // Cost only when session rows carried it — unknown stays absent (not zero).
+  if (!sawCost) return base as Usage;
+  return {
+    ...base,
+    cost: {
+      input: costInput,
+      output: costOutput,
+      cacheRead: costCacheRead,
+      cacheWrite: costCacheWrite,
+      total: costTotal,
+    },
+  };
+}
+
+/**
+ * Resolve the independent role run's session.jsonl from a public summon result.
+ * Prefers explicit runDirectory, then terminal artifacts, then no_receipt runPointer.
+ */
+export function sessionFileFromPublicSummon(
+  summoned: PublicSummonResult,
+): string | undefined {
+  if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
+    return join(summoned.runDirectory, "session", "session.jsonl");
+  }
+  const fromArtifacts = summoned.terminal?.artifacts
+    ?.map((a) => (a as { path?: string }).path)
+    .find((p): p is string => typeof p === "string" && p.endsWith("session.jsonl"));
+  if (fromArtifacts !== undefined) return fromArtifacts;
+  const outcome = summoned.terminal?.roleOutcome;
+  if (outcome === undefined) return undefined;
+  const facts = (outcome as { decisiveFacts?: Record<string, unknown> }).decisiveFacts;
+  const pointer = facts?.runPointer;
+  if (typeof pointer === "string" && pointer.trim() !== "") {
+    return join(pointer, "session", "session.jsonl");
+  }
+  return undefined;
+}
+
+/** Shared usage projection for nested public summons — undefined when unknown. */
+export async function usageFromPublicSummon(
+  summoned: PublicSummonResult,
+): Promise<Usage | undefined> {
+  const sessionFile = sessionFileFromPublicSummon(summoned);
+  if (sessionFile === undefined) return undefined;
+  return readAssistantUsageFromSessionFile(sessionFile);
+}

package/src/session-opening-materials.ts

@@ -3,7 +3,7 @@
  * errors. Main-role materials derive from PUBLIC_ROLE_RECORDS (including
  * gatekeeper and navigator). Province map reuses that public gatekeeper record
  * plus officer material constants (notary shared). Auditor composition stays in
- * loadAuditorSoul; loaders share joinPackageMaterials.
+ * loadAuditorSoul(subject); loaders share joinPackageMaterials.
  */
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";

package/src/shape-unreadable-failure.ts

@@ -0,0 +1,49 @@
+/**
+ * Single authoritative shape-unreadable marker (#675 / ADR 0055).
+ * Settlement stamps it; consumers only read it — never re-derive from cause=output.
+ */
+
+export const SHAPE_UNREADABLE_KEY = "shapeUnreadable" as const;
+
+export type ShapeUnreadableStamp = {
+  readonly [SHAPE_UNREADABLE_KEY]: true;
+  readonly candidate: unknown;
+  readonly acceptedReceipt: false;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Settlement seat path: stamp retained candidate as shape-unreadable (not infrastructure). */
+export function stampShapeUnreadableDetails(candidate: unknown): ShapeUnreadableStamp {
+  return {
+    [SHAPE_UNREADABLE_KEY]: true,
+    candidate,
+    acceptedReceipt: false,
+  };
+}
+
+/**
+ * Marker presence, decided independently of the candidate value: a stamped
+ * `undefined` candidate is a shape-unreadable decision, not an absent marker.
+ */
+export type RetainedShapeUnreadable = { readonly candidate: unknown };
+
+/**
+ * Read the settlement-stamped shape candidate from a failure decisiveFacts payload.
+ * Looks at root and secondaryEvidence only for the typed marker — no cause inference.
+ */
+export function retainedShapeUnreadable(decisiveFacts: unknown): RetainedShapeUnreadable | undefined {
+  if (!isRecord(decisiveFacts)) return undefined;
+  if (decisiveFacts[SHAPE_UNREADABLE_KEY] === true) {
+    return { candidate: decisiveFacts.candidate };
+  }
+  const secondary = isRecord(decisiveFacts.secondaryEvidence)
+    ? decisiveFacts.secondaryEvidence
+    : undefined;
+  if (secondary !== undefined && secondary[SHAPE_UNREADABLE_KEY] === true) {
+    return { candidate: secondary.candidate };
+  }
+  return undefined;
+}

package/src/submission-errors.ts

@@ -5,6 +5,9 @@ function gatekeeperNonPassMessage(result: GatekeeperNonPassResult): string {
     const findings = result.findings.length === 0 ? "（无 findings）" : result.findings.join("; ");
     return `门下省打回重写，findings：${findings}`;
   }
+  if (result.status === "unreadable") {
+    return `门下省官回执形状不可读（${result.officer}）：${result.reason}`;
+  }
   return `门下省 ${result.status}（${result.stage}）：${result.reason}`;
 }