@hostanagent/tool-runner 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GeekArt Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @hostanagent/tool-runner 0.2.4
+
+HostAnAgent 协议 1.0 的独立交付包。当前是本地候选产物，尚未公开发布。
+
+安装固定归档：`npm install ./hostanagent-tool-runner-0.2.4.tgz`。依赖 Client Core 的包需同时安装 `hostanagent-client-core-0.2.4.tgz`。
+
+完整接入指南随包提供在 `SDK_ONBOARDING.md`，包含服务端 Key、产品登录代理、恢复、工具与组件扩展；无需取得私有源码仓库权限即可阅读已安装包中的指南。
+
+公开入口：包根。Client Core 另有 Node 专用 `/bridge`；Widget 另有独立浏览器脚本 `/embed`（dist/agent-chat.js）。Client Core 包根无 DOM 依赖。浏览器只能连接产品登录代理，不持有应用/供应商 Key。挂载或恢复历史不自动安装 ToolRunner。
+
+本客户端包及随包文档采用 [MIT](https://opensource.org/license/mit)，Copyright (c) 2026 GeekArt Inc.。第三方信息见 THIRD_PARTY_NOTICES.md。软件许可不包含托管服务或模型使用额度；尚未公开发布。

package/SDK_ONBOARDING.md

@@ -0,0 +1,125 @@
+# HostAnAgent SDK / Widget 0.2.4 接入
+
+0.2.4 为 MIT 许可准备版本，尚未公开上传。包含 D07 诊断契约及 durable 执行结束分类；0.2.3 及更早历史产物保持不变。
+
+此版本交付本地产物和安装验证，尚未上传 npm、PyPI 或 CDN。四个客户端包及随包文档、示例采用 MIT，Copyright (c) 2026 GeekArt Inc.，完整文本随包提供在 LICENSE。软件授权范围为客户端接入代码，托管服务和模型使用额度另行提供。不要向供应商填写 Key，也不要把 HAA 应用 Key 放进浏览器。
+
+## 1. 准备 Agent 与服务端身份
+
+在控制台创建并发布 Agent，记下不可变版本 ID。模型访问与计费由平台管理，产品只实现自己的登录、业务权限与工具。
+
+当前代码已整合 D01 的自助受限 Key 与 `/v1/runtime/bootstrap`。创建限制到目标 Agent 的服务端 Key：文本接入需要 `runtime:read`、`runtime:write`；显式执行工具时增加 `tools:execute`。聊天框不需要 `configuration:read/write`。默认代理只消费运行发现，缺失时拒绝初始化，绝不回退读取完整配置。部署状态以文档仓库实施记录为准；下面的独立示例仍使用显式 mock，不连接线上账号。
+
+仅服务端设置：
+
+```text
+HAA_BACKEND_URL=https://api.hostanagent.com
+HAA_APPLICATION_KEY=<受限的 HostAnAgent 应用 Key>
+PRODUCT_PUBLIC_ORIGIN=https://your-product.example
+```
+
+MCP `https://api.hostanagent.com/mcp` 仍只用于配置，不是运行、余额或充值入口。
+
+## 2. 从本地产物安装并运行最小示例
+
+在发布目录之外新建目录，将三个 `.tgz` 和 `example/` 复制过来。安装命令使用具体文件名，不依赖仓库、源码别名、Vite 或 latest：
+
+```bash
+npm install --save-exact ./hostanagent-client-core-0.2.4.tgz ./hostanagent-chat-widget-0.2.4.tgz ./hostanagent-tool-runner-0.2.4.tgz
+node example/server.mjs
+```
+
+打开 `http://127.0.0.1:4176`，点击登录模拟用户后发送文本。此示例仅监听本机，使用明确标注的模拟登录、运行发现、模型和资产，没有实际供应商请求、自动入账或业务工具。`PORT` 可以覆盖端口。`/balance` 与 `/model` 演示零余额及模型关闭。
+
+真实产品使用发布目录 `templates/app-backend-bridge/product-server.mjs`（源码位于 `examples/app-backend-bridge/`），其依赖入口是已安装的 `@hostanagent/client-core/bridge`。把返回的 Node handler 挂在 `/api/agent/*`，静态文件和产品登录由你的服务处理。回调替换点：
+
+- `authenticateProductUser(request)` 验证已有登录 cookie，返回稳定用户 ID 和本次登录会话 ID；不接收浏览器声称的 user_id。
+- `canUseAgent(subject, agentId)` 查询实时业务 ACL；Agent/版本由运行发现提供。
+- 可选 `canExecuteTool(subject, call, operation)` 校验工具名、版本、资源、参数摘要和操作权限。不挂载时所有 claim/receipts 都拒绝。
+- 可选 `canUseExecutor(subject, {path, method, body})` 消费 D02 的执行器授权钩子。产品必须把稳定 executor ID 解析到自己的可信登记，再逐次检查 Agent、绑定、执行位置和当前权限；未传回调时所有连接、心跳、候选、报告和断开路径均拒绝。此许可不自动放开 claim/receipts。
+
+代理仅暴露运行及明确授权的执行器路径，按 Subject 读取会话/Run，再检查授权版本；身份变化时拒绝旧页面的 `X-Agent-Identity`。该值只是 bootstrap 返回的登录绑定，不能代替 cookie。每次请求重新读取发现与 ACL；停用/归档阻止所有版本的新 Run，允许有权限的历史读取。平台已强制检查 Key scope、Agent 范围与账号状态；本版已整合 D05：可通过 `/agents/{id}/runtime?version_id=...` 读取可启动状态；服务端在幂等查询后检查停用/归档，已接受 Run 的同 key 重试仍返回原结果。
+
+## 3. 文本 Run、思考强度与恢复
+
+```ts
+import { AgentClient, bootstrap } from '@hostanagent/client-core';
+const metadata = await bootstrap('/api/agent');
+const client = new AgentClient({ endpoint: '/api/agent', agentVersion: '固定版本 ID', identityId: metadata.identity_id });
+client.subscribe(state => { /* 从 state.run.messages 渲染流式正文；不要执行工具 */ });
+await client.send('整理我的任务', { reasoning_effort: 'high', limits: { max_cost_usd: '1.000000000000' } });
+```
+
+五档 `low/medium/high/xhigh/max` 以 bootstrap 的模型 `reasoning_options` 为准，不支持的档位由平台拒绝。USD 始终是十进制字符串。零余额报 `INSUFFICIENT_BALANCE`，没有模型调用；目前测试入账需平台管理员人工处理，在线充值未开放。模型关闭/价格未就绪不自动换模型。
+
+网络断开、停止和未知结果的处理不同：
+
+| 情况 | 处理 |
+|---|---|
+| SSE 中断/事件缺口 | 自动读原 Run 快照，从 `resume_cursor` 补读，不发送新 Run |
+| 创建请求响应丢失 | 显式重试相同 `send` 内容，内存里冻结的幂等键与完整参数保持不变 |
+| 已拿到 Run ID，但快照失败 | 重试相同内容只读该 Run，不再 POST 创建 |
+| 页面重载/进程退出 | 默认不持久化正文；由产品记录已接受 Run ID 或原请求与幂等键后核对，不生成新键猜测重做 |
+| 追加输入响应未知 | 使用原内容和原幂等键重试 `/inputs` |
+| 用户停止 | `await client.cancel()`，以服务端状态为准；不是业务任务已取消的证明 |
+| 收起/卸载/断开连接 | 仅释放视图/观察连接，不取消 Run |
+
+恢复已有 Session 用其冻结的 `agent_version` 构造 client，再 `restore(sessionId)`；恢复 Run 用 `connect(runId)`。Widget 带 `sessionId` 时会先读旧版本，绝不跟随最新发布。显式升级需要销毁旧视图并创建不带旧 sessionId 的新 Widget。身份切换先 `runner?.revoke()`，再 `client.resetIdentity()`、销毁旧视图，用新登录 bootstrap 重新挂载。
+
+## 4. 显式挂载工具
+
+文本 Widget 不导入或自动启动 ToolRunner。可以在产品确认执行权限后单独安装：
+
+```ts
+import { AgentToolRunner, proxyCoordinator } from '@hostanagent/tool-runner';
+const runner = AgentToolRunner.attach(client, {
+  executorId: productExecutorId,
+  coordinator: proxyCoordinator(client),
+  handlers: { 'product.read_selection': async () => product.readAuthorizedSelection() },
+  receipts: productReceiptStore,
+  authorize: (call, phase) => product.authorizeTool(call, phase),
+  reconcile: call => product.reconcileReceipt(call.id, call.arguments_digest),
+  onError: () => showReconciliationRequired(),
+});
+```
+
+上面的 `product*` 都是接入方明确提供的对象，不是内置 API。0.2.4 包含 D02 的 `ExecutorConnection`、持久 assignment、`flushReceipts`、执行/核对授权与诊断接口；连接和心跳仍由产品显式调用，不自动启动执行器。参考发布目录 `templates/durable-tool-runner/README.md`（源码位于 `examples/durable-tool-runner/`），独立 Node 声明已包含全部入口。
+
+无副作用读取先验收，写工具再配持久回执、业务幂等和参数绑定审批。`replayed` claim 只允许重投已有回执或核对，不能重跑 handler。协调器的 receipt 必须返回 `{ accepted: true }` 才能继续；普通异常表示业务结果待核对，只有业务已确认失败/取消时才抛出 `BusinessFailure` / `BusinessCancelled`。handler 必须等待 progress 回执。新旧身份使用各自的 runner/client/store 实例；默认 MemoryReceiptStore 不提供跨进程持久化。真实 SitRep/AIAniGen 接入仍由对应产品验收。
+
+## 5. 固定脚本与组件扩展
+
+将发布目录 `vendor/agent-chat/0.2.4/agent-chat.js` 和同目录 LICENSE 原样复制到产品静态目录，核对 manifest 的 SHA-256 / SRI。脚本内也保留完整 MIT 声明；再次打包、压缩或分发时应保留该许可注释。该脚本包含 Client Core，没有外部 JS 依赖：
+
+```html
+<div id="assistant" style="height:600px"></div>
+<script src="/vendor/agent-chat/0.2.4/agent-chat.js"></script>
+<script>
+  AgentChat.mount('#assistant', { endpoint: '/api/agent', agentId: '你的 Agent ID' });
+</script>
+```
+
+严格 CSP 的产品将挂载代码放在自己的外部脚本中。传入明确 `agentVersion` 时保留旧接入的无 bootstrap 挂载行为；新产品代理需同时传入 `identityId: metadata.identity_id`（先调用 `bootstrap`），或直接传入已初始化的 `client`。也可 `import { mount } from '@hostanagent/chat-widget'`；模块依赖固定 `@hostanagent/client-core@0.2.4`。
+
+支持受控 Markdown（标题、段落、列表、引用、强调、代码块和复制）、安全链接、公开推理、工具/确认卡片；原始 HTML 是纯文本，不加载 Markdown 图片，不执行模型返回的脚本。`renderers` 是产品可信代码，产品负责它的安全性。通用工具 JSON 展示上限 16,000 字符，正文 Markdown 展示上限 200,000 字符。
+
+`selectAttachments(): Promise<ReferenceCard[]>` 由产品选择/上传并授权资源；卡片的 `ref` 作为 `context_refs` 发送，图片和音频不会因此成为模型输入。活动 Run 的 `/inputs` 只接受文本，资源引用需下一轮发送。`getReferences(message)` 可从产品数据返回来源/资产卡片（title、description、url、ref）；只允许 HTTP(S)、同源绝对路径或片段链接。不默认写 localStorage/IndexedDB。
+
+## 6. 发布与升级
+
+| 产物 | 版本与入口 | 兼容边界 |
+|---|---|---|
+| Python `hostanagent-client` | 0.2.4；`from hostanagent import AgentClient` | Python >=3.10；协议 1.0；仅 httpx 运行依赖 |
+| TS Client Core | 0.2.4；包根、`/bridge`（仅 Node） | 包根无 DOM；Node >=22.12；浏览器 fetch/Streams/crypto |
+| ToolRunner | 0.2.4；包根 | 已整合 D02 连接与可靠回执语义；需显式协调器/handler |
+| Widget | 0.2.4；包根、`/embed` | 协议 1.0；Shadow DOM；浏览器最终证据见交付记录 |
+
+0.2.0 增加完整 Run 参数、错误关联 ID、运行发现与 Node 代理、组件扩展，并修复接受成功后的重试重复运行风险。0.2.1 整合主分支 D01/D02/D03/D04，采用同一份规范协议产物，修复新增执行器类型的 NodeNext 导入，并提供 D02 同款显式执行器代理授权。升级 ToolRunner 时按上节核对回执确认、普通异常和业务失败语义。产品应成组升级 JS 三包和脚本，先在 mock 验证，再接真实已授权服务；保留旧 0.2.0/0.2.1 文件。0.2.2 已整合 D05 固定版本和停用规则；修复空会话恢复残留、批量 SSE 回放误判超限，以及发送完成时清除后续编辑或抢走阅读焦点的问题。未知请求未核对前，Client Core 拒绝切换其他 Session，仍使用原 key 恢复；身份切换仍明确丢弃旧身份状态。服务端协议仍为 1.0，生产联合验收另行进行。
+
+0.2.3 完成源码包、发布工作流与安装矩阵准备；0.2.4 补齐 GeekArt Inc. 的 MIT 声明及独立脚本许可注释。0.2.3 及更早产物保持原样。
+
+从明确提交构建：`pnpm release:pack`（要求干净 checkout）；输出 `artifacts/0.2.4/manifest.json`、三包、固定脚本、示例和产品代理/持久回执模板。manifest 同时记录准确契约摘要、全部文件 SHA-256 和 SRI；安装/浏览器验证先核对完整清单。只复制 Git 跟踪的示例文件，不纳入示例目录内的本地环境文件或依赖目录。已有版本目录会拒绝覆盖。开发中可用 `pnpm release:pack --candidate` 生成独立候选目录并记录实际 source_dirty 状态。运行 `pnpm test:packages <产物目录>`，在系统临时目录通过 tarball 安装、严格 Node 无 DOM / 浏览器类型检查与执行。测试只复制第三方编译器类型工具，不链接任何项目源码。
+
+MIT 许可见各包、示例和模板中的 LICENSE；第三方信息见各包 THIRD_PARTY_NOTICES.md。构建和校验不执行上传。另有 `scripts/publish-release.mjs <产物目录>` 核对可发布性与远端同版本摘要，只有显式加入 `--publish` 才上传；版权声明不完整时会在上传前停止。保留旧产物，核对包名权限、服务端集成和发布授权后再公开上传。Railway 仍按已提交源码手动部署。
+
+兼容窗口：0.2.0/0.2.1 的固定版本运行接口继续兼容当前协议 1.0；D02 执行器使用 0.2.1 起的接口，D05 元数据与逻辑 Agent 选择需要已整合 D05 的服务端。Python 便捷入口见 wheel 内 README。未来删除字段或改变运行语义必须先发布不兼容版本和迁移说明，不能覆盖同版本产物。当前仅提供自托管文件，不存在可承诺的公共 CDN URL。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# 许可与构建来源
+
+本客户端包及随包文档采用 MIT，Copyright (c) 2026 GeekArt Inc.，完整文本见 LICENSE。第三方依赖继续适用各自的许可证。
+
+发布的 JavaScript 只包含本仓库代码。Client Core 使用平台内置 fetch/Streams/crypto；Node bridge 使用 Node 内置模块。ToolRunner 和 Widget ES 模块精确依赖本项目 Client Core；Widget IIFE 将 Client Core 打入脚本。没有引入 Markdown/HTML 第三方解析器。
+
+开发构建工具为 TypeScript（Apache-2.0）、Vite / Rollup / esbuild（MIT），以及测试用 Vitest（MIT）和 Playwright（Apache-2.0）。它们不是包的运行依赖。开发工具及其依赖完整许可证保留在各自已安装的包中；如另行分发工具本身应一并保留对应许可。版本与完整性由仓库 pnpm-lock.yaml 固定。

package/dist/connection.d.ts

@@ -0,0 +1,14 @@
+import type { AgentClient, ExecutorConnect, ExecutorHeartbeat, ExecutorRecord, PendingToolCalls } from '@hostanagent/client-core';
+import type { ExecutorDiagnostic } from './index.js';
+/** Explicit lifecycle over a product-authorized bridge. No background execution or implicit mount. */
+export declare class ExecutorConnection {
+    private client;
+    readonly registration: ExecutorConnect;
+    constructor(client: AgentClient, registration: ExecutorConnect);
+    connect(): Promise<ExecutorRecord>;
+    heartbeat(status?: ExecutorHeartbeat): Promise<ExecutorRecord>;
+    disconnect(): Promise<ExecutorRecord>;
+    pending(cursor?: string, limit?: number): Promise<PendingToolCalls>;
+    report(runId: string, toolCallId: string, state: ExecutorDiagnostic): Promise<unknown>;
+    private path;
+}

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import type { AgentClient, PublicToolCall, ReceiptCreate } from '@hostanagent/client-core';
+export interface Assignment {
+    toolCall: PublicToolCall;
+    grant: string;
+    replayed: boolean;
+}
+export interface Coordinator {
+    claim(call: PublicToolCall, executorId: string): Promise<Assignment | null>;
+    receipt(assignment: Assignment, receipt: ReceiptCreate): Promise<unknown>;
+}
+export interface ReceiptStore {
+    get(callId: string): Promise<ReceiptCreate | undefined>;
+    put(callId: string, receipt: ReceiptCreate): Promise<void>;
+    remove(callId: string): Promise<void>;
+    /** Optional durable assignment journal. Persist before calling any business handler. */
+    prepare?(assignment: Assignment): Promise<void>;
+    pending?(): Promise<Assignment[]>;
+}
+export declare class MemoryReceiptStore implements ReceiptStore {
+    private items;
+    get(id: string): Promise<ReceiptCreate | undefined>;
+    put(id: string, value: ReceiptCreate): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+export interface ToolContext {
+    toolCallId: string;
+    operationKey: string;
+    argumentsDigest: string;
+    signal: AbortSignal;
+    progress(message: string): Promise<void>;
+}
+export type ToolHandler = (arguments_: Record<string, unknown>, context: ToolContext) => Promise<unknown>;
+/** Only use these when the business system has confirmed its final outcome. */
+export declare class BusinessFailure extends Error {
+}
+export declare class BusinessCancelled extends Error {
+}
+export type ExecutorDiagnostic = 'reconciliation_required' | 'receipt_pending';
+export interface RunnerOptions {
+    coordinator: Coordinator;
+    handlers: Record<string, ToolHandler>;
+    /** The application persists identity and business idempotency if recovery is required. */
+    executorId: string;
+    receipts?: ReceiptStore;
+    reconcile?: (call: PublicToolCall) => Promise<ReceiptCreate | undefined>;
+    authorize?: (call: PublicToolCall, phase: 'execute' | 'reconcile') => Promise<void>;
+    onDiagnostic?: (call: PublicToolCall, state: ExecutorDiagnostic) => void;
+    onError?: (call: PublicToolCall, error: unknown) => void;
+}
+export declare function proxyCoordinator(client: AgentClient): Coordinator;
+/** Execution is opt-in and coordinated. Chat rendering never instantiates this class. */
+export declare class AgentToolRunner {
+    private seen;
+    private active;
+    private busy;
+    private unsubscribe;
+    private receipts;
+    private options;
+    private client;
+    private stopped;
+    constructor(client: AgentClient, options: RunnerOptions);
+    static attach(client: AgentClient, options: RunnerOptions): AgentToolRunner;
+    private execute;
+    private deliver;
+    private unknown;
+    private reconcile;
+    /** Explicit recovery also delivers saved results for runs that have already stopped. */
+    flushReceipts(): Promise<void>;
+    /** Stops new assignments. In-flight business handlers decide how to finish. */
+    detach(): void;
+    /** Call when product identity changes; application authorization remains final. */
+    revoke(): void;
+}
+export { ExecutorConnection } from './connection.js';

package/dist/index.js

@@ -0,0 +1,225 @@
+/*!
+MIT License
+
+Copyright (c) 2026 GeekArt Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+class y {
+  constructor(t, e) {
+    this.client = t, this.registration = e;
+  }
+  client;
+  registration;
+  connect() {
+    return this.client.request("/executors/connect", { method: "POST", body: JSON.stringify(this.registration) });
+  }
+  heartbeat(t = {}) {
+    return this.client.request(this.path("heartbeat"), { method: "POST", body: JSON.stringify(t) });
+  }
+  disconnect() {
+    return this.client.request(this.path("disconnect"), { method: "POST" });
+  }
+  pending(t, e = 50) {
+    const i = new URLSearchParams({ limit: String(e), ...t ? { cursor: t } : {} });
+    return this.client.request(`${this.path("pending")}?${i}`);
+  }
+  report(t, e, i) {
+    return this.client.request(this.path("calls/report"), { method: "POST", body: JSON.stringify({ run_id: t, tool_call_id: e, state: i }) });
+  }
+  path(t) {
+    return `/executors/${encodeURIComponent(this.registration.executor_id)}/${t}`;
+  }
+}
+class f {
+  items = /* @__PURE__ */ new Map();
+  async get(t) {
+    return structuredClone(this.items.get(t));
+  }
+  async put(t, e) {
+    this.items.set(t, structuredClone(e));
+  }
+  async remove(t) {
+    this.items.delete(t);
+  }
+}
+class w extends Error {
+}
+class l extends Error {
+}
+function g(o) {
+  return {
+    async claim(t, e) {
+      try {
+        const i = await o.request(`/runs/${t.run_id}/tool-calls/${t.id}/claim`, { method: "POST", body: JSON.stringify({ executor_id: e }) });
+        return { toolCall: i.tool_call, grant: i.grant, replayed: i.replayed };
+      } catch (i) {
+        if (typeof i == "object" && i !== null && "status" in i && i.status === 409) return null;
+        throw i;
+      }
+    },
+    receipt(t, e) {
+      const i = t.toolCall;
+      return o.request(`/runs/${i.run_id}/tool-calls/${i.id}/receipts`, { method: "POST", headers: { "X-Tool-Grant": t.grant }, body: JSON.stringify(e) });
+    }
+  };
+}
+class h {
+  seen = /* @__PURE__ */ new Set();
+  active = /* @__PURE__ */ new Map();
+  busy = /* @__PURE__ */ new Set();
+  unsubscribe = null;
+  receipts;
+  options;
+  client;
+  stopped = !1;
+  constructor(t, e) {
+    this.client = t, this.options = e, this.receipts = e.receipts || new f();
+  }
+  static attach(t, e) {
+    const i = new h(t, e);
+    return i.unsubscribe = t.subscribe((r) => {
+      if (r.run)
+        for (const s of r.run.tool_calls)
+          s.run_id === r.run.id && (s.cancel_requested && i.active.get(s.id)?.abort(), !["completed", "failed", "cancelled", "expired"].includes(r.run.status) && ["ready", "claimed", "accepted"].includes(s.status) && e.handlers[s.name] && !i.seen.has(s.id) && (i.seen.add(s.id), i.execute(s)));
+    }), i;
+  }
+  async execute(t) {
+    if (!this.busy.has(t.id)) {
+      this.busy.add(t.id);
+      try {
+        const e = await this.options.coordinator.claim(t, this.options.executorId);
+        if (!e || this.stopped) return;
+        if (["id", "run_id", "binding_id", "name", "version", "arguments_digest"].some((n) => e.toolCall[n] !== t[n]))
+          throw new Error("分派内容与工具调用不一致");
+        t = e.toolCall;
+        const i = await this.receipts.get(t.id);
+        if (i && a(i)) {
+          await this.deliver(e, i);
+          return;
+        }
+        if (await this.receipts.prepare?.(e), e.replayed || i) {
+          await this.reconcile(e);
+          return;
+        }
+        const r = new AbortController();
+        this.active.set(t.id, r);
+        let s = 0;
+        const d = { receipt_id: crypto.randomUUID(), kind: "accepted" };
+        if (await this.receipts.put(t.id, d), await this.deliver(e, d), this.stopped) {
+          this.unknown(t);
+          return;
+        }
+        await this.options.authorize?.(t, "execute");
+        let c;
+        try {
+          const n = await this.options.handlers[t.name](t.arguments, {
+            toolCallId: t.id,
+            operationKey: t.id,
+            argumentsDigest: t.arguments_digest,
+            signal: r.signal,
+            progress: async (p) => {
+              const u = { receipt_id: crypto.randomUUID(), kind: "progress", progress_sequence: ++s, progress: p };
+              await this.receipts.put(t.id, u), await this.deliver(e, u);
+            }
+          });
+          c = { receipt_id: crypto.randomUUID(), kind: "completed", result: structuredClone(n) };
+        } catch (n) {
+          if (!(n instanceof w) && !(n instanceof l)) {
+            this.unknown(t);
+            return;
+          }
+          c = { receipt_id: crypto.randomUUID(), kind: n instanceof l ? "cancelled" : "failed", error: n.message };
+        }
+        await this.receipts.put(t.id, c), await this.deliver(e, c);
+      } catch (e) {
+        let i = !1;
+        try {
+          i = a(await this.receipts.get(t.id));
+        } catch {
+        }
+        this.options.onDiagnostic?.(t, i ? "receipt_pending" : "reconciliation_required"), this.options.onError?.(t, e);
+      } finally {
+        this.active.delete(t.id), this.busy.delete(t.id);
+      }
+    }
+  }
+  async deliver(t, e) {
+    e = structuredClone(e);
+    for (let i = 0; i < 3; i++)
+      try {
+        const r = await this.options.coordinator.receipt(t, e);
+        if (typeof r != "object" || r === null || !("accepted" in r) || r.accepted !== !0) throw new Error("回执尚未确认");
+        if (!a(e) && typeof r == "object" && r !== null && "late" in r && r.late) throw new Error("调用已停止或过期");
+        a(e) && await this.receipts.remove(t.toolCall.id);
+        return;
+      } catch (r) {
+        if (i === 2 || this.stopped) throw r;
+        await new Promise((s) => setTimeout(s, 250 * 2 ** i));
+      }
+  }
+  unknown(t) {
+    this.options.onDiagnostic?.(t, "reconciliation_required"), this.options.onError?.(t, new Error("执行结果需要接入方核对；不会自动重做操作"));
+  }
+  async reconcile(t) {
+    await this.options.authorize?.(t.toolCall, "reconcile");
+    const e = structuredClone(await this.options.reconcile?.(t.toolCall));
+    if (!e) {
+      this.unknown(t.toolCall);
+      return;
+    }
+    if (!a(e)) throw new Error("核对必须返回业务已确认的最终结果");
+    await this.receipts.put(t.toolCall.id, e), await this.deliver(t, e);
+  }
+  /** Explicit recovery also delivers saved results for runs that have already stopped. */
+  async flushReceipts() {
+    for (const t of await this.receipts.pending?.() || [])
+      if (!this.busy.has(t.toolCall.id)) {
+        this.busy.add(t.toolCall.id);
+        try {
+          const e = await this.receipts.get(t.toolCall.id);
+          e && a(e) ? await this.deliver(t, e) : await this.reconcile(t);
+        } catch (e) {
+          this.options.onError?.(t.toolCall, e);
+        } finally {
+          this.busy.delete(t.toolCall.id);
+        }
+      }
+  }
+  /** Stops new assignments. In-flight business handlers decide how to finish. */
+  detach() {
+    this.stopped = !0, this.unsubscribe?.(), this.unsubscribe = null;
+  }
+  /** Call when product identity changes; application authorization remains final. */
+  revoke() {
+    this.detach();
+    for (const t of this.active.values()) t.abort();
+  }
+}
+function a(o) {
+  return !!o && ["completed", "failed", "cancelled"].includes(o.kind);
+}
+export {
+  h as AgentToolRunner,
+  l as BusinessCancelled,
+  w as BusinessFailure,
+  y as ExecutorConnection,
+  f as MemoryReceiptStore,
+  g as proxyCoordinator
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@hostanagent/tool-runner",
+  "version": "0.2.4",
+  "type": "module",
+  "description": "Explicit application-owned executor coordination",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "SDK_ONBOARDING.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@hostanagent/client-core": "0.2.4"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ffskyfan/HostAnAgentWeb.git",
+    "directory": "packages/tool-runner"
+  },
+  "license": "MIT"
+}