@aipack-ai/multi-agent 1.1.5 → 1.1.7

package/dist/index.d.ts

@@ -59,6 +59,22 @@ interface AgentNode {
     inputMapping?: (ctx: SharedContext) => string | Request;
     /** 输出转换：将Agent结果写入SharedContext */
     outputMapping?: (result: Result, ctx: SharedContext) => void;
+    /** 节点级重试配置（失败/超时自动重试，默认不重试） */
+    retry?: NodeRetryOpts;
+    /** 节点级超时（ms）：单次执行超过该时长抛出超时错误（可与 retry 配合重试） */
+    timeoutMs?: number;
+    /**
+     * 依赖的其他节点 ID（仅 Supervisor auto 调度使用）：
+     * 声明后该 Worker 在所依赖的 Worker 全部完成后再执行。
+     */
+    dependsOn?: string[];
+}
+/** 节点级重试配置 */
+interface NodeRetryOpts {
+    /** 最大尝试次数（含首次执行，默认 1 即不重试） */
+    maxAttempts?: number;
+    /** 重试间隔（ms，默认 0 立即重试） */
+    backoffMs?: number;
 }
 /** Agent间流转边 */
 interface AgentEdge {
@@ -110,12 +126,15 @@ interface MultiAgentResult {
     success: boolean;
     /** 错误信息 */
     error?: string;
+    /** 失败的 Agent ID 列表（onWorkerError/onMapperError='skip' 容忍失败时暴露） */
+    failedAgents?: string[];
 }
 /** 多Agent流式事件类型 */
 type MultiAgentEvent = {
     type: 'agent_start';
     agentId: string;
-    agentName: string;
+    agentName: string; /** 该节点的输入摘要（文本） */
+    input?: string;
 } | {
     type: 'agent_result';
     agentId: string;
@@ -150,6 +169,18 @@ type MultiAgentEvent = {
     type: 'graph_error';
     error: string;
 };
+/** 图执行配置选项（createAgentGraph 参数） */
+interface GraphExecutionOpts {
+    /**
+     * 并行分支（多条出边同时匹配）执行时的最大并发数（默认 Infinity，不限制）
+     */
+    concurrency?: number;
+    /**
+     * 单个节点的最大访问次数（环图防死循环安全阀，默认 10）。
+     * 超限时图以 stopReason='max_visits_exceeded' 安全截断
+     */
+    maxVisitsPerNode?: number;
+}
 /** AgentGraph: 编排核心 */
 interface AgentGraph {
     /** 添加Agent节点 */
@@ -168,7 +199,10 @@ interface AgentGraph {
     getState(): GraphExecutionState;
     /** 中止执行 */
     abort(): void;
-    /** 事件监听 */
+    /**
+     * 事件监听：事件名对应 MultiAgentEvent 的 type 字段
+     * （如 'agent_start' / 'agent_result' / 'graph_done'），run 与 stream 均会触发
+     */
     on(event: string, listener: EventListener): this;
 }
 /** Pipeline 配置选项 */
@@ -182,7 +216,10 @@ interface PipelineOpts {
 interface RouterOpts {
     /** 从路由Agent输出中解析目标Agent ID */
     resolve: (routerResult: Result) => string;
-    /** 未匹配到目标时的默认路由Agent ID */
+    /**
+     * 未匹配到目标时的默认路由Agent ID。
+     * resolve 返回的 ID 不在目标列表中时，自动回退路由到该 Agent
+     */
     defaultTarget?: string;
     /** 是否将原始输入传递给目标Agent（默认true），否则传递路由Agent的输出 */
     passOriginalInput?: boolean;
@@ -209,6 +246,12 @@ interface SupervisorOpts {
      * 默认 true
      */
     passOriginalInput?: boolean;
+    /**
+     * Worker 失败策略：
+     * - 'fail-fast': 任一 Worker 失败立即中止（默认，与 sequential 模式语义一致）
+     * - 'skip': 容忍失败，跳过失败的 Worker 继续，失败的 Worker ID 暴露在 result.failedAgents
+     */
+    onWorkerError?: 'fail-fast' | 'skip';
 }
 /** Debate 配置选项 */
 interface DebateOpts {
@@ -227,6 +270,12 @@ interface MapReduceOpts {
     concurrency?: number;
     /** Reducer 的输入格式化（默认将所有 mapper 结果用分隔符连接） */
     reduceInputFormat?: (mapperResults: Map<number, Result>) => string;
+    /**
+     * Mapper 失败策略：
+     * - 'fail-fast': 任一子任务失败立即中止（默认）
+     * - 'skip': 容忍失败，仅汇总成功的子任务，失败的虚拟 Agent ID 暴露在 result.failedAgents
+     */
+    onMapperError?: 'fail-fast' | 'skip';
 }
 /** MCPBridge 配置选项 */
 interface MCPBridgeOpts {
@@ -302,6 +351,22 @@ declare class SimpleToolRegistry implements ToolRegistry {
 /** 创建默认 SharedContext */
 declare function createSharedContext(init?: Partial<SharedContext>): SharedContext;
 
+/**
+ * core/executor.ts - 图执行引擎
+ *
+ * 负责 AgentGraph 的执行逻辑：从入口节点出发，
+ * 根据边条件遍历图，依次执行各节点的 Runtime。
+ */
+
+/** abort() 触发的中止错误，run() 会将其转换为 stopReason='aborted' 的结果 */
+declare class GraphAbortedError extends Error {
+    constructor();
+}
+/** 节点执行超时错误（timeoutMs 触发，可配合 retry 重试） */
+declare class NodeTimeoutError extends Error {
+    constructor(nodeId: string, timeoutMs: number);
+}
+
 /**
  * core/graph.ts - AgentGraph 实现
  *
@@ -310,7 +375,24 @@ declare function createSharedContext(init?: Partial<SharedContext>): SharedConte
  */
 
 /** 创建空的 AgentGraph，通过链式调用定义图结构 */
-declare function createAgentGraph(): AgentGraph;
+declare function createAgentGraph(opts?: GraphExecutionOpts): AgentGraph;
+
+/**
+ * core/event-stream.ts - 流式事件队列工具
+ *
+ * 统一各执行器 stream() 的 push-pull 事件队列实现：
+ * 后台执行图逻辑，事件按发生顺序产出给消费者，
+ * 同时同步分发到外部事件监听（on() API 的 eventSink）。
+ */
+
+/**
+ * 创建流式事件生成器。
+ *
+ * @param execute - 后台执行函数，通过 emit 发出事件；
+ *   返回的 Promise 决不 reject（错误应转换为 graph_error 事件后 resolve）
+ * @param sink - 外部事件监听（可选），异常会被吞掉以防中断事件传播
+ */
+declare function createEventStream(execute: (emit: (event: MultiAgentEvent) => void) => Promise<void>, sink?: (event: MultiAgentEvent) => void): AsyncGenerator<MultiAgentEvent>;
 
 /**
  * patterns/pipeline.ts - Pipeline 顺序链模式
@@ -561,4 +643,4 @@ declare class GraphDebugger {
 /** 创建 GraphDebugger */
 declare function createDebugger(graph: AgentGraph): GraphDebugger;
 
-export { type AgentEdge, type AgentGraph, type AgentNode, type DebateOpts, type EventBus, type EventListener, GraphDebugger, type GraphExecutionState, type GraphTrace, MCPBridge, type MCPBridgeOpts, type MCPToolCallRequest, type MCPToolCallResult, type MCPToolDefinition, type MCPToolParameter, type MapReduceOpts, type MultiAgentEvent, type MultiAgentResult, type NodeExecutionState, type PipelineOpts, type RouterOpts, type ScheduleMode, type SharedContext, SimpleEventBus, SimpleToolRegistry, type SupervisorOpts, type ToolRegistry, type TraceStep, createAgentGraph, createDebate, createDebugger, createMCPBridge, createMapReduce, createMultiAgentMcpServerHost, createPipeline, createRouter, createSharedContext, createSupervisor };
+export { type AgentEdge, type AgentGraph, type AgentNode, type DebateOpts, type EventBus, type EventListener, GraphAbortedError, GraphDebugger, type GraphExecutionOpts, type GraphExecutionState, type GraphTrace, MCPBridge, type MCPBridgeOpts, type MCPToolCallRequest, type MCPToolCallResult, type MCPToolDefinition, type MCPToolParameter, type MapReduceOpts, type MultiAgentEvent, type MultiAgentResult, type NodeExecutionState, type NodeRetryOpts, NodeTimeoutError, type PipelineOpts, type RouterOpts, type ScheduleMode, type SharedContext, SimpleEventBus, SimpleToolRegistry, type SupervisorOpts, type ToolRegistry, type TraceStep, createAgentGraph, createDebate, createDebugger, createEventStream, createMCPBridge, createMapReduce, createMultiAgentMcpServerHost, createPipeline, createRouter, createSharedContext, createSupervisor };