@akagilnc/pi-workflow-roles 0.1.3783 → 0.1.3795

package/dist/collector-role.js

@@ -1,9 +1,10 @@
 import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "./collector-config.js";
-import { createSystemCollectorClock, } from "./collector-evidence.js";
+import { COLLECTOR_DEFAULT_WAIT_WINDOW_MS, createSystemCollectorClock, } from "./collector-evidence.js";
 import { createGhApiRunner, listPullRequestNumbersByTicket, } from "./collector-github.js";
-import { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, projectEvidenceEntryView, } from "./collector-ledger.js";
+import { createCollectorHandbookStore, resolveCollectorHandbookRoot, } from "./collector-handbook.js";
+import { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OPEN_WAIT_WINDOW_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, projectEvidenceEntryView, } from "./collector-ledger.js";
 import { buildCollectorReceipt, } from "./collector-receipt.js";
-import { collectorBindTargetArgsSchema, collectorObserveArgsSchema, collectorOutputArgsSchema, collectorReadArgsSchema, collectorRequestArgsSchema, collectorWaitArgsSchema, } from "./collector-tool-schemas.js";
+import { collectorBindTargetArgsSchema, collectorHandbookWriteArgsSchema, collectorObserveArgsSchema, collectorOpenWaitWindowArgsSchema, collectorOutputArgsSchema, collectorReadArgsSchema, collectorRequestArgsSchema, collectorWaitArgsSchema, } from "./collector-tool-schemas.js";
 import { COLLECTOR_ACCEPTED_TEXT } from "./package-contracts/collector-output.js";
 import { CorrectableSubmissionError, isCorrectableExecuteError } from "./submission-correctable-error.js";
 import { CollectorUnknownEvidenceError } from "./collector-identity.js";
@@ -26,13 +27,15 @@ export class CollectorTargetBindError extends CorrectableSubmissionError {
         this.name = "CollectorTargetBindError";
     }
 }
-export { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, };
+export { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OPEN_WAIT_WINDOW_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, };
 export const COLLECTOR_REQUIRED_TOOLS = [
     COLLECTOR_BIND_TARGET_TOOL,
     COLLECTOR_OBSERVE_TOOL,
     COLLECTOR_READ_TOOL,
     COLLECTOR_REQUEST_TOOL,
+    COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
     COLLECTOR_WAIT_TOOL,
+    COLLECTOR_HANDBOOK_WRITE_TOOL,
     COLLECTOR_OUTPUT_TOOL,
 ];
 /** Envelope-owned transport flags (ADR 0018 / #676 E). */
@@ -58,23 +61,61 @@ export const COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
             type: "string",
         }),
     }),
+    Object.freeze({
+        name: "ak-collector-wait-ms",
+        definition: Object.freeze({
+            description: `Collector wait-window duration in milliseconds (default ${COLLECTOR_DEFAULT_WAIT_WINDOW_MS}). Caller-configurable; opens at a work step, not session start (#678 D4).`,
+            type: "string",
+        }),
+    }),
 ]);
 const observeSchema = collectorObserveArgsSchema;
 const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
+const openWaitWindowSchema = collectorOpenWaitWindowArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const bindSchema = collectorBindTargetArgsSchema;
+const handbookWriteSchema = collectorHandbookWriteArgsSchema;
 const outputSchema = collectorOutputArgsSchema;
+function parseWaitWindowMsFlag(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
+    if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1)
+        return raw;
+    if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim())) {
+        const value = Number(raw.trim());
+        if (Number.isSafeInteger(value) && value >= 1)
+            return value;
+    }
+    throw new Error("Collector --ak-collector-wait-ms must be a positive safe-integer millisecond string");
+}
 function buildMethodContext(activation) {
     const pr = activation.ledger.config.prNumber;
-    return [
+    const handbook = activation.handbookView;
+    const lines = [
         "<collector_method>",
         `host: github.com`,
         `repository: ${activation.repository.canonical}`,
-        `prNumber: ${pr === undefined ? "unbound — call ak_collector_bind_target with the role-decided issue/PR before observe" : String(pr)}`,
+        `prNumber: ${pr === undefined ? "未绑定" : String(pr)}`,
+        `waitWindowMs: ${String(activation.ledger.config.waitWindowMs)}`,
         `requests: ${JSON.stringify(activation.manifest.requests.map((request) => ({ id: request.id })))}`,
+        `handbookGeneralSource: ${handbook.generalSource}`,
+        `handbookRepoSource: ${handbook.repoSource}`,
         "</collector_method>",
-    ].join("\n");
+    ];
+    // Opaque working memory only — no directional instructions (ADR 0073).
+    // JSON + `<` → \u003c keeps bodies from forging the delivery close tag (#677).
+    if (handbook.general.length > 0 || handbook.repo.length > 0) {
+        const payload = JSON.stringify({
+            general: handbook.general,
+            repo: handbook.repo,
+            generalSource: handbook.generalSource,
+            repoSource: handbook.repoSource,
+            repository: activation.repository.canonical,
+        }).replaceAll("<", "\\u003c");
+        lines.push("", "<collector_handbook>", payload, "</collector_handbook>");
+    }
+    return lines.join("\n");
 }
 function parsePositiveTicket(raw, label) {
     if (raw === undefined || raw === null)
@@ -83,7 +124,7 @@ function parsePositiveTicket(raw, label) {
         return raw;
     if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim()))
         return Number(raw.trim());
-    throw new CollectorTargetBindError(`ak_collector_bind_target ${label} must be a positive safe integer`);
+    throw new CollectorTargetBindError(`通进司绑定 ${label} 须为正安全整数`);
 }
 /**
  * Shared envelope installs business tools and material callback after lifecycle gates.
@@ -100,6 +141,7 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             const repoFlag = pi.getFlag("ak-collector-repo");
             const prFlag = pi.getFlag("ak-collector-pr");
             const requestManifestFlag = pi.getFlag("ak-collector-request-manifest");
+            const waitMsFlag = pi.getFlag("ak-collector-wait-ms");
             if (typeof repoFlag !== "string" || repoFlag.trim().length === 0) {
                 throw new Error("Collector requires --ak-collector-repo");
             }
@@ -115,9 +157,29 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             const manifest = typeof requestManifestFlag === "string" && requestManifestFlag.trim().length > 0
                 ? await loadCollectorManifest(requestManifestFlag)
                 : emptyCollectorManifest();
+            const waitWindowMs = parseWaitWindowMsFlag(waitMsFlag);
             const clock = dependencies.createClock?.() ?? createSystemCollectorClock();
             const transport = dependencies.createTransport();
-            const ledger = dependencies.createLedger({ repository, prNumber, manifest }, clock, ctx);
+            const ledger = dependencies.createLedger({ repository, prNumber, manifest, waitWindowMs }, clock, ctx);
+            // #677: handbook under admitted book topology (session path → books/<key>/collector-handbook).
+            const sessionPath = ctx.sessionManager?.getSessionFile?.()
+                ?? ctx.sessionManager?.getSessionDir?.();
+            if (typeof sessionPath !== "string" || sessionPath.length === 0) {
+                throw new Error("通进司手册要求 session 路径位于 books/<bookKey>/");
+            }
+            const placement = resolveCollectorHandbookRoot(sessionPath);
+            const seedGeneral = dependencies.loadHandbookSeed === undefined
+                ? undefined
+                : (await dependencies.loadHandbookSeed()).trim();
+            const handbook = createCollectorHandbookStore({
+                ledgerHome: placement.ledgerHome,
+                handbookRoot: placement.root,
+                repositoryCanonical: repository.canonical,
+                ...(seedGeneral === undefined || seedGeneral.length === 0
+                    ? {}
+                    : { seedGeneral }),
+            });
+            const handbookView = await handbook.read();
             return {
                 soul,
                 repository,
@@ -125,6 +187,8 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                 ledger,
                 transport,
                 clock,
+                handbook,
+                handbookView,
             };
         },
         assembleMaterials(activation, baseSystemPrompt) {
@@ -180,7 +244,7 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                         const prNumber = parsePositiveTicket(params.prNumber, "prNumber");
                         const issueNumber = parsePositiveTicket(params.issueNumber, "issueNumber");
                         if (prNumber === undefined && issueNumber === undefined) {
-                            throw new CollectorTargetBindError("ak_collector_bind_target requires role-decided prNumber and/or issueNumber");
+                            throw new CollectorTargetBindError("通进司绑定须由角色判定 prNumber 与/或 issueNumber");
                         }
                         let bound = prNumber;
                         if (issueNumber !== undefined) {
@@ -190,14 +254,14 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                                 ticketNumber: issueNumber,
                             });
                             if (associated.length === 0) {
-                                throw new CollectorTargetBindError(`no PR associated with issue #${issueNumber} in ${activation.repository.canonical}; pass an explicit --pr or a different issueNumber`);
+                                throw new CollectorTargetBindError(`${activation.repository.canonical} 的 issue #${issueNumber} 无关联 PR；请改用明确 --pr 或其他 issueNumber`);
                             }
                             if (associated.length > 1) {
-                                throw new CollectorTargetBindError(`multiple PRs associated with issue #${issueNumber}: ${associated.join(", ")}; pass an explicit prNumber or --pr`);
+                                throw new CollectorTargetBindError(`issue #${issueNumber} 关联多个 PR：${associated.join("、")}；请改用明确 prNumber 或 --pr`);
                             }
                             const fromIssue = associated[0];
                             if (prNumber !== undefined && prNumber !== fromIssue) {
-                                throw new CollectorTargetBindError(`prNumber ${prNumber} conflicts with issue #${issueNumber} association PR ${fromIssue}`);
+                                throw new CollectorTargetBindError(`prNumber ${prNumber} 与 issue #${issueNumber} 关联 PR ${fromIssue} 冲突`);
                             }
                             bound = fromIssue;
                         }
@@ -297,8 +361,8 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
             pi.registerTool({
                 name: COLLECTOR_REQUEST_TOOL,
                 label: "通进司请求",
-                description: "按配置请求体与关联标记，在所引最新快照 HEAD 发一次请求。",
-                promptSnippet: "按配置发一次请求",
+                description: "在所引最新快照 HEAD 发一次请求。requestId 可取配置清单，或角色依手册/现场判定的稳定 id；后者须同时提供 body。",
+                promptSnippet: "发一次评审请求",
                 parameters: requestSchema,
                 async execute(toolCallId, params, signal, _onUpdate, ctx) {
                     const activation = getActivation();
@@ -306,7 +370,11 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                         throw new Error("通进司未激活");
                     try {
                         activation.ledger.beginOperational(COLLECTOR_REQUEST_TOOL, toolCallId);
-                        const details = await activation.ledger.request(params, activation.transport, activation.clock, signal);
+                        const details = await activation.ledger.request({
+                            requestId: params.requestId,
+                            snapshotId: params.snapshotId,
+                            ...(typeof params.body === "string" ? { body: params.body } : {}),
+                        }, activation.transport, activation.clock, signal);
                         activation.ledger.completeOperational(toolCallId);
                         return {
                             content: [{
@@ -323,11 +391,105 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                     }
                 },
             });
+            pi.registerTool({
+                name: COLLECTOR_HANDBOOK_WRITE_TOOL,
+                label: "通进司手册写入",
+                description: "写入通用手册或当前仓库差异全文（整份替换）。",
+                promptSnippet: "更新 bot 手册",
+                parameters: handbookWriteSchema,
+                async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+                    const activation = getActivation();
+                    if (activation === undefined)
+                        throw new Error("通进司未激活");
+                    try {
+                        activation.ledger.beginOperational(COLLECTOR_HANDBOOK_WRITE_TOOL, toolCallId);
+                        // scope/body shape authority = collectorHandbookWriteArgsSchema (host parameters).
+                        const details = await activation.handbook.write(params.scope, params.body);
+                        activation.handbookView = await activation.handbook.read();
+                        activation.ledger.completeOperational(toolCallId);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `手册已写入：${details.scope}`,
+                                }],
+                            details: {
+                                scope: details.scope,
+                                path: details.path,
+                                byteLength: details.byteLength,
+                                generalSource: activation.handbookView.generalSource,
+                                repoSource: activation.handbookView.repoSource,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        if (isCorrectableExecuteError(error))
+                            throw error;
+                        hostActions.failInfrastructure(error, ctx, toolCallId);
+                    }
+                    finally {
+                        try {
+                            activation.ledger.completeOperational(toolCallId);
+                        }
+                        catch {
+                            // already completed or not begun
+                        }
+                    }
+                },
+            });
+            pi.registerTool({
+                name: COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
+                label: "通进司开启等待窗",
+                description: "在工作步骤上开启等待窗：新建并自动触发的 PR 传创建成功时刻；已有 PR 在触发阶段结束后省略 startedAt（=现在）。窗长由使用方配置，默认十分钟；开启后不因 PR 更新重置。",
+                promptSnippet: "按工作步骤开启等待窗",
+                parameters: openWaitWindowSchema,
+                async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+                    const activation = getActivation();
+                    if (activation === undefined)
+                        throw new Error("通进司未激活");
+                    try {
+                        activation.ledger.beginOperational(COLLECTOR_OPEN_WAIT_WINDOW_TOOL, toolCallId);
+                        let startedAt;
+                        if (typeof params.startedAt === "string" && params.startedAt.trim().length > 0) {
+                            const parsed = new Date(params.startedAt);
+                            if (Number.isNaN(parsed.getTime())) {
+                                throw new Error("通进司等待窗 startedAt 须为有效 ISO 时间");
+                            }
+                            startedAt = parsed;
+                        }
+                        activation.ledger.openWaitWindow(activation.clock, startedAt === undefined ? undefined : { startedAt });
+                        activation.ledger.completeOperational(toolCallId);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: "等待窗已开启",
+                                }],
+                            details: {
+                                activationTime: activation.ledger.activationTime?.toISOString(),
+                                deadlineTime: activation.ledger.deadlineTime?.toISOString(),
+                                waitWindowMs: activation.ledger.config.waitWindowMs,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        if (isCorrectableExecuteError(error))
+                            throw error;
+                        hostActions.failInfrastructure(error, ctx, toolCallId);
+                    }
+                    finally {
+                        try {
+                            activation.ledger.completeOperational(toolCallId);
+                        }
+                        catch {
+                            // already completed or not begun
+                        }
+                    }
+                },
+            });
             pi.registerTool({
                 name: COLLECTOR_WAIT_TOOL,
                 label: "通进司等待",
-                description: "再观察前等待；单次上限五分钟且不超剩余资格。",
-                promptSnippet: "资格截止前等待",
+                description: "再观察前等待；实际睡眠不超过剩余等待窗。",
+                promptSnippet: "等待窗内等待",
                 parameters: waitSchema,
                 async execute(toolCallId, params, signal, _onUpdate, ctx) {
                     const activation = getActivation();
@@ -346,6 +508,8 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                         };
                     }
                     catch (error) {
+                        if (isCorrectableExecuteError(error))
+                            throw error;
                         hostActions.failInfrastructure(error, ctx, toolCallId);
                     }
                 },

package/dist/collector-tool-schemas.js

@@ -1,17 +1,54 @@
 import { Type } from "typebox";
-import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.js";
 import { openToolObject } from "./open-tool-schema.js";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
+/**
+ * Stable request identity: non-empty after trim, no leading/trailing whitespace.
+ * Host schema + ledger identity seam share this contract (#677 / D2 dedup).
+ */
+export const COLLECTOR_REQUEST_ID_PATTERN = /^\S(?:.*\S)?$/;
 export const collectorRequestArgsSchema = Type.Object({
-    requestId: Type.String({ minLength: 1, description: "配置请求身份" }),
+    requestId: Type.String({
+        minLength: 1,
+        pattern: COLLECTOR_REQUEST_ID_PATTERN.source,
+        description: "请求身份（配置 id 或角色判定的稳定 id；首尾无空白）",
+    }),
     snapshotId: Type.String({ minLength: 1, description: "最新留存观察快照" }),
+    body: Type.Optional(Type.String({
+        minLength: 1,
+        description: "角色判定的请求正文；request-manifest 未收录该 requestId 时必填",
+    })),
+}, { additionalProperties: false });
+/** UTF-8 byte ceiling per handbook body — keeps next activation materials inside context budget. */
+export const COLLECTOR_HANDBOOK_MAX_BYTES = 64 * 1024;
+export const collectorHandbookWriteArgsSchema = Type.Object({
+    scope: Type.Union([
+        Type.Literal("general"),
+        Type.Literal("repo"),
+    ], { description: "general＝通用手册；repo＝当前仓库差异" }),
+    body: Type.String({
+        description: `手册全文（opaque 工作记忆；整份替换；UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节）`,
+    }),
 }, { 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: "等待毫秒；单次上限五分钟且不超剩余资格" }),
+    durationMs: Type.Integer({
+        minimum: 1,
+        description: "等待毫秒；实际睡眠不超过剩余等待窗（#678；无包内单次任意上限）",
+    }),
+}, { additionalProperties: false });
+/**
+ * #678 D4: open the wait window at a work step.
+ * Omit startedAt for existing-PR trigger-phase end (= now).
+ * Pass PR creation success time for new-PR auto-trigger rounds.
+ */
+export const collectorOpenWaitWindowArgsSchema = Type.Object({
+    startedAt: Type.Optional(Type.String({
+        minLength: 1,
+        description: "等待窗起点 ISO 时间；新建 PR 用创建成功时刻；省略＝现在（触发阶段结束）",
+    })),
 }, { additionalProperties: false });
 /**
  * #676 A: role-decided target bind. The model judges task materials and submits