@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/task/delegate/delegate-tool.d.ts

@@ -0,0 +1,681 @@
+/**
+ * @fileoverview delegate_task Tool
+ *
+ * 基于 agent-core 的 delegate_task 实现
+ * 参考: packages/core/src/core/environment/expend/task/task-tool.ts
+ *
+ * 功能：
+ * - 委派子Agent执行任务（仅后台模式）
+ * - 支持多种 subagent 类型
+ * - 支持任务关联（task_id）
+ * - 发布 task.background.* EnvEvent 事件供外部订阅
+ *
+ * Note: 自 2026-06 起，delegate_task 仅支持后台模式。
+ * 父 agent 通过返回的 task_id 主动查询进度。
+ */
+import { z } from "zod";
+import type { Tool, ToolResult } from "../../tool/types";
+import type { TaskComponent } from "../task-component";
+/**
+ * Background Task Event Types
+ * 这些事件由 BackgroundTaskManager 发布，标识为 task.background.*
+ */
+export declare const BackgroundTaskEventTypes: {
+    readonly STARTED: "task.background.started";
+    readonly PROGRESS: "task.background.progress";
+    readonly COMPLETED: "task.background.completed";
+    readonly FAILED: "task.background.failed";
+    readonly TIMEOUT: "task.background.timeout";
+    readonly STOPPED: "task.background.stopped";
+    /**
+     * Task #3147 (subagent ask_user cascade → 标准 notify event)
+     * 当 delegate_task 触发的 sub-agent 内部调用 ask_user tool 并抛出 AskUserError 时，
+     * BackgroundTaskManager.executeTask 的 catch 块捕获后，发布此事件供 CLI EventHandler
+     * 走**标准** notify 流程（与 task.background.completed 等完全一致）：
+     *   - EventMessageFormatter 渲染 payload（含 question + subSessionId + rule-based hints）
+     *   - handleEventMessageWithEnv → executeInternal 把消息喂给主 agent LLM
+     *   - 主 agent 用 ask_user tool 展示问题、等用户答复
+     *   - 拿到答复后用 delegate_task(subagentType=..., existingSubSessionId=payload.subSessionId, ...)
+     *     复用 sub-session 让 sub-agent 继承消息历史继续推进（无需 resume function）。
+     *
+     * 关键：hints 由 BackgroundTaskManager 在构造事件时 rule-based 填充（事件自带），
+     * CLI 端 formatter 只渲染，handler 端零特殊化。
+     */
+    readonly ASK_USER: "task.background.ask_user";
+};
+export interface BackgroundTaskStartedPayload {
+    backgroundTaskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    description: string;
+    subagentType: string;
+}
+export interface BackgroundTaskProgressPayload {
+    backgroundTaskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    status: string;
+    progress?: number;
+    description?: string;
+    associatedTaskId?: number;
+}
+export interface BackgroundTaskCompletedPayload {
+    backgroundTaskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    status: "completed" | "failed" | "timeout" | "stopped";
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    description?: string;
+    associatedTaskId?: number;
+}
+/**
+ * Task #3147 — ask_user 事件 payload（标准 notify event 流程）
+ *
+ * 当 BackgroundTaskManager.executeTask 的 catch 块识别到 AskUserError 时发布。
+ * CLI 端 EventHandler 订阅 `task.background.ask_user` 事件后走**标准** notify
+ * 流程（跟 task.background.completed 等完全一致，无任何特殊化）：
+ *   - EventMessageFormatter 渲染 payload（question + subSessionId + hints）成消息
+ *   - handleEventMessageWithEnv → executeInternal 把消息喂给主 agent LLM
+ *   - 主 agent 用 ask_user tool 把 question 展示给用户
+ *   - 拿到用户答复后用 delegate_task(subagentType=payload.subagentType,
+ *     existingSubSessionId=payload.subSessionId, prompt=<用户答复>)
+ *     复用 sub-session 让 sub-agent 继承之前消息历史继续推进（无需 resume function）。
+ *
+ * hints 是 rule-based 提示数组，BackgroundTaskManager 在构造事件时填充。
+ */
+export interface BackgroundTaskAskUserPayload {
+    backgroundTaskId: string;
+    subSessionId: string;
+    parentSessionId: string;
+    subagentType: string;
+    description: string;
+    /**
+     * 解码后的 AskUserError fields（来自 __ASK_USER_ERROR__:...JSON.parse）：
+     * - query: 原始 ask_user 调用时传入的问题文本（含可选 "(选项: A, B)" 后缀）
+     * - sessionId: AskUserError.sessionId（sub-agent 的 session id，与 subSessionId 一致）
+     * - nodeId: AskUserError.nodeId（sub-agent 内部 ask_user 节点的 ID）
+     * - nodeType: AskUserError.nodeType（默认 'agent'）
+     * - agentSessionId: AskUserError.agentSessionId（optional，用于跨工具链 resume）
+     */
+    query: string;
+    sessionId: string;
+    nodeId: string;
+    nodeType: string;
+    agentSessionId?: string;
+    /** 原始 __ASK_USER_ERROR__:... 错误字符串（备份，便于诊断） */
+    error: string;
+    executionTimeMs: number;
+    associatedTaskId?: number;
+    /**
+     * Task #3147 — Rule-based hints（事件载荷自带）
+     *
+     * 原本 #3142 写在 formatter 的 [🤖 Agent 操作提示] 块，按用户预期重做为
+     * **事件 payload 自带** 的 hints 数组：rule-based 由 BackgroundTaskManager
+     * 在构造 ASK_USER 事件时填充，formatter 只负责渲染，handler 端零特殊化。
+     *
+     * 内容：
+     * - 「显示给用户」/「等待回复」/「delegate_task 续传」
+     *
+     * 包含必要 ID（subagentType / subSessionId / backgroundTaskId）便于 LLM
+     * 看到消息后直接构造 delegate_task 续传调用。
+     */
+    hints: string[];
+}
+export interface SubAgentSpec {
+    id: string;
+    name: string;
+    description: string;
+    mode: "subagent" | "primary" | "all";
+    promptOverride?: string;
+    /** 允许的工具列表（白名单） */
+    allowedTools?: string[];
+    /** 拒绝的工具列表（黑名单） */
+    deniedTools?: string[];
+}
+export declare const builtInSubAgents: SubAgentSpec[];
+export declare function getSubAgentSpec(id: string): SubAgentSpec | undefined;
+export declare const DelegateToolParameters: z.ZodObject<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    subagent_type: z.ZodDefault<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+    similar_task_ids: z.ZodArray<z.ZodNumber, "many">;
+    sub_session_id: z.ZodOptional<z.ZodString>;
+    triggerEventId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    prompt: string;
+    subagent_type: string;
+    similar_task_ids: number[];
+    reason?: string | undefined;
+    timeout?: number | undefined;
+    sub_session_id?: string | undefined;
+    triggerEventId?: string | undefined;
+}, {
+    description: string;
+    prompt: string;
+    similar_task_ids: number[];
+    reason?: string | undefined;
+    timeout?: number | undefined;
+    subagent_type?: string | undefined;
+    sub_session_id?: string | undefined;
+    triggerEventId?: string | undefined;
+}>;
+export type DelegateToolParams = z.infer<typeof DelegateToolParameters>;
+export interface DelegateToolResult {
+    tool: Tool;
+    backgroundTaskManager: BackgroundTaskManager;
+}
+export interface BackgroundTask {
+    id: string;
+    /**
+     * Task #2590 follow-up — runId of the sub-agent run launched by this task.
+     *
+     * Pre-allocated in `executeWithAbort` and passed to `env.handle_query` via
+     * `AgentContext.runId` so the record is populated BEFORE the run actually
+     * starts. Used for run-scoped abort via `agentComponent.abortRun(runId)`
+     * instead of the agent-name-scoped `agentComponent.abort(subagentType)`
+     * (which silently killed concurrent same-type sub-agents and is the
+     * root cause of silent-fail empty `result`).
+     */
+    runId?: string;
+    subSessionId: string;
+    parentSessionId: string;
+    description: string;
+    subagentType: string;
+    status: "pending" | "running" | "completed" | "failed" | "timeout" | "stopped" | "awaiting-user";
+    createdAt: number;
+    /** Timestamp of the latest lifecycle state change or progress notification. */
+    lastUpdatedAt?: number;
+    startedAt?: number;
+    completedAt?: number;
+    result?: string;
+    error?: string;
+    progress?: number;
+    progressMessage?: string;
+    abortController?: AbortController;
+    associatedTaskId?: number;
+    similarTaskIds?: number[];
+    /**
+     * Task #4042 (ESPlugin v2 Phase 2)：trigger event ID
+     *
+     * 由 ES 触发的 delegate_task 会把 triggerEventId 通过 publishBackgroundEvent
+     * 透传到所有 task.background.* event，让事件 trigger CLI 可反查 EventStore
+     * 拿原始 chatId。不存在时表示非 ES 触发（向后兼容）。
+     */
+    triggerEventId?: string;
+    /**
+     * ★ Task #4042 follow-up — delegate 时刻捕获的回复通道快照。
+     *
+     * 之前 notify event 不带 replyChannel，CLI EventHandler 处理 task.background.*
+     * 时只能 fallback 到 REPL 的全局 `lastReplyChannel`（last-write-wins），
+     * 多群并发时"最后来的群消息决定所有任务通知回哪个群"（#4035/#4038/#4039 串群）。
+     *
+     * 修复：createTask 时把 parent EnvContext 的 replyChannel 快照到 task，
+     * publishBackgroundEvent 时写进 event.metadata.replyChannel，让每个通知自带
+     * 自己 task 诞生时的回复目标；EventHandler.extractChatId 优先用它做
+     * chat-keyed session 隔离与回复路由，不再依赖全局 lastReplyChannel。
+     */
+    replyChannel?: {
+        type?: string;
+        appId?: string;
+        chatId?: string;
+        messageId?: string;
+        profile?: string;
+        params?: Record<string, unknown>;
+    };
+}
+export interface CreateBackgroundTaskOptions {
+    parentSessionId: string;
+    description: string;
+    prompt: string;
+    subagentType: string;
+    timeout?: number;
+    similarTaskIds?: number[];
+    /**
+     * 如果 subagentType 是 workflow 类型被 entry-agent 中介，
+     * 此字段记录原始 workflow 名称（用于日志/审计/追踪）。
+     *
+     * 背景：.roy/design/2026-06-29-workflow-subagent-entry-agent-design.md
+     */
+    originalWorkflowName?: string;
+    /**
+     * ★ 已有 sub-agent session ID（可选）。
+     * 传入时跳过 sessionComponent.create()，改为 sessionComponent.get() 校验后复用。
+     * 用于超时/失败后的重试场景，sub agent 继承之前会话上下文（消息历史保留），
+     * 只需在 metadata 中标记 reused_sub_session=true + reused_at=timestamp。
+     *
+     * 2026-07-10 新增（Task #1752 subSessionId 复用与超时重试机制）
+     */
+    existingSubSessionId?: string;
+    /**
+     * ★ Task #4042 (ESPlugin v2 Phase 2)：trigger event ID
+     *
+     * 当 delegate_task 由 ES 触发时（用户在飞书群里说"调研 X"，主 agent 调 delegate_task），
+     * ES 先通过 EventStore.insertTriggerEvent 把原始飞书消息落库，拿到 triggerEventId，
+     * 然后调用 delegate_task 时把 triggerEventId 传到这里。
+     *
+     * BackgroundTaskManager 会：
+     *  1. 把 triggerEventId 写到 sub-session.metadata.triggerEventId（sub-agent 读 ALS 仍可用）
+     *  2. 透传到后续所有 task.background.* event metadata（让 CLI event-handler 反查 EventStore）
+     */
+    triggerEventId?: string;
+}
+/**
+ * 构建 entry-agent 调度的 prompt 包装 (Task #2164 beta-compare divergence #2)
+ *
+ * 当 delegate_task 检测到 workflow 类型 subagent (或 5 legacy yaml alias) 时,
+ * 用此函数包装原始 prompt, 明确告诉 entry-agent 要调度哪个 workflow.
+ *
+ * 结构化设计 (beta divergence vs reference #2146):
+ * - 使用 `<workflow_name>NAME</workflow_name>` XML 标签作为唯一权威的 workflow 名来源
+ * - 取代 reference 让 LLM 通过 pattern examples 解析 workflow 名的方案
+ * - 工作流名应严格从这个标签解析 (避免 LLM 模式猜测)
+ * - 用法: prompt.match(/<workflow_name>([^<]+)<\/workflow_name>/)?.[1]
+ */
+export declare function buildEntryAgentPrompt(options: {
+    workflowName: string;
+    originalPrompt: string;
+    description: string;
+}): string;
+/**
+ * 5 个 legacy yaml subagent 名称 (Task #2164 兼容性)
+ *
+ * 用户历史上可能在 ~/.local/share/roy-agent/agents/ 下配置过这些名字的 yaml 文件，
+ * 为了不破坏用户配置, Beta 把它们统一改写到 workflow-runner.
+ *
+ * 设计：Set 查找 O(1)，不引入额外 dispatcher 类。
+ */
+export declare const WORKFLOW_COMPAT_ALIASES: ReadonlySet<string>;
+export declare const DEFAULT_TIMEOUT = 1800000;
+/**
+ * Background Task Manager (简化版)
+ *
+ * 管理后台任务的创建、执行、状态跟踪
+ * 发布 task.background.* 事件供外部订阅
+ */
+export declare class BackgroundTaskManager {
+    private env;
+    /**
+     * Task #2539 — processRegistries 上限。超过上限时 createTask 拒绝（拒绝 throw），
+     * 防止 spawn 出 bug 时无界累积。默认 1000（足够日常使用，又不至于无限增长）。
+     * 实际活跃 task 数受 processRegistries.size 限制；正常 task 完成后 finalizeTask
+     * 会清掉 map entry；残留 PID task（BL-4c）保留 map entry 直到 killAll 才清。
+     */
+    private readonly maxProcessRegistries;
+    /**
+     * Task #2539 — terminalTasks 上限。终态任务从 tasks Map 移到这里，cap 1000。
+     * 超过上限时丢最旧的（保持 LRU 语义：最近完成的任务优先保留，便于 query_background_process 查询）。
+     */
+    private readonly maxTerminalTasks;
+    private tasks;
+    /**
+     * Task #2539 — 终态任务镜像。
+     * finalizeTask 时把 BackgroundTask 从 tasks Map 移到这里；getTask 优先查 tasks，其次 terminalTasks。
+     * 上限 maxTerminalTasks，超过时丢最旧。
+     */
+    private terminalTasks;
+    private abortControllers;
+    private progressTimers;
+    /**
+     * Per-task ProcessRegistry（2026-07 新增）。
+     * 跟踪该 task 派生的所有子进程 PID；timeout/stop/dispose 时遍历杀进程树。
+     * 内部值是 ProcessRegistry 实例；存储而不暴露，便于测试访问。
+     *
+     * Task #2539 — 终态释放契约：transient registry（tasks / abortControllers /
+     * workflowRunRegistries / 本 task 的 processRegistries entry）在 sub session
+     * 终态触发后必须释放；processRegistries 仅在 size==0 时 delete map 入口
+     * （保留 BL-4c force-stop 重试 contract）。
+     */
+    private processRegistries;
+    /**
+     * Per-task workflow run registry (Task #2144).
+     * 跟踪该 task 派生的所有 workflow_run runId；stopTask() 时遍历调 workflowService.stopRun。
+     * 镜像 processRegistries 的 Map<bgTaskId, Set<workflowRunId>> 模式。
+     */
+    private workflowRunRegistries;
+    /**
+     * WorkflowService 引用（Task #2144 — 反向注入，避免 task → workflow 直接 import）。
+     * WorkflowComponent 启动时通过 setWorkflowService() 注入。
+     */
+    private workflowService?;
+    constructor(env: any);
+    /**
+     * Task #2144 — 注入 WorkflowService 引用。
+     * 由 WorkflowComponent 在初始化时反向注入（避免 task → workflow 直接 import）。
+     * 缺省时 propagateStopToWorkflowRuns 仅记录 warn 日志，不抛错。
+     */
+    setWorkflowService(svc: {
+        stopRun(runId: string, reason?: string): Promise<void>;
+    }): void;
+    /**
+     * Task #2144 — Attach a workflow runId to a bgTask。
+     * 当 sub-session 通过 workflow_run 启动 workflow 时调用，把 runId 注册到
+     * 对应 bgTaskId 的 workflowRunRegistries，供 stopTask() 级联 stop。
+     *
+     * 空字符串 / 缺失参数静默忽略（避免脏数据）；重复 attach 同一 runId 幂等。
+     */
+    attachWorkflowRun(bgTaskId: string, workflowRunId: string): void;
+    /**
+     * Task #2144 — Detach a workflow runId from a bgTask。
+     * 当 workflow_run 自然完成（success）时调用，把 runId 从 registry 中移除，
+     * 避免 propagateStopToWorkflowRuns 重复 stop 已完成的 workflow。
+     * 缺省时 propagateStop 仍会 stopRun，但 stopRun 对已完成 workflow 是幂等的。
+     */
+    detachWorkflowRun(bgTaskId: string, workflowRunId: string): void;
+    /**
+     * Task #2190 — Replace a placeholder runId with the real engine runId.
+     * 触发时机：sub-session 调 workflow_run 时，wrapper 立即用 reservedRunId
+     * 做 PRE-attach；engine 随后通过 onSessionCreated 报回真实 runId；tool 调
+     * 此 hook 把 registry 里的占位 id 替换成真实 id，使后续 stop_task 能针对
+     * 真实 workflow 调用 stopRun。
+     *
+     * 语义：若 oldRunId 存在则删除；若 newRunId 非空则加入（覆盖式 swap）。
+     * 空字符串 / 缺失参数静默忽略；bgTaskId 不存在则 no-op。
+     */
+    replaceWorkflowRun(bgTaskId: string, oldRunId: string, newRunId: string): void;
+    /**
+     * Task #2144 — 级联 stop 所有 attach 到 bgTaskId 的 workflow runs。
+     * 在 stopTask() 的 killAll() 之后调；workflowService.stopRun 对已完成 workflow
+     * 是幂等的（try/catch + logger.warn 吞掉 "Session not found" 等异常）。
+     * 主 session 直接调用（无 bgTaskId）时 workflowRunRegistries 为空，no-op。
+     *
+     * Task #2190 — returns `{ runIds, stopResults }` so stopTask() can populate
+     * `attached_workflow_run_ids` and `workflow_stop_results` in the payload.
+     * `stopResults[i]` mirrors `runIds[i]` 1:1; entries carry `{ runId, success, error? }`.
+     */
+    private propagateStopToWorkflowRuns;
+    /**
+     * Task #2539 — 终态联动释放 transient registry（success / error / cancel / timeout 共用）。
+     *
+     * 释放：
+     * - tasks Map 中本 task entry（BackgroundTask 对象本身；持有者持有引用时可继续读，但不再可查询）
+     * - abortControllers Map 中本 task entry
+     * - workflowRunRegistries Map 中本 task entry（per-task Set）
+     * - progressTimers Map 中本 task entry（通过 stopProgressReporter）
+     *
+     * 保留（BL-4c force-stop 重试 contract）：
+     * - processRegistries Map 中本 task entry — 仅在 size==0 时 delete map 入口，
+     *   残留 PID 时保留 map entry 供下一次 forceStopAllAcrossParents 重试。
+     *
+     * 幂等：重复调用 no-op（map 上 .delete 第二次返回 false）。
+     * 不存在的 taskId：no-op，不报错。
+     */
+    finalizeTask(taskId: string, reason: string): void;
+    /**
+     * Task #2539 — processRegistries 当前 size（可观测）。
+     * 用于 heap stress 测试 / 监控埋点。
+     */
+    getProcessRegistrySize(): number;
+    /**
+     * Task #2539 — processRegistries 上限。
+     */
+    getMaxProcessRegistries(): number;
+    /**
+     * Task #2539 — 清掉所有 size==0 的 processRegistry map entries（保守兜底）。
+     * 不主动调用；正常路径由 finalizeTask 在 size==0 时 delete。
+     * 提供这个 API 供测试 / 监控。
+     *
+     * @returns cleaned count
+     */
+    cleanupEmptyProcessRegistries(): number;
+    /**
+   * Workflow entry-agent 默认名称
+   *
+   * 当 delegate_task 检测到 workflow 类型 subagent 时，委托给该 entry-agent。
+   * 详见 .roy/design/2026-06-29-workflow-subagent-entry-agent-design.md
+   */
+    static readonly DEFAULT_WORKFLOW_ENTRY_AGENT = "workflow-runner";
+    /**
+     * 检查 subagentType 是否需要走 entry-agent 路由（workflow 类型）
+     *
+     * 返回 entry-agent 名称（如果有），否则返回 undefined（走原路径）。
+     *
+     * 注意：这里必须 try/catch，因为 this.env?.getComponent 可能抛错。
+     *
+     * Task #2164 beta-compare divergence #1: 单一层 canonicalization
+     * - 5 个 legacy yaml alias (strict-task-agent/code-review/...) 直接在这里重写,
+     *   handleBackgroundTask 不再二次检测
+     * - 参考 reference 在 createDelegateTool().execute() + handleBackgroundTask()
+     *   两层 rewriting, beta 只 1 层
+     */
+    resolveEntryAgent(subagentType: string): string | undefined;
+    /**
+     * Internal compat-rewrite detection (Task #2164 trace #3)
+     *
+     * 用 wrapFunction 包一层让 free-standing 检测逻辑也能进入 OTel span,
+     * 参考 reference 把这逻辑标记为 "not-applicable" 因为 @TracedAs 不支持 free function.
+     * Beta 用 wrapFunction 让 `delegate.detectWorkflowShortcut` span 被记录。
+     */
+    private static _detectWorkflowShortcutWrapped;
+    /** 公开的 static 入口，wrapFunction 不污染 caller API */
+    static detectWorkflowShortcutCompat(subagentType: string): boolean;
+    /**
+     * Get SessionComponent from env
+     */
+    private getSessionComponent;
+    /**
+     * sub-session → task 的确定性反查。
+     *
+     * sub-agent 的 `task_create` 用 `sessionId = ctx.session_id`（即 sub-session id），
+     * 因此可按 session_id 反查它创建的第一个 task。用于在 completion 时稳定地确定
+     * `associatedTaskId`，避免依赖易失的 `getCurrentTaskId()`（被 task_complete 清空）
+     * 或有歧义的结果文本正则。
+     */
+    private resolveAssociatedTaskIdBySubSession;
+    /**
+     * Publish a task.background.* event
+     *
+     * Task #4042 (ESPlugin v2 Phase 2)：可选 triggerEventId 参数。
+     * 当 ES 触发 delegate_task 时，主 agent 会通过 EventStore.insertTriggerEvent
+     * 先把原始飞书事件落库，拿到 triggerEventId；sub-agent 完成后 emit notify event
+     * 携带 triggerEventId，主 agent 处理 notify event 时反查 EventStore 拿原始 chatId。
+     *
+     * 不传 triggerEventId 时，向后兼容老代码路径（metadata.triggerEventId 缺失）。
+     */
+    private publishBackgroundEvent;
+    /**
+     * 带 triggerEventId 的 publishBackgroundEvent 公开版（用于测试和外部调用）
+     *
+     * @internal 测试 / 集成用，普通调用方走 publishBackgroundEvent 私有方法
+     */
+    publishBackgroundEventWithTrigger<T>(type: string, payload: T, parentSessionId: string | undefined, triggerEventId: string, replyChannel?: BackgroundTask["replyChannel"]): void;
+    /**
+     * Task #3xxx — 解析 AskUserError 信息
+     *
+     * env.handle_query() 路径下，ask_user 抛出的 AskUserError 会被 agent-component 编码成
+     * `__ASK_USER_ERROR__:{JSON}` 字符串，然后通过 `throw new Error(result.error)`
+     * 抛出（environment.ts:417），所以 catch 块只能拿到 plain Error instance。
+     * 直接 throw 的场景（如未来插件扩展）也能命中 instance / name 检查。
+     *
+     * 复用 interactive.ts:1300 parseAskUserError 的识别规则（避免重复实现）：
+     *   1. error instanceof AskUserError
+     *   2. error.name === 'AskUserError'
+     *   3. error.message 包含 __ASK_USER_ERROR__: 前缀 → JSON.parse
+     *
+     * @returns 解码后的 AskUserErrorInfo；null 表示不是 ask_user 错误（继续走普通 error 分支）
+     */
+    private static parseAskUserErrorFromMessage;
+    createTask(options: CreateBackgroundTaskOptions): Promise<{
+        taskId: string;
+        subSessionId: string;
+    }>;
+    /**
+     * Task #3146 — sub-agent ask_user cascade（移除 resume function）
+     *
+     * 历史：原 `resumeFromAskUserAnswer()` 由 Task #3142 引入，用于用户答复后
+     * 通过 BackgroundTaskManager 复用 sub-session 续传 sub-agent。
+     *
+     * 决定（用户指令）：**无需实现 resume function**——续传完全由 delegate_task
+     * 自然完成。具体流程：
+     *   1. BackgroundTaskManager.executeTask 在 catch 块识别 AskUserError 后，
+     *      保留 sub-session 并发布 `task.background.ask_user` 事件。
+     *   2. CLI 收到事件后直接显示问题给用户（不送 LLM）。
+     *   3. 用户答复后，主 agent（或用户命令）通过 `delegate_task` 工具调用
+     *      `subagentType=original.subagentType, existingSubSessionId=original.subSessionId`
+     *      即可复用 sub-session（保留 message history）继续推进 sub-agent。
+     *
+     * 因此本方法不再提供；续传是 delegate_task + existingSubSessionId 内建能力。
+     */
+    private executeTask;
+    /**
+     * Start progress reporter for a task
+     */
+    private startProgressReporter;
+    /**
+     * Stop progress reporter for a task
+     */
+    private stopProgressReporter;
+    private executeWithAbort;
+    stopTask(taskId: string): Promise<{
+        success: boolean;
+        task?: BackgroundTask;
+        message: string;
+        /**
+         * Task #2190 — workflow runId list that was attached at stop time.
+         * Main session can audit which workflow_runs were stopped as a
+         * cascade of this stop_task. Always an array (empty if none).
+         */
+        attached_workflow_run_ids?: string[];
+        /**
+         * Task #2190 — per-id stop outcomes from `propagateStopToWorkflowRuns`.
+         * 1:1 with `attached_workflow_run_ids` when both arrays have entries.
+         * Each entry: `{ runId, success, error? }`.
+         */
+        workflow_stop_results?: Array<{
+            runId: string;
+            success: boolean;
+            error?: string;
+        }>;
+    }>;
+    getTask(taskId: string): BackgroundTask | undefined;
+    listTasks(): BackgroundTask[];
+    /**
+     * Task #2255 — ESC idle-with-active-descendant fix.
+     *
+     * Returns true if there is at least one background task whose
+     * `parentSessionId` matches the given parent AND whose status is
+     * `pending` or `running`. Used by REPL.handleEscKey() to decide
+     * whether to cascade-stop the session tree even when the main LLM
+     * is idle (isExecuting=false).
+     *
+     * Cheap: O(N) over the in-memory tasks Map (typically <10 active
+     * per session). Not persisted to DB — runs from in-memory state only.
+     */
+    hasActiveTaskForParent(parentSessionId: string): boolean;
+    /**
+     * Task #2245 — ESC cascade stop.
+     *
+     * Stop all BackgroundTask instances whose `parentSessionId` matches the given
+     * parent, regardless of which sub-agent type created them. Calls the existing
+     * `stopTask(taskId)` per entry, which already propagates to attached workflow
+     * runs (Task #2144). Returns `{ stoppedTaskIds }` so callers (e.g. REPL ESC
+     * handler / `cascadeStopSessionTree`) can audit cascade coverage.
+     *
+     * Only acts on `pending` / `running` tasks; `completed` / `failed` / `stopped`
+     * / `timeout` are skipped (idempotent).
+     *
+     * Iron rule: does NOT mutate `parentSessionId` or any background-task identity.
+     * No effect on tasks whose parent does not match.
+     */
+    stopAllForParent(parentSessionId: string): Promise<{
+        stoppedTaskIds: string[];
+    }>;
+    /**
+     * Task #2245 — ESC force-stop (second-press within 2s window).
+     *
+     * Traverse ALL BackgroundTask entries (regardless of parent), kill their
+     * process trees via ProcessRegistry, and mark them `stopped`. Used as the
+     * force path when `stopAllForParent` (graceful) leaves residual orphans.
+     *
+     * Task #2245 — BL-4: iterates ALL tasks (not just running/pending) so that
+     * tasks already marked `stopped` by graceful `stopTask()` but with leaked
+     * PIDs can still be retried. Combined with `ProcessRegistry.killAll()`
+     * retaining `stillAlive` PIDs, this enables second-ESC force retry.
+     *
+     * Task #2245 — P1-#1: also calls `propagateStopToWorkflowRuns` for each task
+     * so that attached workflow runs are cascaded into the engine's stop
+     * (the original cascade gap — only `dispose()` did this previously).
+     *
+     * Task #2245 — P1-#2: publishes `task.background.stopped` event for each
+     * task that is freshly marked `stopped` by this force pass, so the parent
+     * session and CLI UI see the stop signal (previously force path was silent).
+     *
+     * Task #2245 — P1-#8: renamed to `forceStopAllAcrossParents` to clarify
+     * that this iterates ALL tasks (regardless of parent), unlike
+     * `stopAllForParent(parentId)` which is parent-scoped. `forceStopAll` is
+     * kept as a deprecated alias for backward compatibility.
+     */
+    forceStopAllAcrossParents(): Promise<void>;
+    /**
+     * Task #2245 — P1-#8: deprecated alias for `forceStopAllAcrossParents`.
+     * Kept for backward compatibility with code that still calls `forceStopAll`.
+     * New code should call `forceStopAllAcrossParents` directly.
+     * @deprecated use forceStopAllAcrossParents
+     */
+    forceStopAll(): Promise<void>;
+    /**
+     * Dispose and cleanup all resources
+     * Call this when shutting down to prevent process from hanging
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Create delegate_task tool
+ */
+export declare function createDelegateTool(taskComponent: TaskComponent): Tool;
+/**
+ * Task #4042 ESPlugin v2 P0（生产路径修复）：从当前 EnvContext 派生 triggerEventId。
+ *
+ * 完整 v2 链路：
+ *   lark event → EventStore.insertTriggerEvent → triggerEventId
+ *     → 主 agent delegate_task(triggerEventId) → task.background.* metadata.triggerEventId
+ *     → CLI EventHandler 反查 EventStore 拿原始 chatId / messageId。
+ *
+ * 问题：triggerEventId 只在 LLM 显式传参时才透传，而它对 LLM 是个晦涩 token，
+ * 生产上几乎不传 → notify event 缺 metadata.triggerEventId → v2 path 永不命中，
+ * 退回老 replyChannel fallback（正是 #4035/#4038/#4039 串群根因）。
+ *
+ * 兜底来源（优先级从高到低）：
+ *   1. EnvContext.envEvent.metadata.triggerEventId（LarkCliInstance.handleEvent 注入）
+ *   2. EnvContext.envEvent.payload.triggerEventId（同上的 payload 副本）
+ *
+ * 非 ES 触发场景（普通 CLI / REPL 输入）返回 undefined，向后兼容。
+ */
+declare function _deriveTriggerEventIdFromEnvContext(): string | undefined;
+/**
+ * traced 版 deriveTriggerEventIdFromEnvContext（供 debug trace 观测派生结果）。
+ */
+export declare const deriveTriggerEventIdFromEnvContext: typeof _deriveTriggerEventIdFromEnvContext;
+/**
+ * Task #4042 follow-up：把当前 EnvContext.replyChannel 拍成不可变快照。
+ *
+ * 为什么快照：replyChannel 对象可能被后续事件修改（父子共享/ALS 继承），
+ * 而 BackgroundTask 生命周期长（sub-agent 可能跑几十分钟），必须固化 delegate
+ * 时刻的回复目标，避免"通知发出时读到的 replyChannel 已经是别的群"。
+ *
+ * 返回 undefined 当没有 EnvContext / 没有 replyChannel / replyChannel 无 chatId+messageId
+ * （无有效回复目标时不要塞空对象，保持向后兼容）。
+ */
+declare function _captureReplyChannelSnapshot(): BackgroundTask["replyChannel"] | undefined;
+/**
+ * traced 版 captureReplyChannelSnapshot（供 debug trace 观测 task 的回复目标快照）。
+ */
+export declare const captureReplyChannelSnapshot: typeof _captureReplyChannelSnapshot;
+declare function handleBackgroundTask(backgroundTaskManager: BackgroundTaskManager, parentSessionId: string, description: string, prompt: string, subagentType: string, timeout?: number, similarTaskIds?: number[], 
+/**
+ * ★ 2026-07-10 新增（Task #1752 subSessionId 复用机制）
+ * 已有 sub session ID。传入时 BackgroundTaskManager.createTask 跳过 create()，
+ * 改为 get() 校验后复用 sub session；不传则保持新建模式。
+ */
+existingSubSessionId?: string, 
+/**
+ * ★ Task #4042 ESPlugin v2：EventStore trigger event ID。
+ * 传入时透传给 createTask → publishBackgroundEvent，写进 task.background.*
+ * 事件 metadata，供主 agent 反查原始 chatId。
+ */
+triggerEventId?: string): Promise<ToolResult>;
+export { handleBackgroundTask };

package/dist/env/task/delegate/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Delegate Tools Index
+ */
+export { createDelegateTool, BackgroundTaskManager } from "./delegate-tool";
+export { createStopTool } from "./stop-tool";
+export type { DelegateToolResult, DelegateToolParams, DelegateToolParameters } from "./delegate-tool";
+export type { BackgroundTask, SubAgentSpec } from "./delegate-tool";
+export { BackgroundTaskEventTypes, type BackgroundTaskStartedPayload, type BackgroundTaskProgressPayload, type BackgroundTaskCompletedPayload, } from "./delegate-tool";