@ai-agent-forge/plugin-subagent-delegate 0.88.10 → 0.88.12

package/dist/delegate.js

@@ -10,11 +10,15 @@
  * result projection (status / reason codes / message counts / short summary).
  * Raw child messages never enter the tool result (context budget spec).
  *
- * The scheduler's deadline fence is tick-driven by design (no hidden timers),
- * and this consumer has no tick driver of its own, so the tool exposes no
- * `deadlineMs` parameter: a bound that nothing enforces would be a false
- * affordance. Wait bounds are `taskTimeoutMs` (drain) and the host's
- * `limits.drainTimeoutMs` inside the scheduler.
+ * The scheduler's deadline fence is tick-driven by design (no hidden timers in
+ * the scheduler; `tick()` is the only enforcement point). This consumer owns
+ * the production wall-clock driver: a lazy ticker runs at
+ * `BACKGROUND_DEADLINE_TICK_INTERVAL_MS` while background tasks with pending
+ * deadlines are in flight and only calls `runtime.tick()`, so `subagent_run`
+ * can expose `deadlineMs` for background submissions (default
+ * `DEFAULT_BACKGROUND_TASK_DEADLINE_MS`, 60 minutes). Wait bounds are
+ * `taskTimeoutMs` (drain) and the host's `limits.drainTimeoutMs` inside the
+ * scheduler.
  *
  * 迁自宿主 `src/capabilities/subagent-delegate.ts`（D-075 S4 第三批拆包）。除 import
  * 来源外保持宿主行为：公共契约（agent-task 键/档案、通信接线、血缘读取、快照）改自
@@ -720,6 +724,19 @@ function utf8ByteLength(text) {
 }
 const DEFAULT_MAX_TASKS_PER_CALL = 4;
 const DEFAULT_TASK_TIMEOUT_MS = 300_000;
+/**
+ * 后台委派缺省死线（60 分钟，出厂默认登记见 docs/design/产品默认值清单.md）：挂死
+ * 后台任务的兜底寿命。`subagent_run background:true` 提交即带 `deadlineAt`；工具参数
+ * `deadlineMs`（正整数）可按调用覆盖。死线到达由调度器 tick 强制为 `timed_out`
+ * （设计 §5.7）；前台任务不走死线（父侧 drain 预算 `taskTimeoutMs` 已有界）。
+ */
+const DEFAULT_BACKGROUND_TASK_DEADLINE_MS = 3_600_000;
+/**
+ * 生产 tick 驱动间隔：存在带未决死线的在途后台任务时才启动的墙钟 ticker（惰性启停）。
+ * ticker 只调用 `runtime.tick()`，不携带策略——tick 仍是唯一强制点，调度器"测试可控
+ * 时钟"语义不变（测试注入 clock 或以假 timers 驱动本间隔即得确定性死线）。
+ */
+const BACKGROUND_DEADLINE_TICK_INTERVAL_MS = 30_000;
 /**
  * 配置通道读取（manifest 默认 + agent-dir 文件合并后的 `api.config`）：
  * 非整数/低于下限即 fail fast 并指名键，不让错误配置静默生效。
@@ -1151,9 +1168,6 @@ export function createCapability(api, options) {
             progressUnsubscribes.add(unsubscribe);
             return host;
         },
-        ...(baseAdapter.dispose === undefined
-            ? {}
-            : { dispose: async () => void (await baseAdapter.dispose?.()) }),
     };
     const runtime = createSubagentRuntime({
         adapter,
@@ -1162,7 +1176,59 @@ export function createCapability(api, options) {
         ...(sessionAbortSignal === undefined ? {} : { parentSignal: sessionAbortSignal }),
         ...(limits === undefined ? {} : { limits }),
         ...(api.logger === undefined ? {} : { logger: api.logger }),
+        // Durable replay assembly（2026-10-13）：宿主 durable 设施原样下传（形状即
+        // runtime 的 results 契约）；缺席 = 不持久化（回读 undefined，既有语义）。
+        ...(options?.results === undefined ? {} : { results: options.results }),
     });
+    // ---------------------------------------------------------------------------
+    // 生产 tick 驱动（设计 §5.7）：调度器的死线强制点是显式 tick()，本消费者挂载唯一
+    // 的墙钟驱动——存在带未决死线的在途后台任务时才启动 ticker（惰性启停），每跳只调
+    // runtime.tick()，不携带任何策略。无未决死线的用法零定时器；dispose 必停。
+    // ---------------------------------------------------------------------------
+    /** 受监视的后台任务：taskId -> 提交时的绝对死线（仅作记账，强制语义全在 tick）。 */
+    const pendingDeadlines = new Map();
+    let deadlineTicker;
+    const ensureDeadlineTicker = () => {
+        if (deadlineTicker !== undefined || pendingDeadlines.size === 0)
+            return;
+        deadlineTicker = setInterval(() => {
+            // tick 自身不抛（终态投影等内部故障均已兜底）；保险兜底不吞任务面，下一跳重试。
+            try {
+                runtime.tick();
+            }
+            catch {
+                // 留待下一跳；显式 tick / cancel 仍可用。
+            }
+        }, BACKGROUND_DEADLINE_TICK_INTERVAL_MS);
+        deadlineTicker.unref?.();
+    };
+    const stopDeadlineTickerIfIdle = () => {
+        if (deadlineTicker === undefined || pendingDeadlines.size > 0)
+            return;
+        clearInterval(deadlineTicker);
+        deadlineTicker = undefined;
+    };
+    const unwatchBackgroundDeadline = (taskId) => {
+        if (!pendingDeadlines.delete(taskId))
+            return;
+        stopDeadlineTickerIfIdle();
+    };
+    /** 任务结算（含被死线强制、取消、异常）即解除监视；reject 通道（persist 失败等）同样解除。 */
+    const watchBackgroundDeadline = (handle, deadlineAt) => {
+        pendingDeadlines.set(handle.id, deadlineAt);
+        ensureDeadlineTicker();
+        void handle
+            .result()
+            .catch(() => { })
+            .then(() => unwatchBackgroundDeadline(handle.id));
+    };
+    const stopDeadlineTicker = () => {
+        if (deadlineTicker !== undefined) {
+            clearInterval(deadlineTicker);
+            deadlineTicker = undefined;
+        }
+        pendingDeadlines.clear();
+    };
     /**
      * `subagent_run` 的定义按**当前角色表**现场构建（D-081 即时生效）：set/remove 之后
      * 以同 owner 同名重注册（runtime 语义 = 更新）让新菜单与 `role` 参数枚举在父会话的
@@ -1184,6 +1250,9 @@ export function createCapability(api, options) {
             "task's settlement is announced to you (agent-task-settled), but notifications are not per-task acceptances: " +
             "accept and act on (todos/goals/next steps) only the final assembly task's report; other settled lines are " +
             "status only." +
+            // 死线兜底（设计 §5.7）：后台任务缺省 60 分钟死线，挂死任务到点被强制 timed_out。
+            " Background tasks carry a watchdog deadline by default (60 minutes; override per call with `deadlineMs`): " +
+            "a task still running when its deadline passes is force-settled timed_out." +
             (roles.size === 0
                 ? ""
                 : ` Configured subagent roles (pass \`role\`): ${renderRoleMenu()}. A role's instructions frame every task in the call; ` +
@@ -1238,6 +1307,14 @@ export function createCapability(api, options) {
                 description: "Submit without waiting: return task tickets immediately and keep working; settled results are " +
                     "announced at your next model round and can be read with subagent_result (optionally waiting).",
             })),
+            // 死线兜底（设计 §5.7）：仅后台合法——前台任务已有父侧 drain 预算，两种边界
+            // 不混用；前台携带按 invalid_input 拒绝，不留"配了但不生效"的假象。
+            deadlineMs: Type.Optional(Type.Integer({
+                minimum: 1,
+                description: "Watchdog deadline for this call's background tasks, in ms (positive integer; requires background: true). " +
+                    `Default ${DEFAULT_BACKGROUND_TASK_DEADLINE_MS} (60 minutes). A background task still running when its ` +
+                    "deadline passes is force-settled timed_out (reason deadline_passed).",
+            })),
         }),
         execute: executeSubagentRun,
     });
@@ -1249,6 +1326,18 @@ export function createCapability(api, options) {
         // undefined，后续路径与 context 缺省完全一致。
         const contextBlock = renderDelegateContext(parseDelegateContext(input.context));
         const background = input.background === true;
+        // 死线兜底（设计 §5.7）：正整数校验；仅后台合法——前台任务已有父侧 drain 预算，
+        // 两种边界不混用，前台携带按 invalid_input 拒绝（不留"配了但不生效"的假象）。
+        const rawDeadlineMs = input.deadlineMs;
+        if (rawDeadlineMs !== undefined) {
+            if (typeof rawDeadlineMs !== "number" || !Number.isInteger(rawDeadlineMs) || rawDeadlineMs < 1) {
+                throw new SubagentDelegateError("subagent_invalid_input", `subagent_run deadlineMs must be a positive integer (ms), got ${JSON.stringify(rawDeadlineMs)}`);
+            }
+            if (background !== true) {
+                throw new SubagentDelegateError("subagent_invalid_input", "subagent_run deadlineMs applies to background submissions only; pass background: true (foreground tasks are bounded by the drain timeout instead)");
+            }
+        }
+        const backgroundDeadlineMs = background === true ? (rawDeadlineMs ?? DEFAULT_BACKGROUND_TASK_DEADLINE_MS) : undefined;
         // 嵌套深度硬限（退役切片 2，Option A）：沿 S2 血缘头回溯本会话层级，已达
         // maxNestedDepth 层时整次调用结构化拒绝——递归的兜底边界（不依赖模型自觉）。
         // resume 不涉深度（S5 裁定：续写既有会话不计新层级，走 subagent_resume）。
@@ -1293,6 +1382,9 @@ export function createCapability(api, options) {
                     ? `${composeRolePrompt(role, prompt)}\n\n${composeParentView(session, session.getSessionId()) ?? ""}`.trim()
                     : composeRolePrompt(role, prompt);
             try {
+                // 后台死线（设计 §5.7）：提交即带绝对 deadlineAt（相对调度器墙钟），强制点在
+                // 调度器 tick；死线只兜"挂死任务"，正常结算远早于它。
+                const deadlineAt = backgroundDeadlineMs === undefined ? undefined : Date.now() + backgroundDeadlineMs;
                 pending.push({
                     index,
                     handle: runtime.submit({
@@ -1311,7 +1403,9 @@ export function createCapability(api, options) {
                                     [AGENT_TASK_CHILD_PROFILE_KEY]: role.profile ?? { version: 1, roleId: role.id },
                                 }),
                         },
+                        ...(deadlineAt === undefined ? {} : { deadlineAt }),
                     }),
+                    ...(deadlineAt === undefined ? {} : { deadlineAt }),
                 });
             }
             catch (error) {
@@ -1333,8 +1427,16 @@ export function createCapability(api, options) {
                 try {
                     const handle = await item.handle;
                     tickets.push({ taskId: handle.id });
+                    // 死线监视（设计 §5.7）：登记未决死线并惰性启动生产 tick 驱动；任务结算
+                    //（含被死线强制/取消/异常）即解除并在归零时停下 ticker。
+                    if (item.deadlineAt !== undefined)
+                        watchBackgroundDeadline(handle, item.deadlineAt);
                     const sink = options?.backgroundDigestSink;
                     if (sink !== undefined) {
+                        // result() 的 reject 通道在 durable results store persist 失败时打开
+                        //（durable replay assembly 启用后真实存在）：摘要观察失败不影响任务
+                        // 本身（终态已在调度器落库可查），也不产生未处理 rejection；宿主 sink
+                        // 自带守卫（sdk.ts 结算回注失败只记 hostLogger warn）。
                         void handle
                             .result()
                             .then((record) => {
@@ -1980,7 +2082,12 @@ export function createCapability(api, options) {
             for (const unsubscribe of progressUnsubscribes)
                 unsubscribe();
             progressUnsubscribes.clear();
+            // 生产 tick 驱动必随 dispose 停止（不允许隐藏定时器活过调度器）。
+            stopDeadlineTicker();
             // 先释放调度器（任务终态落定），再回收 runner 池（先释放任务再杀进程）。
+            // dispose 的 reject 通道在 durable results store persist 失败时打开（durable
+            // replay assembly 启用后真实存在）：释放失败的收尾错误已由 runtime 内部按
+            // 任务暴露，同步 cleanup 路径无法再抛，这里只保证不产生未处理的 rejection。
             void runtime
                 .dispose()
                 .then(() => pool?.shutdown())