@akagilnc/pi-workflow-roles 0.1.5079 → 0.1.5096

package/src/role-runtime.ts

@@ -23,6 +23,7 @@ import {
   durableSessionPointer,
   resolveBookKeyFromGit,
 } from "./activation-ledger.ts";
+import { readPackageMaterial } from "./session-opening-materials.ts";
 import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
 import {
   createToolExecutionObservationFace,
@@ -38,7 +39,7 @@ import {
 } from "./engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "./package-resources/engine-material.ts";
 import { registerEngineDetourTool } from "./engine-detour-tool.ts";
-import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
+import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE } from "./receipt-delivery-policy.ts";
 import type { CollectorClock } from "./collector-evidence.ts";
 import type { CollectorGitHubTransport } from "./collector-github.ts";
 import {
@@ -98,7 +99,8 @@ import {
   type AuditorRuntimeDependencies,
 } from "./auditor-role.ts";
 
-import { 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";
+import { formatNavigatorReport, NAVIGATOR_EVENT_TYPE, NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
+import { loadNavigatorWorkBaseSuffix } from "./navigator-work-base.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
   classifyPackagedRoleTerminalResult,
@@ -108,7 +110,7 @@ import {
 } from "./navigator-invocation-identity.ts";
 import { recordTypedProviderHttpStatus } from "./typed-provider-http.ts";
 import { NAVIGATOR_POST_ROLE_GRACE_MS, raceNavigatorGrace } from "./public-cli/settlement.ts";
-import { PACKAGED_ROLE_REGISTRY, isOfficerReviewSeat, packagedRoleActivationFlags, packagedRoleInputFlag, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag, type PackagedRole } from "./packaged-role-registry.ts";
+import { PACKAGED_ROLE_REGISTRY, isOfficerReviewSeat, packagedRoleActivationFlags, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag, type PackagedRole } from "./packaged-role-registry.ts";
 import { isAuditEscalationProjection } from "./audit-escalation.ts";
 import {
   createJudgeRoleRuntime,
@@ -301,7 +303,6 @@ import {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
-  createGatekeeperOutputTool,
   runGatekeeper,
   gateOfficerForSubject,
 } from "./gatekeeper-role.ts";
@@ -309,7 +310,6 @@ export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
-  createGatekeeperOutputTool,
   runGatekeeper,
   gateOfficerForSubject,
 };
@@ -452,29 +452,7 @@ export const ROLE_FLAG = {
   },
 } as const;
 
-/** Host-neutral in-process role help for Navigator prepare (Pi and Grok share this). */
-export function formatNavigatorRoleHelp(role: NavigatorTargetRole): string {
-  const metadata = packagedRoleMetadata(role);
-  const lines = [
-    `Usage: ak-role ${role}`,
-    ROLE_FLAG.definition.description,
-  ];
-  const inputFlag = packagedRoleInputFlag(role);
-  if (inputFlag !== undefined) {
-    lines.push(`  --${inputFlag} <value>    ${role} input material`);
-  }
-  const phaseFlag = packagedRolePhaseFlag(role);
-  if (phaseFlag !== undefined && metadata !== undefined) {
-    lines.push(
-      `  --${phaseFlag} <value>    ${role} phase: ${(metadata.phases.filter((p) => p !== null) as string[]).join(" | ")}`,
-    );
-  }
-  lines.push(`Public next-command form: ak-role ${role}`);
-  return lines.join("\n");
-}
-
-type NavigatorAttendanceDependency = Omit<NavigatorAttendance, "knownRoutePlaybookReadFailure"> &
-  Partial<Pick<NavigatorAttendance, "knownRoutePlaybookReadFailure">>;
+type NavigatorAttendanceDependency = NavigatorAttendance;
 
 export type RoleRuntimeDependencies = {
   /** Package root for packaged engine-note resolution (#879). */
@@ -754,7 +732,7 @@ export function createNavigatorRoleRuntime(
   roleHost: RoleHost,
   dependencies: NavigatorRuntimeDependencies,
 ) {
-  return createFiledOfficerRuntime(
+  const base = createFiledOfficerRuntime(
     roleHost,
     {
       role: "navigator",
@@ -763,6 +741,43 @@ export function createNavigatorRoleRuntime(
     },
     dependencies,
   );
+  let playbookBound = false;
+  return {
+    async activate() {
+      await base.activate();
+      if (playbookBound) return;
+      playbookBound = true;
+      // Standing system prompt, not a per-turn user message. Native read failure
+      // is the explanation (ADR 0061); no code-written sentence.
+      const loadRoutePlaybook = dependencies.loadRoutePlaybook
+        ?? (() => readPackageMaterial("resources/navigator-route-playbook.md"));
+      let playbookRead: Promise<string> | undefined;
+      roleHost.on("before_agent_start", async (event) => {
+        const basePrompt = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
+        const parts: string[] = [];
+        try {
+          playbookRead ??= loadRoutePlaybook();
+          const content = await playbookRead;
+          dependencies.recordRoutePlaybookReadFailure?.(undefined);
+          if (content.trim() !== "") parts.push(content);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.trim() !== "") {
+            dependencies.recordRoutePlaybookReadFailure?.(message);
+            parts.push(message);
+          }
+        }
+        const prompt = typeof event.prompt === "string" ? event.prompt : "";
+        const work = await loadNavigatorWorkBaseSuffix(prompt);
+        if (work !== undefined && work.trim() !== "") parts.push(work);
+        if (parts.length === 0) return;
+        const text = parts.join("\n\n");
+        return {
+          systemPrompt: basePrompt.trim() === "" ? text : `${basePrompt}\n\n${text}`,
+        };
+      });
+    },
+  };
 }
 
 /** #675: public 审刑院 seat on the shared filed-officer envelope. */
@@ -1311,13 +1326,11 @@ export function createRoleRuntimeExtension(
         const raced = await raceNavigatorGrace(settlePromise, NAVIGATOR_POST_ROLE_GRACE_MS);
         if (raced.status !== "timeout") return;
         if (pendingNavigatorPresentation === undefined) {
-          const routePlaybookReadFailure = attendance.knownRoutePlaybookReadFailure?.();
           const report: NavigatorReport = {
             disposition: "unavailable",
             unavailableReason: "Navigator exceeded post-role delivery grace",
             unavailableSource: "unknown",
             unavailableCause: "unknown",
-            ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
           };
           const event: NavigatorEvent = {
             version: 1,
@@ -1329,7 +1342,6 @@ export function createRoleRuntimeExtension(
             unavailableReason: "Navigator exceeded post-role delivery grace",
             unavailableSource: "unknown",
             unavailableCause: "unknown",
-            ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
           };
           pendingNavigatorPresentation = { event, report };
         }
@@ -1600,7 +1612,7 @@ export function createRoleRuntimeExtension(
         } catch {}
         envelopeHost.sendMessage({
           customType: "ak-receipt-delivery-prompt",
-          content: RECEIPT_DELIVERY_PROMPT,
+          content: JSON.stringify(receiptDelivery.deliveryState()),
           display: false,
         }, { triggerTurn: true, deliverAs: "followUp" });
       } else if (receiptDelivery.nextAction() === "no-receipt" && !noReceiptRecorded) {
@@ -1773,6 +1785,11 @@ export function createRoleRuntimeExtension(
     });
     const navigator = createNavigatorRoleRuntime(roleHost, {
       loadSoul: () => requireRoleSoul("navigator"),
+      recordRoutePlaybookReadFailure: (message) => {
+        envelopeHost.appendEntry(NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, {
+          message: message ?? "",
+        });
+      },
     });
     const auditor = createAuditorRoleRuntime(roleHost, {
       loadSoul: () => requireRoleSoul("auditor"),
@@ -2159,11 +2176,8 @@ export function createRoleRuntimeExtension(
               pendingNavigatorPresentation = { event: navigatorEvent, report };
             },
           });
-          // Warm live help during activation so prepare is not help-bound under load.
-          // Concrete work context also starts full preparation so session create
-          // overlaps the role run. Placeholder subjects wait for before_agent_start
-          // (user prompt may replace the subject key) but still inherit warm help.
-          navigatorAttendance.warmHelp?.();
+          // Concrete work context starts standby attendance (record only, no model).
+          // Placeholder subjects wait for before_agent_start (user prompt may replace the subject key).
           if (
             navigatorWorkContext.contextError === undefined &&
             navigatorWorkContext.subjectProvenance !== "placeholder"

package/src/secretariat-role.ts

@@ -12,12 +12,12 @@ import { SECRETARIAT_OUTPUT_TOOL_NAME, type SecretariatVerdict } from "./secreta
 export { SECRETARIAT_OUTPUT_TOOL_NAME } from "./secretariat-contracts.ts";
 export type { SecretariatVerdict };
 
-/** 中书省终局回执形状；形状指引，非 schema 闸。 */
+/** 中书省终局回执形状。 */
 export const secretariatVerdictSchema = withTerminatingOutputDeclarations(
   Type.Object(
     {
       secretariatStatus: Type.Unknown({
-        description: "converged | escalate（终局形状指引，非闸）",
+        description: "converged | escalate",
       }),
       ticketNumber: Type.Optional(
         Type.Number({ description: "本票号；署时指向最终正文所在票" }),
@@ -44,7 +44,7 @@ export type SecretariatVerdictParameters = Static<typeof secretariatVerdictSchem
 export const SECRETARIAT_OUTPUT_TOOL_SPEC = {
   name: SECRETARIAT_OUTPUT_TOOL_NAME,
   label: "中书省输出",
-  description: "中书省终局回执（署或上呈）；给事中封驳须改票重送，不在此终局。",
+  description: "中书省终局回执。",
   promptSnippet: "中书省终局回执",
   parameters: secretariatVerdictSchema,
 } as const;

package/src/worker-role.ts

@@ -48,7 +48,7 @@ export type { WorkerOutput };
 // One shared description across every variant
 // so openToolObjectFromUnion's identical-declaration collapse drops none of it.
 const CODER_STATUS_DESCRIPTION =
-  "planned | completed | refused | partially_completed | unfinished — 形状指引，非 schema 闸；completed 回执含 TDD、同模式、引入回归、行为事实四项证据；unfinished 缺前置或违宪约束致本局未完成时可用，缺待决 owner 决定或答复属缺前置。" as const;
+  "planned | completed | refused | partially_completed | unfinished。unfinished：缺前置或违宪约束致本局未完成。" as const;
 const coderOutputVariants = Type.Union([
   Type.Object({
     status: Type.Unknown({ description: CODER_STATUS_DESCRIPTION }),
@@ -254,7 +254,7 @@ export function createFixerRoleRuntime(
         pi.registerTool({
           name: FIXER_OUTPUT_TOOL_NAME,
           label: "修内司输出",
-          description: "提交修内司终局回执；基础设施失败走 abort，不经本工具。",
+          description: "提交修内司终局回执。",
           promptSnippet: "提交修内司终局回执",
           parameters: fixerOutputSchema,
           async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
@@ -381,7 +381,7 @@ export function createCoderRoleRuntime(
         pi.registerTool({
           name: CODER_OUTPUT_TOOL_NAME,
           label: "将作监输出",
-          description: "提交将作监终局回执；本工具无 escalate 通道。",
+          description: "提交将作监终局回执。",
           promptSnippet: "提交将作监终局回执",
           parameters: coderOutputSchema,
           async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {