@cicctencent/agent-core 1.0.25 → 1.0.27

package/dist/cjs/run-capability/script-package-runner.js

@@ -0,0 +1,171 @@
+"use strict";
+// ============================================================
+// DefaultScriptPackageRunner — 基于 CodeSandbox 的轻量默认实现
+// ============================================================
+// 职责（对应 docs/FLOW_ORCHESTRATION.md §3.2）：
+//   1. 读取脚本入口内容（物化脚本包由调用方负责）
+//   2. artifact 挂载：复制产物文件到沙箱工作目录
+//   3. 注入 inputs / artifacts 映射（前置 JSON 注入，语言适配）
+//   4. 经 CodeSandbox.execute 执行
+//   5. 解析 __FLOW_RESULT__ 哨兵，返回结构化结果
+// 依赖注入 CodeSandbox 接口（而非具体实现），实现可替换。
+// ============================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultScriptPackageRunner = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const types_ts_1 = require("./types.js");
+class DefaultScriptPackageRunner {
+    sandboxProvider;
+    constructor(sandboxProvider) {
+        this.sandboxProvider = sandboxProvider;
+    }
+    async resolveSandbox() {
+        const p = this.sandboxProvider;
+        return typeof p === 'function' ? await p() : p;
+    }
+    async run(req) {
+        const sandbox = await this.resolveSandbox();
+        // 1. 取代码
+        let code = req.code;
+        if (!code) {
+            if (!req.entryFile) {
+                throw new Error('ScriptRunRequest requires code or entryFile');
+            }
+            code = await fs.readFile(req.entryFile, 'utf-8');
+        }
+        // 2. artifact 挂载：复制到沙箱工作目录，构建 名称→文件名 映射
+        const artifactMap = await this.mountArtifacts(sandbox, req.artifactMounts || {});
+        // 3. shell 模式：将用户代码写入独立文件再 source，避免 prelude 干扰
+        let shellUserCodeFile = null;
+        if (req.language === 'shell') {
+            shellUserCodeFile = path.join(sandbox.rootDir, `__flow_user_${Date.now()}.sh`);
+            await fs.writeFile(shellUserCodeFile, code, 'utf-8');
+        }
+        // 4. 注入 prelude（语言适配）
+        const finalCode = this.buildFinalCode(req.language, code, req.inputs || {}, artifactMap, shellUserCodeFile);
+        // 5. 执行
+        const result = await sandbox.execute(finalCode, req.language, req.timeoutMs);
+        // 6. 解析哨兵
+        const parsed = this.parseResult(result.stdout);
+        return {
+            ok: result.exitCode === 0 && !parsed.parseError,
+            output: parsed.output,
+            stdout: parsed.cleanStdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+            files: result.files,
+            duration: result.duration,
+            error: result.exitCode !== 0
+                ? result.stderr || `exit code ${result.exitCode}`
+                : parsed.parseError,
+        };
+    }
+    /** 复制产物文件到沙箱工作目录，返回 名称→文件名 映射 */
+    async mountArtifacts(sandbox, mounts) {
+        const map = {};
+        for (const [name, srcPath] of Object.entries(mounts)) {
+            const fileName = path.basename(srcPath);
+            const dest = path.join(sandbox.rootDir, fileName);
+            await fs.copyFile(srcPath, dest);
+            map[name] = fileName;
+        }
+        return map;
+    }
+    /**
+     * 构建注入 inputs/artifacts 后的最终代码。
+     * Node：const __inputs__ = ...; const __artifacts__ = ...; 前缀
+     * Python：json.loads 包裹（JSON 字面量非合法 Python）
+     */
+    buildFinalCode(language, code, inputs, artifacts, shellUserCodeFile) {
+        const inputsJson = JSON.stringify(inputs);
+        const artifactsJson = JSON.stringify(artifacts);
+        if (language === 'python') {
+            return [
+                'import json as __flow_json__',
+                `__inputs__ = __flow_json__.loads(${JSON.stringify(inputsJson)})`,
+                `__artifacts__ = __flow_json__.loads(${JSON.stringify(artifactsJson)})`,
+                '',
+                code,
+            ].join('\n');
+        }
+        if (language === 'nodejs') {
+            return [
+                `const __inputs__ = ${inputsJson};`,
+                `const __artifacts__ = ${artifactsJson};`,
+                '',
+                code,
+            ].join('\n');
+        }
+        // shell：通过环境变量注入，用户代码独立文件 source 执行（防 prelude 干扰）
+        const prelude = [
+            `export __INPUTS__='${inputsJson.replace(/'/g, `'\\''`)}'`,
+            `export __ARTIFACTS__='${artifactsJson.replace(/'/g, `'\\''`)}'`,
+        ];
+        if (shellUserCodeFile) {
+            const safePath = shellUserCodeFile.replace(/'/g, `'\\''`);
+            prelude.push(`source '${safePath}'`);
+        }
+        else {
+            prelude.push('', code);
+        }
+        return prelude.join('\n');
+    }
+    /** 从 stdout 解析 __FLOW_RESULT__ 行，其余行作为日志保留 */
+    parseResult(stdout) {
+        const lines = stdout.split('\n');
+        const kept = [];
+        let output;
+        let parseError;
+        for (const line of lines) {
+            const idx = line.indexOf(types_ts_1.FLOW_RESULT_MARKER);
+            if (idx < 0) {
+                kept.push(line);
+                continue;
+            }
+            const jsonText = line.slice(idx + types_ts_1.FLOW_RESULT_MARKER.length).trim();
+            try {
+                output = JSON.parse(jsonText);
+            }
+            catch (e) {
+                parseError = `invalid ${types_ts_1.FLOW_RESULT_MARKER} JSON: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        return { output, cleanStdout: kept.join('\n'), parseError };
+    }
+}
+exports.DefaultScriptPackageRunner = DefaultScriptPackageRunner;
+//# sourceMappingURL=script-package-runner.js.map

package/dist/cjs/run-capability/script-package-runner.js.map

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

package/dist/cjs/run-capability/skill-script-runner.d.ts

@@ -0,0 +1,19 @@
+import type { CodeSandbox } from '../sandbox/code-sandbox.js';
+import { type ScriptPackageRunner, type ScriptRunRequest, type ScriptRunResult } from './types.js';
+/** 沙箱供给：同步实例或异步工厂（如按会话惰性创建沙箱） */
+export type SandboxProvider = CodeSandbox | (() => Promise<CodeSandbox>);
+export declare class SkillScriptPackageRunner implements ScriptPackageRunner {
+    private readonly skillsRoot;
+    private readonly sandboxProvider;
+    private readonly fallback;
+    /**
+     * @param skillsRoot   运行时 skill 物化根目录（绝对路径），如 <cwd>/data/skills
+     * @param sandboxProvider 沙箱（data/sandboxes 下）
+     * @param fallback     非整包请求时回退的 runner（默认逻辑）
+     */
+    constructor(skillsRoot: string, sandboxProvider: SandboxProvider, fallback: ScriptPackageRunner);
+    private resolveSandbox;
+    run(req: ScriptRunRequest): Promise<ScriptRunResult>;
+    private runSkillPackage;
+}
+//# sourceMappingURL=skill-script-runner.d.ts.map

package/dist/cjs/run-capability/skill-script-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-script-runner.d.ts","sourceRoot":"","sources":["../../../src/run-capability/skill-script-runner.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAEH,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACvB,MAAM,YAAY,CAAC;AAEpB,iCAAiC;AACjC,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AAuBzE,qBAAa,wBAAyB,YAAW,mBAAmB;IAO5D,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR7B;;;;OAIG;gBAEkB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,mBAAmB;YAGpC,cAAc;IAKtB,GAAG,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;YAS5C,eAAe;CAoDhC"}

package/dist/cjs/run-capability/skill-script-runner.js

@@ -0,0 +1,165 @@
+"use strict";
+// ============================================================
+// SkillScriptPackageRunner — skill 整包执行（复用 data/skills + sandboxes）
+// ============================================================
+// 设计动机（见 docs/FLOW_ORCHESTRATION.md §3.2 与对话决策）：
+//   Flow 的 script 阶段常需运行一个 skill 包里的脚本（如 investment-strategy
+//   的 sync_pools.py），这类脚本依赖整包上下文——顶层 lib.py / config.py 以及
+//   自身 SKILL_DIR 路径推导。DefaultScriptPackageRunner 只把单文件 entryFile
+//   丢进沙箱，丢失了包结构，导致 `ModuleNotFoundError: No module named 'lib'`。
+//
+// 本实现不另造执行环境，直接复用既有约定：
+//   - 源：运行时已物化在 <skillsRoot>/<skillPath> 的 skill 包（data/skills）
+//   - 沙箱：调用方提供的 CodeSandbox（data/sandboxes 下）
+//   把整个包目录树复制到沙箱 rootDir（保留结构），再以 CLI 范式运行入口脚本。
+//
+// 非整包请求（提供 entryFile/code）自动回退给 DefaultScriptPackageRunner，
+// 保持向后兼容。
+// ============================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillScriptPackageRunner = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const types_ts_1 = require("./types.js");
+/** 递归复制目录树（保留相对结构） */
+async function copyDirRecursive(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === '__pycache__' || entry.name.startsWith('.')) {
+                continue; // 跳过缓存/隐藏目录
+            }
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+class SkillScriptPackageRunner {
+    skillsRoot;
+    sandboxProvider;
+    fallback;
+    /**
+     * @param skillsRoot   运行时 skill 物化根目录（绝对路径），如 <cwd>/data/skills
+     * @param sandboxProvider 沙箱（data/sandboxes 下）
+     * @param fallback     非整包请求时回退的 runner（默认逻辑）
+     */
+    constructor(skillsRoot, sandboxProvider, fallback) {
+        this.skillsRoot = skillsRoot;
+        this.sandboxProvider = sandboxProvider;
+        this.fallback = fallback;
+    }
+    async resolveSandbox() {
+        const p = this.sandboxProvider;
+        return typeof p === 'function' ? await p() : p;
+    }
+    async run(req) {
+        // 整包模式：skillPath 存在时走 skill 整包执行
+        if (req.skillPath && req.entry) {
+            return this.runSkillPackage(req);
+        }
+        // 否则回退到默认单文件行为（entryFile / code）
+        return this.fallback.run(req);
+    }
+    async runSkillPackage(req) {
+        const sandbox = await this.resolveSandbox();
+        const rootDir = sandbox.rootDir;
+        // 1. 整包物化：把 <skillsRoot>/<skillPath> 整个目录树复制到沙箱 rootDir
+        const pkgSrc = path.join(this.skillsRoot, req.skillPath);
+        await copyDirRecursive(pkgSrc, rootDir);
+        // 2. 构造 launcher：在沙箱内以 CLI 范式运行 <entry> + argv，cwd = rootDir，
+        //    并透传子进程 stdout/stderr（含 __FLOW_RESULT__ 哨兵行），便于解析。
+        const entryAbs = path.join(rootDir, req.entry);
+        const argv = Array.isArray(req.argv) ? req.argv : [];
+        const launcher = [
+            'import subprocess, sys, json',
+            'entry = ' + JSON.stringify(entryAbs),
+            'argv = ' + JSON.stringify(argv),
+            'proc = subprocess.run([sys.executable, entry, *argv],',
+            '                     cwd=' + JSON.stringify(rootDir) + ',',
+            '                     capture_output=True, text=True)',
+            'if proc.stdout:',
+            '    sys.stdout.write(proc.stdout)',
+            'if proc.stderr:',
+            '    sys.stderr.write(proc.stderr)',
+            'sys.exit(proc.returncode)',
+        ].join('\n');
+        // 3. 执行（launcher 本身为 python）
+        const result = await sandbox.execute(launcher, (req.language === 'python' ? 'python' : 'python'), req.timeoutMs);
+        // 4. 解析哨兵（launcher 已透传子进程 stdout）
+        const parsed = parseResultMarker(result.stdout);
+        return {
+            ok: result.exitCode === 0 && !parsed.parseError,
+            output: parsed.output,
+            stdout: parsed.cleanStdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+            files: result.files,
+            duration: result.duration,
+            error: result.exitCode !== 0
+                ? result.stderr || `exit code ${result.exitCode}`
+                : parsed.parseError,
+        };
+    }
+}
+exports.SkillScriptPackageRunner = SkillScriptPackageRunner;
+/** 从 stdout 解析 __FLOW_RESULT__ 行，其余行作为日志保留 */
+function parseResultMarker(stdout) {
+    const lines = stdout.split('\n');
+    const kept = [];
+    let output;
+    let parseError;
+    for (const line of lines) {
+        const idx = line.indexOf(types_ts_1.FLOW_RESULT_MARKER);
+        if (idx < 0) {
+            kept.push(line);
+            continue;
+        }
+        const jsonText = line.slice(idx + types_ts_1.FLOW_RESULT_MARKER.length).trim();
+        try {
+            output = JSON.parse(jsonText);
+        }
+        catch (e) {
+            parseError = `invalid ${types_ts_1.FLOW_RESULT_MARKER} JSON: ${e instanceof Error ? e.message : String(e)}`;
+        }
+    }
+    return { output, cleanStdout: kept.join('\n'), parseError };
+}
+//# sourceMappingURL=skill-script-runner.js.map

package/dist/cjs/run-capability/skill-script-runner.js.map

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

package/dist/cjs/run-capability/types.d.ts

@@ -0,0 +1,50 @@
+import type { ScriptLanguage } from '../sandbox/types.js';
+/** 脚本输出哨兵前缀（stdout 单行协议） */
+export declare const FLOW_RESULT_MARKER = "__FLOW_RESULT__";
+/** 脚本运行请求 */
+export interface ScriptRunRequest {
+    /** 方式一：物化后的脚本包入口文件绝对路径（index.js / index.py） */
+    entryFile?: string;
+    /** 方式二：直接代码内容（优先于 entryFile） */
+    code?: string;
+    /**
+     * 方式三（skill 整包）：运行时已物化在 <skillsRoot>/<skillPath> 的 skill 包。
+     * Runner 会把整个包目录树复制到沙箱（保留结构，使顶层 lib.py/config.py 等
+     * 同包依赖可被 import），并以 <skillPath>/<entry> 作为 CLI 入口执行。
+     * 与 entryFile/code 互斥；当 skillPath 存在时优先采用整包模式。
+     */
+    skillPath?: string;
+    /** 整包模式下的入口脚本相对路径，如 "pool-manager/scripts/sync_pools.py" */
+    entry?: string;
+    /** 整包模式下传给入口脚本的命令行参数（CLI 范式，如 ["--preflight"]） */
+    argv?: string[];
+    /** 脚本语言 */
+    language: ScriptLanguage;
+    /** 注入脚本的输入（前置 JSON 注入） */
+    inputs?: Record<string, unknown>;
+    /**
+     * 挂载进沙箱工作目录的产物文件路径列表（fetch 阶段落盘的 artifact）。
+     * Runner 将其复制到沙箱 rootDir，并把 名称→文件名 映射注入脚本。
+     */
+    artifactMounts?: Record<string, string>;
+    /** 执行超时 (ms) */
+    timeoutMs?: number;
+}
+/** 脚本运行结构化结果 */
+export interface ScriptRunResult {
+    ok: boolean;
+    /** __FLOW_RESULT__ 解析出的结构化输出（脚本未输出则为 undefined） */
+    output?: unknown;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /** 沙箱工作目录中新产生的文件（相对路径） */
+    files: string[];
+    duration: number;
+    error?: string;
+}
+/** 脚本包运行器（统一契约，实现可替换） */
+export interface ScriptPackageRunner {
+    run(req: ScriptRunRequest): Promise<ScriptRunResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/run-capability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/run-capability/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,4BAA4B;AAC5B,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,aAAa;AACb,MAAM,WAAW,gBAAgB;IAC7B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,gBAAgB;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yBAAyB;AACzB,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACxD"}

package/dist/cjs/run-capability/types.js

@@ -0,0 +1,16 @@
+"use strict";
+// ============================================================
+// RunCapability — 语言无关脚本运行契约
+// ============================================================
+// 定位：通用流程编排底座的 script 能力后端（见 docs/FLOW_ORCHESTRATION.md）。
+// 只定义契约与轻量默认实现，不感知任何业务（回测/报表等）。
+//
+// 输出协议（与自动化任务 __NODE_AUTOMATION_RESULT__ 风格一致）：
+//   脚本通过 stdout 打印一行：__FLOW_RESULT__ + JSON.stringify(output)
+//   Runner 从 stdout 中解析该行作为结构化结果，其余 stdout 作为日志透传。
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOW_RESULT_MARKER = void 0;
+/** 脚本输出哨兵前缀（stdout 单行协议） */
+exports.FLOW_RESULT_MARKER = '__FLOW_RESULT__';
+//# sourceMappingURL=types.js.map

package/dist/cjs/run-capability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/run-capability/types.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,6BAA6B;AAC7B,+DAA+D;AAC/D,0DAA0D;AAC1D,gCAAgC;AAChC,EAAE;AACF,gDAAgD;AAChD,8DAA8D;AAC9D,mDAAmD;AACnD,+DAA+D;;;AAI/D,4BAA4B;AACf,QAAA,kBAAkB,GAAG,iBAAiB,CAAC"}

package/dist/esm/a2a/index.d.ts

@@ -3,8 +3,8 @@ export { A2AClient, buildAuthHeaders } from './client.js';
 export type { AuthConfig, A2AClientOptions, AgentDebugTrace, AgentDebugTraceHandler } from './client.js';
 export { createA2ARemoteRunner, extractTextFromMessage } from './runner.js';
 export type { A2ARemoteRunnerConfig } from './runner.js';
-export { A2AServerHandler, InMemoryA2ATaskStore, createA2AAgentCard, createA2AMessage, mapAgentEventToA2AEvent, } from './server.js';
-export type { A2AHandlerResponse, A2AServerAgentConfig, A2AServerHandlerOptions, A2AStreamingJsonRpcResponse, A2ATaskStore, } from './server.js';
+export { A2AServerHandler, InMemoryA2ATaskStore, createA2AAgentCard, createA2AMessage, mapAgentEventToA2AEvent, DEFAULT_A2A_EVENT_MAPPERS, withHeartbeat, } from './server.js';
+export type { A2AHandlerResponse, A2AServerAgentConfig, A2AServerHandlerOptions, A2AStreamingJsonRpcResponse, A2ATaskStore, A2AEventMapper, A2AEventAccumulator, A2ATaskRunner, A2ARunContext, HeartbeatItem, } from './server.js';
 export { RestA2AClient } from './rest-client.js';
 export type { RestCapabilityCard, RestCapabilityResult, RestSSEEvent, RestTaskStatus, RestA2AClientOptions, } from './rest-client.js';
 export { createRestA2ARemoteRunner } from './rest-runner.js';

package/dist/esm/a2a/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/a2a/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,WAAW,EACX,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,OAAO,EACP,wBAAwB,EACxB,0BAA0B,EAC1B,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEzG,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/a2a/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,WAAW,EACX,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,EACb,WAAW,EACX,OAAO,EACP,wBAAwB,EACxB,0BAA0B,EAC1B,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEzG,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/a2a/index.js

@@ -3,7 +3,7 @@
 // ============================================================
 export { A2AClient, buildAuthHeaders } from "./client.js";
 export { createA2ARemoteRunner, extractTextFromMessage } from "./runner.js";
-export { A2AServerHandler, InMemoryA2ATaskStore, createA2AAgentCard, createA2AMessage, mapAgentEventToA2AEvent, } from "./server.js";
+export { A2AServerHandler, InMemoryA2ATaskStore, createA2AAgentCard, createA2AMessage, mapAgentEventToA2AEvent, DEFAULT_A2A_EVENT_MAPPERS, withHeartbeat, } from "./server.js";
 // ---- REST 风格 A2A ----
 export { RestA2AClient } from "./rest-client.js";
 export { createRestA2ARemoteRunner } from "./rest-runner.js";

package/dist/esm/a2a/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/a2a/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,aAAa;AACb,+DAA+D;AA4B/D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG5E,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AASrB,wBAAwB;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/a2a/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,aAAa;AACb,+DAA+D;AA4B/D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG5E,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,GACd,MAAM,aAAa,CAAC;AAcrB,wBAAwB;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/a2a/server.d.ts

@@ -16,10 +16,75 @@ export interface A2ATaskStore {
     set(task: A2ATask): void | Promise<void>;
     delete?(id: string): void | Promise<void>;
 }
+/**
+ * 引擎事件 → A2A 事件映射器。
+ *
+ * 返回 `null` 表示该事件不转发到 A2A 流（静默丢弃）。
+ * `acc` 在单次运行内共享，可用于累积最终文本等跨事件状态。
+ */
+export type A2AEventMapper = (event: AgentEvent, task: A2ATask, acc: A2AEventAccumulator) => A2ATaskEvent | null;
+/** 单次运行内共享的累积状态 */
+export interface A2AEventAccumulator {
+    /** 累积的最终文本输出 */
+    finalText: string;
+    /** 供自定义映射器存放任意中间状态 */
+    [key: string]: unknown;
+}
+/** 单次 A2A 任务运行的上下文 */
+export interface A2ARunContext {
+    task: A2ATask;
+    params: A2ASendTaskParams;
+    /** 从 params.message 提取的纯文本 prompt */
+    message: string;
+    /** 取消信号 —— 由 tasks/cancel 或客户端断连触发 */
+    abortSignal: AbortSignal;
+}
+/**
+ * 任务执行器：产出引擎事件流。
+ *
+ * 相较 `getEngine`，本接口不假设事件来自 `AgentEngine`，
+ * 从而允许接入方在自有服务层（多租户解析、线程落库、可观测性等）
+ * 之上驱动运行，仍复用内核的协议编排、心跳与取消能力。
+ */
+export type A2ATaskRunner = (ctx: A2ARunContext) => AsyncIterable<AgentEvent>;
 export interface A2AServerHandlerOptions {
-    getEngine: (params: A2ASendTaskParams) => AgentEngine | Promise<AgentEngine>;
+    /**
+     * 引擎工厂（便捷路径）：内核负责调用 `engine.run(...)`。
+     * 与 `runTask` 二选一；同时提供时 `runTask` 优先。
+     */
+    getEngine?: (params: A2ASendTaskParams) => AgentEngine | Promise<AgentEngine>;
+    /**
+     * 自定义任务执行器（高级路径）：接管事件来源。
+     *
+     * 适用于事件由应用服务层产生（而非直接操作 AgentEngine）的场景，
+     * 内核依旧提供任务状态机、心跳、取消与事件映射。
+     */
+    runTask?: A2ATaskRunner;
     buildRunOptions?: (params: A2ASendTaskParams, task: A2ATask) => Partial<RunOptions> | Promise<Partial<RunOptions>>;
     taskStore?: A2ATaskStore;
+    /**
+     * 自定义事件映射表（按 `AgentEvent.type` 索引），覆盖同名的内置映射。
+     *
+     * 用于接入方按需改写事件形态，新增事件类型只需加一行映射，
+     * 无需修改流式主循环。返回 `null` 的事件不会下发。
+     */
+    eventMappers?: Record<string, A2AEventMapper>;
+    /**
+     * 未被内置或自定义映射覆盖的事件的兜底处理。
+     * - `'drop'`（默认）：丢弃，保持 A2A 流干净
+     * - `'passthrough'`：以 `metadata` 形式透传，便于调试或富客户端消费
+     */
+    unknownEventStrategy?: 'drop' | 'passthrough';
+    /**
+     * SSE 心跳间隔（毫秒）。设为 `0` 或不设则禁用。
+     *
+     * 引擎长时间无事件输出时（如长工具调用），定期产出心跳事件，
+     * 避免中间代理/网关因空闲超时切断连接。
+     */
+    heartbeatIntervalMs?: number;
+    /** 任务生命周期钩子（落库、指标、会话映射等副作用挂载点） */
+    onTaskCreated?: (task: A2ATask, params: A2ASendTaskParams) => void | Promise<void>;
+    onTaskUpdated?: (task: A2ATask) => void | Promise<void>;
 }
 export interface A2AStreamingJsonRpcResponse {
     jsonrpc: '2.0';
@@ -35,14 +100,61 @@ export declare class InMemoryA2ATaskStore implements A2ATaskStore {
 }
 export declare function createA2AAgentCard(config: A2AServerAgentConfig): A2AAgentCard;
 export declare function createA2AMessage(text: string, role?: 'user' | 'agent', taskId?: string, contextId?: string): A2AMessage;
+/** withHeartbeat 产出项：引擎事件或保活心跳 */
+export type HeartbeatItem<T> = {
+    kind: 'event';
+    value: T;
+} | {
+    kind: 'heartbeat';
+};
+/**
+ * 为任意异步迭代器叠加心跳保活。
+ *
+ * 当上游在 `intervalMs` 内没有产出事件时，产出一个 `heartbeat` 项，
+ * 供调用方下发 keep-alive，避免反向代理因空闲超时切断长连接。
+ *
+ * 实现要点（手写 race 极易出错之处）：
+ * 1. `pending` 跨轮复用 —— 心跳胜出时**不能**丢弃已发起的 `next()`，
+ *    否则会漏事件或重复消费迭代器；
+ * 2. 定时器在每轮 `finally` 中**必定清理** —— 否则长任务会累积大量
+ *    游离 timer，持续占用事件循环；
+ * 3. 结束时调用上游 `return()` —— 保证下游提前 break 时上游能及时释放。
+ */
+export declare function withHeartbeat<T>(source: AsyncIterable<T>, intervalMs: number, abortSignal?: AbortSignal): AsyncGenerator<HeartbeatItem<T>>;
+/**
+ * 内置引擎事件映射表。
+ *
+ * 以表驱动替代 switch，接入方可通过 `eventMappers` 覆盖任意条目
+ * 或新增事件类型，无需改动流式主循环。
+ */
+export declare const DEFAULT_A2A_EVENT_MAPPERS: Record<string, A2AEventMapper>;
+/**
+ * 引擎事件 → A2A 事件的默认映射（保留具名导出以兼容既有调用方）。
+ */
 export declare function mapAgentEventToA2AEvent(event: AgentEvent, task: A2ATask): A2ATaskEvent | null;
 export declare class A2AServerHandler {
     private readonly options;
     private store;
+    private readonly mappers;
+    /** 运行中任务的中止控制器 —— 支撑 tasks/cancel 真正停止引擎 */
+    private readonly running;
     constructor(options: A2AServerHandlerOptions);
+    /** 持久化任务并触发更新钩子（钩子异常不影响协议主流程） */
+    private persist;
+    /**
+     * 解析本次运行的事件流来源。
+     *
+     * 优先使用 `runTask`（应用自行驱动），否则回落到 `getEngine` 便捷路径。
+     * `abortSignal` 一律置于 overrides 展开之后，确保取消链路不被覆盖。
+     */
+    private resolveEventStream;
+    /** 应用映射表，未命中时按 unknownEventStrategy 兜底 */
+    private mapEvent;
     handleJsonRpc(request: A2AJsonRpcRequest): Promise<A2AHandlerResponse>;
     sendTask(params: A2ASendTaskParams): Promise<A2ATask>;
     sendTaskStreaming(params: A2ASendTaskParams): AsyncGenerator<A2ATaskEvent>;
+    /** 创建任务、落库并触发创建钩子 */
+    private beginTask;
     getTask(params: A2AGetTaskParams): Promise<A2ATask>;
     cancelTask(params: A2ACancelTaskParams): Promise<A2ATask>;
     private createSubmittedTask;