@zhin.js/agent 0.3.1 → 1.0.2

package/lib/subagent/subagent-runtime.d.ts

@@ -0,0 +1,173 @@
+/**
+ * SubagentRuntime — 后台子任务执行管理器
+ *
+ * 职责：
+ *   1. 接收主 agent 发起的 spawn 请求，创建后台子 agent
+ *   2. 为子 agent 配备受限工具集（文件/Shell/网络，不含消息/spawn/技能）
+ *   3. 管理子 agent 生命周期（运行跟踪、完成/失败回告）
+ *   4. 完成后将结果投递回主流程，由主 agent 摘要后发送到原始频道
+ */
+import { type Message } from '@zhin.js/core';
+import { type AIProvider, type AgentTool, type Usage, type ContentPart, type ModelRegistry } from '@zhin.js/ai';
+import type { ResolvedAgentBinding } from '../config/types.js';
+import type { McpRegistry } from '../orchestrator/mcp-registry.js';
+import { type ZhinAgentConfig } from '../config/index.js';
+import { AgentDispatcher, type AgentRole } from '../orchestrator/agent-dispatcher.js';
+import { type AgentMeta } from '../discovery/agents.js';
+import { type SubagentContextMode } from '../subagent-preset.js';
+import type { ToolCallRecord } from '../core/tool-calls-user-format.js';
+import type { ZhinAgentEventEmitter } from '../event/event-emitter.js';
+export interface SubagentOrigin {
+    message: Message;
+}
+export interface SpawnOptions {
+    task: string;
+    label?: string;
+    origin: SubagentOrigin;
+    /** 配置/route 中的 agent 名（ai.agents + *.agent.md） */
+    agent?: string;
+    /** 显式绑定（优先于 agent 名解析） */
+    binding?: ResolvedAgentBinding;
+    /** 来自 *.agent.md 正文的 system prompt */
+    systemPrompt?: string;
+    /** Agent 角色（可选，默认为 'subtask'） */
+    role?: AgentRole;
+    /** fork | fresh；缺省由预设或角色决定 */
+    contextMode?: SubagentContextMode;
+    /** fork 时由 SubagentRuntime 注入的主会话快照（内部） */
+    contextPreamble?: string;
+    /** 任务上下文（可选） */
+    context?: Record<string, unknown>;
+    /** 首条 user 消息（含 vision parts）；缺省则用 task 字符串 */
+    runInput?: string | ContentPart[];
+    /** 用于向用户发送「任务【id】:执行通道 => label」进度提示 */
+    notifyContext?: Message;
+    /** 编排 Task ID（Kernel 持久化；Dispatcher 仅内存投影） */
+    orchestrationTaskId?: string;
+    /** spawn_task 声明的子任务工具（与父会话 sessionLoaded 取交集作为初始池） */
+    requestedTools?: string[];
+    /** spawn_task 声明的技能名 */
+    requestedSkills?: string[];
+    /** 父会话已 load 的工具名 */
+    parentSessionLoaded?: string[];
+    /** 父会话已 load 的技能名 */
+    parentLoadedSkills?: string[];
+}
+export interface SubagentLifecycleEvent {
+    phase: 'spawn' | 'start' | 'finish';
+    taskId: string;
+    label: string;
+    task: string;
+    origin: SubagentOrigin;
+    role?: AgentRole;
+    /** ai.agents 名，如 pm / architect / dev */
+    agent?: string;
+    status?: 'ok' | 'error';
+    result?: string;
+    error?: string;
+}
+/** Async subagent completion payload — delivered to main agent first. */
+export interface SubagentCompletePayload {
+    taskId: string;
+    label: string;
+    task: string;
+    origin: SubagentOrigin;
+    status: 'ok' | 'error';
+    result: string;
+    toolCalls: ToolCallRecord[];
+    agent?: string;
+}
+export interface SubagentResultDelivery {
+    text: string;
+    toolCalls?: {
+        tool: string;
+        args: Record<string, any>;
+        result: any;
+    }[] | ToolCallRecord[];
+    /** 主 Agent deferred auto-continue turn 的完整出站元素（优先于 text+toolCalls） */
+    elements?: import('@zhin.js/ai').OutputElement[];
+    /** 子任务 ID（非 IM ResultSink 投递时使用） */
+    taskId?: string;
+    /** 子任务状态（非 IM ResultSink 投递时使用） */
+    status?: 'ok' | 'error';
+}
+export type SubagentResultSender = (origin: SubagentOrigin, delivery: SubagentResultDelivery) => Promise<void>;
+export interface SubagentRuntimeOptions {
+    provider: AIProvider;
+    getProvider?: (alias: string) => AIProvider;
+    resolveBinding?: (agentName: string) => ResolvedAgentBinding | null;
+    getMcpRegistry?: () => McpRegistry | null;
+    workspace: string;
+    createTools: () => AgentTool[];
+    subagentTools?: string[];
+    maxIterations?: number;
+    /** 并行子 agent 硬上限（ADR 0030） */
+    maxParallelSubagents?: number;
+    /** Exec policy config to enforce on subagent bash tools */
+    execPolicyConfig?: Required<ZhinAgentConfig>;
+    modelRegistry?: ModelRegistry | null;
+    /** 子 agent 完成后回传 token 用量（并入主会话 turn 统计） */
+    onSubagentUsage?: (usage: Usage) => void;
+    /** 注册子 agent 生命周期 Promise，供主会话在 turn 结束前可选等待 */
+    registerSubagentTask?: (done: Promise<void>) => void;
+    /** Agent 调度器（可选，用于角色管理） */
+    agentDispatcher?: AgentDispatcher;
+    /** 生命周期事件回调（供上层桥接到统一事件总线） */
+    onEvent?: (event: SubagentLifecycleEvent) => void | Promise<void>;
+    /** 异步子 agent 完成：结果交还主 agent（优先于 resultSender） */
+    onSubagentComplete?: (payload: SubagentCompletePayload) => Promise<void>;
+    /** 与主 ZhinAgent 相同的 AI 处理事件总线（processing / tool / mcp 等） */
+    eventEmitter?: ZhinAgentEventEmitter | null;
+    /** 解析 *.agent.md 元数据 */
+    resolveAgentMeta?: (agentName: string) => Promise<AgentMeta | null>;
+    /** fork 模式：主会话 active_leaf 快照 */
+    getParentContextSnapshot?: (origin: SubagentOrigin) => Promise<string | undefined>;
+}
+export declare class SubagentRuntime {
+    private provider;
+    private getProviderFn;
+    private resolveBindingFn;
+    private getMcpRegistryFn;
+    private workspace;
+    private createTools;
+    private maxIterations;
+    private maxParallelSubagents;
+    private subagentTools;
+    private execPolicyConfig;
+    private modelRegistry;
+    private runningTasks;
+    private resultSender;
+    private onSubagentUsage;
+    private registerSubagentTask;
+    private agentDispatcher;
+    private onEvent;
+    private onSubagentCompleteFn;
+    private eventEmitter;
+    private resolveAgentMetaFn;
+    private getParentContextSnapshotFn;
+    constructor(options: SubagentRuntimeOptions);
+    setEventEmitter(emitter: ZhinAgentEventEmitter | null): void;
+    setSender(sender: SubagentResultSender): void;
+    setModelRegistry(registry: ModelRegistry | null): void;
+    configureRouting(deps: {
+        getProvider?: (alias: string) => AIProvider;
+        resolveBinding?: (agentName: string) => ResolvedAgentBinding | null;
+        getMcpRegistry?: () => McpRegistry | null;
+        resolveAgentMeta?: (agentName: string) => Promise<AgentMeta | null>;
+        getParentContextSnapshot?: (origin: SubagentOrigin) => Promise<string | undefined>;
+    }): void;
+    private enrichSpawnOptions;
+    /** 同步执行子 agent（入站 route 用）；返回最终文本，不经过 resultSender */
+    spawnSync(options: SpawnOptions): Promise<string>;
+    spawn(options: SpawnOptions): Promise<string>;
+    getRunningCount(): number;
+    cancel(taskId: string): boolean;
+    private parallelCapacityError;
+    private trackRunningTask;
+    private releaseRunningTask;
+    private runSubagent;
+    private deliverAsyncResult;
+    private buildSubagentPrompt;
+    dispose(): void;
+}
+//# sourceMappingURL=subagent-runtime.d.ts.map

package/lib/subagent/subagent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-runtime.d.ts","sourceRoot":"","sources":["../../src/subagent/subagent-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAA2B,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzI,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAK/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1E,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACf,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,KAAK,SAAS,EAAgD,MAAM,wBAAwB,CAAC;AAOtG,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAQxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAQvE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAClC,wCAAwC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,qBAAqB;IACrB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,qBAAqB;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,EAAE,GAAG,cAAc,EAAE,CAAC;IAC1F,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,aAAa,EAAE,aAAa,EAAE,CAAC;IACjD,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,sBAAsB,KAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,UAAU,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,CAAC;IAC5C,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,CAAC;IACpE,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,SAAS,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC7C,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,4CAA4C;IAC5C,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzC,gDAAgD;IAChD,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACrD,2BAA2B;IAC3B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,4DAA4D;IAC5D,YAAY,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC5C,wBAAwB;IACxB,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACpE,iCAAiC;IACjC,wBAAwB,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACpF;AAMD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,gBAAgB,CAA8D;IACtF,OAAO,CAAC,gBAAgB,CAAoC;IAC5D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,gBAAgB,CAAmC;IAC3D,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,oBAAoB,CAAyC;IACrE,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,OAAO,CAAmE;IAClF,OAAO,CAAC,oBAAoB,CAA+D;IAC3F,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,kBAAkB,CAA4D;IACtF,OAAO,CAAC,0BAA0B,CAAmE;gBAEzF,OAAO,EAAE,sBAAsB;IAsB3C,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI;IAI5D,SAAS,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAI7C,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI;IAItD,gBAAgB,CAAC,IAAI,EAAE;QACrB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,CAAC;QAC5C,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,CAAC;QACpE,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;QAC1C,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACpE,wBAAwB,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;KACpF,GAAG,IAAI;YAQM,kBAAkB;IA6BhC,sDAAsD;IAChD,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA+CjD,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA+DnD,eAAe,IAAI,MAAM;IAIzB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAY/B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,kBAAkB;YAMZ,WAAW;YAoPX,kBAAkB;IAoChC,OAAO,CAAC,mBAAmB;IAiC3B,OAAO,IAAI,IAAI;CAMhB"}