@lingxiao-office/sdk 1.0.0

package/dist/agents/WorkerTaskAgent.js

@@ -0,0 +1,114 @@
+/**
+ * WorkerTaskAgent - 子 Agent 实现
+ * 由 Leader 派发执行具体任务的 Agent
+ */
+import { contentToPlainText, } from '../llm/types.js';
+import { BaseAgent } from './BaseAgentRuntime.js';
+/**
+ * WorkerTaskAgent - 子 Agent
+ * 继承 BaseAgent，增加任务执行和进度报告功能
+ */
+export class WorkerTaskAgent extends BaseAgent {
+    taskId;
+    progressCallback;
+    constructor(config) {
+        super(config);
+        this.taskId = config.taskId;
+        if (config.skillNames) {
+            this.skillNames = config.skillNames;
+        }
+    }
+    /**
+     * 设置进度回调
+     */
+    setProgressCallback(callback) {
+        this.progressCallback = callback;
+    }
+    /**
+     * 报告进度
+     */
+    reportProgress(message) {
+        if (this.progressCallback) {
+            this.progressCallback(message);
+        }
+        this.emitter.emit('agent:progress', {
+            agentId: this.agentId,
+            name: this.name,
+            taskId: this.taskId,
+            message,
+        });
+    }
+    isExecutionResult(value) {
+        return Boolean(value &&
+            typeof value === 'object' &&
+            'status' in value &&
+            'summary' in value);
+    }
+    /**
+     * 执行工具调用（扩展基类方法）
+     */
+    async executeToolCall(toolCall) {
+        this.reportProgress(`执行工具: ${toolCall.function.name}`);
+        // 记录工具调用日志
+        if (this.db) {
+            this.db.insertAgentLog({
+                session_id: this.sessionId,
+                agent_id: this.agentId,
+                agent_name: this.name,
+                agent_role: this.role,
+                task_id: this.taskId,
+                event_type: 'tool_call_start',
+                content: JSON.stringify({
+                    tool_name: toolCall.function.name,
+                    arguments: toolCall.function.arguments,
+                }),
+                timestamp: Date.now() / 1000,
+            });
+        }
+        const result = await super.executeToolCall(toolCall);
+        const resultPreview = typeof result === 'string'
+            ? result.slice(0, 500)
+            : contentToPlainText(result).slice(0, 500);
+        // 记录工具结果日志
+        if (this.db) {
+            this.db.insertAgentLog({
+                session_id: this.sessionId,
+                agent_id: this.agentId,
+                agent_name: this.name,
+                agent_role: this.role,
+                task_id: this.taskId,
+                event_type: 'tool_result',
+                content: JSON.stringify({
+                    tool_name: toolCall.function.name,
+                    result_preview: resultPreview,
+                }),
+                timestamp: Date.now() / 1000,
+            });
+        }
+        return result;
+    }
+    /**
+     * Agent 主循环（扩展基类方法）
+     */
+    async run(task, isResume = false, recoveredState) {
+        this.reportProgress(`开始任务: ${task.subject}`);
+        const result = await super.run(task, isResume, recoveredState);
+        if (this.isExecutionResult(result)) {
+            if (result.status === 'completed') {
+                this.reportProgress(`任务完成: ${task.subject}`);
+            }
+            else if (result.status === 'blocked') {
+                this.reportProgress(`任务阻塞: ${task.subject} - ${result.summary}`);
+            }
+            else {
+                this.reportProgress(`任务失败: ${task.subject} - ${result.summary}`);
+            }
+        }
+        else {
+            this.reportProgress(`任务完成: ${task.subject}`);
+        }
+        return result;
+    }
+}
+export default WorkerTaskAgent;
+//# sourceMappingURL=WorkerTaskAgent.js.map

package/dist/agents/WorkerTaskAgent.js.map

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

package/dist/agents/agentP0Message.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Worker (BaseAgent) P0 message dispatching helper.
+ *
+ * 历史问题：BaseAgent 在收到任意 P0 消息时无脑 abort 当前 LLM，
+ * 表现为：worker 正在生成长 tool_input 时，被无关的 P0 事件
+ * （task_complete/task_failed 串扰、agent_health_critical 报告等）
+ * 中断，整轮丢弃，重新思考。
+ *
+ * 真正需要 abort worker 当前 LLM 的 P0 类型只有两种：
+ *   - user_intervention：Leader 通过 send_message_to_agent 注入新指令，
+ *     语义上就是"打断现在做的事"。
+ *   - force_terminate：SessionManager 取消任务，必须立即停。
+ *
+ * 其他 P0（task_complete / task_failed / agent_health_critical）对 worker 而言
+ * 都不是行动指令（要么是其他 agent 的状态、要么是自己的健康报告回声），
+ * 应忽略，不要破坏当前 LLM 的部分输出。
+ */
+export interface AgentP0MessageLite {
+    priority?: number;
+    to?: string;
+    from?: unknown;
+    type?: string;
+}
+export type AgentP0Action = {
+    kind: 'ignore';
+} | {
+    kind: 'abort';
+    sender: string;
+    type: string;
+};
+/**
+ * 决定 worker 收到 P0 消息时应做什么。
+ *
+ * - priority !== 0 / to 不匹配：'ignore'
+ * - from === 'user' 直接来自用户：'ignore'（用户路径走其他通道，与本订阅无关）
+ *   注：现实中 Leader 注入的 user_intervention from 是 leader 的 busName，
+ *   并非字面 'user'，所以这条路径不影响 user_intervention 的中断。
+ * - type ∈ {user_intervention, force_terminate}：'abort'
+ * - 其他类型（task_complete/task_failed/agent_health_critical/未知）：'ignore'
+ */
+export declare function decideAgentP0Action(data: AgentP0MessageLite, busName: string): AgentP0Action;
+//# sourceMappingURL=agentP0Message.d.ts.map

package/dist/agents/agentP0Message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentP0Message.d.ts","sourceRoot":"","sources":["../../src/agents/agentP0Message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAUpD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,MAAM,GACd,aAAa,CAQf"}

package/dist/agents/agentP0Message.js

@@ -0,0 +1,48 @@
+/**
+ * Worker (BaseAgent) P0 message dispatching helper.
+ *
+ * 历史问题：BaseAgent 在收到任意 P0 消息时无脑 abort 当前 LLM，
+ * 表现为：worker 正在生成长 tool_input 时，被无关的 P0 事件
+ * （task_complete/task_failed 串扰、agent_health_critical 报告等）
+ * 中断，整轮丢弃，重新思考。
+ *
+ * 真正需要 abort worker 当前 LLM 的 P0 类型只有两种：
+ *   - user_intervention：Leader 通过 send_message_to_agent 注入新指令，
+ *     语义上就是"打断现在做的事"。
+ *   - force_terminate：SessionManager 取消任务，必须立即停。
+ *
+ * 其他 P0（task_complete / task_failed / agent_health_critical）对 worker 而言
+ * 都不是行动指令（要么是其他 agent 的状态、要么是自己的健康报告回声），
+ * 应忽略，不要破坏当前 LLM 的部分输出。
+ */
+/**
+ * Worker 真正需要 abort 当前 LLM 的 P0 类型集合。
+ */
+const WORKER_ABORT_TYPES = new Set([
+    'user_intervention',
+    'force_terminate',
+]);
+/**
+ * 决定 worker 收到 P0 消息时应做什么。
+ *
+ * - priority !== 0 / to 不匹配：'ignore'
+ * - from === 'user' 直接来自用户：'ignore'（用户路径走其他通道，与本订阅无关）
+ *   注：现实中 Leader 注入的 user_intervention from 是 leader 的 busName，
+ *   并非字面 'user'，所以这条路径不影响 user_intervention 的中断。
+ * - type ∈ {user_intervention, force_terminate}：'abort'
+ * - 其他类型（task_complete/task_failed/agent_health_critical/未知）：'ignore'
+ */
+export function decideAgentP0Action(data, busName) {
+    if (data.priority !== 0)
+        return { kind: 'ignore' };
+    if (data.to !== busName)
+        return { kind: 'ignore' };
+    const sender = String(data.from ?? '');
+    if (sender === 'user')
+        return { kind: 'ignore' };
+    const type = String(data.type ?? '');
+    if (!WORKER_ABORT_TYPES.has(type))
+        return { kind: 'ignore' };
+    return { kind: 'abort', sender, type };
+}
+//# sourceMappingURL=agentP0Message.js.map

package/dist/agents/agentP0Message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentP0Message.js","sourceRoot":"","sources":["../../src/agents/agentP0Message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACzC,mBAAmB;IACnB,iBAAiB;CAClB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAwB,EACxB,OAAe;IAEf,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACnD,IAAI,IAAI,CAAC,EAAE,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACrC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC7D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACzC,CAAC"}

package/dist/agents/errors/TimeoutError.d.ts

@@ -0,0 +1,12 @@
+/**
+ * TimeoutError - Agent 执行超时错误
+ *
+ * 用于标识 Agent 执行超时,触发 Conclude 阶段
+ */
+export declare class TimeoutError extends Error {
+    readonly agentId: string;
+    readonly iteration: number;
+    readonly elapsedMinutes: number;
+    constructor(message: string, agentId: string, iteration: number, elapsedMinutes: number);
+}
+//# sourceMappingURL=TimeoutError.d.ts.map

package/dist/agents/errors/TimeoutError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeoutError.d.ts","sourceRoot":"","sources":["../../../src/agents/errors/TimeoutError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,OAAO,EAAE,MAAM;aACf,SAAS,EAAE,MAAM;aACjB,cAAc,EAAE,MAAM;gBAHtC,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM;CAQzC"}

package/dist/agents/errors/TimeoutError.js

@@ -0,0 +1,20 @@
+/**
+ * TimeoutError - Agent 执行超时错误
+ *
+ * 用于标识 Agent 执行超时,触发 Conclude 阶段
+ */
+export class TimeoutError extends Error {
+    agentId;
+    iteration;
+    elapsedMinutes;
+    constructor(message, agentId, iteration, elapsedMinutes) {
+        super(message);
+        this.agentId = agentId;
+        this.iteration = iteration;
+        this.elapsedMinutes = elapsedMinutes;
+        this.name = 'TimeoutError';
+        // 保持正确的原型链
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}
+//# sourceMappingURL=TimeoutError.js.map

package/dist/agents/errors/TimeoutError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeoutError.js","sourceRoot":"","sources":["../../../src/agents/errors/TimeoutError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGnB;IACA;IACA;IAJlB,YACE,OAAe,EACC,OAAe,EACf,SAAiB,EACjB,cAAsB;QAEtC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,YAAO,GAAP,OAAO,CAAQ;QACf,cAAS,GAAT,SAAS,CAAQ;QACjB,mBAAc,GAAd,cAAc,CAAQ;QAGtC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,WAAW;QACX,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/agents/external/ExternalAgentOrphans.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 扫描并终止孤儿外部 Agent 进程（claude / codex 子进程）。
+ *
+ * 实现策略（跨平台，确定性，与 killOrphanWorkers 对称）：
+ *   1. 主路径 —— 枚举持久化注册表（PidRegistry）中所有 external-agent 条目。
+ *      - 指定 sessionId（会话收尾）：清掉该会话的全部残留外部 Agent。
+ *      - 未指定 sessionId（全局孤儿回收）：仅回收 isOrphanedEntry 判定为真孤儿的条目。
+ *      全平台可用，不再依赖 /proc（旧实现 darwin 会落到 readdirSync('/proc') 抛错再被
+ *      catch 兜底，每次调用都产生 warn 噪声 —— 已根治）。
+ *   2. Linux 补充网 —— 旧版本遗留、未进注册表的孤儿仍可通过 /proc environ 标记兜底回收。
+ *
+ * @param sessionId 如果指定，只清理该 session 的外部 Agent；否则只清理真孤儿
+ * @returns 清理的进程数
+ */
+export declare function killExternalAgentOrphans(sessionId?: string): Promise<number>;
+//# sourceMappingURL=ExternalAgentOrphans.d.ts.map

package/dist/agents/external/ExternalAgentOrphans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExternalAgentOrphans.d.ts","sourceRoot":"","sources":["../../../src/agents/external/ExternalAgentOrphans.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BlF"}

package/dist/agents/external/ExternalAgentOrphans.js

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { agentLogger } from '../../core/Log.js';
+import { killProcess } from '../../utils/platform.js';
+import { PidRegistry, isOrphanedEntry } from '../../core/PidRegistry.js';
+/**
+ * 扫描并终止孤儿外部 Agent 进程（claude / codex 子进程）。
+ *
+ * 实现策略（跨平台，确定性，与 killOrphanWorkers 对称）：
+ *   1. 主路径 —— 枚举持久化注册表（PidRegistry）中所有 external-agent 条目。
+ *      - 指定 sessionId（会话收尾）：清掉该会话的全部残留外部 Agent。
+ *      - 未指定 sessionId（全局孤儿回收）：仅回收 isOrphanedEntry 判定为真孤儿的条目。
+ *      全平台可用，不再依赖 /proc（旧实现 darwin 会落到 readdirSync('/proc') 抛错再被
+ *      catch 兜底，每次调用都产生 warn 噪声 —— 已根治）。
+ *   2. Linux 补充网 —— 旧版本遗留、未进注册表的孤儿仍可通过 /proc environ 标记兜底回收。
+ *
+ * @param sessionId 如果指定，只清理该 session 的外部 Agent；否则只清理真孤儿
+ * @returns 清理的进程数
+ */
+export async function killExternalAgentOrphans(sessionId) {
+    let cleaned = 0;
+    // 主路径：持久化注册表，全平台可用。
+    try {
+        const candidates = PidRegistry.listAll().filter(e => e.kind === 'external-agent');
+        for (const entry of candidates) {
+            if (sessionId) {
+                if (entry.sessionId !== sessionId)
+                    continue;
+            }
+            else if (!isOrphanedEntry(entry)) {
+                continue;
+            }
+            try {
+                await killProcess(entry.pid, 'SIGTERM', { tree: true });
+                cleaned++;
+                PidRegistry.unregister(entry.pid);
+                agentLogger.info(`[ExternalAgentOrphans] Sent SIGTERM to orphan external agent PID ${entry.pid} (session=${entry.sessionId})`);
+            }
+            catch {
+                // Process may have already exited.
+            }
+        }
+    }
+    catch (error) {
+        agentLogger.warn(`[ExternalAgentOrphans] Registry orphan scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Linux 补充网：回收旧版本遗留、未进注册表的孤儿外部 Agent。
+    if (process.platform === 'linux') {
+        cleaned += await scanProcForOrphanExternalAgents(sessionId);
+    }
+    return cleaned;
+}
+/**
+ * Linux /proc 兜底扫描：找出 environ 中带 LINGXIAO_EXTERNAL_AGENT_SESSION 但不在注册表内
+ * 的进程（旧版本遗留孤儿）。已在注册表内的由主路径处理，这里跳过避免重复计数。
+ */
+async function scanProcForOrphanExternalAgents(sessionId) {
+    let cleaned = 0;
+    try {
+        for (const pid of readdirSync('/proc').filter(name => /^\d+$/.test(name))) {
+            try {
+                const envPath = `/proc/${pid}/environ`;
+                if (!existsSync(envPath))
+                    continue;
+                const envContent = readFileSync(envPath, 'utf-8');
+                if (!envContent.includes('LINGXIAO_EXTERNAL_AGENT_SESSION='))
+                    continue;
+                if (sessionId) {
+                    const match = envContent.match(/LINGXIAO_EXTERNAL_AGENT_SESSION=([^\x00]+)/);
+                    if (match && match[1] !== sessionId)
+                        continue;
+                }
+                const pidNum = Number.parseInt(pid, 10);
+                // 已被注册表管辖 → 交主路径处理，避免重复。
+                if (PidRegistry.findByPid(pidNum))
+                    continue;
+                try {
+                    await killProcess(pidNum, 'SIGTERM', { tree: true });
+                    cleaned++;
+                    agentLogger.info(`[ExternalAgentOrphans] /proc fallback: Sent SIGTERM to legacy orphan external agent PID ${pidNum}`);
+                }
+                catch {
+                    // Process may have already exited.
+                }
+            }
+            catch {
+                // Process may have exited or /proc env may be unreadable.
+            }
+        }
+    }
+    catch (error) {
+        agentLogger.warn(`[ExternalAgentOrphans] /proc fallback scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return cleaned;
+}
+//# sourceMappingURL=ExternalAgentOrphans.js.map

package/dist/agents/external/ExternalAgentOrphans.js.map

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

package/dist/agents/external/ExternalAgentRunner.d.ts

@@ -0,0 +1,78 @@
+import type { EventEmitter } from '../../core/EventEmitter.js';
+import type { MessageBus } from '../../core/MessageBus.js';
+import type { DatabaseManager } from '../../core/Database.js';
+import type { TokenTracker } from '../BaseAgentRuntime.js';
+import type { Task as BoardTask, TaskBoard } from '../../core/TaskBoard.js';
+import type { AgentRole } from '../RoleRegistry.js';
+import type { RecoveryFaultClass } from '../../core/RecoveryRecords.js';
+import type { AgentHandle } from '../AgentPoolRuntime.js';
+import type { StructuredCompletionPayload } from '../pool/AgentPoolCompletionPayload.js';
+import type { ExternalAgentInput, ExternalAgentProcessHandle, ExternalDriver, ExternalRunResult } from './types.js';
+import { type ExternalCompletionReport } from './completionReport.js';
+import type { WorkerTaskPayload } from '../../core/WorkerProcessRunner.js';
+import type { WorkerFailureDiagnostics } from '../../core/AgentProtocol.js';
+export interface ExternalAgentRunnerDeps {
+    emitter: EventEmitter;
+    bus: MessageBus;
+    db: DatabaseManager;
+    sessionId: string;
+    leaderBusName: string;
+    sp: (name: string) => string;
+    tokenTracker: TokenTracker;
+    onHandle?: (handle: ExternalAgentProcessHandle) => void;
+}
+export declare class ExternalAgentRunner {
+    private readonly driver;
+    private readonly deps;
+    constructor(driver: ExternalDriver, deps: ExternalAgentRunnerDeps);
+    run(input: ExternalAgentInput): Promise<ExternalRunResult>;
+    private spawnProcess;
+    private feedStdin;
+    private terminateChild;
+    private handleExternalEvent;
+    private setupStreamHandlers;
+    private setupTimers;
+    private handleProcessCompletion;
+}
+/**
+ * ExternalAgentProtocolError：完成报告未通过 worker completion 契约。
+ * faultClass 固定为 'external_agent_protocol'，供恢复分类确定性判定。
+ */
+export declare class ExternalAgentProtocolError extends Error {
+    readonly faultClass: RecoveryFaultClass;
+    constructor(reason: string | undefined, feedback: string);
+}
+/** runExternalAgent 执行体所需的最小结构化上下文。pool 自身满足该结构。 */
+export interface ExternalAgentRunContext {
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly tracker: TokenTracker;
+    readonly db: DatabaseManager;
+    readonly emitter: EventEmitter;
+    readonly bus: MessageBus;
+    readonly taskBoard: TaskBoard;
+    readonly leaderBusName: string;
+    sp(name: string): string;
+    transitionAgentStatus(handle: AgentHandle, newStatus: AgentHandle['status']): void;
+    getTaskRunGeneration(handle: AgentHandle): number;
+    emitAgentEvent<T extends string>(handle: AgentHandle, event: T, payload: Record<string, unknown>): void;
+    emitInteractiveRuntimeState(handle: AgentHandle): void;
+    clearRecoveryRecordAndNotify(taskId: string): void;
+    scheduleHandleCleanup(name: string): void;
+    buildWorkerPayload(handle: AgentHandle, task: BoardTask, role: AgentRole): Promise<WorkerTaskPayload>;
+    assertExternalCompletionAccepted(task: BoardTask, role: AgentRole, completionReport: ExternalCompletionReport, modelId: string): Promise<void>;
+    recordTaskResultPendingAcceptance(handle: AgentHandle, result: string, completionPayload: StructuredCompletionPayload): void;
+    applyWorkerOutputToBlackboard(taskId: string, result: string): void;
+    sendCriticalBusMessageToLeader(to: string, type: 'task_complete' | 'task_failed' | 'worker_recovery', payload: unknown): void;
+    markAgentRecovering(handle: AgentHandle, faultClass: RecoveryFaultClass, reason: string, diagnostics?: WorkerFailureDiagnostics): {
+        status: string;
+        recoveryAction?: string;
+    };
+}
+/**
+ * 从 AgentPool.runExternalAgent 下沉的外部 backend agent 执行体。
+ * 选 driver → 构造 ExternalAgentRunner → run → 解析完成报告 → 校验 → 状态机收尾。
+ * public 接口签名不变，原类方法改为薄委托。
+ */
+export declare function runExternalAgent(ctx: ExternalAgentRunContext, handle: AgentHandle, role: AgentRole, task: BoardTask): Promise<string>;
+//# sourceMappingURL=ExternalAgentRunner.d.ts.map

package/dist/agents/external/ExternalAgentRunner.d.ts.map

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