@akagilnc/pi-workflow-roles 0.1.3789 → 0.1.3797

package/dist/collector-identity.js

@@ -90,6 +90,17 @@ export class CollectorNonOpenRequestError extends CorrectableSubmissionError {
         this.name = "CollectorNonOpenRequestError";
     }
 }
+/** #678: wait window not open or already ended — bounce without latching fatal so materials still seal. */
+export class CollectorWaitWindowClosedError extends CorrectableSubmissionError {
+    constructor(action) {
+        super(action === "request"
+            ? "通进司请求不在资格截止前"
+            : action === "wait-before-open"
+                ? "通进司等待需要先在工作步骤开启等待窗（新建 PR 用创建成功时刻；已有 PR 在触发阶段结束后开启）"
+                : "通进司等待不在资格截止前");
+        this.name = "CollectorWaitWindowClosedError";
+    }
+}
 function candidateRecord(candidate) {
     if (candidate === undefined || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
         return undefined;

package/dist/collector-ledger.js

@@ -1,11 +1,13 @@
-import { applyEvidenceVersionHistory, assignWindowRelations, COLLECTOR_ELIGIBILITY_MS, measureNormalizedBytes, normalizeAuthenticatedUserEvidence, normalizeIssueCommentEvidence, normalizePullRequestEvidence, normalizePullRequestReactionEvidence, normalizeReviewCommentEvidence, normalizeReviewEvidence, sha256Text, } from "./collector-evidence.js";
+import { applyEvidenceVersionHistory, assignWindowRelations, COLLECTOR_DEFAULT_WAIT_WINDOW_MS, measureNormalizedBytes, normalizeAuthenticatedUserEvidence, normalizeIssueCommentEvidence, normalizePullRequestEvidence, normalizePullRequestReactionEvidence, normalizeReviewCommentEvidence, normalizeReviewEvidence, sha256Text, } from "./collector-evidence.js";
 import { buildCollectorRequestBody, } from "./collector-github.js";
-import { CollectorNonOpenRequestError } from "./collector-identity.js";
+import { CollectorNonOpenRequestError, CollectorWaitWindowClosedError, } from "./collector-identity.js";
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.js";
 export const COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
 export const COLLECTOR_READ_TOOL = "ak_collector_read";
 export const COLLECTOR_REQUEST_TOOL = "ak_collector_request";
 export const COLLECTOR_WAIT_TOOL = "ak_collector_wait";
+/** #678 D4: open wait window at a work step — business tool, ledger-booked. */
+export const COLLECTOR_OPEN_WAIT_WINDOW_TOOL = "ak_collector_open_wait_window";
 /** #676 A: role-decided target bind — business tool, ledger-booked. */
 export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
 /** #677: opaque handbook write — business tool, ledger-booked. */
@@ -16,6 +18,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
     COLLECTOR_OBSERVE_TOOL,
     COLLECTOR_READ_TOOL,
     COLLECTOR_REQUEST_TOOL,
+    COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
     COLLECTOR_WAIT_TOOL,
     COLLECTOR_HANDBOOK_WRITE_TOOL,
 ];
@@ -57,13 +60,28 @@ const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait";
 function isOperationalTool(name) {
     return COLLECTOR_OPERATIONAL_TOOLS.includes(name);
 }
-export function createCollectorLedger(config, options) {
+function resolveWaitWindowMs(raw) {
+    if (raw === undefined)
+        return COLLECTOR_DEFAULT_WAIT_WINDOW_MS;
+    if (!Number.isSafeInteger(raw) || raw < 1) {
+        throw new Error("通进司 waitWindowMs 须为正安全整数毫秒");
+    }
+    return raw;
+}
+export function createCollectorLedger(input, options) {
+    const config = {
+        repository: input.repository,
+        prNumber: input.prNumber,
+        manifest: input.manifest,
+        waitWindowMs: resolveWaitWindowMs(input.waitWindowMs),
+    };
     const clock = options?.clock;
     const journal = options?.journal;
     let fatal = false;
     let fatalReason;
     let outputCandidate = false;
     let pendingOutputCallId;
+    let sessionReady = false;
     let activationTime;
     let deadlineTime;
     let activationMono;
@@ -110,7 +128,7 @@ export function createCollectorLedger(config, options) {
     };
     const remainingMs = (clock) => {
         if (deadlineMono === undefined)
-            return COLLECTOR_ELIGIBILITY_MS;
+            return config.waitWindowMs;
         return Math.max(0, deadlineMono - monoNowOrThrow(clock));
     };
     const prIdentity = (pr) => `${pr.state}|${pr.headOid}|${pr.updatedAt ?? ""}`;
@@ -181,8 +199,10 @@ export function createCollectorLedger(config, options) {
         return copy;
     };
     const commitActivationWindow = (nextActivation, nextDeadline) => {
+        // D6: once open, PR updates / second open must not reset the window.
         if (activationTime !== undefined)
             return;
+        sessionReady = true;
         activationTime = nextActivation;
         deadlineTime = nextDeadline;
         bindDeadlineMonoFromWall();
@@ -310,6 +330,9 @@ export function createCollectorLedger(config, options) {
                 if (typeof data.activationTime === "string" && typeof data.deadlineTime === "string") {
                     commitActivationWindow(new Date(data.activationTime), new Date(data.deadlineTime));
                 }
+                else if (data.sessionReady === true) {
+                    sessionReady = true;
+                }
                 continue;
             }
             if (entry.customType === COLLECTOR_SNAPSHOT_ENTRY_TYPE) {
@@ -370,7 +393,7 @@ export function createCollectorLedger(config, options) {
             return outputCandidate || pendingOutputCallId !== undefined;
         },
         get activationRecorded() {
-            return activationTime !== undefined;
+            return sessionReady;
         },
         get activationTime() {
             return activationTime;
@@ -407,17 +430,39 @@ export function createCollectorLedger(config, options) {
         },
         latchFatal,
         assertNotFatal,
-        recordActivation(clock) {
+        recordActivation(_clock) {
             assertNotFatal();
-            if (activationTime !== undefined)
+            if (sessionReady)
                 return;
-            activationTime = clock.wallNow();
-            activationMono = clock.monoNow();
-            deadlineTime = new Date(activationTime.getTime() + COLLECTOR_ELIGIBILITY_MS);
-            deadlineMono = activationMono + COLLECTOR_ELIGIBILITY_MS;
+            sessionReady = true;
+            // Session ready only — wait window opens later at a work step (#678 D4).
+            appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
+                sessionReady: true,
+            });
+        },
+        openWaitWindow(clock, options) {
+            assertNotFatal();
+            if (!sessionReady) {
+                throw latchFatal("通进司开启等待窗需要先激活会话");
+            }
+            if (activationTime !== undefined)
+                return; // D6: do not reset
+            const startedAt = options?.startedAt ?? clock.wallNow();
+            if (!(startedAt instanceof Date) || Number.isNaN(startedAt.getTime())) {
+                throw new Error("通进司等待窗 startedAt 须为有效时间");
+            }
+            const nextDeadline = new Date(startedAt.getTime() + config.waitWindowMs);
+            // Bind mono relative to current clock so a past startedAt shortens remaining correctly.
+            activationTime = startedAt;
+            deadlineTime = nextDeadline;
+            const wallNow = clock.wallNow().getTime();
+            const monoNow = clock.monoNow();
+            activationMono = monoNow - (wallNow - startedAt.getTime());
+            deadlineMono = monoNow + (nextDeadline.getTime() - wallNow);
             appendJournal(COLLECTOR_ACTIVATION_ENTRY_TYPE, {
                 activationTime: activationTime.toISOString(),
                 deadlineTime: deadlineTime.toISOString(),
+                waitWindowMs: config.waitWindowMs,
             });
         },
         recordOutputCandidate() {
@@ -502,7 +547,7 @@ export function createCollectorLedger(config, options) {
         },
         async observe(transport, clock, signal) {
             assertNotFatal();
-            if (activationTime === undefined) {
+            if (!sessionReady) {
                 throw latchFatal("通进司观察需要激活");
             }
             if (signal?.aborted) {
@@ -592,6 +637,7 @@ export function createCollectorLedger(config, options) {
                 prNumber: requireBoundPr(),
                 prState: pr.state,
                 headOid: pr.headOid,
+                ...(pr.createdAt === undefined ? {} : { prCreatedAt: pr.createdAt }),
                 complete: true,
                 evidenceIds: storedIds,
                 pageDiagnostics,
@@ -625,7 +671,7 @@ export function createCollectorLedger(config, options) {
         },
         async request(input, transport, clock, signal) {
             assertNotFatal();
-            if (activationTime === undefined || deadlineTime === undefined) {
+            if (!sessionReady) {
                 throw latchFatal("通进司请求需要激活");
             }
             if (ledger.unresolvedTransportFailure) {
@@ -662,7 +708,8 @@ export function createCollectorLedger(config, options) {
             }
             if (pastCutoff(clock)) {
                 finalObservationRequired = true;
-                throw latchFatal("通进司请求不在资格截止前");
+                // #678: do not latch fatal — materials must still seal after the window ends.
+                throw new CollectorWaitWindowClosedError("request");
             }
             // Caller manifest body wins when requestId is configured; otherwise role body.
             const configuredBody = configured?.requestBody ?? roleBody;
@@ -766,18 +813,22 @@ export function createCollectorLedger(config, options) {
         },
         async wait(input, clock, signal) {
             assertNotFatal();
-            if (activationTime === undefined) {
+            if (!sessionReady) {
                 throw latchFatal("通进司等待需要激活");
             }
+            // #678: wait never invents a window start. Work-step open (create-success / trigger-end)
+            // must be explicit — silent "now" would break the new-PR create-success clock.
+            if (activationTime === undefined || deadlineTime === undefined) {
+                throw new CollectorWaitWindowClosedError("wait-before-open");
+            }
             // durationMs shape authority = collectorWaitArgsSchema (host parameters).
             if (pastCutoff(clock)) {
                 finalObservationRequired = true;
-                throw latchFatal("通进司等待不在资格截止前");
+                throw new CollectorWaitWindowClosedError("wait");
             }
             const remaining = remainingMs(clock);
-            // Single-wait runtime cadence cap (v2 §6 / §9); schema max stays 15m.
-            const COLLECTOR_SINGLE_WAIT_MAX_MS = 300_000;
-            const effectiveMs = Math.min(input.durationMs, remaining, COLLECTOR_SINGLE_WAIT_MAX_MS);
+            // Cap only by remaining window — no package-local single-wait ceiling (ADR 0035 / #678).
+            const effectiveMs = Math.min(input.durationMs, remaining);
             const startedAt = clock.wallNow().toISOString();
             const waitId = sha256Text(`wait:${startedAt}:${effectiveMs}`).slice(0, 16);
             await clock.sleep(effectiveMs, signal);
@@ -860,6 +911,9 @@ function buildObserveModelView(input) {
         completedAt: input.snapshot.completedAt,
         prState: input.snapshot.prState,
         headOid: input.snapshot.headOid,
+        ...(input.snapshot.prCreatedAt === undefined
+            ? {}
+            : { prCreatedAt: input.snapshot.prCreatedAt }),
         complete: input.snapshot.complete,
         evidence: relevant.map((record) => projectEvidenceEntryView(record)),
         requestAttempts: input.attempts.map((attempt) => ({

package/dist/collector-role.js

@@ -1,10 +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 { createCollectorHandbookStore, resolveCollectorHandbookRoot, } from "./collector-handbook.js";
-import { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_TOOL, COLLECTOR_OBSERVE_TOOL, COLLECTOR_OUTPUT_TOOL, COLLECTOR_READ_TOOL, COLLECTOR_REQUEST_TOOL, COLLECTOR_WAIT_TOOL, projectEvidenceEntryView, } from "./collector-ledger.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, collectorHandbookWriteArgsSchema, 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";
@@ -27,12 +27,13 @@ export class CollectorTargetBindError extends CorrectableSubmissionError {
         this.name = "CollectorTargetBindError";
     }
 }
-export { COLLECTOR_BIND_TARGET_TOOL, COLLECTOR_HANDBOOK_WRITE_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,
@@ -60,14 +61,34 @@ 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;
     const handbook = activation.handbookView;
@@ -76,6 +97,7 @@ function buildMethodContext(activation) {
         `host: github.com`,
         `repository: ${activation.repository.canonical}`,
         `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}`,
@@ -119,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");
             }
@@ -134,9 +157,10 @@ 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?.();
@@ -412,11 +436,60 @@ export function createCollectorRoleRuntime(pi, dependencies, hostActions) {
                     }
                 },
             });
+            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();
@@ -435,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,5 +1,4 @@
 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 });
@@ -35,7 +34,21 @@ 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