@akagilnc/pi-workflow-roles 0.1.4980 → 0.1.4989

package/src/review-submission.ts

@@ -0,0 +1,29 @@
+/** One shared terminating receipt contract for review officers (#1028). */
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
+
+export const REVIEW_SUBMISSION_OUTPUT_TOOL_NAME = "ak_submission_output" as const;
+
+/** Open receipt: the queue reads only status; all other submitted fields ride unchanged. */
+export const reviewSubmissionSchema = withTerminatingOutputDeclarations(
+  openToolObject(
+    Type.Object({
+      status: Type.Optional(Type.Unknown({
+        description: "converged | continue | escalate — 非三态时请重读后重交，勿改标。",
+      })),
+      findings: Type.Optional(Type.Unknown({ description: "审核发现，原样留存" })),
+      reason: Type.Optional(Type.Unknown({ description: "上呈理由" })),
+      violations: Type.Optional(Type.Unknown({ description: "违规条目" })),
+      conflicts: Type.Optional(Type.Unknown({ description: "待决冲突" })),
+      fix: Type.Optional(Type.Unknown({ description: "continue 时的补救说明；可写 summary 摘要，其余内容原样留存" })),
+      classes: Type.Optional(Type.Unknown({ description: "已裁决 finding 类；可说明 name、owner、boundary、disposition，原样留存" })),
+      note: Type.Optional(Type.Unknown({ description: "裁决附注" })),
+      evidence: Type.Optional(Type.Unknown({ description: "留存证据" })),
+      decisionGate: Type.Optional(Type.Unknown({ description: "需人权威处置的问题与选项；可说明 question、options，原样留存" })),
+    }),
+  ),
+);
+
+export type ReviewSubmission = { readonly status?: unknown; readonly [key: string]: unknown };

package/src/role-envelope.ts

@@ -11,8 +11,8 @@ import {
 } from "./engine-detour.ts";
 import {
   createDefaultGateOfficerSummon,
-  requireGatekeeperPass,
-} from "./gatekeeper-pass-envelope.ts";
+  requireSubmissionGate,
+} from "./submission-gate.ts";
 import type {
   HostContext,
   HostEventRegistration,
@@ -233,12 +233,12 @@ export async function prepareRoleEnvelope(options: {
     // seat remains reachable through MCP.
     setActiveTools(names) { preferredTools = [...names]; },
     getActiveTools() { return [...preferredTools]; },
-    async requireGatekeeperPass(gateOptions) {
+    async requireSubmissionGate(gateOptions) {
       const packageRoot =
         typeof options.dependencies.packageRoot === "string"
           ? options.dependencies.packageRoot
           : undefined;
-      return requireGatekeeperPass({
+      return requireSubmissionGate({
         context: gateOptions.context,
         subject: gateOptions.subject,
         ...(gateOptions.signal === undefined ? {} : { signal: gateOptions.signal }),
@@ -301,7 +301,7 @@ export async function prepareRoleEnvelope(options: {
     if (record.kind === "role_infrastructure_failure") return;
     const code = typeof record.code === "string" && record.code.length > 0
       ? record.code
-      : record.status === "bounce" || record.status === "escalate" || record.status === "no_receipt"
+      : record.status === "continue" || record.status === "escalate" || record.status === "no_receipt"
         ? record.status
         : undefined;
     if (code === undefined) return;
@@ -314,11 +314,12 @@ export async function prepareRoleEnvelope(options: {
     };
   }
   function textDiagnostic(content: ContentPart[]): string | undefined {
-    // Keep concatenated text bytes intact for resume relay (#813 online P2):
-    // only emptiness uses the trimmed form; do not alter Markdown/spacing.
+    // Keep each text item's bytes intact and its boundary readable on the
+    // string-only host continuation channel.
     const text = content
-      .map((part) => (part.type === "text" ? part.text : ""))
-      .join("");
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n\n");
     return text.trim().length > 0 ? text : undefined;
   }
   /** Arm closeRound + abort path with the durable infrastructure failure for this round. */
@@ -483,6 +484,13 @@ export async function prepareRoleEnvelope(options: {
         details: result.details,
         isError: false,
       });
+      if (result.terminate === false) {
+        rejection = {
+          code: "continue",
+          toolCallIds: [toolCallId],
+          message: textDiagnostic(projected.content) ?? "continue",
+        };
+      }
       // Candidate only: seal waits for closeRound after the host round boundary.
       return { content: projected.content, isError: projected.isError };
     } catch (error) {

package/src/role-runtime.ts

@@ -119,7 +119,7 @@ import {
   type ReviewerActivation,
   type ReviewerAdmittedInputs,
 } from "./reviewer-role.ts";
-import type { GatekeeperNonPassResult } from "./gatekeeper-role.ts";
+import type { SubmissionGateNonPassResult } from "./gatekeeper-role.ts";
 
 /**
  * Private transport flag names/definitions for Reviewer admitted inputs.
@@ -256,7 +256,7 @@ import {
 
 /** One envelope map for Gatekeeper non-pass and other correct submission rejects (#525). */
 type SubmissionNonPassResult =
-  | GatekeeperNonPassResult
+  | SubmissionGateNonPassResult
   | CoderSkillExpansionEvidenceMissingResult;
 import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.ts";
 import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.ts";
@@ -319,7 +319,7 @@ export {
   runGatekeeper,
   gateOfficerForSubject,
 };
-export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, GateOfficer, RunGatekeeperOptions } from "./gatekeeper-role.ts";
+export type { GatekeeperResult, GatekeeperSubject, SubmissionGateNonPassResult, GateOfficer, RunGatekeeperOptions } from "./gatekeeper-role.ts";
 import { ParentQueueReaskError } from "./submission-errors.ts";
 
 export {
@@ -490,7 +490,7 @@ export type RoleRuntimeDependencies = {
   /**
    * Composition-root adapter table for nested gate officer summons (#969).
    * Production leaves unset (default pi + packaged externals). Tests inject
-   * faux nested hosts so prepareRoleEnvelope.requireGatekeeperPass is bitten
+   * faux nested hosts so prepareRoleEnvelope.requireSubmissionGate is bitten
    * without reimplementing the envelope summon closure.
    */
   hostAdapters?: readonly import("./public-cli/role-turn-host-resolution.ts").NamedRoleTurnHostAdapter[];
@@ -667,6 +667,14 @@ function createFiledOfficerRuntime(
             if (isAuditEscalationProjection(projected)) {
               return { content: [], details: projected, terminate: true as const };
             }
+            if (projected !== null && typeof projected === "object" && "status" in projected
+              && projected.status === "continue" && "receipt" in projected) {
+              return {
+                content: [{ type: "text" as const, text: readableGateItem(projected.receipt) }],
+                details: projected,
+                terminate: false,
+              };
+            }
             const pass = spec.relayGatePass === true && projected !== null && typeof projected === "object" && "officer" in projected && "receipt" in projected
               ? projected
               : undefined;
@@ -937,15 +945,15 @@ export function createDiaristRoleRuntime(
   );
 }
 
-/** Countersign status words the queue reads (#753). */
+/** Shared review-submission status words the queue reads (#1028). */
 const COUNTERSIGN_QUEUE_STATUSES = new Set(["converged", "continue", "escalate"]);
 
 /**
- * Plain-language re-ask when countersignStatus is not a known queue word.
+ * Plain-language re-ask when status is not a known queue word.
  * Back to countersign itself — notary is not summoned (#753).
  */
 const COUNTERSIGN_STATUS_REASK =
-  "countersignStatus 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
+  "status 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
 
 /** Secretariat status words the submission gate reads. */
 const SECRETARIAT_QUEUE_STATUSES = new Set(["converged", "escalate"]);
@@ -969,7 +977,7 @@ export function createSecretariatRoleRuntime(
   const beforeAccept: FiledOfficerBeforeAccept | undefined =
     hostActions !== undefined
       ? async ({ toolCallId, parameters, signal, ctx }) => {
-          if (roleHost.requireGatekeeperPass === undefined) {
+          if (roleHost.requireSubmissionGate === undefined) {
             const error = new Error("host cannot mount the secretariat submission gate");
             error.name = "InfrastructureFailure";
             return hostActions.failInfrastructure(error, ctx, toolCallId);
@@ -990,7 +998,7 @@ export function createSecretariatRoleRuntime(
             return undefined;
           }
           try {
-            const pass = await roleHost.requireGatekeeperPass!({
+            const pass = await roleHost.requireSubmissionGate!({
               context: ctx,
               subject: { kind: "secretariat_verdict" },
               ...(signal === undefined ? {} : { signal }),
@@ -1005,6 +1013,7 @@ export function createSecretariatRoleRuntime(
               pass !== undefined
               && pass !== null
               && typeof pass === "object"
+              && pass.status === "converged"
               && "receipt" in pass
             ) {
               const {
@@ -1112,7 +1121,7 @@ export function createCountersignRoleRuntime(
 ) {
   // Notary inner gate difference only — lifecycle stays on the shared envelope.
   // Pointer-only summons: officer self-fetches from run dossier (#632 / ADR 0079).
-  // #753 queue: read countersignStatus only — escalate skips gate (thrown to caller);
+  // #1028 queue: read shared status — escalate skips gate (thrown to caller);
   // unreadable status returns to countersign; else notary inner gate.
   const beforeAccept: FiledOfficerBeforeAccept | undefined =
     hostActions !== undefined
@@ -1122,8 +1131,8 @@ export function createCountersignRoleRuntime(
               ? (parameters as Record<string, unknown>)
               : undefined;
           const status =
-            record !== undefined && typeof record.countersignStatus === "string"
-              ? record.countersignStatus
+            record !== undefined && typeof record.status === "string"
+              ? record.status
               : undefined;
           if (status === undefined || !COUNTERSIGN_QUEUE_STATUSES.has(status)) {
             // Parent status unreadable → back to countersign itself; do not summon notary,
@@ -1134,13 +1143,13 @@ export function createCountersignRoleRuntime(
             // Parent escalate → throw to caller as-is; notary does not attend (#753).
             return undefined;
           }
-          if (roleHost.requireGatekeeperPass === undefined) {
+          if (roleHost.requireSubmissionGate === undefined) {
             const error = new Error("host cannot mount the countersign gate");
             error.name = "InfrastructureFailure";
             return hostActions.failInfrastructure(error, ctx, toolCallId);
           }
           try {
-            return await roleHost.requireGatekeeperPass({
+            return await roleHost.requireSubmissionGate({
               context: ctx,
               subject: { kind: "countersign_verdict" },
               ...(signal === undefined ? {} : { signal }),
@@ -1202,7 +1211,15 @@ export function createRoleRuntimeExtension(
     };
     const roleHost = createSubmissionLedgerHost(
       envelopeHost.host,
-      new Map(PACKAGED_ROLE_REGISTRY.map(({ role, outputTool }) => [outputTool, role])),
+      new Map(PACKAGED_ROLE_REGISTRY.reduce<(readonly [string, import("./public-cli/terminal.ts").TerminalRoleName | readonly import("./public-cli/terminal.ts").TerminalRoleName[]])[]>((entries, { role, outputTool }) => {
+        const existingIndex = entries.findIndex(([name]) => name === outputTool);
+        if (existingIndex < 0) entries.push([outputTool, role]);
+        else {
+          const previous = entries[existingIndex]![1];
+          entries[existingIndex] = [outputTool, [...(Array.isArray(previous) ? previous : [previous]), role]];
+        }
+        return entries;
+      }, [])),
       failInfrastructure,
       async (closed, context) => projectClosedSubmission(closed, context),
     );

package/src/submission-errors.ts

@@ -1,9 +1,9 @@
-import type { GatekeeperNonPassResult } from "./gatekeeper-role.ts";
+import type { SubmissionGateNonPassResult } from "./gatekeeper-role.ts";
 import { readableGateItem } from "./readable-gate-item.ts";
 
 /**
  * Tool-result text the parent model sees (#753 / #750 evidence).
- * bounce | escalate → officer receipt verbatim (JSON when structured).
+ * continue | escalate → officer receipt verbatim (JSON when structured).
  * no_receipt → honest lifecycle fact. No findings rewrite, no「（无 findings）」.
  * #775: structured field content via readableGateItem (DRY with other gate seams).
  */
@@ -11,8 +11,8 @@ function serializeReceipt(receipt: unknown): string {
   return readableGateItem(receipt);
 }
 
-function gatekeeperNonPassMessage(result: GatekeeperNonPassResult): string {
-  if (result.status === "bounce" || result.status === "escalate") {
+function gatekeeperNonPassMessage(result: SubmissionGateNonPassResult): string {
+  if (result.status === "continue" || result.status === "escalate") {
     return serializeReceipt(result.receipt);
   }
   if (result.status === "transport_failure") {
@@ -26,8 +26,8 @@ function gatekeeperNonPassMessage(result: GatekeeperNonPassResult): string {
 
 /** Structured non-pass; `.result` is session-projected via tool_result, message feeds the model. */
 export class GatekeeperDecisionError extends Error {
-  readonly result: GatekeeperNonPassResult;
-  constructor(result: GatekeeperNonPassResult, message?: string) {
+  readonly result: SubmissionGateNonPassResult;
+  constructor(result: SubmissionGateNonPassResult, message?: string) {
     super(message ?? gatekeeperNonPassMessage(result));
     this.name = "GatekeeperDecisionError";
     this.result = result;

package/src/{gatekeeper-pass-envelope.ts → submission-gate.ts}

@@ -1,14 +1,14 @@
 /**
- * Shared submit-path envelope for 门下省 gates (ADR 0018 / #675 / #753).
+ * Shared submissionGate path for review officers (ADR 0018 / #675 / #753).
  * Owns officer-pointer book + host abort/non-pass faces + review queue loop.
  * Role modules only project via projectGatekeeperRun / runGatekeeper — no book, no catch.
  *
  * Queue guarantee only (#753 / #756 / #750):
  *   parent submit → summon officer → read conclusion field
- *   pass → accept end
- *   bounce → raw officer receipt back to parent; escalate → audit_escalation terminal,
- *     without binding a correctable parent submission
- *   not three-state → resume officer with plain-language re-ask (no round cap)
+ *   converged → accept end
+ *   continue → raw officer receipt as a nonterminal result; parent may resubmit
+ *   escalate → audit_escalation terminal, without binding a correctable parent submission
+ *   unrecognized status → resume officer with plain-language re-ask (no round cap)
  *   transport / no_receipt → present honestly
  * Four pairs: countersign↔notary, judge↔auditor, worker↔inspector, secretariat↔countersign (#969).
  * Code does not judge content, map next-step for parent, or label unreadable/unusable.
@@ -20,7 +20,7 @@ import {
   GatekeeperDecisionError,
   officerConclusionReask,
   projectGatekeeperRun,
-  type GatekeeperPassHostActions,
+  type SubmissionGateHostActions,
   type GatekeeperResult,
   type GatekeeperSubject,
   type GateOfficer,
@@ -71,8 +71,8 @@ function bookDirectOfficerPointer(
   summoned: PublicSummonResult,
 ): void {
   if (
-    result.status !== "pass"
-    && result.status !== "bounce"
+    result.status !== "converged"
+    && result.status !== "continue"
     && result.status !== "escalate"
     && result.status !== "needs_reask"
     && result.status !== "transport_failure"
@@ -101,7 +101,8 @@ function bookDirectOfficerPointer(
  * Carries officer receipt + nested runId so seat settlement can project the
  * public terminal without a second authority.
  */
-export type GatekeeperPassOutcome = {
+export type SubmissionGateOutcome = {
+  readonly status: "converged" | "continue";
   readonly officer: GateOfficer;
   readonly receipt: unknown;
   readonly runId?: string;
@@ -110,13 +111,13 @@ export type GatekeeperPassOutcome = {
 /**
  * Shared envelope: project gate, book officer pointer, map onto host actions.
  * Review loop has no round cap (#753 no-round-cap).
- * On pass, returns the officer snapshot (receipt + nested runId) for seat projection.
+ * On converged, returns the officer snapshot (receipt + nested runId) for seat projection.
  */
-export async function requireGatekeeperPass(options: {
+export async function requireSubmissionGate(options: {
   readonly context: ExtensionContext | HostContext;
   readonly subject: GatekeeperSubject;
   readonly signal?: AbortSignal;
-  readonly hostActions: GatekeeperPassHostActions;
+  readonly hostActions: SubmissionGateHostActions;
   readonly toolCallId: string;
   /**
    * In-flight parent typed payload for this gate turn (#879). Relayed verbatim
@@ -125,9 +126,9 @@ export async function requireGatekeeperPass(options: {
   readonly submission?: unknown;
   /** Lowest seam: same as runGatekeeper options.summonOfficer — offline tracers only. */
   readonly summonOfficer?: GateOfficerSummon;
-}): Promise<GatekeeperPassOutcome | void> {
+}): Promise<SubmissionGateOutcome | void> {
   let reask: string | undefined;
-  // No round cap — end only on pass, bounce/escalate, or real failure.
+  // No round cap — end only on converged, continue/escalate, or real failure.
   const summonOfficer =
     options.summonOfficer ??
     createDefaultGateOfficerSummon({
@@ -156,8 +157,19 @@ export async function requireGatekeeperPass(options: {
         options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
       }
     }
-    if (gatekeeper.status === "pass") {
+    if (gatekeeper.status === "converged") {
       return {
+        status: "converged",
+        officer: projected.officer,
+        receipt: gatekeeper.receipt,
+        ...(typeof gatekeeper.runId === "string" && gatekeeper.runId.trim() !== ""
+          ? { runId: gatekeeper.runId }
+          : {}),
+      };
+    }
+    if (gatekeeper.status === "continue") {
+      return {
+        status: "continue",
         officer: projected.officer,
         receipt: gatekeeper.receipt,
         ...(typeof gatekeeper.runId === "string" && gatekeeper.runId.trim() !== ""
@@ -181,7 +193,8 @@ export async function requireGatekeeperPass(options: {
     if (gatekeeper.status === "escalate") {
       throw new GatekeeperDecisionError(gatekeeper);
     }
-    // bounce | no_receipt: parent stands and may resubmit. Not a run abort.
+    // no_receipt: keep the lifecycle failure channel; continue is an ordinary
+    // nonterminal tool result above, not an exception or correctable rejection.
     options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
     throw new GatekeeperDecisionError(gatekeeper);
   }

package/src/submission-ledger.ts

@@ -593,7 +593,7 @@ export async function sealAcceptedSubmission(options: {
  */
 export function createSubmissionLedgerHost(
   host: RoleHost,
-  outputTools: ReadonlyMap<string, TerminalRoleName>,
+  outputTools: ReadonlyMap<string, TerminalRoleName | readonly TerminalRoleName[]>,
   failInfrastructure: (error: unknown, context: HostContext) => never = (error) => { throw error; },
   projectClosure: (closed: ClosedSubmission, context: HostContext) => void | Promise<void> = () => undefined,
   options?: { home?: string },
@@ -646,7 +646,16 @@ export function createSubmissionLedgerHost(
   return {
     ...host,
     registerTool(tool) {
-      const role = outputTools.get(tool.name);
+      const registeredRole = outputTools.get(tool.name);
+      let role: TerminalRoleName | undefined;
+      if (typeof registeredRole === "string") {
+        role = registeredRole;
+      } else if (registeredRole !== undefined) {
+        const activeRole = host.getFlag("ak-role");
+        role = typeof activeRole === "string" && registeredRole.includes(activeRole as TerminalRoleName)
+          ? activeRole as TerminalRoleName
+          : undefined;
+      }
       if (role === undefined) return host.registerTool(tool);
       host.registerTool({
         ...tool,
@@ -735,7 +744,8 @@ export function createSubmissionLedgerHost(
             await projectClosure(closed, context);
             return result;
           }
-          // Terminating-tool wrap records every call; terminate flag does not withhold params.
+          // A continuing gate leaves the candidate recorded but has not accepted it.
+          if (result.terminate === false) return result;
           const closed: ClosedSubmission = {
             role,
             kind: "accepted",

package/src/ticket-trajectory.ts

@@ -44,7 +44,7 @@ import {
   validateAcceptedDetails,
   type TerminatingToolName,
 } from "./package-contracts/terminating-tools.ts";
-import { PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
+import { LEGACY_REVIEW_OUTPUT_ROLES, PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
 
 
 /** Declared refresh bound for the same viewing surface (seconds). */
@@ -140,9 +140,11 @@ async function realpathOrLexicalIfMissing(path: string): Promise<string> {
   }
 }
 
-const TOOL_TO_ROLE: ReadonlyMap<string, string> = new Map(
-  PACKAGED_ROLE_REGISTRY.map((entry) => [entry.outputTool, entry.role]),
-);
+const TOOL_TO_ROLE: ReadonlyMap<string, string> = new Map([
+  ...PACKAGED_ROLE_REGISTRY.filter((entry) => entry.outputTool !== "ak_submission_output")
+    .map((entry) => [entry.outputTool, entry.role] as const),
+  ...LEGACY_REVIEW_OUTPUT_ROLES,
+]);
 
 const NAME_PREFIX_ROLES: readonly string[] = PACKAGED_ROLE_REGISTRY.map((entry) => entry.role);
 
@@ -324,6 +326,9 @@ function resolveStation(input: {
   invocationRole?: string;
   runId: string;
 }): { station: string; stationSource: StationSource } {
+  if (input.invocationRole && input.toolNames.includes("ak_submission_output")) {
+    return { station: input.invocationRole, stationSource: "invocation" };
+  }
   for (const toolName of input.toolNames) {
     const role = roleFromToolName(toolName);
     if (role) return { station: role, stationSource: "tool" };

package/src/worker-role.ts

@@ -287,7 +287,7 @@ export function createFixerRoleRuntime(
             let pass;
             try {
               pass = WORKER_DONE_STATUSES.has(workerStatusOf(output))
-                ? await pi.requireGatekeeperPass!({
+                ? await pi.requireSubmissionGate!({
                     context: ctx,
                     subject: { kind: "worker_completion" },
                     ...(_signal === undefined ? {} : { signal: _signal }),
@@ -303,6 +303,13 @@ export function createFixerRoleRuntime(
               }
               throw error;
             }
+            if (pass?.status === "continue") {
+              return {
+                content: [{ type: "text" as const, text: readableGateItem(pass.receipt) }],
+                details: output,
+                terminate: false,
+              };
+            }
             const acceptedDetails = output;
             return {
               content: pass === undefined ? [] : [{ type: "text" as const, text: readableGateItem(pass.receipt) }],
@@ -435,7 +442,7 @@ export function createCoderRoleRuntime(
             let pass;
             try {
               pass = WORKER_DONE_STATUSES.has(workerStatusOf(output))
-                ? await pi.requireGatekeeperPass!({
+                ? await pi.requireSubmissionGate!({
                     context: ctx,
                     subject: { kind: "worker_completion" },
                     ...(_signal === undefined ? {} : { signal: _signal }),
@@ -451,6 +458,13 @@ export function createCoderRoleRuntime(
               }
               throw error;
             }
+            if (pass?.status === "continue") {
+              return {
+                content: [{ type: "text" as const, text: readableGateItem(pass.receipt) }],
+                details: output,
+                terminate: false,
+              };
+            }
             const acceptedDetails = output;
             return {
               content: pass === undefined ? [] : [{ type: "text" as const, text: readableGateItem(pass.receipt) }],