@akagilnc/pi-workflow-roles 0.1.3236 → 0.1.3249

package/src/collector-role.ts

@@ -18,9 +18,11 @@ import type { CollectorGitHubTransport } from "./collector-github.ts";
 import {
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
   createCollectorLedger,
+  projectEvidenceEntryView,
   type CollectorLedger,
 } from "./collector-ledger.ts";
 import {
@@ -30,32 +32,55 @@ import {
 import {
   collectorObserveArgsSchema,
   collectorOutputArgsSchema,
+  collectorReadArgsSchema,
   collectorRequestArgsSchema,
   collectorWaitArgsSchema,
 } from "./collector-tool-schemas.ts";
 import { COLLECTOR_ACCEPTED_TEXT } from "./package-contracts/collector-output.ts";
+import { CorrectableSubmissionError, isCorrectableExecuteError } from "./submission-correctable-error.ts";
+import { CollectorUnknownEvidenceError } from "./collector-identity.ts";
+
+export { CollectorUnknownEvidenceError } from "./collector-identity.ts";
+
+/**
+ * #641 chain②: normal completion must never declare `infrastructureFailure`.
+ * When the runtime can machine-verify a lawful receipt assembly, a declaration
+ * is model misuse — bounce it as correctable guidance instead of host failure.
+ */
+export class CollectorNormalCompletionDeclarationError extends CorrectableSubmissionError {
+  constructor() {
+    super("runtime 已按机器状态核验本局为正常完工（回执可合法组装）：正常完工的交件不得填 infrastructureFailure，请省略该字段后重新提交。");
+    this.name = "CollectorNormalCompletionDeclarationError";
+  }
+}
 
-export { COLLECTOR_FIXED_KICKOFF } from "./collector-config.ts";
+export {
+  COLLECTOR_FIXED_KICKOFF,
+} from "./collector-config.ts";
 export {
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 };
 
 export const COLLECTOR_REQUIRED_TOOLS = [
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
   COLLECTOR_OUTPUT_TOOL,
 ] as const;
 
 const observeSchema = collectorObserveArgsSchema;
+const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const outputSchema = collectorOutputArgsSchema;
 
 type RequestParams = Static<typeof requestSchema>;
+type ReadParams = Static<typeof readSchema>;
 type WaitParams = Static<typeof waitSchema>;
 type OutputParams = Static<typeof outputSchema>;
 
@@ -260,7 +285,7 @@ export function createCollectorRoleRuntime(
     pi.registerTool({
       name: COLLECTOR_OBSERVE_TOOL,
       label: "通进司观察",
-      description: "抓取配置目标的完整 GitHub PR 证据，存不可变快照入卷。",
+      description: "抓取配置目标的完整 GitHub PR 证据，存不可变快照入卷。正文在上下文中只给头部摘录加指针；需要头部之外的正文时，用 ak_collector_read 按 evidenceId 开卷；findings 的拆分与归类由你在交件时完成。",
       promptSnippet: "抓取配置目标 PR 证据",
       parameters: observeSchema,
       async execute(toolCallId: string, _params: unknown, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
@@ -269,7 +294,7 @@ export function createCollectorRoleRuntime(
         }
         try {
           activation.ledger.beginOperational(COLLECTOR_OBSERVE_TOOL, toolCallId);
-          const { snapshot, modelView } = await activation.ledger.observe(
+          const { snapshot, contextView } = await activation.ledger.observe(
             activation.transport,
             activation.clock,
             signal,
@@ -282,12 +307,55 @@ export function createCollectorRoleRuntime(
           return {
             content: [{
               type: "text" as const,
-              text: JSON.stringify(modelView),
+              // #641 chain①: model context carries bounded body heads + pointers only.
+              text: JSON.stringify(contextView),
+            }],
+            // #641 the bounded projection is the only provider-visible face on every host
+            // (Grok/ACP relays tool details as MCP structuredContent); full bodies stay
+            // in the ledger volume and enter context only by explicit ak_collector_read.
+            details: contextView,
+          };
+        } catch (error) {
+          hostActions.failInfrastructure(error, ctx, toolCallId);
+        }
+      },
+    });
+
+    pi.registerTool({
+      name: COLLECTOR_READ_TOOL,
+      label: "通进司开卷",
+      description: "按 evidenceId 开卷读取一条已观测材料的全量正文与指针；只在观察头部摘录不足以判读时调用。",
+      promptSnippet: "按指针开卷读材料",
+      parameters: readSchema,
+      async execute(toolCallId: string, params: ReadParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
+        if (activation === undefined) {
+          throw new Error("通进司未激活");
+        }
+        try {
+          activation.ledger.beginOperational(COLLECTOR_READ_TOOL, toolCallId);
+          const record = activation.ledger.getEvidence(params.evidenceId);
+          if (
+            record === undefined ||
+            (record.kind !== "review" && record.kind !== "issue_comment" && record.kind !== "review_comment" && record.kind !== "reaction") ||
+            typeof record.body !== "string"
+          ) {
+            throw new CollectorUnknownEvidenceError(params.evidenceId);
+          }
+          const material = projectEvidenceEntryView(record);
+          activation.ledger.completeOperational(toolCallId);
+          return {
+            content: [{
+              type: "text" as const,
+              // #641 chain①: full bodies enter provider context only by explicit pointer.
+              text: JSON.stringify(material),
             }],
-            details: modelView,
+            details: material,
           };
         } catch (error) {
-          hostActions.failInfrastructure(error, ctx);
+          if (isCorrectableExecuteError(error)) throw error;
+          // typed toolCallId books the shared infrastructure fact so settlement can
+          // tell a read tool's real host failure from a correctable pointer bounce.
+          hostActions.failInfrastructure(error, ctx, toolCallId);
         }
       },
     });
@@ -319,7 +387,7 @@ export function createCollectorRoleRuntime(
             details,
           };
         } catch (error) {
-          hostActions.failInfrastructure(error, ctx);
+          hostActions.failInfrastructure(error, ctx, toolCallId);
         }
       },
     });
@@ -350,7 +418,7 @@ export function createCollectorRoleRuntime(
             details,
           };
         } catch (error) {
-          hostActions.failInfrastructure(error, ctx);
+          hostActions.failInfrastructure(error, ctx, toolCallId);
         }
       },
     });
@@ -358,8 +426,20 @@ export function createCollectorRoleRuntime(
     pi.registerTool({
       name: COLLECTOR_OUTPUT_TOOL,
       label: "通进司输出",
-      description: "观察完成后提交；回执由 runtime 组装。",
+      description: "观察完成后提交；回执由 runtime 组装。正常完工提交空对象 {}（如需报 finding，填 findings 指针数组）；仅在基础设施真实失败时才可填 infrastructureFailure，无失败时必须省略该字段。",
       promptSnippet: "提交通进司回执",
+      // #641 chain②: the seat owns the normal-completion decision. The probe
+      // runs the exact receipt assembly (validation only, no accept side
+      // effects); success ⇒ machine-verified normal completion ⇒ bounce.
+      bounceInfrastructureDeclaration(params) {
+        if (activation === undefined) return undefined;
+        try {
+          buildCollectorReceipt(activation.ledger, params, activation.clock);
+        } catch {
+          return undefined;
+        }
+        return new CollectorNormalCompletionDeclarationError();
+      },
       parameters: outputSchema,
       async execute(toolCallId: string, params: OutputParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
         if (activation === undefined) {

package/src/collector-tool-schemas.ts

@@ -7,16 +7,39 @@ export const collectorRequestArgsSchema = Type.Object({
   requestId: Type.String({ minLength: 1, description: "配置请求身份" }),
   snapshotId: Type.String({ minLength: 1, description: "最新留存观察快照" }),
 }, { additionalProperties: false });
+export const collectorReadArgsSchema = Type.Object({
+  evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),
+}, { additionalProperties: false });
 export const collectorWaitArgsSchema = Type.Object({
   durationMs: Type.Integer({ minimum: 1, maximum: COLLECTOR_ELIGIBILITY_MS, description: "等待毫秒；单次上限五分钟且不超剩余资格" }),
 }, { additionalProperties: false });
-/** Runtime owns the observed groups; the model only signals sole-final submission. */
+
+/**
+ * #641 chain①: the collector LLM does the splitting/classification (#245:
+ * 他自己就是llm为什么不能读不能拆). Findings are submitted as pointer refs into
+ * the stored evidence; the runtime enriches each with the machine pointer
+ * (repo/PR/comment id/url/author/kind/时间) and validates resolvability.
+ * Category is a short LLM classification label, never a body transcription.
+ */
+export const collectorFindingArgsSchema = Type.Object({
+  evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),
+  category: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: "该 finding 的简短归类标签；需要头部之外的正文时先用 ak_collector_read 开卷再判读，不得誊写评论正文" })),
+}, { additionalProperties: false });
+
+export const collectorOutputBaseSchema = Type.Object({
+  findings: Type.Optional(Type.Array(collectorFindingArgsSchema, {
+    description: "本次收集到的逐条 findings；零 finding 的模板通知不得进入。正常完工无 finding 时省略。",
+  })),
+}, { additionalProperties: true, description: "正常完工提交空对象 {}；仅在基础设施真实失败时才填写 infrastructureFailure，无失败时必须省略该字段。" });
+
+/** Runtime owns the observed evidence; the model submits findings and signals sole-final submission. */
 export const collectorOutputArgsSchema = withInfrastructureFailureDeclaration(
-  Type.Object({}, { additionalProperties: true }),
+  collectorOutputBaseSchema,
 );
 (collectorOutputArgsSchema as unknown as { required: string[] }).required = [];
 
 export type CollectorObserveArgs = Static<typeof collectorObserveArgsSchema>;
 export type CollectorRequestArgs = Static<typeof collectorRequestArgsSchema>;
+export type CollectorReadArgs = Static<typeof collectorReadArgsSchema>;
 export type CollectorWaitArgs = Static<typeof collectorWaitArgsSchema>;
 export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;

package/src/host-contracts.ts

@@ -1,4 +1,5 @@
 import { Type, type Static, type TLiteral, type TSchema } from "typebox";
+import type { CorrectableSubmissionError } from "./submission-correctable-error.ts";
 
 type HostContentPart = { type: "text"; text: string } | { type: "toolCall"; id: string; name: string; arguments?: unknown } | { type: string };
 type HostMessage = { role: string; content?: unknown; toolName?: string; isError?: boolean; stopReason?: string };
@@ -209,7 +210,12 @@ type HostSessionManager = { getLeafEntry(): HostSessionEntry | undefined; getLea
 /** Context supplied by a host for one activation and its interceptable events. */
 export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
 
-export type HostToolDefinition<S extends TSchema = TSchema, D = unknown, C = HostContext> = { name: string; label: string; description: string; promptSnippet?: string; parameters: S; execute( toolCallId: string, params: Static<S>, signal: AbortSignal | undefined, update: ((result: HostToolResult<D>) => void) | undefined, context: C, ): Promise<HostToolResult<D>>; };
+export type HostToolDefinition<S extends TSchema = TSchema, D = unknown, C = HostContext> = { name: string; label: string; description: string; promptSnippet?: string; parameters: S; execute( toolCallId: string, params: Static<S>, signal: AbortSignal | undefined, update: ((result: HostToolResult<D>) => void) | undefined, context: C, ): Promise<HostToolResult<D>>; /**
+ * #641 chain② opt-in: when the output params carry the shared infrastructure
+ * declaration but the seat can machine-verify a lawful normal completion, the
+ * registration may bounce the submission as a correctable error instead of
+ * failing the host. Return the correctable error to bounce, or undefined to
+ * keep the shared host-failure path. */ bounceInfrastructureDeclaration?(params: unknown, toolCallId: string, context: C): CorrectableSubmissionError | undefined; };
 
 type BeforeAgentStartEvent = { prompt: string; systemPrompt: string; systemPromptOptions: { skills?: readonly unknown[]; contextFiles?: readonly unknown[]; appendSystemPrompt?: string } };
 type InputEvent = { text: string; images?: Array<{ type: "image"; data: string; mimeType: string }>; source?: string };

package/src/package-contracts/collector-output.ts

@@ -42,13 +42,21 @@ export type CollectorSnapshot = {
   normalizedByteLength: number;
 };
 
+/**
+ * #641 chain① receipt evidence record: pointer/integrity facts only. Bodies and
+ * raw payloads stay in the volume (observe details + GitHub pointer) and are
+ * never transcribed into the receipt.
+ */
 export type CollectorEvidenceRecord = {
   evidenceId: string;
   kind: string;
   versionId: string;
   contentDigest: string;
   firstObservedAt: string;
-  raw: unknown;
+  githubId?: number;
+  authorLogin?: string;
+  htmlUrl?: string;
+  authoritativeTime?: string | null;
 };
 
 export type CollectorReceipt = {
@@ -104,6 +112,6 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     snapshots: records(safeGet(value, "snapshots")).map((snapshot) => ({
       snapshotId: safeGet(snapshot, "snapshotId"), observedAt: safeGet(snapshot, "observedAt"), completedAt: safeGet(snapshot, "completedAt"), completedMono: safeGet(snapshot, "completedMono"), host: safeGet(snapshot, "host"), repository: safeGet(snapshot, "repository"), prNumber: safeGet(snapshot, "prNumber"), prState: safeGet(snapshot, "prState"), headOid: safeGet(snapshot, "headOid"), complete: safeGet(snapshot, "complete"), evidenceIds: strings(safeGet(snapshot, "evidenceIds")), pageDiagnostics: records(safeGet(snapshot, "pageDiagnostics")), normalizedByteLength: safeGet(snapshot, "normalizedByteLength"),
     } as CollectorSnapshot)),
-    evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), raw: safeGet(record, "raw") } as CollectorEvidenceRecord)),
+    evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), githubId: safeGet(record, "githubId"), authorLogin: safeGet(record, "authorLogin"), htmlUrl: safeGet(record, "htmlUrl"), authoritativeTime: safeGet(record, "authoritativeTime") } as CollectorEvidenceRecord)),
   };
 }

package/src/package-contracts/terminating-infrastructure.ts

@@ -12,6 +12,7 @@
  * Error so settlement keeps the original cause (kind=failure, exit 1).
  */
 import { Type, type TSchema } from "typebox";
+import type { CorrectableSubmissionError } from "../submission-correctable-error.ts";
 
 export const INFRASTRUCTURE_FAILURE_DECLARATION_KEY =
   "infrastructureFailure" as const;
@@ -115,15 +116,26 @@ function infrastructureFailureError(diagnostic: string): Error {
  * The one early call for every terminating output `execute`: if the parameters
  * carry the infra declaration, hand the diagnostic error to the shared host
  * `failInfrastructure` seam (which aborts the run). No-op otherwise.
+ *
+ * #641 chain②: an optional seat-owned bounce hook may intercept the
+ * declaration first — when the seat can machine-verify a lawful normal
+ * completion, it returns a correctable error and the declaration is treated as
+ * model misuse (交件契约封驳) instead of a host failure. Returning undefined
+ * keeps the shared failure path.
  */
 export function failOnInfrastructureFailureDeclaration<C>(
   parameters: unknown,
   hostActions: TerminatingInfrastructureHostActions<C>,
   ctx: C,
   toolCallId: string,
+  bounceInfrastructureDeclaration?: (params: unknown, toolCallId: string, ctx: C) => CorrectableSubmissionError | undefined,
 ): void {
   const diagnostic = infrastructureFailureDiagnostic(parameters);
   if (diagnostic === undefined) return;
+  if (bounceInfrastructureDeclaration !== undefined) {
+    const bounce = bounceInfrastructureDeclaration(parameters, toolCallId, ctx);
+    if (bounce !== undefined) throw bounce;
+  }
   hostActions.failInfrastructure(
     infrastructureFailureError(diagnostic),
     ctx,

package/src/public-cli/settlement.ts

@@ -44,6 +44,7 @@ import {
 // interval binding on historical session bytes). Provider-stop retain authority is Sitian.
 import {
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 } from "../collector-ledger.ts";
@@ -109,6 +110,7 @@ import {
 import {
   classifyPackagedRoleTerminalResult,
   findLatestDurablePackagedRoleTerminal,
+  hasNavigatorInfrastructureFailureBase,
   isAcceptedPackagedRoleTerminalResult,
   isReceiptSettlementBindingClear,
   NAVIGATOR_INVOCATION_ENTRY,
@@ -1604,6 +1606,7 @@ function boundErroredToolCandidate(
 /** Collector operational tools that fail closed via host infrastructure abort. */
 const COLLECTOR_INFRASTRUCTURE_TOOLS = new Set<string>([
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 ]);
@@ -1613,12 +1616,22 @@ type InfrastructureFailureSpec = Readonly<{
   matchTool: (toolName: string) => boolean;
   cause: ControlledFailureCause;
   identityName: string;
+  /**
+   * Errored results only count as infrastructure when the durable details carry
+   * the typed navigator fact. ak_collector_read also rejects known correctable
+   * misuses (CollectorUnknownEvidenceError pointer bounces) as errored tool
+   * results — those must not surface as CollectorInfrastructureError.
+   */
+  requireInfrastructureFact?: (toolName: string) => boolean;
 }>;
 
 const COLLECTOR_INFRASTRUCTURE_FAILURE_SPEC: InfrastructureFailureSpec = {
   matchTool: (toolName) => COLLECTOR_INFRASTRUCTURE_TOOLS.has(toolName),
   cause: "activation",
   identityName: "CollectorInfrastructureError",
+  // read alone has a correctable rejection mode (unknown/non-openable pointers);
+  // only its typed infrastructure-failure fact counts as a real host failure.
+  requireInfrastructureFact: (toolName) => toolName === COLLECTOR_READ_TOOL,
 };
 
 const ENGINE_DETOUR_INFRASTRUCTURE_FAILURE_SPEC: InfrastructureFailureSpec = {
@@ -1648,6 +1661,9 @@ function extractInfrastructureToolFailure(
     ) {
       continue;
     }
+    if (spec.requireInfrastructureFact?.(message.toolName) === true) {
+      if (!hasNavigatorInfrastructureFailureBase(message.details)) continue;
+    }
     const diagnostic = toolResultText(message);
     if (diagnostic.length === 0) continue;
     return {

package/src/role-runtime.ts

@@ -45,6 +45,7 @@ import type { CollectorGitHubTransport } from "./collector-github.ts";
 import {
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
   createCollectorRoleRuntime,
@@ -388,6 +389,7 @@ export type { ComplianceDecision } from "./compliance-transport.ts";
 export {
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 } from "./collector-role.ts";

package/src/submission-ledger.ts

@@ -283,19 +283,25 @@ export function createSubmissionLedgerHost(
           if (state.sealed) throw new Error("提交账已封账");
           // #541 / #575: shared infra-declaration fail lives on the ledger seam,
           // before any role execute or sole-final work (one owner for every seat).
-          failOnInfrastructureFailureDeclaration(
-            params,
-            {
-              failInfrastructure(error, ctx) {
-                failInfrastructure(error, ctx);
-              },
-            },
-            context,
-            toolCallId,
-          );
+          // #641 chain②: seats may opt into bouncing a machine-verified normal
+          // completion misdeclared as infrastructure failure — the bounce throws a
+          // correctable error from the declaration call, so it lands in the same
+          // correctable-rejection path as execute-thrown rejections below. The
+          // candidate is booked first so the bounced attempt stays observable.
           append({ type: "candidate", attemptId, toolCallId, toolName: tool.name, sequence: ++state.sequence });
           let result: HostToolResult<unknown>;
           try {
+            failOnInfrastructureFailureDeclaration(
+              params,
+              {
+                failInfrastructure(error, ctx) {
+                  failInfrastructure(error, ctx);
+                },
+              },
+              context,
+              toolCallId,
+              tool.bounceInfrastructureDeclaration,
+            );
             result = await tool.execute(toolCallId, params, signal, update, context);
           } catch (error) {
             if (isCorrectableExecuteError(error)) {