@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2535

package/src/public-cli/settlement.ts

@@ -93,6 +93,7 @@ import {
 } from "../navigator-invocation-identity.ts";
 import type { NavigatorPhase } from "../navigator-attendance.ts";
 import { NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, parseNoReceiptLifecycleFacts, type NoReceiptLifecycleFacts } from "../receipt-delivery-policy.ts";
+import { INSPECTOR_OUTPUT_TOOL_NAME } from "../inspector-contracts.ts";
 import {
   ensureRunArtifactsDir,
   type AdmittedCoderInvocation,
@@ -100,6 +101,7 @@ import {
   type AdmittedDoctorInvocation,
   type AdmittedFixerInvocation,
   type AdmittedJudgeInvocation,
+  type AdmittedInspectorInvocation,
   type AdmittedMergerInvocation,
   type AdmittedNotaryInvocation,
   type AdmittedReviewerInvocation,
@@ -3057,6 +3059,83 @@ export async function trySettleDoctorTerminalResult(
   return settleLawfulDoctorTerminalResult(admitted);
 }
 
+export function extractInspectorRoleOutcome(entries: readonly SessionEntry[]): TerminalResult["roleOutcome"] | undefined {
+  if (!isReceiptSettlementBindingClear(entries)) return undefined;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const message = entries[index]?.message;
+    if (message?.role !== "toolResult" || message.toolName !== INSPECTOR_OUTPUT_TOOL_NAME) continue;
+    if (!isAcceptedPackagedRoleTerminalResult(message)) continue;
+    const details = message.details;
+    if (typeof details !== "object" || details === null) continue;
+    const status = Reflect.get(details, "status");
+    if (status !== "pass" && status !== "bounce") continue;
+    const findings = Reflect.get(details, "findings");
+    return { kind: "accepted", role: "inspector", status, decisiveFacts: { findings } };
+  }
+  return undefined;
+}
+
+type UnusableOutputReceipt = Readonly<{
+  candidate: unknown;
+  diagnostic: string;
+}>;
+
+function findUnusableOutputReceipt(
+  entries: readonly SessionEntry[],
+  toolName: string,
+  isUsable: (candidate: unknown) => boolean,
+  diagnostic: string,
+): UnusableOutputReceipt | undefined {
+  let acceptedNonUsable: unknown | undefined;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const message = entries[index]?.message;
+    if (message?.role !== "toolResult") continue;
+    const residual = boundErroredToolCandidate(entries, index, message, toolName);
+    if (residual !== undefined) {
+      return { candidate: residual.candidate, diagnostic: residual.diagnostic };
+    }
+    if (
+      acceptedNonUsable === undefined &&
+      message.toolName === toolName &&
+      isAcceptedPackagedRoleTerminalResult(message) &&
+      !isUsable(message.details)
+    ) {
+      acceptedNonUsable = message.details;
+    }
+  }
+  return acceptedNonUsable === undefined
+    ? undefined
+    : { candidate: acceptedNonUsable, diagnostic };
+}
+
+export async function trySettleInspectorTerminalResult(
+  admitted: AdmittedInspectorInvocation,
+): Promise<TerminalResult | undefined> {
+  const entries = await readLawfulSettlementEntries(admitted);
+  if (entries === undefined) return undefined;
+  const outcome = extractInspectorRoleOutcome(entries);
+  if (outcome !== undefined) {
+    return withOptionalGateProjection({
+      roleOutcome: outcome,
+      navigator: extractNavigatorFact(entries), artifacts: [], runId: admitted.runId,
+    }, admitted.sessionDirectory);
+  }
+  const unusable = findUnusableOutputReceipt(
+    entries,
+    INSPECTOR_OUTPUT_TOOL_NAME,
+    (candidate) => isRecord(candidate) &&
+      (candidate.status === "pass" || candidate.status === "bounce"),
+    "给事中回执无显式 pass/bounce",
+  );
+  return unusable === undefined
+    ? undefined
+    : settleFailureTerminalResult(admitted, {
+      cause: "output",
+      diagnostic: unusable.diagnostic,
+      details: { candidate: unusable.candidate, acceptedReceipt: false },
+    });
+}
+
 /** Lawful Notary accepted outcome (pass/bounce). */
 export type LawfulNotaryRoleOutcome = {
   kind: "accepted";
@@ -3099,46 +3178,26 @@ async function settleLawfulNotaryTerminalResult(
   if (entries === undefined) return undefined;
   const extracted = extractNotaryRoleOutcome(entries);
   if (extracted === undefined) {
-    // No usable Notary release → existing non-zero failure channel with candidate (#475 / ADR 0055).
-    // One reverse pass: prefer errored residual; else latest accepted-once non-usable details.
-    let acceptedNonUsable: unknown | undefined;
-    for (let index = entries.length - 1; index >= 0; index -= 1) {
-      const message = entries[index]?.message;
-      if (message?.role !== "toolResult") continue;
-      const residual = boundErroredToolCandidate(
-        entries,
-        index,
-        message,
-        NOTARY_OUTPUT_TOOL_NAME,
-      );
-      if (residual !== undefined) {
-        return settleFailureTerminalResult(admitted, {
-          cause: "output",
-          diagnostic: residual.diagnostic,
-          details: { candidate: residual.candidate, acceptedReceipt: false },
-        });
-      }
-      if (
-        acceptedNonUsable === undefined &&
-        message.toolName === NOTARY_OUTPUT_TOOL_NAME &&
-        isAcceptedPackagedRoleTerminalResult(message)
-      ) {
-        // Accepted once but not a lawful pass/bounce — hold as fallback.
+    const unusable = findUnusableOutputReceipt(
+      entries,
+      NOTARY_OUTPUT_TOOL_NAME,
+      (candidate) => {
         try {
-          validateRecordedNotaryOutput(message.details);
+          validateRecordedNotaryOutput(candidate);
+          return true;
         } catch {
-          acceptedNonUsable = message.details;
+          return false;
         }
-      }
-    }
-    if (acceptedNonUsable !== undefined) {
-      return settleFailureTerminalResult(admitted, {
+      },
+      "符宝郎回执无显式 pass/bounce",
+    );
+    return unusable === undefined
+      ? undefined
+      : settleFailureTerminalResult(admitted, {
         cause: "output",
-        diagnostic: "符宝郎回执无显式 pass/bounce",
-        details: { candidate: acceptedNonUsable, acceptedReceipt: false },
+        diagnostic: unusable.diagnostic,
+        details: { candidate: unusable.candidate, acceptedReceipt: false },
       });
-    }
-    return undefined;
   }
   const navigator = extractNavigatorFact(entries);
   return withOptionalGateProjection(

package/src/public-cli/terminal.ts

@@ -38,7 +38,8 @@ export type TerminalRoleName =
   | "doctor"
   | "reviewer"
   | "merger"
-  | "notary";
+  | "notary"
+  | "inspector";
 
 /** Merger/Collector residual only — Notary/audit residual abolished (#475). */
 export type ResidualIncompleteTerminalOutcome = {

package/src/role-runtime.ts

@@ -1,5 +1,5 @@
 import { writeSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
@@ -39,6 +39,9 @@ import {
 import type { ComplianceDecision } from "./compliance-transport.ts";
 import { createDoctorRoleRuntime } from "./doctor-role.ts";
 import { createNotaryRoleRuntime } from "./notary-role.ts";
+import { inspectorOutputSchema, projectInspectorReceipt } from "./inspector-role.ts";
+import { failOnInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
+import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
 import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
@@ -367,6 +370,7 @@ type ActivationRuntime = {
   collector: { activate(context: ExtensionContext, event: { reason: string }): Promise<void> };
   doctor: { activate(): Promise<void> };
   notary: { activate(): Promise<void> };
+  inspector: { activate(): Promise<void> };
   merger(): Promise<void>;
 };
 
@@ -404,6 +408,7 @@ function activationStage(role: PackagedRole, runtime: ActivationRuntime): { id:
     case "collector": return { id: "load-and-install", run: async () => runtime.collector.activate(runtime.context, runtime.event) };
     case "doctor": return { id: "load-and-install", run: async () => runtime.doctor.activate() };
     case "notary": return { id: "load-and-install", run: async () => runtime.notary.activate() };
+    case "inspector": return { id: "load-and-install", run: async () => runtime.inspector.activate() };
     case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
   }
 }
@@ -486,6 +491,7 @@ export type RoleRuntimeDependencies = {
   createCollectorTransport?(): CollectorGitHubTransport;
   loadDoctorSoul?(): Promise<string>;
   loadNotarySoul?(): Promise<string>;
+  loadInspectorSoul?(): Promise<string>;
   loadNotarySourceRun?(path: string): Promise<import("./notary-contracts.ts").NotarySourceRunLocator>;
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
@@ -989,6 +995,42 @@ export function createRoleRuntimeExtension(
       async loadCase(path) { if (!dependencies.loadDoctorCase) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorCase(path); },
       async auditCompliance(options) { if (!dependencies.auditDoctorCompliance) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.auditDoctorCompliance(options); },
     }, hostActions);
+    let inspectorSoul: string | undefined;
+    let inspectorRegistered = false;
+    const inspector = {
+      async activate(): Promise<void> {
+        if (!dependencies.loadInspectorSoul) throw new Error("Inspector runtime dependencies are not configured");
+        inspectorSoul = (await dependencies.loadInspectorSoul()).trim();
+        if (inspectorSoul.length === 0) throw new Error("Inspector soul is empty");
+        if (!inspectorRegistered) {
+          inspectorRegistered = true;
+          pi.registerTool({
+            name: INSPECTOR_OUTPUT_TOOL_NAME,
+            label: "给事中输出",
+            description: "给事中终局回执，状态为 pass 或 bounce。",
+            promptSnippet: "给事中终局回执",
+            parameters: inspectorOutputSchema,
+            async execute(toolCallId, parameters, _signal, _onUpdate, ctx): Promise<AgentToolResult<unknown>> {
+              failOnInfrastructureFailureDeclaration(parameters, hostActions, ctx, toolCallId);
+              const leaf = ctx.sessionManager.getLeafEntry();
+              const calls = leaf?.type === "message" && leaf.message.role === "assistant"
+                ? leaf.message.content.filter((part) => part.type === "toolCall")
+                : [];
+              if (calls.length !== 1 || calls[0]?.id !== toolCallId || calls[0]?.name !== INSPECTOR_OUTPUT_TOOL_NAME) {
+                throw new Error("给事中回执非唯一终局工具调用");
+              }
+              return projectInspectorReceipt(parameters);
+            },
+          });
+          pi.on("before_agent_start", (event) => {
+            if (inspectorSoul === undefined) throw new Error("给事中未激活");
+            return { systemPrompt: `${event.systemPrompt}\n\n<inspector_soul>\n${inspectorSoul}\n</inspector_soul>` };
+          });
+        }
+        const tools = pi.getAllTools().filter((tool) => tool.name === INSPECTOR_OUTPUT_TOOL_NAME);
+        if (tools.length !== 1) throw new Error(`Inspector required tool collision or missing: ${INSPECTOR_OUTPUT_TOOL_NAME}`);
+      },
+    };
     const notary = createNotaryRoleRuntime(pi, {
       async loadSoul() {
         if (!dependencies.loadNotarySoul) throw new Error("Notary runtime dependencies are not configured");
@@ -1138,6 +1180,7 @@ export function createRoleRuntimeExtension(
         collector,
         doctor,
         notary,
+        inspector,
         merger: async () => {
           if (dependencies.mergerGitState === undefined) {
             sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);