@lingxiao-office/sdk 1.0.0

package/dist/agents/LeaderAgent.d.ts

@@ -0,0 +1,752 @@
+/**
+ * LeaderAgent - 领导者 Agent
+ * 负责任务分解、协调和监督多个子 Agent
+ *
+ * 参考 Python 版本的 LeaderAgent 实现
+ */
+import { type ChatMessage, type ChatResponse, type MessageContent, type ThinkingBlock, type ToolCall, type ToolDefinition } from '../llm/types.js';
+import type { ContentGenerator } from '../llm/ContentGenerator.js';
+import type { RecoveredTaskInfo } from '../contracts/types/Agent.js';
+import type { ToolRegistry } from '../tools/Registry.js';
+import { MessageBus, type BusMessage } from '../core/MessageBus.js';
+import type { EventEmitter } from '../core/EventEmitter.js';
+import { DatabaseManager } from '../core/Database.js';
+import { TaskBoard, type Task } from '../core/TaskBoard.js';
+import type { AgentPool, AgentHandle } from './AgentPoolRuntime.js';
+import type { TokenTracker } from './BaseAgentRuntime.js';
+import { WorkNoteManager } from '../core/WorkNoteManager.js';
+import { AgentRoleRegistry } from './RoleRegistry.js';
+import { ContextManager } from '../core/ContextManager.js';
+import { LeaderToolsExecutor } from './LeaderTools.js';
+import { LeaderDirectToolsExecutor } from './LeaderDirectTools.js';
+import { LeaderContextBuilder, type LeaderContextBuilderDeps } from './leader/LeaderContextBuilder.js';
+import { type CompletionSignal } from './leader/p0Message.js';
+import { type ResolvedRoleCapability } from './RoleCapabilityModel.js';
+import { TeamSynchronizer } from './TeamSynchronizer.js';
+import { type PermissionRequestPayload, type PermissionUpdate, type ToolPermissionContext } from '../core/PermissionSystem.js';
+import type { PermissionUpdateDestination } from '../core/PermissionStore.js';
+import type { LeaderInteractionSnapshot } from '../core/SessionRuntimeState.js';
+import type { EternalRuntimeSnapshot } from '../core/EternalLoop.js';
+import type { ContextRuntimeState } from '../core/ContextRuntimeState.js';
+import { type WorkerArtifactTrace, type WorkerContractComplianceProof, type WorkerRecoveryPayload, type WorkerVerificationItem } from '../core/AgentProtocol.js';
+import { type LlmRoundHooks } from './runtime/LlmRoundExecutor.js';
+import { ToolScheduler } from './runtime/ToolScheduler.js';
+import type { ToolResultContent } from './runtime/ToolResponseProcessor.js';
+import type { CapabilityIntentProfile } from '../contracts/types/Autonomy.js';
+import { type LeaderSupervisionAgentSnapshot, type LeaderSupervisionConfig, type LeaderSupervisionEvaluation, type LeaderSupervisionState } from './LeaderSupervisionPolicy.js';
+import { AgentHealthMonitor } from '../core/AgentHealthMonitor.js';
+import { LeaderPermissionManager } from './LeaderPermissionManager.js';
+import { LeaderProgressInvariant } from './LeaderProgressInvariant.js';
+import { LeaderWorkOrchestrator } from './LeaderWorkOrchestrator.js';
+import { LeaderSupervisionCoordinator } from './LeaderSupervisionCoordinator.js';
+import { LeaderExecutionController, type LeaderExecutionMode, type RouteDecision } from './LeaderExecutionController.js';
+import { LeaderThinkingEngine } from './leader/LeaderThinkingLoop.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 { GraphAnalysis } from '../core/blackboard/types.js';
+import { LeaderBlackboard } from './LeaderBlackboard.js';
+import { UnifiedScheduler, type DispatchOptions as SchedDispatchOptions } from './UnifiedScheduler.js';
+import { DispatchDecisionCoordinator } from './DispatchDecisionCoordinator.js';
+import { SharedLedger } from '../core/SharedLedger.js';
+import { buildExpansion, renderExpansionHint } from '../core/SpecFirstPipeline.js';
+import { ContractHotSync } from '../core/ContractHotSync.js';
+import { IntegrationVerifyInjector } from '../core/IntegrationVerifyInjector.js';
+import { DeterministicAcceptance } from '../core/DeterministicAcceptance.js';
+import { RepairStrategyEngine } from '../core/RepairStrategyEngine.js';
+import { OrchestrationRuntime } from './OrchestrationRuntime.js';
+export declare function formatWorkerRecoveryPayload(payload: WorkerRecoveryPayload): string;
+/**
+ * LeaderAgent 配置
+ */
+export interface LeaderConfig {
+    sessionId: string;
+    llm: ContentGenerator;
+    toolRegistry: ToolRegistry;
+    board: TaskBoard;
+    bus: MessageBus;
+    pool: AgentPool;
+    tracker: TokenTracker;
+    workspace: string;
+    db: DatabaseManager;
+    emitter: EventEmitter;
+    model: string;
+    customPrompt?: string;
+    defaultSkillsContent?: string;
+    workflowManager?: WorkflowManager;
+    workflowEngine?: WorkflowEngine;
+    scheduledTaskManager?: ScheduledTaskManager;
+}
+export type { RecoveredTaskInfo } from '../contracts/types/Agent.js';
+/**
+ * LeaderAgent - 领导者 Agent
+ * 负责任务分解与协调，管理多个子 Agent 的执行
+ */
+export declare class LeaderAgent {
+    /** Max automatic recovery attempts for stuck open work */
+    static readonly OPEN_WORK_RECOVERY_MAX_ATTEMPTS = 3;
+    /** Tool calls count threshold for diagnostic logging */
+    static readonly TOOL_CALLS_DIAGNOSTIC_THRESHOLD = 5;
+    sessionId: string;
+    llm: ContentGenerator;
+    board: TaskBoard;
+    bus: MessageBus;
+    pool: AgentPool;
+    tracker: TokenTracker;
+    workspace: string;
+    db: DatabaseManager;
+    emitter: EventEmitter;
+    model: string;
+    name: string;
+    /** 带 sessionId 前缀的 bus 收件人名 */
+    get busName(): string;
+    /** 本会话 leader 的 bus 收件人名（等同 busName） */
+    get leaderBusName(): string;
+    /** 给任意 agent name 加上本会话前缀 */
+    /** 用户中断控制器，abort 时会 kill 正在执行的 shell 命令 */
+    private userInterruptController;
+    sessionPrefix(name: string): string;
+    protected customPrompt?: string;
+    protected defaultSkillsContent: string;
+    protected running: boolean;
+    /**
+     * 当前 run() 的 in-flight Promise（P0 #2 单飞锁）。
+     * - stop() 后 finished=true，run() 仍在 await LLM/工具调用，外部紧接着 sendUserInput 可能重启 run()。
+     *   此字段保证同一时刻只有一个 run() 在跑：第二次进入直接返回当前 Promise，等旧 run() finally 设回 null 后再启动。
+     * - 用 protected 是因为运行时扩展共享主循环。
+     */
+    protected currentRunPromise: Promise<string> | null;
+    /** Restart requested while a stopped run is still unwinding. */
+    protected pendingRunRestartPromise: Promise<string> | null;
+    protected rawXmlRetryCount: number;
+    protected emptyResponseRetryCount: number;
+    protected conversation: ChatMessage[];
+    protected pendingUserInput: MessageContent;
+    protected waitingForUser: boolean;
+    protected controlMode: 'manual' | 'eternal';
+    protected currentLlmAbortController: AbortController | null;
+    protected finished: boolean;
+    private userInterruptPending;
+    /** 用户消息队列：Leader 忙碌时到来的用户消息按序存放，空闲后依次处理 */
+    protected userMessageQueue: Array<BusMessage>;
+    /** Leader 是否正在执行 leaderThinkAndAct（即正在忙碌） */
+    protected isBusy: boolean;
+    /** Public getter for isBusy — allows SessionManager to check Leader state */
+    get busy(): boolean;
+    protected pendingReview: boolean;
+    /**
+     * 原始用户任务文本(防漂移锚点)。新会话首条 user prompt 时捕获,
+     * 供每轮 getDynamicContext() 置顶「当前使命」锚点段(见 LeaderContextBuilder)。
+     */
+    protected originalGoal: string | null;
+    /** 防漂移:对外暴露原始用户任务文本,供 create_task 注入每个子任务的 context。 */
+    getOriginalGoal(): string | null;
+    /**
+     * Leader 上下文构建子模块(L1/B4 抽出)。fingerprint 状态已迁入 builder。
+     */
+    private _contextBuilder;
+    protected get contextBuilder(): LeaderContextBuilder;
+    protected emitRoundComplete(trigger: string): void;
+    protected planApproved: boolean;
+    /** 非打断式用户指导消息，在下轮 LLM 调用时作为 system 消息注入 */
+    protected nudgeMessage: string | null;
+    protected lastScratchpadReviewDigest: string | null;
+    protected lastRuntimeContextFingerprint: string | null;
+    protected lastContextMemoryFingerprint: string | null;
+    protected lastProgressReportDigest: string | null;
+    protected turnCount: number;
+    protected lastOpenWorkRecoveryFingerprint: string | null;
+    protected openWorkRecoveryAttempts: number;
+    /** Active team name for this session (set when Leader calls team_manage(action="create")). */
+    protected activeTeamName: string | null;
+    /** Agent 完成报告队列：P0 到达时立即保存报告正文，直到注入 Leader conversation 后才清除 */
+    protected pendingAgentCompletionSignals: CompletionSignal[];
+    /** P0 消息处理下沉载体 — handleLeaderP0Message 改为薄委托 */
+    private _leaderP0Handler;
+    protected workerResultQueue: Promise<void>;
+    protected lastOpenWorkRecoveryAtMs: number;
+    /** LLM 连续错误重试计数 */
+    protected llmErrorRetryCount: number;
+    protected readonly LLM_MAX_ERROR_RETRIES: number;
+    /**
+     * 进度哈希检测 + Watchdog — 委托给 LeaderProgressInvariant
+     */
+    protected progressInvariant: LeaderProgressInvariant;
+    protected workOrchestrator: LeaderWorkOrchestrator;
+    protected workNoteManager: WorkNoteManager;
+    getWorkNoteManager(): WorkNoteManager;
+    protected toolsExecutor: LeaderToolsExecutor;
+    protected directToolsExecutor: LeaderDirectToolsExecutor;
+    protected roleRegistry: AgentRoleRegistry;
+    protected contextManager: ContextManager;
+    protected orchestrationRuntime: OrchestrationRuntime;
+    protected toolRegistry: ToolRegistry;
+    protected executionMode: LeaderExecutionMode;
+    protected executionReason: string;
+    protected permManager: LeaderPermissionManager;
+    protected teamSynchronizer: TeamSynchronizer | null;
+    protected healthMonitor: AgentHealthMonitor;
+    protected supervCoordinator: LeaderSupervisionCoordinator;
+    protected executionController: LeaderExecutionController;
+    protected fileChangesApi: InstanceType<typeof import('../web-server/FileChangesApi.js').FileChangesApi> | null;
+    protected thinkingEngine: LeaderThinkingEngine;
+    protected workflowManager?: WorkflowManager;
+    protected workflowEngine?: WorkflowEngine;
+    protected scheduledTaskManager?: ScheduledTaskManager;
+    protected readonly supervisionConfig: LeaderSupervisionConfig;
+    protected supervisionState: LeaderSupervisionState;
+    /** 黑板集成模块 — 持有 blackboardGraph / graphBridge / dispatcherEngine */
+    protected leaderBlackboard: LeaderBlackboard | null; /** 共享账本 — 替代 BlackboardGraph 的轻量共享状态 */
+    protected readonly sharedLedger: SharedLedger;
+    protected contractHotSync: ContractHotSync | null;
+    protected readonly integrationInjector: IntegrationVerifyInjector;
+    protected readonly deterministicAcceptance: DeterministicAcceptance;
+    protected readonly repairEngine: RepairStrategyEngine;
+    /** 统一调度器 — 全局唯一 worker dispatch 入口 */
+    protected scheduler: UnifiedScheduler | null;
+    getScheduler(): UnifiedScheduler | null;
+    protected dispatchDecisionCoordinator: DispatchDecisionCoordinator | null;
+    /** requestLeaderDispatchDecision 去重：避免事件驱动 + 主循环兜底重复注入同一批提示 */
+    private lastLeaderDecisionSig;
+    /**
+     * 构造器级（实例级）事件退订函数集合：attachTaskLifecycleToTeamMailbox 注册的
+     * task:failed / task:cancelled 监听器存放于此。这些监听器在构造器注册一次、
+     * 不随 run() 重入而重注册，因此必须在 dispose()（实例终结）时退订，
+     * 而非 run() 的 finally（否则同实例重跑 run() 后团队通知会永久失效）。
+     */
+    private _taskTeamUnsubscribers;
+    /** onConfigReload 退订函数：在 dispose() 时调用以防止监听器泄漏 */
+    private _configReloadUnsubscribe;
+    /**
+     * Leader 已"看过并决定等待"的 dispatchable 任务集合指纹。
+     * 非 eternal 模式下，Leader 思考完一轮仍未派发某 dispatchable 任务（如等待上游、
+     * 或有意先观察）会 latch waitingForUser。若主循环每轮都因"还有 dispatchable"把它
+     * 重新唤醒 think，就成了用户看到的"没开 eternal 却无限请求 LLM"。
+     * 用指纹记住"这批 dispatchable 我已经决定等了"，集合不变就不再重复唤醒；
+     * 集合变化（新任务解锁 / 派发后减少）才重新驱动一次。
+     */
+    private waitedDispatchableSig;
+    /** 公开访问器 — SessionRoutes 等外部消费者用来读取黑板分析 */
+    getLeaderBlackboard(): LeaderBlackboard | null;
+    getSpecPipeline(): {
+        buildExpansion: typeof buildExpansion;
+        renderExpansionHint: typeof renderExpansionHint;
+    };
+    getContractHotSync(): ContractHotSync | null;
+    getIntegrationInjector(): IntegrationVerifyInjector;
+    getDeterministicAcceptance(): DeterministicAcceptance;
+    getRepairEngine(): RepairStrategyEngine;
+    getSharedLedger(): SharedLedger;
+    /**
+     * 获取黑板图分析结果（供 LeaderThinkingEngine 注入上下文）
+     * 黑板模式未启用时返回 null
+     */
+    getBlackboardAnalysis(): GraphAnalysis | null;
+    /** 黑板模式是否启用 */
+    isBlackboardEnabled(): boolean;
+    protected resolveTaskContractReadiness(task: Task): {
+        ready: boolean;
+        reasons?: string[];
+    };
+    private refreshContractBoundTasks;
+    protected buildInitialUserContent(content: MessageContent): MessageContent;
+    /**
+     * 订阅 task:failed/cancelled，向 active team 中所有 *running* worker 直推系统通知。
+     *
+     * 设计取舍（2026-05-27 重构）：
+     *   - 直接走 MessageBus，不再写 TeamMailbox。系统通知是"实时事件"，
+     *     塞进 mailbox 会污染 inbox_check 的"补漏"语义，让任何 worker 重启
+     *     后都看到一堆别的任务的失败 fanout，毫无相关性。
+     *   - completed 路径完全静默：worker 自己的 task_complete + work note 已经覆盖。
+     *   - failed/cancelled 必通知：用 user_intervention 类型，让 worker 立刻注入到上下文。
+     *   - 没有 active team / 没有 running worker → 默默跳过。
+     */
+    private attachTaskLifecycleToTeamMailbox;
+    /**
+     * 任务终态时自动回收 task 级 worktree。
+     *
+     * - completed: 尝试 ff-only merge 到 base branch，成功则 remove worktree + 删分支；
+     *   merge 失败（非 ff 或 dirty）只记日志，保留 worktree 供 Leader 手动处理。
+     * - failed / cancelled: force remove worktree + 删分支（放弃工作）。
+     *
+     * 所有操作 try-catch 包裹，失败只记日志，不阻塞任务生命周期。
+     */
+    private attachWorktreeCleanup;
+    constructor(config: LeaderConfig);
+    private ensureFullBlackboardInitialized;
+    /**
+     * 把需要显式派发决策的任务交回 Leader：注入 system 提示并触发下一轮思考。
+     * 这是重构前 LeaderAgent 主循环「已解锁可调度」提示路径的复用入口。
+     */
+    protected requestLeaderDispatchDecision(tasks: Task[]): void;
+    /**
+     * 调度器派发 hook — 把 TaskBoard task 物化为运行中的 worker。
+     *
+     * 调用约定：
+     * - scheduler 已经在 budget / 单调度入口语义上做完检查；这里只负责把 task 转成 worker。
+     * - 失败返回 false，scheduler 会回滚 budget；不抛错以避免 tick 循环失败。
+     */
+    protected runScheduledDispatch(task: Task, opts?: SchedDispatchOptions): Promise<boolean>;
+    protected toLeaderSupervisionAgents(handles: AgentHandle[]): LeaderSupervisionAgentSnapshot[];
+    protected getLeaderSupervisionEvaluation(running: AgentHandle[]): LeaderSupervisionEvaluation;
+    protected getLeaderSupervisionWaitTimeoutMs(running: AgentHandle[]): number;
+    protected _unsubscribeAgentActivityEvents(): void;
+    protected markLeaderSupervisionProgress(progressAtMs?: number): void;
+    protected surfaceIdleWarnings(idleAgents: LeaderSupervisionAgentSnapshot[], nowMs?: number): void;
+    getPermissionContext(): ToolPermissionContext;
+    protected loadPermissionContextFromState(): void;
+    applyPermissionUpdates(updates: PermissionUpdate[], destination?: PermissionUpdateDestination): ToolPermissionContext;
+    protected requestPermissionUpdate(payload: PermissionRequestPayload): string;
+    getControlMode(): 'manual' | 'eternal';
+    isEternalMode(): boolean;
+    setControlMode(mode: 'manual' | 'eternal'): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    protected resolvePendingPermissionFromUserInput(content: string): 'resolved' | 'pending' | 'none';
+    /**
+     * 从 Web UI 直接解决权限请求（绕过文本输入解析）
+     * 由 AcpHandler 调用，当用户在 Web UI 点击批准/拒绝时触发
+     */
+    resolvePermissionFromWebUI(requestId: string, decision: 'approved' | 'rejected' | 'allowAll'): void;
+    protected getActiveToolDefinitions(): ToolDefinition[];
+    isToolUseSuppressedForCurrentTurn(): boolean;
+    protected setExecutionRoute(decision: RouteDecision): void;
+    protected chooseExecutionRoute(intentProfile?: CapabilityIntentProfile | null): RouteDecision;
+    private beginUserTurn;
+    setDelegateMode(reason: string): void;
+    /** Active team for this session (null when no team has been created yet). */
+    getActiveTeam(): string | null;
+    /**
+     * Set / clear the active team name for this session and persist to session_state.
+     * dispatch_agent uses this with the explicit TeamMemberRegistry roster.
+     */
+    setActiveTeam(teamName: string | null): void;
+    protected acceptWorkerTaskResult(input: {
+        taskId: string;
+        taskRunGeneration?: number;
+        status: 'terminal';
+        exitReason: 'completed' | 'failed';
+        result: string;
+        agentName?: string;
+        summary?: string;
+        verdict?: 'PASS' | 'FAIL' | 'BLOCKED';
+        artifacts?: WorkerArtifactTrace;
+        verification?: WorkerVerificationItem[];
+        next_steps?: string[];
+        blocked_by_discovery?: string[];
+        needs_leader_coordination?: boolean;
+        evidence_refs?: string[];
+        contract_compliance?: WorkerContractComplianceProof;
+        toolTrace?: WorkerArtifactTrace;
+    }): Promise<void>;
+    protected processWorkerTaskResult(input: {
+        taskId: string;
+        taskRunGeneration?: number;
+        status: 'terminal';
+        exitReason: 'completed' | 'failed';
+        result: string;
+        agentName?: string;
+        summary?: string;
+        verdict?: 'PASS' | 'FAIL' | 'BLOCKED';
+        artifacts?: WorkerArtifactTrace;
+        verification?: WorkerVerificationItem[];
+        next_steps?: string[];
+        blocked_by_discovery?: string[];
+        needs_leader_coordination?: boolean;
+        evidence_refs?: string[];
+        contract_compliance?: WorkerContractComplianceProof;
+        toolTrace?: WorkerArtifactTrace;
+    }): Promise<void>;
+    /**
+     * Attribute a task's terminal outcome to the agent that ran it (N5-A task_outcome).
+     * Recorded at the true terminal points (completeTask / failTask), not at receipt entry,
+     * so an orchestration-rejected 'completed' that gets redispatched does NOT inflate the
+     * success count. Best-effort: never blocks receipt handling. The ref matches the
+     * agent_spawned埋点 (agents/<name>) so usage + outcome correlate per agent.
+     */
+    private recordAgentOutcome;
+    protected captureBughuntWorkerEvidence(input: {
+        taskId: string;
+        status: 'terminal';
+        exitReason: 'completed' | 'failed';
+        result: string;
+        agentName?: string;
+    }): void;
+    protected consumePendingAgentCompletionsIntoConversation(): Promise<boolean>;
+    /**
+     * 任务完成时落盘 Implementation 报告，便于 Leader / 下游 agent 通过
+     * session_artifacts 工具读取真实交付内容（结果摘要 + scratchpad 尾巴）。
+     */
+    protected persistImplementationArtifact(input: {
+        taskId: string;
+        agentName?: string;
+        result: string;
+    }): void;
+    /**
+     * LeaderContextBuilder 依赖句柄:经 getter 闭包捕获运行期才初始化的实例字段,
+     * 避免在构造期(字段尚未赋值)即解析。fingerprint 状态与上下文装配逻辑均下沉至 builder。
+     */
+    protected buildContextBuilderDeps(): LeaderContextBuilderDeps;
+    protected buildRuntimeStateSection(): string;
+    protected buildLeaderLiveRuntimeAwareness(): string;
+    protected appendRuntimeContextManifestIfChanged(): boolean;
+    protected appendContextMemoryIfChanged(): Promise<boolean>;
+    protected hasNonTerminalTasks(): boolean;
+    protected hasExplicitUserGate(): boolean;
+    protected maybeDriveOpenWork(): Promise<boolean>;
+    protected reconcileRecoveringTasks(): boolean;
+    protected getRecoveryStatusSummary(): {
+        total: number;
+        blocked: number;
+        statusText?: string;
+    };
+    protected maybeFinalizeCompletedSession(): Promise<boolean>;
+    protected maybeContinueFromStopHook(final: string): Promise<{
+        shouldContinue: boolean;
+        feedback?: string;
+        signal?: {
+            source: string;
+            detail?: string;
+        };
+    }>;
+    resolveRoleCapability(input: {
+        roleName: string;
+        baseRoleName?: string;
+        roleDescription: string;
+        systemPrompt: string;
+        tools: string[];
+        requestedSkillNames?: string[];
+    }): ResolvedRoleCapability;
+    selectSkillsForRole(input: {
+        roleName: string;
+        baseRoleName?: string;
+        roleDescription: string;
+        systemPrompt: string;
+        tools: string[];
+        requestedSkillNames?: string[];
+    }): string[];
+    /**
+     * 注册系统预置角色
+     */
+    protected registerBuiltinRoles(): void;
+    /**
+     * 热加载：重新计算 settings.json 中 `roles.basic_tools_enabled` / `roles.overrides`
+     * 对内置角色 tools 的影响，覆写 RoleRegistry 里 createdBy='system' 的条目。
+     *
+     * 不动自定义角色（createdBy='llm'/'user'）。已派出的 worker 仍持有旧 tools 快照，
+     * 新 dispatch 的 worker 通过 RoleRegistry.get(name).tools 自动取到新值。
+     */
+    reloadBuiltinRoles(): void;
+    protected registerCustomAgentRoles(): void;
+    /**
+     * 添加消息到对话历史，带 Ring Buffer 保护
+     */
+    addMessage(msg: ChatMessage): void;
+    /**
+     * 获取系统提示（稳定核心 — 可被 Anthropic cache 缓存）
+     */
+    protected getSystemPrompt(): string;
+    /**
+     * Keep the primary Leader system prompt aligned with runtime mode changes.
+     *
+     * Existing sessions may switch Solo/Team/Workflow after the first system
+     * message has already been persisted. The runtime LLM input should reflect
+     * the current mode immediately, while the historical conversation table
+     * remains append-only.
+     */
+    private hashContextContent;
+    protected syncSystemPromptForCurrentMode(): void;
+    /**
+     * Leader 侧状态镜像类 system 槽位（每轮刷新、最新值即权威）。
+     * upsertRuntimeSystemSlot / collapseLeaderSystemSlots 据此做单槽 in-place 更新，
+     * 治本「每轮 append manifest/黑板分析堆积占满上下文」。与 mode hint 同契约：只改内存
+     * 运行时视图，DB 保持 append-only（manifest 是可重算状态镜像，崩溃/审计无损）。
+     */
+    private static readonly LEADER_SYSTEM_SLOTS;
+    /**
+     * 单槽 in-place system 注入（状态镜像类）。命中同槽覆盖内容 + collapse 残留，无匹配 append。
+     * 只改 this.conversation 内存视图，不落库（同 pruneStaleModeHints / syncSystemPromptForCurrentMode 契约）。
+     */
+    private upsertRuntimeSystemSlot;
+    /**
+     * 收敛 conversation 中 append-only 累积的所有状态镜像槽位（每个槽只留最后一条）。
+     * resume 从 DB 重建带回的历史残留在此一次性收敛（治本 R1）。
+     */
+    private collapseLeaderSystemSlots;
+    /**
+     * 模式切换（solo↔team / execution route）后立即对齐运行时 Leader 上下文。
+     *
+     * 由 SessionManagerRuntime.setCollaborationMode / setExecutionRoutePreference 在写 DB 后调用，
+     * 覆盖 Web/CLI/TUI 全部切换入口——切换不再「等下一条用户消息触发 think 才生效」。
+     *
+     * 纯同步、不触发 think（避免空转 ping LLM，见 leader-keeps-pinging-llm 教训）：
+     *  - syncSystemPromptForCurrentMode: 重写 conversation[0] 主 system prompt 为当前 mode profile；
+     *  - pruneStaleModeHints: 移除切换前 append-only 残留的旧 mode hint，刷新保留的最新 hint
+     *    （含新 route 偏好 section），消除「旧 [Solo 模式] 与新 [Team 模式] 并存」的注入冲突。
+     *
+     * Node 单线程下它只能在 think 的 await 让出点（LLM in-flight）插入；已发请求用旧快照不受影响，
+     * 下一轮 think 读新数组。session 未加载时调用方已跳过（DB 是真理，下次加载/resume 首轮 think 对齐）。
+     */
+    applyRuntimeModeChange(): void;
+    /**
+     * 修剪 conversation 中 append-only 累积的 mode hint system 消息：只保留最后一条并刷新为当前
+     * getTeamModeHint()（反映最新 collaboration mode + route 偏好），移除切换前残留的旧 hint。
+     * 仅修剪内存运行时视图；DB 历史（leader_conversation 表）保持 append-only 不动。
+     * 识别用内容指纹（isModeHintContent）而非 metadata——表无 metadata 列，resume 重建后仍可识别。
+     */
+    private pruneStaleModeHints;
+    /**
+     * 获取动态上下文（Context Manifest dynamic context）— 作为独立 system 消息注入
+     * 避免动态内容变化导致 Anthropic prompt cache 失效。
+     *
+     * 实现已下沉至 LeaderContextBuilder.getDynamicContext()(含「当前使命」锚点置顶 +
+     * A2 token 预算门:超 context window 60% 时按优先级丢弃低优 fragment,mission 必留)。
+     */
+    protected getDynamicContext(): string | null;
+    /**
+     * Build the per-turn team-mode hint shown to the Leader before each user
+     * message. 实现已下沉至 LeaderContextBuilder.getTeamModeHint()。
+     */
+    protected getTeamModeHint(): string | null;
+    get isRunning(): boolean;
+    markWaitingForUser(waiting: boolean): void;
+    /**
+     * 标记当前正在等待的用户输入（硬用户门）。
+     * ask_user 必须调用它把内存 pendingUserInput 与 DB 写入对齐，
+     * 否则 hasExplicitUserGate() 读到内存为 null，主循环 un-latch 守卫
+     * 会把"等用户回答"误判成"软空闲等待"并继续偷跑派活。
+     */
+    markPendingUserInput(input: MessageContent): void;
+    markPendingReview(pending: boolean): void;
+    approvePlanInternally(): Promise<void>;
+    markFinished(): void;
+    /**
+     * 切换当前会话使用的模型（立即生效，下一轮 LLM 调用使用新模型）
+     */
+    setModel(modelId: string, options?: {
+        persistSessionState?: boolean;
+    }): {
+        ok: boolean;
+        message: string;
+    };
+    /**
+     * 切换权限模式（strict / dev / networked / yolo）
+     */
+    setPermissionMode(mode: string): {
+        ok: boolean;
+        message: string;
+    };
+    /**
+     * 处理用户输入
+     */
+    handleUserInput(content: MessageContent): Promise<void>;
+    /**
+     * 执行工具调用
+     */
+    protected executeToolCall(toolCall: ToolCall): Promise<ToolResultContent>;
+    protected canBatchExecuteToolCalls(toolCalls: ToolCall[]): boolean;
+    protected executeToolCallsBatch(toolCalls: ToolCall[]): Promise<Array<{
+        toolCall: ToolCall;
+        result: ToolResultContent;
+    }>>;
+    protected createToolScheduler(input?: {
+        finishReason?: ChatResponse['finish_reason'];
+        thinking?: ThinkingBlock[];
+        wasOutputTruncated?: boolean;
+        nextSpeakerLlm?: ContentGenerator;
+    }): ToolScheduler<{
+        done: boolean;
+        result?: string;
+    }>;
+    protected createLeaderEventStreamClient(actorLabel: string, hooks?: LlmRoundHooks): ContentGenerator;
+    protected monitorUserInterventionDuringInFlight(input: {
+        stopSignal: AbortSignal;
+        onIntervention: () => void;
+    }): Promise<void>;
+    /**
+     * 处理 LLM 响应
+     */
+    protected processResponse(response: ChatResponse): Promise<{
+        done: boolean;
+        result?: string;
+    }>;
+    private isUserInterventionMessage;
+    private clearConsumedUserInputState;
+    private clearSoftWaitingForUser;
+    private handleLeaderP0Message;
+    /** 懒构造 P0 处理器 — 事件订阅/优先级/时序全部下沉到子模块，行为不变 */
+    private getLeaderP0Handler;
+    /**
+     * Leader 主循环 - 完整复刻 Python 版本
+     *
+     * 单飞锁（P0 #2）：stop() 只置 finished=true 不会 await run() 退出，紧跟的 sendUserInput
+     * 在 isRunning=false 后会再次 launchLeaderDetached，导致并发两份 run() 共享 conversation /
+     * userMessageQueue / abortController，会出现：监听器双倍订阅、消息错位、conversation 交错。
+     * 这里入口检测：若旧 run() 仍未 settle，直接复用其 Promise，外部仍能 await 同一结果。
+     */
+    private startRun;
+    run(initialPrompt?: MessageContent, resume?: boolean, recoveredTasks?: RecoveredTaskInfo[]): Promise<string>;
+    private _runImpl;
+    /**
+     * 段1: _runImpl 启动时注册的事件订阅(bus/blackboard/orchestration/plugin/tools/roles)。
+     *
+     * 返回 unsubscribe 句柄数组,_runImpl 的 finally 块逐个退订。行为与原内联订阅完全一致 ——
+     * 仅是物理搬运,无任何逻辑变更。顺序即退订顺序(bugHunt→crash→plugin→tools→roles→
+     * orchestration run_state→orchestration event_rejected),与原 finally 一一对应。
+     */
+    private _runImpl_setupRunListeners;
+    /**
+     * 段2: 会话恢复 + 消息回放 + 首轮系统提示。
+     *
+     * resume 分支:从 db 回放 conversation,恢复 leader 运行态(waitingForUser/pendingReview/
+     * planApproved/executionMode/customRoles/pendingPermission 等),重置 recoveredTasks 为可
+     * 重新派发。新会话分支:注入 system prompt + dynamic context,把 initialPrompt 锚定为
+     * originalGoal(防漂移),首轮 leaderThinkAndAct。
+     *
+     * 纯物理搬运自原 _runImpl 的 try 块开头,行为零变更。
+     */
+    private _runImpl_initializeSession;
+    /**
+     * 段3: 主循环顶部 —— 运行中 agent 状态显示 + 消息轮询 + 用户消息入队 + 超时唤醒/抢占。
+     *
+     * 行为与原 _runImpl 内联段完全一致。写入 frame.allMsgs / frame.agentMsgs 供后续段读取。
+     * 原段内 maybeDriveOpenWork 后的 continue 改为 return 'continue',由 _runImpl 解释。
+     */
+    private _runImpl_loopPollAndStatus;
+    /**
+     * 段4: 用户消息消费 + permission 解决 + COMPACT + 评审批准/拒绝 + waitingForUser 门控。
+     * 行为与原内联段一致。原段内 continue 改为 return 'continue';评审内层 for-break 保持不变。
+     */
+    private _runImpl_consumeUserMessages;
+    /**
+     * 段5: agent 消息消费 + worker completion signal 注入 + dispatch directive。
+     * 行为与原内联段一致。产出 frame.consumedCompletionKeys / frame.pendingReportsToInject 供段6 读取。
+     * 段内 while-level continue/break 改为返回控制指令;for-内层 continue 保持。
+     */
+    private _runImpl_consumeAgentReports;
+    /**
+     * 段6: 健康巡检 + 派发触发(dispatchable) + 终局判定 + 永驻巡逻 + 监督 idle + 进度停滞检测。
+     * 行为与原内联段一致。无内层循环,原 while-level continue/break 全部转为返回控制指令。
+     */
+    private _runImpl_dispatchAndFinalize;
+    /**
+     * 停止 Leader
+     */
+    stop(): void;
+    /**
+     * 实例终结清理：退订所有构造器级（不随 run() 重注册）的事件监听器，断开对共享 emitter 的引用。
+     *
+     * H1 修复：LeaderAgent 在构造器中创建并订阅共享 emitter 的子系统——
+     *   - attachTaskLifecycleToTeamMailbox 注册的 task:failed / task:cancelled（_taskTeamUnsubscribers）
+     *   - orchestrationRuntime（task:created/updated/assigned/completed/failed/cancelled）
+     *   - leaderBlackboard（task:created/updated/completed/failed）
+     *   - scheduler / dispatchDecisionCoordinator（task:failed 等调度触发器）
+     * 这些监听器均在构造器注册一次、不随 run() 重入而重注册。历史上 dispose 仅退订
+     * dispatchDecisionCoordinator，其余从不退订——同进程会话重建（resumeSession 造新 LeaderAgent）会在
+     * 同一共享 emitter 上持续累积监听器，泄漏监听器及对 leader/board/bus 的引用。
+     *
+     * dispose() 隐含 stop()：先停止主循环（含 dispatchDecisionCoordinator.dispose），再退订其余实例级监听器。
+     * 可安全重复调用（幂等）。
+     */
+    dispose(): void;
+    /**
+     * 用户新输入到达时，只中断当前 LLM round，不结束 Leader 主循环。
+     * 主循环随后会从 MessageBus 读取 user_intervention，并按最高优先级处理。
+     */
+    /**
+     * 泛化中断方法：中断当前 LLM round，不结束 Leader 主循环。
+     * @param reason 中断原因：'user_input' | 'agent_completion'
+     */
+    interruptCurrentRound(reason?: 'user_input' | 'agent_completion'): void;
+    /**
+     * 非打断式用户指导：注入消息到下一轮 LLM 调用，不中断当前思考。
+     * 用户可以通过这种方式给 Leader 补充信息、调整方向，而不需要打断正在进行的工作。
+     */
+    nudgeLeader(message: string): void;
+    /** 是否有待处理的 Agent 完成信号 */
+    isAgentCompletionPending(): boolean;
+    /**
+     * 在 LLM 调用前排空 bus 上已到达但尚未消费的 user_intervention 消息，
+     * 直接注入为 user role 对话，让下一轮 LLM 立即看到用户输入并回复。
+     *
+     * 触发场景：用户在 Leader busy 期间用 interrupt:false 投递的"非打断式"消息。
+     * 历史上这条路径只设置 nudgeMessage（注入为 system role），并且依赖外层
+     * 主循环把 userMessageQueue 单独喂回 leaderThinkAndAct；当 leaderThinkAndAct
+     * 已经在 AgentCore 多轮里运行时，bus 上的用户消息要等当前完整 think-and-act
+     * 全部退出才被处理，体感就是"用户发了消息但 Leader 不答"。
+     *
+     * 现在：每轮 runRound 开始前，主动 poll bus，把用户消息原封不动以
+     * role=user 注入对话；下一次 LLM 调用会立刻看到并回复。
+     *
+     * 返回 true 表示注入了至少一条用户消息。
+     */
+    drainPendingUserMessagesIntoConversation(): Promise<boolean>;
+    isUserInterruptPending(): boolean;
+    clearUserInterruptPending(): void;
+    private checkProgressStagnation;
+    /**
+     * 标记进度更新时间（在每次成功推进时调用）
+     */
+    markLeaderProgress(): void;
+    private startWatchdog;
+    private stopWatchdog;
+    protected maybeReviewScratchpadTailWork(): Promise<boolean>;
+    /**
+     * Leader 思考和行动循环
+     */
+    leaderThinkAndAct(maxToolRounds?: number): Promise<void>;
+    /**
+     * 获取当前消息数
+     */
+    getMessageCount(): number;
+    /**
+     * 获取角色注册表
+     */
+    getRoleRegistry(): AgentRoleRegistry;
+    /**
+     * 获取工具注册表（公开访问）
+     */
+    getToolRegistry(): ToolRegistry;
+    getContextManager(): ContextManager;
+    setConversation(messages: ChatMessage[]): void;
+    /**
+     * 主动压缩 Leader 上下文：先把当前 conversation 同步到 ContextManager，
+     * 触发强制压缩，再把压缩后的消息回写到 conversation。
+     *
+     * 三处入口（TUI dispatcher、Web AcpHandler、HTTP SessionRoutes、COMPACT 字符串）
+     * 都必须走这一个方法，禁止直接调 contextManager.forceCompact() 而不回写。
+     */
+    compactContext(): Promise<{
+        oldTokens: number;
+        newTokens: number;
+        compacted: boolean;
+        compactType?: string;
+        overflow?: boolean;
+        archivePath?: string;
+        inProgress?: boolean;
+        threshold?: number;
+    }>;
+    getContextRuntimeState(): ContextRuntimeState;
+    getEternalRuntimeSnapshot(): EternalRuntimeSnapshot;
+    invalidateEternalSilenceLock(reason?: string): void;
+    publishAssistantOutput(content: string, reasoningContent?: string): void;
+    /**
+     * 获取当前交互运行时快照
+     */
+    getInteractionSnapshot(): LeaderInteractionSnapshot;
+    /**
+     * 检查是否有未完成的任务
+     */
+    hasPendingTasks(): boolean;
+    /**
+     * 检查是否有运行的 Agent
+     */
+    hasRunningAgents(): boolean;
+    /**
+     * 将 Agent 注册到健康巡检系统（供 LeaderTools 等外部调用）
+     */
+    registerAgentHealth(agentId: string, name: string, roleType?: string): void;
+}
+export default LeaderAgent;
+//# sourceMappingURL=LeaderAgent.d.ts.map