@akagilnc/pi-workflow-roles 0.1.3789 → 0.1.3795

package/src/collector-role.ts

@@ -17,6 +17,7 @@ import {
   type CollectorRepository,
 } from "./collector-config.ts";
 import {
+  COLLECTOR_DEFAULT_WAIT_WINDOW_MS,
   createSystemCollectorClock,
   type CollectorClock,
 } from "./collector-evidence.ts";
@@ -34,6 +35,7 @@ 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,
@@ -50,6 +52,7 @@ import {
   collectorBindTargetArgsSchema,
   collectorHandbookWriteArgsSchema,
   collectorObserveArgsSchema,
+  collectorOpenWaitWindowArgsSchema,
   collectorOutputArgsSchema,
   collectorReadArgsSchema,
   collectorRequestArgsSchema,
@@ -85,6 +88,7 @@ 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,
@@ -96,6 +100,7 @@ export const COLLECTOR_REQUIRED_TOOLS = [
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
   COLLECTOR_WAIT_TOOL,
   COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
@@ -127,11 +132,20 @@ export const COLLECTOR_TRANSPORT_FLAGS = Object.freeze([
       type: "string" as const,
     }),
   }),
+  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" as const,
+    }),
+  }),
 ] as const);
 
 const observeSchema = collectorObserveArgsSchema;
 const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
+const openWaitWindowSchema = collectorOpenWaitWindowArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const bindSchema = collectorBindTargetArgsSchema;
 const handbookWriteSchema = collectorHandbookWriteArgsSchema;
@@ -139,11 +153,22 @@ const outputSchema = collectorOutputArgsSchema;
 
 type RequestParams = Static<typeof requestSchema>;
 type ReadParams = Static<typeof readSchema>;
+type OpenWaitWindowParams = Static<typeof openWaitWindowSchema>;
 type WaitParams = Static<typeof waitSchema>;
 type BindParams = Static<typeof bindSchema>;
 type HandbookWriteParams = Static<typeof handbookWriteSchema>;
 type OutputParams = Static<typeof outputSchema>;
 
+function parseWaitWindowMsFlag(raw: unknown): number {
+  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");
+}
+
 export type CollectorRoleDependencies = {
   loadSoul(): Promise<string>;
   createTransport(): CollectorGitHubTransport;
@@ -184,6 +209,7 @@ function buildMethodContext(activation: CollectorActivation): string {
     `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}`,
@@ -244,6 +270,7 @@ export function createCollectorRoleRuntime(
       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");
       }
@@ -258,11 +285,12 @@ export function createCollectorRoleRuntime(
       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 },
+        { repository, prNumber, manifest, waitWindowMs },
         clock,
         ctx,
       );
@@ -557,11 +585,60 @@ export function createCollectorRoleRuntime(
         },
       });
 
+      pi.registerTool({
+        name: COLLECTOR_OPEN_WAIT_WINDOW_TOOL,
+        label: "通进司开启等待窗",
+        description:
+          "在工作步骤上开启等待窗：新建并自动触发的 PR 传创建成功时刻；已有 PR 在触发阶段结束后省略 startedAt（=现在）。窗长由使用方配置，默认十分钟；开启后不因 PR 更新重置。",
+        promptSnippet: "按工作步骤开启等待窗",
+        parameters: openWaitWindowSchema,
+        async execute(toolCallId: string, params: OpenWaitWindowParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
+          const activation = getActivation();
+          if (activation === undefined) throw new Error("通进司未激活");
+          try {
+            activation.ledger.beginOperational(COLLECTOR_OPEN_WAIT_WINDOW_TOOL, toolCallId);
+            let startedAt: Date | undefined;
+            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" as const,
+                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: string, params: WaitParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
           const activation = getActivation();
@@ -582,6 +659,7 @@ export function createCollectorRoleRuntime(
               details,
             };
           } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
             hostActions.failInfrastructure(error, ctx, toolCallId);
           }
         },

package/src/collector-tool-schemas.ts

@@ -1,5 +1,4 @@
 import { Type, type Static } from "typebox";
-import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.ts";
 import { openToolObject } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
@@ -36,7 +35,22 @@ 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 });
 
 /**
@@ -112,5 +126,6 @@ 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 CollectorOpenWaitWindowArgs = Static<typeof collectorOpenWaitWindowArgsSchema>;
 export type CollectorBindTargetArgs = Static<typeof collectorBindTargetArgsSchema>;
 export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;

package/src/host-contracts.ts

@@ -106,6 +106,8 @@ export type RoleTurnActivation =
       /** Bound PR when known at admission; omit when role will bind from materials. */
       readonly pr?: string;
       readonly requestManifestPath?: string;
+      /** Wait-window ms as decimal string (#678 D4); omit → package default 10 minutes. */
+      readonly waitMs?: string;
     }
   | { readonly role: "doctor"; readonly casePath: string }
   | {

package/src/pi/role-turn-host.ts

@@ -116,6 +116,7 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
         ...(activation.requestManifestPath === undefined
           ? []
           : ["--ak-collector-request-manifest", activation.requestManifestPath]),
+        ...(activation.waitMs === undefined ? [] : ["--ak-collector-wait-ms", activation.waitMs]),
       ];
     case "doctor":
       return ["--ak-role", "doctor", "--ak-doctor-case", activation.casePath];

package/src/public-cli/collector-run.ts

@@ -54,6 +54,7 @@ export function buildCollectorTurnRequest(
         // #676 A: omit pr when unbound — role binds via ak_collector_bind_target.
         ...(admitted.prNumber === undefined ? {} : { pr: String(admitted.prNumber) }),
         ...(admitted.requestManifestPath === undefined ? {} : { requestManifestPath: admitted.requestManifestPath }),
+        ...(admitted.waitWindowMs === undefined ? {} : { waitMs: String(admitted.waitWindowMs) }),
       },
     },
     options,
@@ -83,6 +84,7 @@ export async function runPublicCollector(
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
       ...(parsed.requestManifestPath === undefined ? {} : { requestManifestPath: parsed.requestManifestPath }),
+      ...(parsed.waitWindowMs === undefined ? {} : { waitWindowMs: parsed.waitWindowMs }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
       ...(env.model === undefined ? {} : { model: env.model }),
     });

package/src/public-cli/invocation.ts

@@ -178,6 +178,8 @@ export type AdmittedCollectorInvocation = AdmittedRoleInvocationBase & {
   readonly repository: CollectorRepository;
   readonly requestManifestPath?: string;
   readonly manifestDigest: string;
+  /** Wait-window ms (#678 D4); default applied at role activate when omitted. */
+  readonly waitWindowMs?: number;
 };
 
 export type AdmittedDoctorInvocation = AdmittedRoleInvocationBase & {
@@ -727,6 +729,8 @@ export type ParseCollectorArgvResult = {
   project?: string;
   repo?: string;
   requestManifestPath?: string;
+  /** Optional wait-window ms (#678 D4). */
+  waitWindowMs?: number;
 };
 
 export type ParseDoctorArgvResult = {
@@ -1722,6 +1726,7 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
   let repo: string | undefined;
   let prNumber: number | undefined;
   let requestManifestPath: string | undefined;
+  let waitWindowMs: number | undefined;
   const positional: string[] = [];
   const tokens = [...args];
   const definitions = roleOptions("collector");
@@ -1754,6 +1759,17 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
         requestManifestPath = requireOptionPath(taken.def.canonical, taken.value);
         continue;
       }
+      if (taken.def.id === "wait-ms") {
+        if (taken.value === undefined || !/^[1-9]\d*$/.test(taken.value.trim())) {
+          throw new CliUsageError("--wait-ms requires a positive safe-integer millisecond value");
+        }
+        const parsed = Number(taken.value.trim());
+        if (!Number.isSafeInteger(parsed) || parsed < 1) {
+          throw new CliUsageError("--wait-ms requires a positive safe-integer millisecond value");
+        }
+        waitWindowMs = parsed;
+        continue;
+      }
       throw new CliUsageError(`unknown collector option: ${taken.def.canonical}`);
     }
     const token = tokens.shift()!;
@@ -1772,6 +1788,7 @@ export function parseCollectorArgv(args: readonly string[]): ParseCollectorArgvR
     ...(project === undefined ? {} : { project }),
     ...(repo === undefined ? {} : { repo }),
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(waitWindowMs === undefined ? {} : { waitWindowMs }),
   };
 }
 
@@ -1845,6 +1862,8 @@ export type AdmitCollectorInvocationOptions = {
   repo?: string;
   /** Optional public request configuration; copied into the admitted run. */
   requestManifestPath?: string;
+  /** Optional wait-window ms (#678 D4). */
+  waitWindowMs?: number;
   createRunId?: () => string;
   /** Effective model for this invocation — written onto invocation.json. */
   model?: InvocationEffectiveModel;
@@ -1947,6 +1966,7 @@ export async function admitCollectorInvocation(
     repository: repository.canonical,
     repositoryDisplay: repository.display,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(options.waitWindowMs === undefined ? {} : { waitWindowMs: options.waitWindowMs }),
     manifestDigest,
     attachments: attachments.map((a) => ({
       provenancePath: a.provenancePath,
@@ -1977,6 +1997,7 @@ export async function admitCollectorInvocation(
     ...(prNumber === undefined ? {} : { prNumber }),
     repository,
     ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    ...(options.waitWindowMs === undefined ? {} : { waitWindowMs: options.waitWindowMs }),
     manifestDigest,
   };
 }

package/src/public-cli/option-definitions.ts

@@ -602,6 +602,20 @@ const COLLECTOR_OPTIONS = [
       zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。角色亦可依手册/现场自行判定请求正文，不必依赖本文件。",
     },
   },
+  {
+    id: "wait-ms",
+    owner: "collector",
+    canonical: "--wait-ms",
+    aliases: [],
+    valueMetavar: "ms",
+    required: false,
+    repeatable: false,
+    form: "option",
+    description: {
+      en: "Wait-window duration in milliseconds after the work step opens (default 600000 = 10 minutes). Does not require a code change to adjust.",
+      zh: "工作步骤开启后的等待窗时长（毫秒；默认 600000＝十分钟）。改配置即可，无需改代码。",
+    },
+  },
 ] as const satisfies readonly PublicOptionDefinition[];
 
 const DOCTOR_OPTIONS = [

package/src/public-cli/run-lifecycle.ts

@@ -1149,6 +1149,8 @@ type LoadedAdmittedRequestFields = {
   readonly repositoryDisplay?: string;
   readonly requestManifestPath?: string;
   readonly manifestDigest?: string;
+  /** Collector wait-window ms restored on resume (#678). */
+  readonly waitWindowMs?: number;
   /** Doctor — admitted single-case identity restored on resume (#633). */
   readonly issueNumber?: number;
   readonly caseRunsPath?: string;
@@ -1244,6 +1246,7 @@ async function loadResumableRunRecord(
   let repositoryDisplay: string | undefined;
   let requestManifestPath: string | undefined;
   let manifestDigest: string | undefined;
+  let waitWindowMs: number | undefined;
   let issueNumber: number | undefined;
   let caseRunsPath: string | undefined;
   let caseIdentity: DoctorCaseIdentity | undefined;
@@ -1304,6 +1307,9 @@ async function loadResumableRunRecord(
       if (typeof record.manifestDigest === "string" && record.manifestDigest.trim() !== "") {
         manifestDigest = record.manifestDigest;
       }
+      if (typeof record.waitWindowMs === "number" && Number.isSafeInteger(record.waitWindowMs) && record.waitWindowMs >= 1) {
+        waitWindowMs = record.waitWindowMs;
+      }
       // Doctor — admitted single-case identity (#633 resume).
       if (typeof record.issueNumber === "number" && Number.isSafeInteger(record.issueNumber) && record.issueNumber >= 1) {
         issueNumber = record.issueNumber;
@@ -1471,6 +1477,7 @@ async function loadResumableRunRecord(
       ...(repositoryDisplay === undefined ? {} : { repositoryDisplay }),
       ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
       ...(manifestDigest === undefined ? {} : { manifestDigest }),
+      ...(waitWindowMs === undefined ? {} : { waitWindowMs }),
       ...(issueNumber === undefined ? {} : { issueNumber }),
       ...(caseRunsPath === undefined ? {} : { caseRunsPath }),
       ...(caseIdentity === undefined ? {} : { caseIdentity }),
@@ -1913,6 +1920,9 @@ export async function loadResumableCollectorRun(
     ...(loaded.admittedFields.requestManifestPath === undefined
       ? {}
       : { requestManifestPath: loaded.admittedFields.requestManifestPath }),
+    ...(loaded.admittedFields.waitWindowMs === undefined
+      ? {}
+      : { waitWindowMs: loaded.admittedFields.waitWindowMs }),
     manifestDigest,
   };
   return seatLoadedResult(loaded, admitted);