@lingxiao-office/sdk 1.0.0

package/dist/agents/AutonomyDecisionEngine.js

@@ -0,0 +1,150 @@
+/**
+ * AutonomyDecisionEngine —— runtime policy hint renderer for leader tool calls.
+ *
+ * This layer is intentionally NOT an authorization boundary. Capability profile
+ * and confirmation policy are hints/evidence for the LLM/UI/audit trail. Actual
+ * hard permission remains in PermissionSystem / ToolRegistry / explicit user
+ * approval flows.
+ */
+import { AUTONOMY_ACTIONS, DEFAULT_AUTONOMY_MODE, } from '../contracts/types/AutonomyDecision.js';
+import { normalizeAutonomyMode } from '../contracts/types/Autonomy.js';
+export function requiredCapabilityForAction(action) {
+    switch (action) {
+        case 'read':
+        case 'analyze':
+        case 'propose':
+            return 'read';
+        case 'apply_change':
+        case 'workflow_apply':
+            return 'write';
+        case 'run_command':
+            return 'shell';
+        case 'create_task':
+            return 'task';
+        case 'dispatch':
+            return 'dispatch';
+        case 'scope_expand':
+            return null;
+    }
+}
+export function decideAutonomyAction(ctx) {
+    const autonomyMode = normalizeAutonomyMode(ctx.autonomyMode);
+    const profile = ctx.intentProfile;
+    const action = ctx.action ?? (ctx.toolName ? inferActionFromToolTier(ctx.toolTier, ctx.isReadOnly) : inferActionFromRisk(ctx));
+    const requiredCapability = requiredCapabilityForAction(action);
+    const evidence = [];
+    const sources = [];
+    pushEvidence(evidence, sources, 'primary_intent', profile.primaryIntent, profile.reason, 'intent_profile');
+    pushEvidence(evidence, sources, 'intent_phase', profile.phase, undefined, 'intent_profile');
+    pushEvidence(evidence, sources, 'intent_scope', profile.scope.kind, undefined, 'intent_profile');
+    pushEvidence(evidence, sources, 'autonomy_mode', autonomyMode, `hint only; default ${DEFAULT_AUTONOMY_MODE}`, autonomyMode === DEFAULT_AUTONOMY_MODE ? 'autonomy_default' : 'autonomy_explicit');
+    if (ctx.permissionMode)
+        pushEvidence(evidence, sources, 'permission_mode', ctx.permissionMode, 'actual permission boundary is PermissionSystem');
+    if (ctx.leaderExecutionMode)
+        pushEvidence(evidence, sources, 'leader_execution_mode', ctx.leaderExecutionMode, 'route hint');
+    if (ctx.controlMode)
+        pushEvidence(evidence, sources, 'control_mode', ctx.controlMode, 'control hint');
+    if (ctx.toolTier)
+        pushEvidence(evidence, sources, 'tool_tier', ctx.toolTier);
+    pushEvidence(evidence, sources, 'operation_risk', ctx.operationRisk);
+    pushEvidence(evidence, sources, 'read_only_flag', String(ctx.isReadOnly));
+    pushEvidence(evidence, sources, 'rule_action', action, ctx.action ? 'caller normalized tool category' : 'engine fallback category', 'rule_action');
+    if (requiredCapability) {
+        if (profile.denies.includes(requiredCapability)) {
+            pushEvidence(evidence, sources, 'capability_deny', requiredCapability, 'hint: profile says this capability is not intended', 'capability_deny');
+        }
+        else if (profile.grants.includes(requiredCapability)) {
+            pushEvidence(evidence, sources, 'capability_grant', requiredCapability, 'hint: profile grants this capability', 'capability_grant');
+        }
+        else {
+            pushEvidence(evidence, sources, 'capability_grant', requiredCapability, 'hint: profile does not explicitly grant this capability', 'capability_grant');
+        }
+    }
+    if (profile.requiredGates.length > 0) {
+        pushEvidence(evidence, sources, 'required_gate', profile.requiredGates.join(','), 'hint only; does not hard-block in AutonomyDecisionEngine', 'required_gate');
+    }
+    if (profile.constraints.allowedPaths?.length) {
+        pushEvidence(evidence, sources, 'path_constraint', profile.constraints.allowedPaths.join(','), 'hint: intended write/read paths', 'path_constraint');
+    }
+    if (profile.constraints.deniedTools?.length) {
+        pushEvidence(evidence, sources, 'intent_constraint', profile.constraints.deniedTools.join(','), 'hint: tools user does not intend to use', 'intent_constraint');
+    }
+    return {
+        kind: 'allow',
+        intentProfile: profile,
+        autonomyMode,
+        reason: buildReason(action, ctx.operationRisk, profile.primaryIntent, profile.phase),
+        affectedTools: ctx.toolName ? [ctx.toolName] : [],
+        source: pickPrimarySource(sources),
+        evidence,
+        requiredCapability,
+    };
+}
+export function deriveOperationRisk(input) {
+    if (input.isCritical)
+        return 'critical';
+    if (input.readOnly)
+        return 'low';
+    switch (input.toolTier) {
+        case 'read':
+        case 'compute':
+            return 'low';
+        case 'write':
+            return 'medium';
+        case 'execute':
+            return 'high';
+        default:
+            return 'medium';
+    }
+}
+export function inferActionFromToolName(toolName) {
+    if (!toolName)
+        return 'analyze';
+    const lower = toolName.toLowerCase();
+    if (lower.includes('read') || lower.includes('search') || lower.includes('list') || lower.includes('grep') || lower.includes('glob') || lower.includes('code_search') || lower.includes('ast_query') || lower === 'find_tools')
+        return 'read';
+    if (lower === 'create_task' || lower === 'update_task' || lower === 'delete_task')
+        return 'create_task';
+    if (lower.includes('dispatch') || lower.includes('spawn'))
+        return 'dispatch';
+    if (lower.includes('workflow_apply') || lower.includes('apply_workflow'))
+        return 'workflow_apply';
+    if (lower === 'shell' || lower === 'bash' || lower.includes('run_command') || lower.includes('execute_command'))
+        return 'run_command';
+    if (lower.includes('patch') || lower.includes('file_create') || lower.includes('write_file'))
+        return 'apply_change';
+    if (lower.includes('propose') || lower.includes('plan'))
+        return 'propose';
+    return 'analyze';
+}
+function inferActionFromToolTier(toolTier, isReadOnly) {
+    if (isReadOnly || toolTier === 'read')
+        return 'read';
+    if (toolTier === 'compute')
+        return 'analyze';
+    if (toolTier === 'write')
+        return 'apply_change';
+    if (toolTier === 'execute')
+        return 'run_command';
+    return 'analyze';
+}
+function inferActionFromRisk(ctx) {
+    if (ctx.isReadOnly || ctx.operationRisk === 'low')
+        return 'read';
+    if (ctx.operationRisk === 'high' || ctx.operationRisk === 'critical')
+        return 'run_command';
+    return 'apply_change';
+}
+function pushEvidence(evidence, sources, kind, value, note, source) {
+    evidence.push(note ? { kind, value, note } : { kind, value });
+    if (source)
+        sources.push(source);
+}
+function pickPrimarySource(sources) {
+    return sources[0] ?? 'intent_profile';
+}
+function buildReason(action, risk, primaryIntent, phase) {
+    return `runtime policy hint: action=${action}; risk=${risk}; profile=${primaryIntent}/${phase}; actual authorization is handled outside AutonomyDecisionEngine`;
+}
+export { AUTONOMY_ACTIONS };
+//# sourceMappingURL=AutonomyDecisionEngine.js.map

package/dist/agents/AutonomyDecisionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutonomyDecisionEngine.js","sourceRoot":"","sources":["../../src/agents/AutonomyDecisionEngine.ts"],"names":[],"mappings":"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"}

package/dist/agents/BaseAgentRuntime.d.ts

@@ -0,0 +1,509 @@
+/**
+ * BaseAgent - Agent 基类
+ * 完整复刻 Python 版本的所有功能
+ *
+ * 包含:
+ * - ContextManager 集成
+ * - 多模态上下文注入
+ * - 数据库持久化
+ * - 完整的事件日志
+ * - 消息总线干预检查
+ * - 超时重试机制
+ * - 原始 XML 工具调用容错解析
+ * - 工具结果智能截断
+ * - Agent 级上下文管理
+ * - 技能注入
+ * - Scratchpad 工作笔记
+ * - 幻觉检测和处理
+ */
+import { type ChatMessage, type ChatResponse, type ToolCall, type ToolDefinition } from '../llm/types.js';
+import type { ContentGenerator } from '../llm/ContentGenerator.js';
+import type { TokenUsageView } from '../types/canonical.js';
+import type { ToolRegistry } from '../tools/Registry.js';
+import type { MessageBus } from '../core/MessageBus.js';
+import type { EventEmitter } from '../core/EventEmitter.js';
+import type { DatabaseManager } from '../core/Database.js';
+import type { AgentHandle } from './AgentPoolRuntime.js';
+import type { ContractAllowedScope } from '../core/ContractAllowedScope.js';
+import type { AttemptCompletionStructuredResult } from '../tools/implementations/AttemptCompletionTool.js';
+import { ContextManager } from '../core/ContextManager.js';
+import { type ContextManifestAgentArtifact } from '../core/ContextManifest.js';
+import { ToolScheduler } from './runtime/ToolScheduler.js';
+import type { ToolResultContent } from './runtime/ToolResponseProcessor.js';
+import { ToolLoopDetector } from './runtime/ToolLoopDetector.js';
+import { type LoopGuardDecision } from './runtime/ToolFailureLoopGuard.js';
+import { AgentRuntimeState } from './runtime/AgentRuntimeState.js';
+import { AgentContextController } from './AgentContextController.js';
+import { AgentInterventionHandler } from './AgentInterventionHandler.js';
+import { AgentRoundExecutor } from './AgentRoundExecutor.js';
+import type { BlackboardGraph } from '../core/blackboard/BlackboardGraph.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 { AgentTask } from '../types/canonical.js';
+export type Task = AgentTask;
+/**
+ * 把 ToolFailureLoopGuard 的熔断决策转成给 LLM 看的 ERROR 文案。
+ * 放在模块顶层（不依赖 class state）以便未来跨模块复用 + 纯函数可单测。
+ */
+export declare function formatToolFailureLoopError(toolName: string, decision: LoopGuardDecision): string;
+export interface TokenTracker {
+    addUsage(agentId: string, usage: TokenUsageView, modelName?: string): void;
+    getTotal(): number;
+    loadHistory(sessionId: string): void;
+    getSessionTotal(): number;
+    usageMap?: Map<string, TokenUsageView>;
+}
+/**
+ * Agent 配置
+ */
+export interface AgentConfig {
+    agentId: string;
+    name: string;
+    role: string;
+    systemPrompt: string;
+    toolNames: string[];
+    skillNames?: string[];
+    llmClient: ContentGenerator;
+    toolRegistry: ToolRegistry;
+    messageBus: MessageBus;
+    tokenTracker: TokenTracker;
+    workspace: string;
+    sessionId: string;
+    model: string;
+    eventEmitter: EventEmitter;
+    db?: DatabaseManager;
+    handle?: AgentHandle;
+    maxIterations?: number;
+    maxRuntimeMinutes?: number;
+    blackboardGraph?: BlackboardGraph;
+    workflowManager?: WorkflowManager;
+    workflowEngine?: WorkflowEngine;
+    scheduledTaskManager?: ScheduledTaskManager;
+    /** Per-role git author identity for commit attribution. */
+    gitIdentity?: {
+        name: string;
+        email: string;
+    };
+}
+export declare class BaseAgent {
+    agentId: string;
+    name: string;
+    role: string;
+    systemPrompt: string;
+    toolNames: string[];
+    skillNames: string[];
+    llm: ContentGenerator;
+    tools: ToolRegistry;
+    bus: MessageBus;
+    tracker: TokenTracker;
+    workspace: string;
+    sessionId: string;
+    model: string;
+    emitter: EventEmitter;
+    db?: DatabaseManager;
+    protected handle?: AgentHandle;
+    protected blackboardGraph?: BlackboardGraph;
+    protected workflowManager?: WorkflowManager;
+    protected workflowEngine?: WorkflowEngine;
+    protected scheduledTaskManager?: ScheduledTaskManager;
+    /** Per-role git author identity for commit attribution. */
+    protected gitIdentity?: {
+        name: string;
+        email: string;
+    };
+    /** 带 sessionId 前缀的 bus 收件人名（避免跨会话消息串台） */
+    get busName(): string;
+    /** 本会话 leader 的 bus 收件人名 */
+    get leaderBusName(): string;
+    protected messages: ChatMessage[];
+    protected stopped: boolean;
+    protected paused: boolean;
+    protected stalled: boolean;
+    protected interventionMessage: string | null;
+    protected currentLlmAbortController: AbortController | null;
+    /** Leader 注入的 nudge 干预消息，在下轮 LLM 调用时作为 system 注入 */
+    protected nudgeMessage: string | null;
+    private pendingInboxInterventionResult;
+    private terminalRuntimeOutcome;
+    /**
+     * 复用同名 worker 时继承的历史对话（来自上一轮运行、已落在 DB 的 agent_conversation）。
+     *
+     * Why：worker 子进程永远以 isResume=false 启动，run() 会走 initializeMessages → this.messages=[]，
+     * 把任何预置消息清空。所以"继承上下文"不能靠 WorkerProcessEntry 预先 addMessage（会被清掉），
+     * 必须由 run() 在初始化时显式识别这份历史并 weave 进消息序列。非空即代表"这是个被复用/复活的 worker"。
+     *
+     * 这些消息已存在于 DB（上一轮用同一 agentId 保存），run() 继承时不重复回写历史，
+     * 避免下次复用时 agent_conversation 翻倍。
+     */
+    protected inheritedHistory: ChatMessage[] | null;
+    /**
+     * 继承历史的语义：
+     *   - 'resume'：复活同一个任务（追问 / team 复活），把历史当作基底直接续，不再注入任务指令
+     *     （续推由随后投递的 leaderMessage / inbox 驱动）。
+     *   - 'new_task'：复用同名 worker 跑一个新任务，历史作为背景上下文，再追加新任务指令与分隔说明。
+     */
+    protected inheritedHistoryMode: 'resume' | 'new_task';
+    private auditedDefaultBypassFallback;
+    protected runtimeState: AgentRuntimeState;
+    protected readonly MAX_TIMEOUT_RETRIES: number;
+    /** 外层 LLM 错误重试计数（与 LlmGuard 内部 5 次预算解耦，跨 catch 累加） */
+    protected llmErrorRetryCount: number;
+    protected readonly LLM_MAX_ERROR_RETRIES: number;
+    protected maxIterations: number;
+    protected maxRuntimeMinutes: number;
+    /** onConfigReload 退订函数：在 agent 终止时调用以防止监听器泄漏 */
+    private _configReloadUnsubscribe;
+    protected readonly MAX_COMPLETION_GUARD_RETRIES = 3;
+    /**
+     * 连续续跑上限。超过即强制接受当前输出收尾，打破「续跑→短 stop→续跑」空转。
+     * 任意真实工具调用会把计数清零，所以正常多轮工作不受影响。
+     */
+    protected readonly MAX_CONTINUATION_RETRIES = 5;
+    protected contextManager: ContextManager;
+    protected contextController: AgentContextController;
+    protected interventionHandler: AgentInterventionHandler;
+    protected roundExecutor: AgentRoundExecutor;
+    protected lastRuntimeContextFingerprint: string | null;
+    /** 同 toolName+args 连续调用探针；超阈值打断当前 task */
+    protected toolLoopDetector: ToolLoopDetector;
+    /** context:overflow 事件取消订阅函数 */
+    protected _contextOverflowUnsub: (() => void) | null;
+    /** P0 紧急消息介入监听取消订阅函数 */
+    protected _p0InterventionUnsub: (() => void) | null;
+    /**
+     * 框架自动采集的工具产物轨迹 —— 不依赖 worker 主动在 attempt_completion 里
+     * 填 artifacts，也能让 Leader 看到 worker 真实改过哪些文件、跑过哪些命令。
+     *   - file_create → files_created
+     *   - structured_patch → files_modified
+     *   - shell → commands_run（command 原文）
+     *   - python_exec → commands_run（python: 首行）
+     * 与 attempt_completion 声明的 artifacts 在 Leader 端按文件路径去重合并。
+     */
+    protected readonly toolTrace: {
+        filesCreated: Set<string>;
+        filesModified: Set<string>;
+        commandsRun: string[];
+    };
+    private assumptionTracker?;
+    private assumptionTrackerProjectRoot?;
+    /**
+     * DAG-based context state — 追踪消息间依赖关系,支持结构性无损压缩。
+     * 由 addMessage 自动维护; performContextReset 时用 structuralTrim 替代粗暴的"只留最近 15 条"。
+     * 导入: import { ContextDAG } from '../core/compress/ContextDAG.js';
+     */
+    protected contextDAG: import('../core/compress/ContextDAG.js').ContextDAG | null;
+    /**
+     * worker 调用 attempt_completion 时捕获的结构化收尾结果。
+     * run() 结束后透传给 WorkerProcessEntry → task_complete payload → Leader。
+     */
+    protected attemptCompletion?: AttemptCompletionStructuredResult;
+    /** 权限超时计数：连续超时 2 次则终止 agent */
+    protected permissionTimeoutCount: number;
+    /** 标记 agent 应终止（权限超时等场景） */
+    protected shouldTerminate: boolean;
+    protected get toolCallCount(): number;
+    protected set toolCallCount(value: number);
+    protected get currentTaskId(): string | null;
+    protected set currentTaskId(value: string | null);
+    protected get currentTaskWorkingDirectory(): string | null;
+    protected set currentTaskWorkingDirectory(value: string | null);
+    protected get currentTaskWriteScope(): string[];
+    protected set currentTaskWriteScope(value: string[]);
+    protected get currentContractAllowedScope(): ContractAllowedScope | undefined;
+    /** WorkerProcessEntry 在 run 前从 payload 透传契约允许面(多契约已 intersect)。 */
+    setContractAllowedScope(scope?: ContractAllowedScope): void;
+    protected get iteration(): number;
+    protected set iteration(value: number);
+    protected get rawXmlRetryCount(): number;
+    protected set rawXmlRetryCount(value: number);
+    protected get completionGuardRetryCount(): number;
+    protected set completionGuardRetryCount(value: number);
+    private auditDefaultPermissionContext;
+    protected getPermissionContext(): import("../core/PermissionSystem.js").ToolPermissionContext;
+    protected requestPermissionFromLeader(toolName: string, reason: string): Promise<boolean>;
+    protected persistResumeCheckpoint(task: Task): void;
+    protected clearResumeCheckpoint(): void;
+    static readonly THINKING_INSTRUCTION: string;
+    constructor(config: AgentConfig);
+    protected resolveContextLimit(model: string): number;
+    /**
+     * 执行上下文压缩：优先用 ContextDAG 结构性压缩（每次从当前消息无状态重建图）；
+     * fallback 到保留 system + 最近 15 条。
+     */
+    private performContextReset;
+    /** 延迟初始化 ContextDAG */
+    private initContextDAG;
+    /**
+     * 添加消息到对话历史，带 Ring Buffer 保护
+     * #2 优化：在压缩前对大 tool_result 做提前裁剪，减少内存峰值
+     */
+    addMessage(msg: ChatMessage): void;
+    private isRuntimeContractPackMessage;
+    private collapseRuntimeContractPackMessages;
+    private upsertSystemContextMessage;
+    /**
+     * 预置继承历史，供 run() 在初始化阶段 weave 进消息序列。
+     *
+     * Why 不直接 addMessage：worker 子进程以 isResume=false 启动，run() 会走
+     * initializeMessages → this.messages=[] 清空。所以历史必须存到 inheritedHistory 字段，
+     * 由 run() 优先识别后通过 initializeMessagesFromInherited 注入。
+     */
+    seedInheritedHistory(history: ChatMessage[], mode?: 'resume' | 'new_task'): void;
+    protected trimMessageBuffer(messages: ChatMessage[], protectedCount: number, maxMessages: number): ChatMessage[];
+    /**
+     * 获取增强的系统提示
+     * 返回稳定核心（可被 Anthropic cache 缓存）+ 动态附加（不缓存）
+     */
+    protected getEnhancedSystemPrompt(): string;
+    /**
+     * 获取动态上下文（长期记忆索引等）— 作为统一 Context Manifest 注入，
+     * 不混入主 system prompt，避免动态内容变化导致 Anthropic prompt cache 失效
+     */
+    protected getDynamicContext(): string | null;
+    protected buildRuntimeContextFingerprint(): string | null;
+    protected buildAgentArtifactManifest(): ContextManifestAgentArtifact[];
+    protected appendRuntimeContextManifestIfChanged(): Promise<boolean>;
+    /**
+     * 获取工具定义。尊重角色工具白名单，避免所有 agent 都携带全量工具 schema。
+     * 接入 ToolPruner：硬模式过滤 + 确定性 token 预算裁剪。
+     */
+    protected getToolDefinitions(task?: Task): Promise<ToolDefinition[] | undefined>;
+    /**
+     * 推断 ToolPruner 执行模式：根据 agent 的 toolNames 判断。
+     */
+    private inferToolPrunerMode;
+    /**
+     * 记录 Agent 事件到数据库
+     */
+    protected logEvent(eventType: string, content: Record<string, unknown>): Promise<void>;
+    private getAssumptionTracker;
+    private handleAssumptionFeedback;
+    /**
+     * 构建任务提示词，包含技能注入
+     */
+    protected buildTaskPrompt(task: Task): string;
+    /**
+     * 初始化消息列表
+     */
+    protected initializeMessages(task: Task): Promise<void>;
+    /**
+     * 继承历史对话的初始化：worker 子进程总以 isResume=false 启动，run() 默认会
+     * initializeMessages → this.messages=[]，把 WorkerProcessEntry 预注入的历史清空。
+     * 所以"继承上下文"统一收敛到这里，由 run() 在 inheritedHistory 非空时优先走本方法。
+     *
+     * 两种语义（inheritedHistoryMode）：
+     *   - 'resume'（追问 / team 复活同一个任务）：历史即完整对话基底，不再注入任务指令，
+     *     后续推进由随后投递的 leaderMessage / inbox 干预驱动；恢复 toolCallCount 进度。
+     *   - 'new_task'（复用同名 worker 跑新任务）：历史作为背景上下文，追加一条 user 分隔说明
+     *     + 新任务指令 user 消息；进度按新任务从 0 起（initializeTaskScope 已在 run 开头重置）。
+     *
+     * 持久化：历史早已在 DB（上一轮同 agentId 保存），只回写本次新追加的消息，
+     * 避免下次复用时 agent_conversation 翻倍。
+     */
+    protected initializeMessagesFromInherited(task: Task, recoveredIteration?: number, recoveredToolCallCount?: number): Promise<void>;
+    /**
+     * 执行工具调用
+     */
+    protected executeToolCall(toolCall: ToolCall): Promise<ToolResultContent>;
+    /**
+     * 采集单次工具调用的产物轨迹 / 捕获 attempt_completion 结构化收尾。
+     * 仅在工具执行 success 后调用。失败的工具调用不计入产物。
+     */
+    protected recordToolTrace(toolName: string, args: unknown, data: unknown): void;
+    /**
+     * 从 ToolResult.error 文本中提取 LLM_RECOVERY.code（与 createToolError 对齐：error 末尾
+     * 形如 `\n\nLLM_RECOVERY={"code":"...","message":"...",...}`）。若不存在则回退到错误前缀匹配。
+     */
+    protected extractToolErrorCode(errorText: string | undefined): string;
+    /**
+     * 将一次工具失败计入 ToolFailureLoopGuard。
+     * 成功路径不需调用（registry 内部有独立 success 跟踪）。
+     */
+    protected recordToolFailure(toolName: string, args: unknown, errorText: string | undefined): LoopGuardDecision;
+    protected recordContextRead(toolName: string, args: unknown, data: unknown): void;
+    /**
+     * 把框架采集的 toolTrace 转成可序列化的产物快照（用于 task_complete payload）。
+     * 数组去重，commands 保序去重。
+     */
+    protected buildToolTraceSnapshot(): {
+        files_created: string[];
+        files_modified: string[];
+        commands_run: string[];
+    };
+    protected canBatchExecuteToolCalls(toolCalls: ToolCall[]): boolean;
+    protected executeToolCallsBatch(toolCalls: ToolCall[]): Promise<Array<{
+        toolCall: ToolCall;
+        result: ToolResultContent;
+    }>>;
+    protected createToolScheduler(options?: {
+        logToolCall?: boolean;
+        wasOutputTruncated?: boolean;
+    }): ToolScheduler<{
+        done: boolean;
+        result?: string;
+    }>;
+    protected createAgentEventStreamClient(actorLabel: string): ContentGenerator;
+    /**
+     * Agent 文件变更 snapshot — 记录 Agent 级别的文件修改操作到 Changes timeline
+     */
+    protected createAgentFileSnapshot(toolName: string): Promise<void>;
+    /**
+     * 处理 LLM 响应（协调者）
+     */
+    protected processResponse(response: ChatResponse, task: Task): Promise<{
+        done: boolean;
+        result?: string;
+    }>;
+    /**
+     * 处理原生 tool_calls（含死循环检测）
+     */
+    private handleNativeToolCalls;
+    /**
+     * 尝试从纯文本解析内嵌工具调用并执行（含死循环检测）
+     * 返回 null 表示没有可解析的工具调用
+     */
+    private handleParsedToolCalls;
+    /**
+     * 处理包含无法解析的原始工具语法（格式错乱）的情况
+     * 返回 null 表示不包含原始工具语法
+     */
+    private handleRawToolSyntaxRetry;
+    /**
+     * 评估完成状态，如果 completion guard 拒绝则返回重试指令
+     * 返回 null 表示完成校验通过（继续后续流程）
+     */
+    private evaluateCompletionAndRetry;
+    /**
+     * 评估 nextSpeaker 和 stopHook，决定是否需要继续
+     * 返回 null 表示无需继续（应走正常完成流程）
+     */
+    private evaluateContinuation;
+    /**
+     * 执行最终完成流程：日志、工作笔记、事件发射、状态持久化
+     */
+    private finalizeCompletion;
+    /**
+     * 检查收件箱：处理停止消息和 Leader 干预指令。
+     * @param prePolledMessages 可选的已 poll 消息列表，避免重复 poll
+     * @returns true=需要停止Agent, false=继续运行
+     */
+    protected checkInbox(prePolledMessages?: Array<{
+        id?: string;
+        type: string;
+        payload: unknown;
+        content?: unknown;
+        from: string;
+    }>): Promise<boolean>;
+    private applyRuntimeIntervention;
+    private handleRuntimeInterventionMessage;
+    /**
+     * 检查并处理 Leader 的运行时干预指令。
+     * 在每次 LLM 调用前调用，识别 [INTERVENTION:*] 前缀消息。
+     * @returns { type: 'repeat' } 触发循环重试, { type: 'continue' } 继续, null 无干预
+     */
+    protected checkInboxForIntervention(): Promise<{
+        type: 'repeat' | 'continue';
+    } | null>;
+    /**
+     * 检查收件箱是否有恢复暂停的消息
+     */
+    protected checkInboxForResume(): Promise<boolean>;
+    /**
+     * 检查收件箱是否有干预确认消息
+     */
+    protected checkInboxForInterventionConfirm(): Promise<boolean>;
+    protected maybeContinueFromStopHook(final: string): Promise<{
+        shouldContinue: boolean;
+        feedback?: string;
+        signal?: {
+            source: string;
+            detail?: string;
+        };
+    }>;
+    private markTerminalRuntimeOutcome;
+    private isStoppedRuntimeReason;
+    private normalizeTerminalRuntimeOutcome;
+    private buildTerminalFailureResult;
+    private isRuntimeFailureLoopResult;
+    /**
+     * Agent 主循环
+     */
+    /**
+     * 双阶段执行入口
+     * Execute 阶段：正常执行任务
+     * Conclude 阶段：超时后快速收尾
+     */
+    runWithConclude(task: Task, isResume?: boolean, recoveredState?: {
+        iteration?: number;
+        toolCallCount?: number;
+    }): Promise<string | import('./AgentExecutionResult.js').AgentExecutionResult>;
+    /**
+     * Execute 阶段：正常执行任务
+     */
+    private executePhase;
+    /**
+     * Conclude 阶段：超时后快速收尾
+     * 限时 2 分钟，最多 3 轮对话
+     */
+    private concludePhase;
+    /**
+     * 推断任务类型
+     */
+    private inferTaskType;
+    run(task: Task, isResume?: boolean, recoveredState?: {
+        iteration?: number;
+        toolCallCount?: number;
+    }): Promise<string | import('./AgentExecutionResult.js').AgentExecutionResult>;
+    /**
+     * 停止 Agent（完全终止，不可恢复）
+     */
+    stop(): void;
+    /**
+     * 暂停 Agent（保留进度，可随时恢复）
+     * 不杀进程，只 abort 当前 LLM 调用，保存 checkpoint
+     */
+    pause(): void;
+    /**
+     * 干预 Agent（停下来等用户指令）
+     * 暂停当前操作，存储干预指令，等待用户确认后继续
+     */
+    intervene(instruction: string): void;
+    /**
+     * 带着干预指令恢复执行
+     * 将 interventionMessage 注入到对话中
+     */
+    resumeWithIntervention(): void;
+    /**
+     * 保存暂停时的 checkpoint 到 DB
+     */
+    private savePauseCheckpoint;
+    /**
+     * 获取工具调用次数
+     */
+    getToolCallCount(): number;
+    /**
+     * 获取当前迭代次数
+     */
+    getIterationCount(): number;
+    /**
+     * 框架自动采集的工具产物轨迹（已去重、created/modified 互斥）。
+     * WorkerProcessEntry 在 complete payload 里透传给 Leader。
+     */
+    getToolTrace(): {
+        files_created: string[];
+        files_modified: string[];
+        commands_run: string[];
+    };
+    /**
+     * worker 通过 attempt_completion 声明的结构化收尾结果；未调用则为 undefined。
+     */
+    getAttemptCompletion(): AttemptCompletionStructuredResult | undefined;
+    protected evaluateCompletionCandidate(final: string, task: Task): Promise<{
+        accepted: boolean;
+        reason?: string;
+        feedback: string;
+    }>;
+}
+export default BaseAgent;
+//# sourceMappingURL=BaseAgentRuntime.d.ts.map