@lingxiao-office/sdk 1.0.0

package/dist/agents/AgentPoolRuntime.d.ts

@@ -0,0 +1,647 @@
+/**
+ * AgentPool - Agent 进程池管理
+ * 负责管理 Agent 的创建、运行和生命周期
+ *
+ * 1.2 迁移: 使用 WorkerProcessRunner 启动独立 OS 子进程
+ */
+import type { ContentGenerator } from '../llm/ContentGenerator.js';
+import type { LLMErrorKind } from '../llm/errors.js';
+import type { BlackboardDelta } from '../core/blackboard/types.js';
+import type { ToolRegistry } from '../tools/Registry.js';
+import type { BusMessage, MessageBus } from '../core/MessageBus.js';
+import type { EventEmitter, EventName, EventMap } from '../core/EventEmitter.js';
+import type { DatabaseManager } from '../core/Database.js';
+import type { Task as BoardTask, TaskBoard } from '../core/TaskBoard.js';
+import type { TokenTracker } from './BaseAgentRuntime.js';
+import { AgentRoleRegistry } from './RoleRegistry.js';
+import type { AgentRole } from './RoleRegistry.js';
+import { type WorkerContractComplianceProof, type WorkerRecoveryPayload } from '../core/AgentProtocol.js';
+import { WorkerInteractiveRuntime } from './runtime/WorkerInteractiveRuntime.js';
+import { WorkerProcessRunner, type WorkerHandle, type WorkerProcessDiagnostics } from '../core/WorkerProcessRunner.js';
+import type { AgentExecutionResult } from './AgentExecutionResult.js';
+import { type RecoveryFaultClass } from '../core/RecoveryRecords.js';
+import { type WorkNote } from '../core/WorkNoteManager.js';
+import type { ContractPack } from '../core/ContractPack.js';
+import type { WorkflowManager } from '../core/workflow/WorkflowManager.js';
+import type { WorkflowEngine } from '../core/workflow/WorkflowEngine.js';
+import type { ScheduledTaskManager } from '../core/ScheduledTaskManager.js';
+import { type ExternalCompletionReport } from './external/completionReport.js';
+import { type CoreAgentStatus } from '../contracts/adapters/StatusAdapter.js';
+import { RemoteWorkerRegistry, type RemoteWorkerDescriptor } from '../core/transport/RemoteWorkerRegistry.js';
+import { WorkerLifecycle } from './pool/WorkerLifecycle.js';
+import { FaultRecovery } from './pool/FaultRecovery.js';
+import type { StructuredCompletionPayload } from './pool/AgentPoolCompletionPayload.js';
+import { WorkerEventHandlerBinder } from './pool/WorkerEventHandlerBinder.js';
+import { type SpeculativeWinnerEvidence } from '../core/SpeculativeExecutionController.js';
+interface WorkerFailurePayload {
+    error: string;
+    status?: AgentExecutionResult['status'];
+    metadata?: Partial<AgentExecutionResult['metadata']>;
+    outputs?: AgentExecutionResult['outputs'];
+    stats?: {
+        iterations?: number;
+        toolCalls?: number;
+    };
+    tokenUsage?: {
+        total?: number;
+        prompt?: number;
+        completion?: number;
+    };
+}
+export declare function parseWorkerFailurePayload(error: unknown): {
+    error: Error;
+    recoverable: boolean;
+    terminalKind?: AgentExecutionResult['metadata']['terminalKind'];
+    faultClass?: RecoveryFaultClass;
+    llmErrorKind?: LLMErrorKind;
+    reason: string;
+    payload?: WorkerFailurePayload;
+};
+type InjectedAgentEventField = 'sessionId' | 'agentId' | 'agentName' | 'taskId';
+type AgentEventExtra<T extends EventName> = Omit<EventMap[T], InjectedAgentEventField> & Partial<Pick<EventMap[T], Extract<keyof EventMap[T], InjectedAgentEventField>>>;
+export interface WorkerBridgeCursor {
+    lastTimestamp: number;
+    deliveredIdsAtTimestamp: string[];
+}
+export declare function createEmptyWorkerBridgeCursor(): WorkerBridgeCursor;
+export declare function shouldBridgeWorkerMessage(message: Pick<BusMessage, 'id' | 'timestamp'>, cursor: WorkerBridgeCursor): boolean;
+export declare function advanceWorkerBridgeCursor(cursor: WorkerBridgeCursor, messages: Array<Pick<BusMessage, 'id' | 'timestamp'>>): WorkerBridgeCursor;
+export declare function parseWorkerBridgeCursor(value: unknown): WorkerBridgeCursor;
+export declare function serializeWorkerBridgeCursor(cursor: WorkerBridgeCursor): string;
+/**
+ * AgentHandle - Agent 运行时的句柄
+ */
+export interface AgentHandle {
+    agentId: string;
+    name: string;
+    roleType: string;
+    displayRole?: string;
+    taskId: string;
+    status: 'starting' | 'running' | 'stopped';
+    visibility?: 'team' | 'ephemeral';
+    owner?: 'leader' | 'team';
+    interactive?: boolean;
+    persistAcrossTurns?: boolean;
+    teamMember?: string | null;
+    /** 退出原因，仅当 status === 'stopped' 时有效 */
+    exitReason?: 'completed' | 'failed' | 'timeout' | 'crashed' | 'terminated';
+    /** TaskBoard 当前执行代际；每次派发/重派绑定，用于 completion/failed 回执防旧代污染。 */
+    taskRunGeneration?: number;
+    asyncTask?: Promise<string>;
+    startTime: number;
+    endTime?: number;
+    error?: Error;
+    sessionId?: string;
+    iteration?: number;
+    role?: string;
+    /** Last worker heartbeat / process liveness signal. Not proof of task progress. */
+    lastHeartbeat?: number;
+    /** Last meaningful task progress signal. Heartbeats must not refresh this. */
+    lastProgress?: number;
+    /** Last token streaming timestamp */
+    lastTokenAt?: number;
+    /** Last tool call start timestamp */
+    lastToolCallAt?: number;
+    /** Last tool result timestamp */
+    lastToolResultAt?: number;
+    /** Current tool being executed (null if not in tool) */
+    currentToolName?: string | null;
+    /** Brief preview of the last tool result (truncated, for Leader runtime state injection) */
+    lastToolResultPreview?: string;
+    /** Whether agent is waiting for permission approval */
+    pendingPermission?: boolean;
+    toolCalls?: number;
+    runtimeRole?: AgentRole;
+    capabilityDetails?: {
+        baselineRole?: string;
+        skillNames: string[];
+        droppedTools: string[];
+        tools: string[];
+    };
+    interactiveRuntime?: WorkerInteractiveRuntime;
+    /** Canonical worker-process handle. */
+    workerHandle?: WorkerHandle;
+    workerBackend?: 'worker_process' | 'claude' | 'codex' | 'remote';
+    externalSessionId?: string;
+    externalPid?: number;
+    externalExitCode?: number | null;
+    externalExitSignal?: string | null;
+    externalDiagnostics?: {
+        logPath?: string;
+        stderrLogPath?: string;
+        stderrTail?: string[];
+        stdoutTail?: string[];
+        lastEventAt?: number;
+        recoverable?: boolean;
+        recoveryAction?: string;
+    };
+    externalStop?: (reason: string) => boolean;
+    workerInboxBridgeCleanup?: () => void;
+    recoveryLineage?: number;
+    /**
+     * Respawn 限速 (2026-05-28)：
+     * Leader 反复调用 send_message_to_agent / autoRespawn 会无限制 spawn 新 worker，
+     * 把机器跑爆 / 把 provider 配额耗尽。这里记录最近一次 respawn 时间窗 + 失败次数，
+     * AgentPool.respawnAgent 入口会基于此拒绝过频/连续失败的 respawn。
+     */
+    respawnTimestampsMs?: number[];
+    consecutiveRespawnFailures?: number;
+    /**
+     * 完成回执屏障（乱序保护）：worker:complete 回调最先置位（解析 payload 之前）。
+     * worker:exit 回调据此判断「该 worker 已收到合法完成回执」，而非仅依赖
+     * handle.exitReason==='completed' 或事件到达顺序——避免 worker:exit 早于
+     * worker:complete 到达（或 complete 解析中途）时被误判为崩溃而重复恢复重派。
+     */
+    completionReceived?: boolean;
+}
+/**
+ * AgentPool 配置
+ */
+export interface AgentPoolConfig {
+    sessionId: string;
+    llm: ContentGenerator;
+    toolRegistry: ToolRegistry;
+    bus: MessageBus;
+    emitter: EventEmitter;
+    db: DatabaseManager;
+    tracker: TokenTracker;
+    workspace: string;
+    model: string;
+    roleRegistry: AgentRoleRegistry;
+    /** TaskBoard 是任务生命周期唯一写入出口。 */
+    taskBoard: TaskBoard;
+    workflowManager?: WorkflowManager;
+    workflowEngine?: WorkflowEngine;
+    scheduledTaskManager?: ScheduledTaskManager;
+    /** Production default is true; tests may disable it to inspect recovery state without spawning a child worker. */
+    autoRetryRecoveries?: boolean;
+    /**
+     * Test seam：注入一个受控的 WorkerProcessRunner（通常是 fake，避免真起子进程）。
+     * 缺省由 pool 自建真实 runner。binder 在构造期绑到本实例，故必须经 config 注入而非构造后替换。
+     */
+    workerRunner?: WorkerProcessRunner;
+}
+export interface AgentRespawnOptions {
+    failureMode?: 'task_failed' | 'recovery';
+}
+/**
+ * AgentPool - Agent 进程池
+ */
+export type AgentStatus = CoreAgentStatus;
+export declare class AgentPool {
+    private static readonly MAX_RECOVERY_ATTEMPTS;
+    /**
+     * 集中校验并执行 Agent 状态转换。非法转换会抛出 Error。
+     *
+     * AgentPool 不再保存自己的 transition 表；所有合法跳转来自 StateSemantics。
+     * 这样 respawn、stopAll、worker complete/failed 等路径不会各自发展出不同规则。
+     */
+    static transitionAgentStatus(handle: AgentHandle, newStatus: AgentStatus): void;
+    protected forceStopAgent(handle: AgentHandle, exitReason: NonNullable<AgentHandle['exitReason']>, reason?: string): void;
+    protected bindTaskRunGeneration(handle: AgentHandle, task?: BoardTask): number;
+    protected getTaskRunGeneration(handle: AgentHandle): number;
+    protected sessionId: string;
+    protected llm: ContentGenerator;
+    protected toolRegistry: ToolRegistry;
+    protected bus: MessageBus;
+    protected emitter: EventEmitter;
+    protected db: DatabaseManager;
+    protected tracker: TokenTracker;
+    protected workspace: string;
+    protected model: string;
+    protected roleRegistry: AgentRoleRegistry;
+    protected workflowManager?: WorkflowManager;
+    protected workflowEngine?: WorkflowEngine;
+    protected scheduledTaskManager?: ScheduledTaskManager;
+    protected agents: Map<string, AgentHandle>;
+    protected agentCounter: number;
+    protected workerRunner: WorkerProcessRunner;
+    protected interactiveStateUnsubscribers: Array<() => void>;
+    /** onConfigReload 退订函数：在 destroy() 时调用以防止监听器泄漏 */
+    private configReloadUnsubscribe;
+    /** TaskBoard 引用，Worker 完成时直接更新任务状态 */
+    protected taskBoard: TaskBoard;
+    /** 兜底 GC 定时器：每 3 分钟扫描并删除超龄的 non-running handle */
+    private staleHandleGcTimer;
+    /** non-running handle 被视为超龄的时间阈值：5 分钟 */
+    private static readonly STALE_HANDLE_TTL_MS;
+    /** 兜底 GC 扫描间隔：3 分钟 */
+    private static readonly STALE_GC_INTERVAL_MS;
+    /** agents Map 池大小上限：超过此值时强制清理最旧的已完成 handle */
+    private static readonly MAX_POOL_SIZE;
+    /** 工作笔记管理器，用于 dispatch 时自动注入前序上下文 */
+    private workNoteManager;
+    private readonly remoteWorkers;
+    private readonly workerLifecycle;
+    private readonly faultRecovery;
+    private readonly slotScheduler;
+    private readonly traceMemory?;
+    private readonly workerBridgeCursors;
+    private readonly autoRetryRecoveries;
+    /** 事件路由层（worker 进程事件 + 交互运行时事件），抽取自原 setup*EventHandlers */
+    protected readonly eventBinder: WorkerEventHandlerBinder;
+    /** 给任意 agent name 加上本会话前缀，用于 MessageBus 寻址 */
+    private sp;
+    /** 本会话 leader 的 bus 名 */
+    private get leaderBusName();
+    protected sendCriticalBusMessageToLeader(from: string, type: 'task_complete' | 'task_failed' | 'worker_recovery', payload: unknown): void;
+    /**
+     * Update the default model used for subsequently spawned Worker/Agent LLM requests.
+     * Running workers keep their current request; this is a hot switch for the next dispatch/respawn.
+     */
+    setModel(modelId: string): void;
+    getModel(): string;
+    private buildWorkerFailureDiagnostics;
+    private clearRecoveryRecordAndNotify;
+    constructor(config: AgentPoolConfig);
+    /**
+     * 1.3: 设置 Worker 事件处理器，将 Worker 事件转发到 Leader
+     *
+     * 实现已下沉到 WorkerEventHandlerBinder（事件集合与原实现完全一致：不丢不增）。
+     * 保留为薄委托，public 接口签名不变。
+     */
+    protected setupWorkerEventHandlers(): void;
+    /**
+     * 构造事件路由层所需的 host 绑定对象。逐字段映射到原方法体内的 `this.X` 引用，
+     * 不改语义、不丢事件。WorkerLifecycle / FaultRecovery 以结构化子集暴露，
+     * 避免改它们在 AgentPoolRuntime 上的可见性。
+     */
+    protected buildEventHandlerHost(): {
+        sessionId: string;
+        agents: Map<string, AgentHandle>;
+        readonly workerRunner: WorkerProcessRunner;
+        emitter: EventEmitter;
+        bus: MessageBus;
+        db: DatabaseManager;
+        tracker: TokenTracker;
+        taskBoard: TaskBoard;
+        interactiveStateUnsubscribers: (() => void)[];
+        sp: (name: string) => string;
+        workerLifecycle: WorkerLifecycle;
+        faultRecovery: FaultRecovery;
+        transitionAgentStatus: (handle: AgentHandle, s: "starting" | "running" | "stopped") => void;
+        maxRecoveryAttempts: number;
+        parseWorkerFailurePayload: typeof parseWorkerFailurePayload;
+        getById: (id: string) => AgentHandle | undefined;
+        getByName: (name: string) => AgentHandle | undefined;
+        getTaskRunGeneration: (handle: AgentHandle) => number;
+        parseWorkerCompletionPayload: (p: unknown) => {
+            result: string;
+            verdict?: "PASS" | "FAIL" | "BLOCKED";
+            stats: {
+                iterations: number;
+                toolCalls: number;
+            };
+            tokenUsage?: {
+                total?: number;
+                prompt?: number;
+                completion?: number;
+            };
+            summary?: string;
+            artifacts?: {
+                files_created?: string[];
+                files_modified?: string[];
+                commands_run?: string[];
+            };
+            verification?: Array<{
+                kind: string;
+                detail: string;
+                passed?: boolean;
+            }>;
+            next_steps?: string[];
+            blocked_by_discovery?: string[];
+            needs_leader_coordination?: boolean;
+            evidence_refs?: string[];
+            contract_compliance?: WorkerContractComplianceProof;
+            toolTrace?: {
+                files_created?: string[];
+                files_modified?: string[];
+                commands_run?: string[];
+            };
+            speculativeWinner?: SpeculativeWinnerEvidence;
+        };
+        buildWorkerFailureDiagnostics: (handle: AgentHandle, d?: WorkerProcessDiagnostics) => import("../core/AgentProtocol.js").WorkerFailureDiagnostics | undefined;
+        clearRecoveryRecordAndNotify: (taskId: string) => void;
+        applyWorkerOutputToBlackboard: (taskId: string, output: unknown) => void;
+        broadcastWorkNoteAwareness: (note: WorkNote, src: string) => number;
+        cleanupWorkerInboxBridge: (handle: AgentHandle) => void;
+        emitInteractiveRuntimeState: (handle: AgentHandle | undefined) => void;
+        emitAgentEvent: <T extends EventName>(handle: AgentHandle, kind: T, extra: Partial<EventMap[T]>) => void;
+        markAgentRecovering: (handle: AgentHandle, faultClass: RecoveryFaultClass, reason: string, diagnostics?: WorkerRecoveryPayload["diagnostics"], llmErrorKind?: LLMErrorKind) => WorkerRecoveryPayload;
+        markAgentFailed: (handle: AgentHandle, error: Error, source?: string) => void;
+        markAgentTerminated: (handle: AgentHandle, reason: string) => void;
+        forceStopAgent: (handle: AgentHandle, exitReason: NonNullable<AgentHandle["exitReason"]>, reason?: string) => void;
+        recordTaskResultPendingAcceptance: (handle: AgentHandle, result: string, completion?: StructuredCompletionPayload) => void;
+        releaseHeavyResources: (handle: AgentHandle) => void;
+        sendCriticalBusMessageToLeader: (from: string, type: "task_complete" | "task_failed" | "worker_recovery", payload: unknown) => void;
+    };
+    static normalizeAgentName(name: string): string;
+    /** Set blackboard callbacks for worker graph access */
+    setBlackboardCallbacks(getSnapshot: () => string, applyOutput: (agentId: string, output: unknown) => void, getGraph?: () => unknown, getActiveTeam?: () => string | null, getContractPack?: () => ContractPack | null): void;
+    private _blackboardGetSnapshot?;
+    private _blackboardApplyOutput?;
+    private _blackboardGetGraph?;
+    private _getActiveTeam?;
+    private _blackboardGetContractPack?;
+    private applyWorkerOutputToBlackboard;
+    /**
+     * 变更影响上下文提供者 —— 由 ChangeImpactResolver 接入。
+     * 给定任务的 working_directory + write_scope → 返回影响摘要字符串（注入 worker 的 task context）。
+     * 返回空字符串则跳过注入。
+     */
+    private _getChangeImpactContext?;
+    /** 设置变更影响分析回调 (由 LeaderAgent 在初始化 ChangeImpactResolver 后调用) */
+    setChangeImpactProvider(provider: (taskId: string, workingDir: string) => string): void;
+    broadcastSystemContext(content: string, excludeAgentName?: string): number;
+    registerRemoteWorker(endpoint: string, capabilities: string[], options?: Partial<Pick<RemoteWorkerDescriptor, 'id' | 'maxConcurrency' | 'region'>>): RemoteWorkerDescriptor;
+    getRemoteWorkerRegistry(): RemoteWorkerRegistry;
+    private isFullBlackboardMode;
+    broadcastBlackboardDelta(delta: BlackboardDelta, excludeAgentName?: string): number;
+    private broadcastWorkNoteAwareness;
+    protected emitInteractiveRuntimeState(handle: AgentHandle | undefined): void;
+    /**
+     * 统一的 agent:* 事件出口。
+     *
+     * 从 handle 自动注入 sessionId / agentId / agentName / taskId，
+     * 调用方只填差异字段，杜绝零散 emit 漏字段（导致 SseBridge 因 sessionId 缺失丢弃事件）。
+     *
+     * 仅服务于带 handle 的事件；agent:spawned / agent:interactive_state 等已有专用方法的不走此出口。
+     */
+    protected emitAgentEvent<T extends EventName>(handle: AgentHandle, kind: T, extra: AgentEventExtra<T>): void;
+    protected markAgentRecovering(handle: AgentHandle, faultClass: RecoveryFaultClass, reason: string, diagnostics?: WorkerRecoveryPayload['diagnostics'], llmErrorKind?: LLMErrorKind): WorkerRecoveryPayload;
+    private maybeAutoRetryRecoveringWorker;
+    private markRecoveryAutoRetryFailed;
+    markAgentRecoveringFromSupervisor(handle: AgentHandle, faultClass: RecoveryFaultClass, reason: string): void;
+    /**
+     * 构造 FaultRecovery 恢复执行路径的宿主上下文：把 AgentPool 自身的字段/方法
+     * 以结构化对象交给子模块。子模块只依赖这个最小面，不反向 import 整个巨类。
+     *
+     * 恢复/终止顺序语义敏感（并发核心路径），这里只做直通委托，不改任何调用顺序。
+     */
+    private buildRecoveryHostContext;
+    /**
+     * 交互运行时事件处理器（agent:progress / tool_output / terminal:* / permission:* / ...）。
+     *
+     * 实现已下沉到 WorkerEventHandlerBinder（事件集合与原实现完全一致：不丢不增）。
+     * 保留为薄委托，public 接口签名不变。
+     */
+    protected setupInteractiveRuntimeEventHandlers(): void;
+    /**
+     * 注册新 Agent
+     *
+     * P0 #3 修复：调度/唤醒/workflow 三路可能同名 register（normalizedName 撞车）。
+     * 旧实现直接 `this.agents.set` 覆盖，前一个 handle 仍在 starting/running，
+     * 但 Map 里已指向新 handle —— 第一份 worker 进程变成了无人持有的"僵尸"，
+     * 后续 worker:complete/exit by workerId 会错改第二个 handle 的状态。
+     *
+     * 新策略：
+     *   - 已存在且非 stopped：拒绝（抛错），由调用方决定是 reuse 还是先 stopAgent。
+     *   - 已存在但 stopped：允许复用 normalizedName（valid transition 已支持 stopped→starting，
+     *     但旧 handle 仍可能被外部代码持有；为安全这里覆盖前先 cleanup bus 注册）。
+     */
+    register(name: string, roleType: string, taskId: string, agentId?: string): AgentHandle;
+    /**
+     * Prepare the canonical worker runtime for a task without constructing an
+     * in-process agent instance.
+     */
+    prepareWorkerRuntime(handle: AgentHandle, _task: BoardTask): void;
+    private loadInheritedWorkerHistory;
+    private buildWorkerPayload;
+    /**
+     * 追问机制：重新 spawn 一个已完成/已清理的 Agent，加载完整对话历史
+     *
+     * 限速 (2026-05-28)：
+     * - 60s 内 respawn 次数 ≥ MAX_RESPAWN_PER_WINDOW → 拒绝。
+     * - 连续 spawn 失败次数 ≥ MAX_CONSECUTIVE_RESPAWN_FAILURES → 拒绝。
+     * 防止 Leader 反复 send_message_to_agent / autoRespawn 把机器跑爆、provider 配额耗尽。
+     */
+    respawnAgent(handle: AgentHandle, task: BoardTask, leaderMessage?: string, options?: AgentRespawnOptions): Promise<string>;
+    /**
+     * 1.2: 运行 Agent - 使用 WorkerProcessRunner 启动子进程
+     */
+    runAgentWrapper(handle: AgentHandle, task: BoardTask, _isResume?: boolean, _recoveredState?: {
+        iteration?: number;
+        toolCallCount?: number;
+    }): Promise<string>;
+    private runAgentWrapperDispatched;
+    /**
+     * 构造 AgentDispatchContext：把 protected/private 成员收口为结构化上下文对象，
+     * 供下沉到 SlotScheduler.dispatchAgent 的执行体使用，避免其直接依赖整个 pool 句柄。
+     */
+    private asDispatchContext;
+    protected assertExternalCompletionAccepted(task: BoardTask, role: AgentRole, completionReport: ExternalCompletionReport, modelId: string): Promise<void>;
+    protected runExternalAgent(handle: AgentHandle, role: AgentRole, task: BoardTask): Promise<string>;
+    /**
+     * 构造 ExternalAgentRunContext：把 protected/private 成员收口为结构化上下文对象，
+     * 供下沉到 ExternalAgentRunner.runExternalAgent 的执行体使用。
+     */
+    private asExternalRunContext;
+    private collectCompletionFiles;
+    private collectCompletionCommands;
+    private recordWorkerExecutionTrace;
+    protected recordTaskResultPendingAcceptance(handle: AgentHandle, result: string, completion?: StructuredCompletionPayload): void;
+    protected markAgentFailed(handle: AgentHandle, error: Error, source?: string): void;
+    protected markAgentTerminated(handle: AgentHandle, reason: string): void;
+    /**
+     * 构造 WorkerLifecycle 终止路径的宿主上下文：把 AgentPool 自身的字段/方法
+     * 以结构化对象交给子模块。子模块只依赖这个最小面，不反向 import 整个巨类。
+     *
+     * 终止顺序语义敏感（并发核心路径），这里只做直通委托，不改任何调用顺序。
+     */
+    private buildLifecycleHostContext;
+    /** 获取运行中的 Agent */
+    getRunning(): AgentHandle[];
+    /** TeamCommunicationService 用：判断目标 agent 当前是否可接收 bus 推送。 */
+    isAgentRunning(agentName: string): boolean;
+    /**
+     * TeamCommunicationService 用：目标 agent 已离线、但 team 消息已落 mailbox 时，
+     * 尝试把它复活去读邮箱补漏（worker 启动会先 team_inbox）。
+     *
+     * - 仅对「曾被派发过」的 agent 生效：从内存 handle 或 DB agent_state 找回
+     *   agentId / roleType / taskId；从未派发的成员（没有任何运行记录）直接放弃。
+     * - 已在运行 / starting：无需复活。
+     * - respawnAgent 自带 60s 内 3 次的限速门，防止 team 消息把同一 agent 反复拉起。
+     * fire-and-forget：不阻塞 routeDirect；复活后的投递由 mailbox 兜底。
+     */
+    reviveAgentForTeamMessage(agentName: string): void;
+    /**
+     * 按名字找回该 worker 上一次运行使用的 agentId。
+     *
+     * Why：对话历史表 agent_conversation 以 agentId 为主键存取，而"复用同名 worker
+     * 跑下一个任务"时，register() 默认会铸造一个全新 agentId → 新 agentId 查不到任何历史，
+     * 导致同名复用变成"白复用"（上下文没继承）。dispatch 路径调用本方法拿到旧 agentId 传给
+     * register()，让新 worker 与历史对话接上。
+     *
+     * 查找顺序：
+     *   1. 内存里同名且已 stopped 的 handle（5min 内未被 cleanup）→ 直接复用其 agentId。
+     *   2. fallback：DB agent_state 里按名字过滤、取 timestamp 最新一条的 agent_id。
+     * 找不到（从未派发过该名字）→ undefined，register() 会照常铸造新 agentId（全新 worker）。
+     *
+     * 注意：只在"可复用"（stopped / 不存在）时返回；同名仍在运行的情况由 register() 抛错拦截，
+     * 这里返回 undefined 让调用链走正常的拒绝路径。
+     */
+    resolvePriorAgentId(name: string): string | undefined;
+    /**
+     * 获取所有 Agent
+     */
+    getAll(): AgentHandle[];
+    /**
+     * 根据名称获取 Agent
+     */
+    getByName(name: string): AgentHandle | undefined;
+    /**
+     * 根据 ID 获取 Agent
+     */
+    getById(agentId: string): AgentHandle | undefined;
+    /**
+     * 1.2/1.3: 停止指定 Agent（通过 WorkerProcessRunner 终止子进程）
+     */
+    stopAgent(name: string): void;
+    completeAgent(name: string, reason?: string): AgentHandle | undefined;
+    /**
+     * 暂停指定 Agent（保留进度，不杀进程）
+     * 注意：新状态模型中不再有 paused 状态，暂停操作保持 running 状态
+     */
+    pauseAgent(name: string): void;
+    /**
+     * 恢复暂停的 Agent
+     */
+    resumeAgent(name: string): void;
+    /**
+     * 干预指定 Agent（停下来，注入指令，等待用户确认）
+     * 注意：新状态模型中不再有 stalled 状态，干预操作保持 running 状态
+     */
+    interveneAgent(name: string, instruction: string): void;
+    /**
+     * 确认干预，让 Agent 继续执行
+     */
+    confirmIntervention(name: string): void;
+    /**
+     * 完全终止指定 Agent（不可恢复，丢弃进度）
+     */
+    terminateAgent(name: string, reason?: string): void;
+    /**
+     * 1.2/1.3: 停止所有 Agent
+     */
+    stopAll(): void;
+    /**
+     * 获取池状态
+     *
+     * stopped 只是 AgentPool 的内核终态容器，completed/failed/interrupted 必须结合 exitReason 归一化。
+     * 这里使用 normalizeAgentRuntimeStatus，避免 terminated/timeout/crashed 被误算成 completed。
+     */
+    getStatus(): {
+        total: number;
+        starting: number;
+        running: number;
+        stopped: number;
+        completed: number;
+        failed: number;
+        timeout: number;
+        crashed: number;
+        terminated: number;
+    };
+    destroy(): void;
+    /**
+     * 立即释放已终止 handle 上的重型资源引用（interactiveRuntime, workerHandle 等），
+     * 保留轻量元数据（agentId, name, taskId, status, exitReason, timestamps）供诊断查询。
+     * 仅对非 running/starting 状态的 handle 生效，避免意外清理活跃 agent。
+     */
+    /**
+     * 释放仍 claim 指定 task 的 active handle：把它强制转入终态（非 active）并回收重型资源。
+     *
+     * 用于崩溃恢复失败路径——当 TaskBoard 把任务解绑（prepareTaskForRedispatch 清空
+     * assigned_agent）时，pool 侧可能还残留一个 active-looking handle 指着同一 task
+     * （respawn 设回的 running/starting、recovering，或 stopped-no-exitReason 被
+     * normalizeAgentRuntimeStatus 误判成 running）。不释放就会与 board 的「无主」状态
+     * desync：dispatch_agent 读 pool 判「已在执行」、force_complete 读 board 判「未分配」，
+     * 任务进死区无法逃脱。单独调 releaseHeavyResources 无效——它在 active handle 上早返回，
+     * 这里先 forceStopAgent 转非 active 再回收。
+     *
+     * 不改 handle.taskId（其它路径读它做日志/恢复线归属），非 active 已足以让 dispatch 放行。
+     */
+    private releaseHandleForTask;
+    private releaseHeavyResources;
+    /**
+     * 当池大小超过 MAX_POOL_SIZE 时，强制清理最旧的已完成/失败 handle。
+     * 只在 register() 成功后调用，确保新增 handle 不会触发无限增长。
+     */
+    private enforcePoolSizeLimit;
+    /**
+     * 延迟清理已完成的 agent handle，防止长时间运行后 Map 无限增长。
+     * 保留2分钟供诊断查询，之后移除。
+     */
+    private scheduleHandleCleanup;
+    /**
+     * 兜底 GC：扫描所有 non-running handle，删除超过 STALE_HANDLE_TTL_MS 未活动的。
+     * 覆盖 scheduleHandleCleanup 未被调用的异常路径（forceComplete、进程崩溃等）。
+     */
+    private collectStaleHandles;
+    private workerBridgeCursorKey;
+    private workerBridgeCursorStateKey;
+    private readWorkerBridgeCursor;
+    private writeWorkerBridgeCursor;
+    protected installWorkerInboxBridge(handle: AgentHandle): void;
+    protected cleanupWorkerInboxBridge(handle: AgentHandle): void;
+    /** 实例桥接：把静态 transitionAgentStatus 暴露为结构化上下文成员，供下沉执行体调用。 */
+    protected transitionAgentStatusInstance(handle: AgentHandle, newStatus: AgentStatus): void;
+    /** 实例桥接：把模块私有 parseWorkerFailurePayload 暴露为结构化上下文成员。 */
+    protected parseWorkerFailurePayloadInstance(error: unknown): {
+        error: Error;
+        recoverable: boolean;
+        terminalKind?: AgentExecutionResult['metadata']['terminalKind'];
+        faultClass?: RecoveryFaultClass;
+        llmErrorKind?: LLMErrorKind;
+        reason: string;
+        payload?: WorkerFailurePayload;
+    };
+    protected parseWorkerCompletionPayload(payload: unknown): {
+        result: string;
+        verdict?: 'PASS' | 'FAIL' | 'BLOCKED';
+        stats: {
+            iterations: number;
+            toolCalls: number;
+        };
+        tokenUsage?: {
+            total?: number;
+            prompt?: number;
+            completion?: number;
+        };
+        summary?: string;
+        artifacts?: {
+            files_created?: string[];
+            files_modified?: string[];
+            commands_run?: string[];
+        };
+        verification?: Array<{
+            kind: string;
+            detail: string;
+            passed?: boolean;
+        }>;
+        next_steps?: string[];
+        blocked_by_discovery?: string[];
+        needs_leader_coordination?: boolean;
+        evidence_refs?: string[];
+        contract_compliance?: WorkerContractComplianceProof;
+        toolTrace?: {
+            files_created?: string[];
+            files_modified?: string[];
+            commands_run?: string[];
+        };
+        speculativeWinner?: SpeculativeWinnerEvidence;
+    };
+    /**
+     * 智能 watchdog 检查：基于 per-agent 进展信号判断是否停滞
+     * 返回需要干预的 agent 列表及原因
+     */
+    getStagnantAgents(opts?: {
+        idleThresholdMs?: number;
+        toolStalledThresholdMs?: number;
+    }): Array<{
+        handle: AgentHandle;
+        reason: 'idle_no_progress' | 'tool_stalled' | 'heartbeat_lost';
+        elapsedMs: number;
+    }>;
+}
+export default AgentPool;
+//# sourceMappingURL=AgentPoolRuntime.d.ts.map