@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/tools/tool-registry.js

@@ -0,0 +1,379 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { NO_INITIATOR } from '../agent-extensions.js';
+import { silentLogger } from '../ports/logger.js';
+import { AgentTool } from './agent-tool.base.js';
+import { digestInputSchema } from './tool-definition.js';
+import { fail } from './tool-result.js';
+const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+/**
+ * 基类工具的注册表侧超时 = 它自己声明的超时 + 这段宽限。
+ *
+ * **两道不是重复，是分工**：基类那道是真正生效的（合成 AbortSignal 让工具停下
+ * + race 兜住不配合的），这一道只防「基类的计时器自己坏了」。宽限拉得足够大，
+ * 使得它一旦真的赢了，就必然是个 bug 而不是正常的慢——否则两道数字相近时，
+ * 你无法从「tool timed out」这句话分辨是工具慢还是计时逻辑坏了。
+ */
+const OUTER_TIMEOUT_GRACE_MS = 60_000;
+/** 注入给 `supportsBackground` 工具的参数。**定义只此一处**（见基类注释）。 */
+const RUN_IN_BACKGROUND_FIELD = {
+    run_in_background: z
+        .boolean()
+        .optional()
+        .describe('是否后台运行。缺省 false = 等它跑完并直接返回结果；' +
+        'true = 立即返回一个 handle，结果稍后作为新消息回到你的上下文。' +
+        '需要并行推进多件事时用 true。'),
+};
+/**
+ * 工具注册表。搬自 agent-base `ToolRegistry`：去掉 Nest 的扫描（宿主显式 `register`，
+ * Nest 适配包负责把装饰器接过来），分组语义改为选项。
+ *
+ * **工具表顺序 = 注册顺序**。工具表一变，前缀缓存整段 miss，所以宿主要按固定顺序注册
+ * （agent-base 以前靠 Nest 模块的导入顺序，隐式且容易被无关改动打乱）。
+ */
+export class ToolRegistry {
+    logger;
+    entries = new Map();
+    /** 旧名 → 现名（`ToolMeta.formerNames`）。 */
+    aliases = new Map();
+    alwaysOn;
+    permissionRequired;
+    hidden;
+    sanitize;
+    constructor(options = {}) {
+        this.logger = (options.logger ?? silentLogger)('ToolRegistry');
+        this.alwaysOn = new Set(options.alwaysOnCategories ?? ['system']);
+        this.permissionRequired = new Set(options.permissionRequiredCategories ?? []);
+        this.hidden = new Set(options.hiddenCategories ?? []);
+        this.sanitize = options.sanitizeError ?? (text => text);
+    }
+    /** 登记一个工具。名字重复、缺 execute / inputSchema、该声明权限没声明 → 抛。 */
+    register(meta, provider) {
+        this.add(meta, provider);
+        this.logger.debug(`registered tool ${meta.name}`);
+    }
+    add(meta, provider) {
+        if (typeof provider?.execute !== 'function') {
+            throw new Error(`tool '${meta.name}' must implement execute()`);
+        }
+        if (!provider.inputSchema) {
+            throw new Error(`tool '${meta.name}' must declare inputSchema`);
+        }
+        if (this.entries.has(meta.name)) {
+            throw new Error(`duplicate tool name '${meta.name}'`);
+        }
+        if (this.aliases.has(meta.name)) {
+            throw new Error(`tool name '${meta.name}' is already a former name of '${this.aliases.get(meta.name)}'`);
+        }
+        for (const former of meta.formerNames ?? []) {
+            if (former === meta.name || this.entries.has(former)) {
+                throw new Error(`former name '${former}' of tool '${meta.name}' is a current tool name`);
+            }
+            if (this.aliases.has(former)) {
+                throw new Error(`former tool name '${former}' is claimed twice`);
+            }
+        }
+        if (this.permissionRequired.has(meta.category) && !meta.permission) {
+            throw new Error(`tool '${meta.name}' is in category '${meta.category}' and must declare a permission`);
+        }
+        // 启动期 fail-fast：声明了后台运行，schema 就必须是个能被 extend 的对象。
+        // 放到运行时才发现的话，症状是模型看不到 run_in_background 这个参数、
+        // 于是永远同步调用——一个不报错、只是功能静默缺席的坏法。
+        if (provider instanceof AgentTool &&
+            provider.capabilities.supportsBackground &&
+            !(provider.inputSchema instanceof z.ZodObject)) {
+            throw new Error(`tool '${meta.name}' declares supportsBackground but its inputSchema is not a z.object()`);
+        }
+        this.entries.set(meta.name, { meta, provider });
+        for (const former of meta.formerNames ?? []) {
+            this.aliases.set(former, meta.name);
+        }
+    }
+    /**
+     * 对外暴露的 schema —— 后台工具在这里被注入 `run_in_background`。
+     *
+     * 注入而非让工具自己写，是为了让这个参数只有一个定义处：它的语义（缺省
+     * 同步、true 返回 handle）对所有工具必须逐字一致，模型才不用逐个工具去猜。
+     */
+    schemaFor(entry) {
+        const base = entry.provider.inputSchema;
+        if (entry.provider instanceof AgentTool &&
+            entry.provider.capabilities.supportsBackground &&
+            base instanceof z.ZodObject) {
+            return base.extend(RUN_IN_BACKGROUND_FIELD);
+        }
+        return base;
+    }
+    /**
+     * 注册表侧的兜底超时。基类工具以它自己声明的值为准（见常量注释）；非基类
+     * provider 只剩测试 stub，一律给默认值。
+     */
+    timeoutFor(entry) {
+        return entry.provider instanceof AgentTool
+            ? entry.provider.capabilities.timeoutMs + OUTER_TIMEOUT_GRACE_MS
+            : DEFAULT_TOOL_TIMEOUT_MS;
+    }
+    listMeta() {
+        return [...this.entries.values()].map(e => e.meta);
+    }
+    /**
+     * 后台 UI 勾选用：恒上桌的分组是基础设施，运营不能关；`hiddenCategories`
+     * 里的不给勾。
+     */
+    listConfigurable() {
+        return this.listMeta().filter(m => !this.alwaysOn.has(m.category) && !this.hidden.has(m.category));
+    }
+    /**
+     * 后台「工具列表」页用：全部工具（含 system）的完整定义。
+     *
+     * 参数表由 `schemaFor(entry)` 摊平——即**喂给模型的那份** schema（后台工具
+     * 注入的 `run_in_background` 一并在内），审阅页与模型看到的定义同源，不另拼
+     * 第二份事实（同 system prompt 审查页的地基约定）。
+     */
+    listDefinitions() {
+        return [...this.entries.values()].map(entry => this.definitionOf(entry));
+    }
+    /**
+     * 后台「会话下一轮预览」用：**这一轮真正端上桌的**那几件的完整定义。过滤判据与
+     * `buildToolSchemasFor` 是同一个 `isAllowed`，参数表同 `listDefinitions`——预览与
+     * 喂给模型的工具集不可能分叉。
+     */
+    definitionsFor(agent, opts) {
+        const exclude = new Set(opts?.exclude ?? []);
+        const initiator = opts?.initiator ?? NO_INITIATOR;
+        return [...this.entries.values()]
+            .filter(e => this.isAllowed(e.meta, agent, exclude, initiator))
+            .map(entry => this.definitionOf(entry, opts?.descriptions?.[entry.meta.name]));
+    }
+    definitionOf(entry, description) {
+        return {
+            ...entry.meta,
+            ...(description !== undefined ? { description } : {}),
+            supportsBackground: entry.provider instanceof AgentTool &&
+                entry.provider.capabilities.supportsBackground,
+            permission: entry.meta.permission ?? null,
+            ...digestInputSchema(this.schemaFor(entry)),
+        };
+    }
+    /** 写入路径严格校验（运行时读取则宽松静默跳过）。 */
+    validateNames(names) {
+        const unknown = names.filter(n => !this.entries.has(n));
+        if (unknown.length > 0) {
+            throw new Error(`unknown tool(s): ${unknown.join(', ')}`);
+        }
+    }
+    /**
+     * 这个工具这一轮对该 agent 可见吗。
+     *
+     * 这里曾经还有一个 `availableToolNames()`，供 system prompt 的引用清单渲染
+     * 「用某某工具取内容」那半句、并按授权过滤工具名。**2026-08-05 随那半句
+     * 一起删除**：工具能做什么，工具描述自己说了，而工具清单本来就在模型手上
+     * （API 请求的 `tools` 字段）——提示词再点一遍名是第二份事实，改个工具名就
+     * 开始说假话。
+     */
+    isAllowed(meta, agent, exclude, initiator) {
+        if (exclude.has(meta.name))
+            return false;
+        if (meta.permission && !initiator.permissions.has(meta.permission)) {
+            return false;
+        }
+        return (this.alwaysOn.has(meta.category) || agent.enabledTools.includes(meta.name));
+    }
+    /**
+     * 旧工具名 → 现名（`ToolMeta.formerNames`）。交给投影（`ProjectionOptions.toolNameAliases`），
+     * 让旧历史里的调用以现名出现在模型面前。
+     */
+    toolNameAliases() {
+        return new Map(this.aliases);
+    }
+    /** 声明了权限点的工具名 → 那个权限点（`ToolMeta.permission`）。 */
+    permissionGatedTools() {
+        const out = new Map();
+        for (const { meta } of this.entries.values()) {
+            if (meta.permission)
+                out.set(meta.name, meta.permission);
+        }
+        return out;
+    }
+    /**
+     * 自称「纯记账」的工具名（`ToolMeta.accounting`）。
+     *
+     * 消费方是重复调用链（`runtime/loop-reminder.ts`）：这些工具对链透明，夹在
+     * 两次相同调用之间不打断计数。**判据由工具自己声明**，内核因此一个具体工具名
+     * 都不必认识——加一个新的记账工具零内核改动。
+     *
+     * 每轮现算一遍（工具总数是几十量级，且注册表在 bootstrap 后就不再变）：
+     * 缓存要额外处理注册之后的失效，换来的收益是噪音。
+     */
+    accountingToolNames() {
+        const names = new Set();
+        for (const { meta } of this.entries.values()) {
+            if (meta.accounting)
+                names.add(meta.name);
+        }
+        return names;
+    }
+    /**
+     * 自称此刻不可用的工具名（`AgentToolProvider.isAvailable`）。消费方是 loop 的
+     * 本轮摘除清单——走清单而不是在 `isAllowed` 里过滤，后台「下一轮预览」才列得出
+     * 「本轮摘掉了哪些」。
+     */
+    async unavailableToolNames(agent) {
+        const entries = [...this.entries.values()];
+        const available = await Promise.all(entries.map(({ provider }) => Promise.resolve(provider.isAvailable?.(agent) ?? true)));
+        return entries.filter((_, i) => !available[i]).map(({ meta }) => meta.name);
+    }
+    /**
+     * 这份 agent 配置下说明与装饰器不同的工具（`AgentToolProvider.describe`）：工具名 → 说明。
+     * loop 在算本轮摘除清单时一并算好，`buildToolSchemasFor` 与「下一轮预览」的 `definitionsFor`
+     * 用同一份，预览与喂给模型的说明不会分叉。
+     */
+    async descriptionsFor(agent) {
+        const entries = [...this.entries.values()];
+        const described = await Promise.all(entries.map(({ provider }) => Promise.resolve(provider.describe?.(agent) ?? null)));
+        const out = {};
+        entries.forEach(({ meta }, i) => {
+            const text = described[i];
+            if (text != null && text !== meta.description)
+                out[meta.name] = text;
+        });
+        return out;
+    }
+    /**
+     * 会往工作空间里写文件的工具名（`ToolMeta.writesWorkspace`）。
+     *
+     * 消费方是工具调用的文件变化记账（`extensions/tool-file-changes.hook.ts`）：
+     * 只有这些工具前后才扫一次工作目录。判据同样由工具自己声明。
+     */
+    workspaceWriterToolNames() {
+        const names = new Set();
+        for (const { meta } of this.entries.values()) {
+            if (meta.writesWorkspace)
+                names.add(meta.name);
+        }
+        return names;
+    }
+    /**
+     * 只带 schema、无 execute 的工具集——喂 streamText，SDK 只吐 tool-call，执行由
+     * loop 自驱。
+     *
+     * `initiator` **缺省 `NO_INITIATOR`，即 fail-closed**：漏传等于不给要权限的工具，
+     * 而不是给。方向与 `viewer` 的 null（= 系统调用、不过滤）相反，正是因为
+     * 漏传的教训是缺省不能站在宽松那一侧。
+     */
+    buildToolSchemasFor(agent, opts) {
+        const exclude = new Set(opts?.exclude ?? []);
+        const initiator = opts?.initiator ?? NO_INITIATOR;
+        const out = {};
+        for (const entry of this.entries.values()) {
+            const { meta } = entry;
+            if (!this.isAllowed(meta, agent, exclude, initiator))
+                continue;
+            out[meta.name] = tool({
+                description: opts?.descriptions?.[meta.name] ?? meta.description,
+                inputSchema: this.schemaFor(entry),
+            });
+        }
+        return out;
+    }
+    /** 按名执行单个工具。复用 runOne 的超时 + 「工具永不抛」兜底。未知工具 → fail。 */
+    async executeTool(name, input, ctxBase, toolCallId) {
+        const entry = this.entries.get(name);
+        if (!entry)
+            return fail(`unknown tool '${name}'`);
+        return this.runOne(entry.provider, input, ctxBase, toolCallId, this.timeoutFor(entry));
+    }
+    /**
+     * 这次调用**失败了吗**。SSE 事件与落库 part 共用这一个判据。
+     *
+     * **两层信封都要看，这正是它必须单独成为一个方法的原因。** `result.ok` 只说
+     * 明注册表这一层顺利跑完了（工具存在、没超时、没抛异常）；工具**自己判定的
+     * 失败**（`toolError(...)`）是 `{ok:true, data:{kind:'error'}}` —— 外层是
+     * `ok:true`。此前 `isError: !result.ok` 只看外层，于是「文件不存在」「服务商
+     * 没配」这类工具正常给出的失败，在界面上全都显示成绿色的成功。
+     *
+     * `kind:'accepted'`（后台受理）不是失败。
+     */
+    didFail(result) {
+        if (!result.ok)
+            return true;
+        const data = result.data;
+        return (typeof data === 'object' &&
+            data !== null &&
+            data.kind === 'error');
+    }
+    /**
+     * ToolResult → 喂模型的文本。SSE、落库、模型上下文三处同源。
+     *
+     * **出口处一律 `toWellFormed()`**：工具截断外部文本时用 `slice` 很容易把 emoji
+     * 切成孤立的半个代理对，而 Postgres 的 jsonb 整句拒收它（`Unicode low
+     * surrogate must follow a high surrogate`）——tool-result 落不了库，那一轮就
+     * 失败，`agent_run` 收尾也跟着写不进去。在这里规整而不是在落库时：三处同源，
+     * 模型看到的和库里存的仍然逐字相同（与 `replaceNul` 同一个道理）。第三方服务名的过滤（只过失败）
+     * 也在这里（`sanitizeError`），理由同上。
+     */
+    renderToolOutput(name, result) {
+        if (!result.ok)
+            return this.sanitize(result.error).toWellFormed();
+        const provider = this.entries.get(name)?.provider;
+        const text = (provider?.toModelOutput
+            ? provider.toModelOutput(result.data)
+            : JSON.stringify(result.data)).toWellFormed();
+        // 失败的说明多半转述了上游原话（厂商名、接口地址），过宿主的净化。
+        // 成功的结果不过：那是内容，替换就是改资料。
+        return this.didFail(result) ? this.sanitize(text) : text;
+    }
+    /** 工具为这次结果提供的结构化引用（落库进 `MessagePart.ref`）。 */
+    refOf(name, result) {
+        if (!result.ok)
+            return undefined;
+        const provider = this.entries.get(name)?.provider;
+        return provider instanceof AgentTool
+            ? provider.refFor(result.data)
+            : undefined;
+    }
+    /** 这次结果是否钉住不许裁剪（落库进 `MessagePart.pinned`）。失败的调用不问工具。 */
+    pinnedOf(name, result) {
+        if (!result.ok || this.didFail(result))
+            return false;
+        const provider = this.entries.get(name)?.provider;
+        return provider instanceof AgentTool && provider.pinnedFor(result.data);
+    }
+    /**
+     * 工具为这次结果交给模型看的图片（落库进 `MessagePart.images`）。
+     * 失败的调用没有图——`didFail` 为真时这里也不问工具，两处判据同源。
+     */
+    imagesOf(name, result) {
+        if (!result.ok || this.didFail(result))
+            return undefined;
+        const provider = this.entries.get(name)?.provider;
+        const images = provider instanceof AgentTool
+            ? provider.imagesFor(result.data)
+            : undefined;
+        return images && images.length > 0 ? images : undefined;
+    }
+    async runOne(provider, input, ctxBase, toolCallId, timeoutMs) {
+        const ctx = { ...ctxBase, toolCallId };
+        let timer;
+        // work 在超时后仍可能继续跑（provider 没有真正被取消）。用
+        // .catch() 将任何 rejection 转化为 ToolResult 的 resolve，使得
+        // race 的两条分支（work 和 timeout）都恒走 resolve 路径。这样
+        // work 在超时后延迟 reject 也不会导致 unhandled rejection —— 它
+        // 只是调用已经 settle 的外层 promise 的 reject（静默 no-op）。
+        const work = (async () => {
+            const data = await provider.execute(input, ctx);
+            return { ok: true, data };
+        })().catch((err) => fail(err instanceof Error ? err.message : String(err)));
+        try {
+            const timeout = new Promise(resolve => {
+                timer = setTimeout(() => resolve(fail(`tool timed out after ${timeoutMs}ms`)), timeoutMs);
+            });
+            return await Promise.race([work, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tools/tool-registry.js.map

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

package/dist/tools/tool-result.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 工具与注册表之间的返回约定。
+ *
+ * **两层，别搞混**：
+ *
+ * - `ToolOut<T>`（本文件下半部分）是**工具自己**的返回形状。工具实现 MUST NOT
+ *   throw —— 让 LLM 看到错误比中断整个 turn 有价值，故失败也是一种正常返回。
+ * - `ToolResult<T>` 与 `ok()`/`fail()` 是 **`ToolRegistry` 内部**的信封，
+ *   由 `runOne()` 包在工具返回值外面（它还会兜住真抛出的异常）。**工具实现不要
+ *   用 `ok()`/`fail()`** —— 那会套出 `{ok:true, data:{ok:true, data:…}}` 的双层
+ *   信封，而 `fail()` 更糟：外层 `ok:true` 让注册表认为这次调用成功了，失败路径
+ *   根本走不到，模型看到的是一个自相矛盾的 `{"ok":false,…}` JSON。
+ */
+export type ToolResult<T = unknown> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function ok<T>(data: T): ToolResult<T>;
+export declare function fail(error: string): ToolResult<never>;
+/** 包住可能抛出的异步逻辑，统一转成 ToolResult。 */
+export declare function safe<T>(fn: () => Promise<T>): Promise<ToolResult<T>>;
+/**
+ * 工具实现的统一返回形状：成功带数据，失败只带一句给模型看的文本。
+ *
+ * 判别键取 `kind` 而不是 `ok`，正是为了在类型层面与上面那个注册表信封区分开
+ * ——两者若长得一样，误用 `ok()` 就会一路编译通过（`LoadSkill` 曾如此）。
+ */
+export type ToolOut<T> = ({
+    kind: 'ok';
+} & T) | {
+    kind: 'error';
+    message: string;
+};
+export declare function toolError(message: string): {
+    kind: 'error';
+    message: string;
+};
+//# sourceMappingURL=tool-result.d.ts.map

package/dist/tools/tool-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.d.ts","sourceRoot":"","sources":["../../src/tools/tool-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAE5C;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAErD;AAED,mCAAmC;AACnC,wBAAsB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAM1E;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IACnB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAE7E"}

package/dist/tools/tool-result.js

@@ -0,0 +1,19 @@
+export function ok(data) {
+    return { ok: true, data };
+}
+export function fail(error) {
+    return { ok: false, error };
+}
+/** 包住可能抛出的异步逻辑，统一转成 ToolResult。 */
+export async function safe(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+export function toolError(message) {
+    return { kind: 'error', message };
+}
+//# sourceMappingURL=tool-result.js.map

package/dist/tools/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sourceRoot":"","sources":["../../src/tools/tool-result.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,EAAE,CAAI,IAAO;IAC3B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,KAAa;IAChC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,mCAAmC;AACnC,MAAM,CAAC,KAAK,UAAU,IAAI,CAAI,EAAoB;IAChD,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAWD,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/dist/tools/tool-wire.d.ts

@@ -0,0 +1,24 @@
+/** 工具的一个入参（由 zod inputSchema 摊平而来，给后台「工具列表」页展示）。 */
+export interface ToolParamWire {
+    key: string;
+    /** 从 JSON schema 尽力而为推出的类型标签（enum 列出取值）。 */
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+/**
+ * 工具完整定义的对外投影。**参数来自喂给模型的那份 schema**（`run_in_background`
+ * 等注入参数一并在内），审阅的就是模型看到的定义。
+ */
+export interface ToolDefinitionWire {
+    name: string;
+    description: string;
+    category: string;
+    supportsBackground: boolean;
+    /** 要哪个权限点才端上桌；null = 不要。 */
+    permission: string | null;
+    params: ToolParamWire[];
+    /** schema 不是对象、或转换失败时的说明；正常情况下 null。 */
+    schemaNote: string | null;
+}
+//# sourceMappingURL=tool-wire.d.ts.map

package/dist/tools/tool-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wire.d.ts","sourceRoot":"","sources":["../../src/tools/tool-wire.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,4BAA4B;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}

package/dist/tools/tool-wire.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-wire.js.map

package/dist/tools/tool-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wire.js","sourceRoot":"","sources":["../../src/tools/tool-wire.ts"],"names":[],"mappings":""}

package/dist/turn/agent-runtime.d.ts

@@ -0,0 +1,31 @@
+import type { TurnHookRegistry } from '../hooks/turn-hook.registry.js';
+import { type LoggerFactory } from '../ports/logger.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import type { TurnResult } from './turn-envelope.js';
+import { type RunTurnArgs } from './turn-run.js';
+export interface AgentRuntimeDeps {
+    tools: ToolRegistry;
+    hooks: TurnHookRegistry;
+    runs: RunStore;
+    logger?: LoggerFactory;
+    /** 失败文案进会话前的净化（见 `TurnRunDeps.sanitizeError`）。 */
+    sanitizeError?: (text: string) => string;
+}
+/**
+ * 跑一个 turn 的入口。搬自 agent-base `AgentRuntimeService`。
+ *
+ * **没有 StreamBus**：事件往哪去、本轮的中断信号是什么，都由调用方经 `RunTurnArgs` 传进来
+ * （`sink` / `abortSignal`）。内核只要一个同步投递口和一个信号。
+ *
+ * **一轮一个 `TurnRun` 实例**：本类可以是单例，而一轮的状态（工作消息、事件账本、usage、
+ * 迭代计数、压力基线）全是 per-turn 的。
+ */
+export declare class AgentRuntime {
+    private readonly deps;
+    private readonly logger;
+    constructor(deps: AgentRuntimeDeps);
+    /** 宿主负责：open 好 stream、备好 agent 定义与模型句柄。 */
+    runTurn(args: RunTurnArgs): Promise<TurnResult>;
+}
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/turn/agent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../../src/turn/agent-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,KAAK,aAAa,EAAgB,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,kDAAkD;IAClD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAEtB,IAAI,EAAE,gBAAgB;IAInD,2CAA2C;IAC3C,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAShD"}

package/dist/turn/agent-runtime.js

@@ -0,0 +1,30 @@
+import { silentLogger } from '../ports/logger.js';
+import { TurnRun } from './turn-run.js';
+/**
+ * 跑一个 turn 的入口。搬自 agent-base `AgentRuntimeService`。
+ *
+ * **没有 StreamBus**：事件往哪去、本轮的中断信号是什么，都由调用方经 `RunTurnArgs` 传进来
+ * （`sink` / `abortSignal`）。内核只要一个同步投递口和一个信号。
+ *
+ * **一轮一个 `TurnRun` 实例**：本类可以是单例，而一轮的状态（工作消息、事件账本、usage、
+ * 迭代计数、压力基线）全是 per-turn 的。
+ */
+export class AgentRuntime {
+    deps;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = (deps.logger ?? silentLogger)('AgentRuntime');
+    }
+    /** 宿主负责：open 好 stream、备好 agent 定义与模型句柄。 */
+    runTurn(args) {
+        return new TurnRun(args, {
+            tools: this.deps.tools,
+            hooks: this.deps.hooks,
+            runs: this.deps.runs,
+            logger: this.logger,
+            sanitizeError: this.deps.sanitizeError,
+        }).execute();
+    }
+}
+//# sourceMappingURL=agent-runtime.js.map

package/dist/turn/agent-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.js","sourceRoot":"","sources":["../../src/turn/agent-runtime.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAItE,OAAO,EAAoB,OAAO,EAAE,MAAM,eAAe,CAAC;AAW1D;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IAGM;IAFZ,MAAM,CAA4B;IAEnD,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;QACjD,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,cAAc,CAAC,CAAC;IAC9D,CAAC;IAED,2CAA2C;IAC3C,OAAO,CAAC,IAAiB;QACvB,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE;YACvB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;YACpB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,aAAa;SACvC,CAAC,CAAC,OAAO,EAAE,CAAC;IACf,CAAC;CACF"}

package/dist/turn/chunk-projection.d.ts

@@ -0,0 +1,32 @@
+import type { StreamTextOnChunkCallback, ToolSet } from 'ai';
+import type { ToolInputPreviewTracker } from './tool-input-preview.js';
+import type { ToolInputProgressTracker } from './tool-input-progress.js';
+import type { TurnJournal } from './turn-journal.js';
+/**
+ * onChunk 回调里 chunk 的真实形状（已读 `apps/api/node_modules/ai@7.0.31` 的
+ * `.d.ts` 核实：`StreamTextOnChunkCallback<TOOLS>` 收 `{ chunk: TextStreamPart<TOOLS> }`）。
+ *
+ * 版本号写在这里是为了让下次升级时能一眼看出这条核实是哪一版做的——v7 迁移那轮
+ * 漏改了它，一直写着 6.0.211。
+ */
+export type StreamChunk = Parameters<StreamTextOnChunkCallback<ToolSet>>[0]['chunk'];
+/**
+ * AI SDK chunk → 内层领域事件。只投影**流式增量**事件（文本/推理/工具入参
+ * 的实时构建），供 SSE 边打字边显示。
+ *
+ * **零内核状态、零时序约束**：它是 SDK chunk 的机械翻译，进度记账那半边也只
+ * 认自己手里的 tracker。故它住在 loop 外面。
+ *
+ * **不投影 `tool-call` / `tool-result`**：自驱 loop 喂 streamText 的是无
+ * execute 的 schema 工具集，SDK 因此永不产 `tool-result` chunk（无执行→无
+ * 结果），而 `tool-call` 由 loop 在拿到确定的 `step.toolCalls` 后**权威地**
+ * 发出（连同真实执行结果的 `tool-result`）。若这里也投影 `tool-call`，会与
+ * loop 那条重复投递；tool-result 又必须发在 step-finish 之前（见 `TurnRun`
+ * 里的说明），onChunk 里做不到这个时序。故这两类统一归 loop 掌管。
+ *
+ * `progress`/`preview` 两个 tracker 各管一条事件（`tool-input-progress`
+ * 答「写了多少」、`tool-input-preview` 答「写了什么」），互不知道对方，
+ * 这里各喂一遍。
+ */
+export declare function projectChunk(chunk: StreamChunk, journal: TurnJournal, progress: ToolInputProgressTracker, preview: ToolInputPreviewTracker): void;
+//# sourceMappingURL=chunk-projection.d.ts.map

package/dist/turn/chunk-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-projection.d.ts","sourceRoot":"","sources":["../../src/turn/chunk-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAE7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,CAClC,yBAAyB,CAAC,OAAO,CAAC,CACnC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAEd;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE,uBAAuB,GAC/B,IAAI,CAwCN"}