@tool-bridge/server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,764 @@
+import * as http from 'node:http';
+import { Hono } from 'hono';
+
+/**
+ * 公共类型。
+ *
+ * 原样转写规范中的 TS 定义;此处仅补充实现所需的最小派生(如 ACTIONS 常量表)。
+ */
+/** 资源 URI。 */
+type URI = string;
+/** 树上路径,'/' 分隔,不含保留段;如 "docs/context7"。 */
+type TreePath = string;
+/** ISO 8601, UTC。 */
+type Timestamp = string;
+interface Page<T> {
+    /** 存在则表示还有下一页;传回 List 继续。 */
+    cursor?: string;
+    items: T[];
+}
+interface ListOptions {
+    cursor?: string;
+    /** 键集合由各接口 ~help 声明;未声明的键 → invalid_argument。 */
+    filter?: Record<string, string>;
+    /** 规范默认 50、上限 200,超上限静默钳制。 */
+    limit?: number;
+}
+/** "user:alice" | "agent:researcher" | "device:build-01"。 */
+type OwnerRef = string;
+interface CallContext {
+    /** 平台→Plugin envelope 专用:本次调用命中该 plugin 的哪个 export(v2 多 export 路由)。 */
+    exportId?: string;
+    /** 本次调用使用的 SK 的 id(非明文)。 */
+    keyId: string;
+    /** 平台→Plugin envelope 专用:挂载节点 config.providerConfig 透传(每挂载非敏感配置)。 */
+    mountConfig?: Record<string, unknown>;
+    /** 平台→Plugin envelope 专用:本次调用来自哪个挂载节点(同一 plugin 可多路径挂载)。 */
+    mountPath?: TreePath;
+    owner: OwnerRef;
+    /** 反向注册路径收紧规则;缺省按非保留根放行。 */
+    registerPaths?: TreePath[];
+    scopes: Scope[];
+    /** 全链路观测。 */
+    traceId: string;
+}
+type Action = 'read' | 'write' | 'call' | 'register' | 'admin';
+interface Scope {
+    actions: Action[];
+    /** 默认 allow;deny 优先于一切 allow。 */
+    effect?: 'allow' | 'deny';
+    /** 树路径 glob:"**" | "docs/**" | "device/build-01/**"。 */
+    pattern: string;
+}
+
+/**
+ * StateStore:宿主注入的状态存储接口。
+ *
+ * CF = KV / Docker = SQLite / SDK 内嵌 = 内存。core 只依赖此接口;
+ * 一切树配置、SK 哈希表、加密 secret 都经它读写。异步签名以兼容 KV。
+ *
+ * key 布局:
+ *   sk:h:<sha256hex>  → SecretKey(认证热路径)
+ *   sk:i:<id>         → sha256hex(管理面二级索引,指向 sk:h:*)
+ *   node:<path>       → TreeNode
+ *   secret:<name>     → { iv, ciphertext, updatedAt }
+ *   plugin:<id>       → PluginManifest
+ *   sys:bootstrapped  → true(Admin SK 引导幂等标志)
+ *   annotation:<path> → { text, updatedAt, updatedBy }(管理员 Path 补充说明)
+ *   feedback:<path>   → FeedbackEntry[](Agent 使用反馈,单 key 整存)
+ */
+interface StateStore {
+    delete(key: string): Promise<void>;
+    get(key: string): Promise<unknown | null>;
+    /** 批量读取，返回值只包含当前存在的 key；单次最多 100 keys。 */
+    getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
+    list(prefix: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: unknown;
+        }>;
+    }>;
+    put(key: string, value: unknown): Promise<void>;
+}
+
+/**
+ * SecretStore:上游凭证的"只进不出"加密保管。
+ *
+ * 值经 AES-256-GCM 加密后写入注入的 StateStore(key 布局 `secret:<name>`,store.ts)。
+ * 主密钥 `TB_SECRET_ENCRYPTION_KEY` 是部署期 env-only 的 base64url(32 字节)——
+ * 信任根不自举存储(spec-digest)。主密钥缺失/格式非法时能力禁用:Set 抛 unavailable。
+ *
+ * 纯逻辑,仅依赖 WebCrypto(core 无宿主依赖)。`crypto` / `TextEncoder` / `TextDecoder`
+ * 在 Workers 与 Node 20+ 均为全局;此处以模块作用域最小声明补齐类型(不改 tsconfig、不污染全局)。
+ */
+
+/**
+ * SecretStore 的纯逻辑实现。以注入的 StateStore 为后端。
+ *
+ * 主密钥缺失或格式非法(非 base64url / 非 32 字节)→ 实例处于 **unavailable 态**:
+ * Set 抛 unavailable,resolve 返回 undefined(见方法注释)。
+ */
+declare class SecretStoreImpl {
+    private readonly store;
+    /** 32 字节主密钥;undefined 表示 unavailable 态。 */
+    private readonly keyBytes;
+    /** 惰性导入的 CryptoKey(仅可用时);首次加解密时创建并缓存。 */
+    private importedKey;
+    /**
+     * @param masterKey base64url 编码的 32 字节(TB_SECRET_ENCRYPTION_KEY);
+     *   undefined / 解码失败 / 长度非 32 → 实例处于 unavailable 态。
+     */
+    constructor(store: StateStore, masterKey: string | undefined);
+    private static decodeMasterKey;
+    /** secret 能力是否可用(主密钥有效)。 */
+    get available(): boolean;
+    private key;
+    /**
+     * 写入 / 替换 secret;明文仅在此请求中出现。
+     * unavailable 态 → 抛 unavailable(retryable:false):主密钥缺失时 Set 不可用。
+     */
+    set(name: string, value: string, now: Timestamp): Promise<void>;
+    /**
+     * 枚举 secret 元数据。**绝不返回明文/密文**——只出 name + updatedAt(只进不出)。
+     * limit 默认 50、上限 200 钳制。
+     */
+    list(opts?: ListOptions): Promise<Page<{
+        name: string;
+        updatedAt: Timestamp;
+    }>>;
+    /** 删除 secret;不存在 → not_found。 */
+    delete(name: string): Promise<void>;
+    /**
+     * 解密并返回明文(不存在 → undefined)。
+     *
+     * **仅供网关内部 Provider 解析引用名(authRef/skRef/secretRef);不暴露为节点 cmd**
+     * (节点面只有 Set/List/Delete,resolve 不是 cmd)。
+     * unavailable 态(主密钥缺失)同样返回 undefined——本层不区分"无从解密"与"引用名不存在"。
+     * **消费侧契约:配置声明了引用却拿到 undefined 必须 fail closed**(抛 unavailable),
+     * 不得降级为无凭证/匿名出站——上游可能据此当匿名放行或返回误导性结果。
+     * 各 Provider(remote/mcp/http/pluginClient)均按此实现。
+     */
+    resolve(name: string): Promise<string | undefined>;
+}
+
+/**
+ * Context Layer 类型(原样转写;方法签名异步化以兼容对象存储后端)。
+ *
+ * 全部动词可选:能力由 handler 存在性推导(见 context/capabilities.ts)。
+ * 可选能力(Search/Delete)另在 ~describe 的 capabilities 中声明,调用方先探测再用。
+ */
+
+interface ContextEntryMeta {
+    /** "text/markdown" | "application/json" | ... */
+    contentType: string;
+    metadata: Record<string, string>;
+    size?: number;
+    updatedAt: Timestamp;
+    /** node://<namespace-path>/<entry-path>;目录条目以尾 '/' 表示。 */
+    uri: URI;
+    /** 乐观并发:Update/Write 可携带 ifVersion;对象存储后端 = etag。 */
+    version: string;
+}
+interface ContextEntry extends ContextEntryMeta {
+    /** 文本或 JSON;大对象返回 { $ref: <预签名或中转 URL> }。 */
+    content: string | unknown;
+}
+interface ContextEntryInput {
+    content: string | unknown;
+    /** 字符串 content 必填(缺失 → invalid_argument);非字符串 content 缺省 application/json。 */
+    contentType?: string;
+    /** 不匹配 → conflict。 */
+    ifVersion?: string;
+    metadata?: Record<string, string>;
+}
+interface ContextPatch {
+    content?: string | unknown;
+    ifVersion?: string;
+    /** 浅合并。 */
+    metadata?: Record<string, string>;
+}
+interface SearchOptions extends ListOptions {
+    /** 缺省 keyword;semantic 需 capabilities 声明 "search:semantic",未声明 → invalid_argument。 */
+    mode?: 'keyword' | 'semantic';
+}
+/**
+ * Context provider。**全部动词可选**:能力由 handler 存在性推导(context/capabilities.ts),
+ * `~help` 只列真实存在的操作,没有任何写动词即自动只读。
+ *
+ * 这样只读资源、纯搜索服务、append-only 存储都能如实表达自己,不必为满足接口而伪造
+ * 方法或抛 unimplemented。未实现的动词在数据面按 unknown cmd 拒绝(invalid_argument)。
+ */
+interface ContextProvider {
+    Delete?(path: string): Promise<void>;
+    /** 读取单个条目(含内容);不存在 → not_found。 */
+    Get?(path: string): Promise<ContextEntry>;
+    /** 枚举条目(浅层列表 + 分页);path 为 namespace 内相对路径前缀。 */
+    List?(path: string, opts?: ListOptions): Promise<Page<ContextEntryMeta>>;
+    Search?(query: string, opts?: SearchOptions): Promise<Page<ContextEntryMeta>>;
+    /** 部分更新已存在条目的内容或 metadata;不存在 → not_found。 */
+    Update?(path: string, patch: ContextPatch): Promise<ContextEntryMeta>;
+    /** 创建或整体替换条目(幂等 upsert)。 */
+    Write?(path: string, entry: ContextEntryInput): Promise<ContextEntryMeta>;
+}
+
+/**
+ * ObjectStore:对象存储抽象。
+ *
+ * r2(R2 binding)、s3(aws4fetch)与单测内存实现共用此接口;ContextProvider 的
+ * 四动词语义全部落在 objectProvider.ts,后端只做本接口适配。core 无 DOM lib:
+ * 流与 body 用最小结构类型声明,与 Workers / Node 的全局 ReadableStream 结构兼容。
+ */
+/** 最小读流(结构兼容全局 ReadableStream<Uint8Array>)。 */
+interface ObjectBodyStream {
+    cancel?(reason?: unknown): Promise<void>;
+    getReader(): {
+        /** 消费方(如 Node undici 的 Response 收尾)可能调用;实现方建议提供。 */
+        cancel?(reason?: unknown): Promise<void>;
+        read(): Promise<{
+            done: boolean;
+            value?: Uint8Array;
+        }>;
+        releaseLock(): void;
+    };
+}
+/** put 可接受的 body 形态(BodyInit 子集;core 无 DOM lib 故自声明)。 */
+type ObjectBody = string | Uint8Array | ArrayBuffer | ObjectBodyStream;
+interface ObjectMeta {
+    contentType?: string;
+    etag: string;
+    key: string;
+    /**
+     * 用户 metadata。undefined 表示后端 list 未返回(如 S3 ListObjectsV2),
+     * 区别于空对象 {}(确认无 metadata);Search 对 undefined 按需 head 补取。
+     */
+    metadata?: Record<string, string>;
+    size: number;
+    updatedAt: string;
+}
+interface ObjectPutOptions {
+    contentType?: string;
+    /** 与现存对象 etag 不符(含对象不存在)→ TBError conflict。 */
+    ifMatchEtag?: string;
+    metadata?: Record<string, string>;
+}
+interface ObjectListOptions {
+    cursor?: string;
+    /** 提供时浅层列举:共同子前缀折叠为 { prefix }(含 delimiter 本身)。 */
+    delimiter?: string;
+    limit?: number;
+}
+interface ObjectListResult {
+    cursor?: string;
+    /** 文件与折叠前缀按字典序混排(与 R2/S3 行为一致)。 */
+    items: Array<ObjectMeta | {
+        prefix: string;
+    }>;
+}
+interface ObjectStore {
+    /** 幂等:不存在静默。 */
+    delete(key: string): Promise<void>;
+    get(key: string): Promise<{
+        body: ObjectBodyStream;
+        meta: ObjectMeta;
+    } | null>;
+    head(key: string): Promise<ObjectMeta | null>;
+    list(prefix: string, opts?: ObjectListOptions): Promise<ObjectListResult>;
+    /** 生成限时直连 URL;后端不支持则缺省(provider 退化到 relayRefUrl)。 */
+    presign?(key: string, ttlSec: number): Promise<string>;
+    put(key: string, body: ObjectBody, opts?: ObjectPutOptions): Promise<ObjectMeta>;
+}
+
+/**
+ * Tool Layer 的中立类型。
+ *
+ * `ToolSpec` 是**上游工具的中立形状**:mcp(`tools/list` 的 `Tool`)与 http
+ * (`HttpToolDef`)都归一到它,虚拟化(virtualize.ts)与 `~help` 派生(mcpSchema.ts)
+ * 只认 `ToolSpec`,不感知上游是 mcp 还是 http。它把 `ToolMeta`+`ToolDef`
+ * 合并为一个形状:`description` 可缺省(上游可能不带),另携 `confirm`(危险工具二次确认)。
+ */
+/** 上游工具的中立形状(mcp/http 归一目标)。 */
+interface ToolSpec {
+    /** 危险操作二次确认;进 `~help` 的 confirm 行。 */
+    confirm?: boolean;
+    /** 一句话描述;进 `~help` 的 `h` 行。上游可能不带 → 可缺省。 */
+    description?: string;
+    /** 副作用标记(read/write/destructive);进 `~help` 的 effect 行。 */
+    effect?: string;
+    /** JSON Schema;`~help` 的 body 数据源。 */
+    inputSchema?: unknown;
+    /** 工具名(虚拟化前为上游原名,虚拟化后为对外虚拟名)。 */
+    name: string;
+}
+/**
+ * 工具调用结果。`isError:true` 是**工具业务级错误**(上游 HTTP 200
+ * 正常返回、内容为错),按内容协商渲染——**不是** TBError(传输/协议错误才归一为
+ * TBError,见 upstreamError.ts)。
+ */
+interface ToolResult {
+    /** markdown 文本或结构化 JSON(按内容协商输出)。 */
+    content: string | unknown;
+    /** MCP 等上游的原生多模态 content blocks;HTBP 渲染仍使用归一后的 content。 */
+    contentBlocks?: unknown[];
+    isError?: boolean;
+    /** MCP 上游返回的结构化结果;consumer endpoint 转发时保留。 */
+    structuredContent?: Record<string, unknown>;
+}
+
+type SearchCapability = 'search' | 'search:semantic';
+/** 全局工具搜索的完整结果；只在权限和可见性候选筛选后 hydrate。 */
+interface ToolSearchHit {
+    path: TreePath;
+    tool: ToolSpec;
+}
+/** adapter 返回的轻量候选；resumeOffset 仅在当前请求内传递，不暴露给协议调用方。 */
+interface ToolSearchCandidate {
+    name: string;
+    path: TreePath;
+    ref: string;
+    resumeOffset: number;
+    revision: number;
+}
+interface ToolSearchOptions {
+    cursor?: string;
+    limit?: number;
+    mode?: 'keyword' | 'semantic';
+}
+/** 宿主提供的全局工具索引；权限和虚拟化仍由 gateway 处理。 */
+interface SearchIndex {
+    readonly capabilities: readonly SearchCapability[];
+    cursorFor(query: string, candidate: ToolSearchCandidate, mode?: 'keyword' | 'semantic'): Promise<string>;
+    search(query: string, opts?: ToolSearchOptions): Promise<Page<ToolSearchCandidate>>;
+}
+/** 索引持久层使用的轻量记录；完整 ToolSpec 只保留摘要，不进入派生数据库。 */
+interface SerializedToolSearchRecord {
+    description: string;
+    feedback: string;
+    name: string;
+    path: TreePath;
+    toolDigest: string;
+}
+/** rebuild 使用的物化文档；feedback 只来自 owning node 的可见反馈投影。 */
+interface ToolSearchDocument extends ToolSearchHit {
+    feedback?: string;
+}
+/**
+ * 可变索引的宿主契约。写入单位是节点快照，避免逐条 upsert 遗留已删除工具；
+ * rebuild 用于首次 seed 与运维修复，removePrefix 用于设备子树回收。
+ */
+interface MutableSearchIndex extends SearchIndex {
+    initialized(): Promise<boolean>;
+    rebuild(documents: readonly ToolSearchDocument[]): Promise<void>;
+    remove(path: TreePath): Promise<void>;
+    removePrefix(path: TreePath): Promise<void>;
+    replace(path: TreePath, tools: readonly ToolSpec[], opts?: {
+        feedback?: string;
+    }): Promise<void>;
+}
+
+/**
+ * SQLite 系 SearchIndex 的共享实现——D1(Workers)与 better-sqlite3(Node)两个
+ * adapter 的唯一真源。
+ *
+ * 此前两边各持一份逐行相同的 schema DDL、查询 SQL、material-change 判定与
+ * cursor/分页逻辑(共 ~780 行,重合度 >85%),任何一侧改动都得靠人工纪律同步到另
+ * 一侧;`shortTermSql.ts` 只收敛了其中最容易出事的一小段。这里把**所有**与具体
+ * 驱动无关的部分收进 `SqlSearchIndex`,宿主差异压缩成 `SqlSearchDriver` 的五个
+ * 方法:
+ *
+ * - D1 全异步、写入走 `db.batch()`,且单请求有 50 查询预算 —— 故记录插入必须
+ *   攒成 JSON1 块(`insertRecords` 返回少量语句)并声明 `assertInsertBudget`;
+ * - better-sqlite3 全同步、写入走 `db.transaction()`,无查询预算 —— 逐条插入即可。
+ *
+ * core 是宿主中立层:这里只产出 SQL 文本与参数数组,不认识 D1Database 也不认识
+ * better-sqlite3。
+ */
+
+/** 一条待执行语句:SQL 文本 + 按序绑定的参数,不含任何驱动对象。 */
+interface SqlSearchStatement {
+    readonly params: readonly unknown[];
+    readonly sql: string;
+}
+/**
+ * 宿主驱动:把 `SqlSearchStatement` 落到具体数据库上。
+ *
+ * `write` 必须原子(D1 `batch` / SQLite `transaction`)——revision bump 与数据变更
+ * 分裂会让 cursor 指向不存在的 offset。
+ */
+interface SqlSearchDriver {
+    /** 多行只读查询。 */
+    all: <T>(statement: SqlSearchStatement) => Promise<T[]>;
+    /**
+     * 记录插入语句数上限(可选);只有查询预算受限的宿主(D1 50/请求)需要实现。
+     * `count` 是本次 mutation 的记录 + 快照插入语句总数,不含固定的删除/bump。
+     */
+    assertInsertBudget?: (count: number) => void;
+    /** 建表(幂等);构造时已建好的宿主实现成 no-op。 */
+    ensureSchema: () => Promise<void>;
+    /** 单行只读查询;无行返回 null。 */
+    first: <T>(statement: SqlSearchStatement) => Promise<T | null>;
+    /** 把记录变成插入语句(JSON1 攒块 or 逐条绑定)。 */
+    insertRecords: (records: readonly SerializedToolSearchRecord[]) => SqlSearchStatement[];
+    /** 把 path→digest 快照变成插入语句。 */
+    insertSnapshots: (digests: ReadonlyMap<TreePath, string>) => SqlSearchStatement[];
+    /** 原子执行一组写语句。 */
+    write: (statements: readonly SqlSearchStatement[]) => Promise<void>;
+}
+declare class SqlSearchIndex implements MutableSearchIndex {
+    protected readonly driver: SqlSearchDriver;
+    readonly capabilities: readonly SearchCapability[];
+    constructor(driver: SqlSearchDriver);
+    /** 容量 trigger 的 ABORT 在各驱动里错误形状不同,统一按标记串归一。 */
+    private writeOrCapacity;
+    private meta;
+    private snapshotDigests;
+    initialized(): Promise<boolean>;
+    replace(path: TreePath, tools: readonly ToolSpec[], opts?: {
+        feedback?: string;
+    }): Promise<void>;
+    remove(path: TreePath): Promise<void>;
+    removePrefix(path: TreePath): Promise<void>;
+    rebuild(documents: readonly ToolSearchDocument[]): Promise<void>;
+    search(query: string, opts?: ToolSearchOptions): Promise<Page<ToolSearchCandidate>>;
+    cursorFor(query: string, candidate: ToolSearchCandidate, mode?: 'keyword' | 'semantic'): Promise<string>;
+}
+
+/**
+ * Plugin 传输客户端:探活、契约抓取、envelope 调用。
+ *
+ * - envelope 与节点调用同形:POST {endpoint} body `{"tool":"<Method>","arguments":{...}}`,
+ *   `X-TB-Context` 承载 CallContext(base64url,唯一载体)、`X-TB-Request-Id` 每次逻辑调用
+ *   唯一;编解码复用 core plugin/envelope(体积守卫 ≤ 1 MiB)。
+ * - Authorization 按 manifest.auth 解析:platform-token → SecretStore 保留名
+ *   `plugin-token:<id>`;bearer → secretRef。
+ * - 重试:仅对 retryable TBError 与网络失败重试 1 次,Request-Id 不变。
+ * - 超时 30s;响应 4xx/5xx 按 TBError body 归一;`$ref` 不解引用(原样透传调用方)。
+ */
+
+/**
+ * 进程内插件装配表:binding 名 → fetch handler(宿主注入,见 TbAppDeps.pluginBindings)。
+ * handler 通常闭包持有插件模块与其 env(如 `req => plugin.fetch(req, env)`);
+ * 懒加载放进闭包即可(首调时 import()),未挂载/未调用的插件零运行成本。
+ */
+type PluginBindingHandler = (request: Request) => Response | Promise<Response>;
+type PluginBindings = ReadonlyMap<string, PluginBindingHandler>;
+
+/**
+ * gateway 侧的**异步**工具源。
+ *
+ * 这是工具源在平台上**唯一**的契约:`list` + `call` 两个动词,方法返回 Promise
+ * (mcp/http/plugin 实现都要发网络请求)。`list` 产出**虚拟化前**的上游原始 `ToolSpec[]`
+ * (名字是上游真名);虚拟化与反查在调用点用 core 的 `virtualizeTools`/`resolveUpstreamTool`。
+ * 没有 `Get`:`~help` 的数据源是 `list` 的产物,平台从不按名单取单个 spec。
+ */
+interface UpstreamProvider {
+    /** 用**上游真名**调用(调用点已把虚拟名反查为真名)。 */
+    call(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** 枚举上游全部工具(虚拟化前的原名)。 */
+    list(): Promise<ToolSpec[]>;
+}
+
+/**
+ * remote 节点透传:把对 `<path>` 及其后代的 `~help`/`~skill`/`~tree`/`POST`
+ * 请求,改写为对 `baseUrl` 下相对路径的**同形**请求。
+ *
+ * - `baseUrl` 白名单(空 = 拒一切)——注册时与调用时双重校验。
+ * - `skRef` 解析出的凭证作为出站 `Authorization: Bearer`;**本地调用者的 SK 不外传**。
+ * - `X-TB-Via`:入站链经 `checkVia` 判环/跳数(在追加自身之前);出站 `appendVia` 追加自身标识。
+ * - 传输失败经 `normalizeUpstreamError` 归一;远端返回的响应(含其自身 TBError)原样透传。
+ *
+ * 宿主中立(核心零分叉):部署配置以解析后的 {@link RemoteSettings} 注入,
+ * env 解析(TB_REMOTE_ALLOWLIST 等)在宿主适配层(gateway app.ts / SDK config)。
+ */
+
+/** remote 透传的部署配置(宿主解析后注入)。 */
+interface RemoteSettings {
+    /** 放行 http:// 上游(仅本地开发)。 */
+    allowInsecure: boolean;
+    /** baseUrl 的 host 后缀白名单;空数组 = 拒一切 remote。 */
+    allowlist: string[];
+    /** 本实例 X-TB-Via 标识;缺省用**入站请求 host** 派生(跨实例联邦须显式配置才能可靠去环)。 */
+    instanceId?: string;
+    /** X-TB-Via 跳数上限(缺省 4,由宿主适配层落默认)。 */
+    maxHops: number;
+}
+
+/**
+ * 宿主注入面与请求期公共类型。
+ *
+ * 这里只放形状:五个注入点(state / objects / secrets / device / search)、进程内
+ * Provider 钩子与解析后的部署配置。行为实现分散在 paths/federation/deviceNodes/
+ * toolNodes/contextNodes/helpModel 与 routes/*,装配在 tbApp.ts。
+ */
+
+/** 帧协议 call 转发的入参(id 由调用点生成,幂等键)。 */
+interface DeviceInvokeRequest {
+    arguments: Record<string, unknown>;
+    id: string;
+    path: string;
+    tool: string;
+}
+/** 设备通道宿主(CF = DeviceSession DO / Docker = ws;deviceTransport 的消费面)。 */
+interface DeviceChannel {
+    /** HTTP→WS 调用转发:结果为 DeviceCallResult 形状(设备侧 result 帧)。 */
+    invoke(deviceId: string, req: DeviceInvokeRequest): Promise<unknown>;
+    /** WS 升级请求转交(/system/device/ws)。 */
+    ws(deviceId: string, request: Request): Promise<Response>;
+}
+/** 进程内本地 Provider 钩子(SDK registerTool/registerContext 的装配面)。 */
+interface LocalProviderHooks {
+    /** kind:'context' 节点按路径取进程内 ContextProvider;undefined → 走 plugin 解析。 */
+    context?(nodePath: TreePath): ContextProvider | undefined;
+    /** kind:'tool' 节点按路径取进程内工具源;undefined → 走 plugin 解析。 */
+    tool?(nodePath: TreePath): UpstreamProvider | undefined;
+}
+/**
+ * tb app 的宿主注入面(五注入点 + 解析后的部署配置)。
+ * 核心业务逻辑零分叉:Workers 适配层(app.ts)与 SDK(packages/sdk)都注入此形状。
+ */
+interface TbAppDeps {
+    /** 放行 http:// 上游(仅本地开发)。 */
+    allowInsecureHttp: boolean;
+    /** Dashboard 静态资源(Workers Static Assets);缺省 → /ui 404。 */
+    assets?: (request: Request) => Promise<Response>;
+    /**
+     * 规范网关 origin(如 `https://tool-bridge.example.com`)。配置后,OAuth 的
+     * redirect_uri 钉在此规范值上,而非每请求动态取 origin——防止实例经多域名
+     * (自定义域 + *.workers.dev 等)访问时,授权 code 在不同域名间被互换。
+     * 缺省 → 回退到请求期 origin(单域名部署行为不变)。
+     */
+    canonicalOrigin?: string;
+    /** 设备通道;缺省 → device 能力禁用。 */
+    device?: DeviceChannel;
+    /** $ref 中转 token 签名密钥(TB_SECRET_ENCRYPTION_KEY);缺省 → /~ref 404、大对象走 presign 或 unavailable。 */
+    encryptionKey?: string;
+    /** 认证前的实例就绪钩子(引导/延迟注册 flush);每请求调用,幂等由宿主保证。 */
+    ensureReady?: () => Promise<void>;
+    /** SDK 进程内 Provider 表(缺省无)。 */
+    locals?: LocalProviderHooks;
+    /** context 平台对象存储('r2' provider 的落点);缺省 → 该 provider unavailable。 */
+    objects?: () => Promise<ObjectStore> | ObjectStore;
+    /**
+     * 进程内插件装配表(binding 名 → fetch handler)。manifest.endpoint 为
+     * `binding:<name>` 的插件经此直调,零网络跳;未装配的 binding 注册/调用报 unavailable。
+     */
+    pluginBindings?: PluginBindings;
+    /** context Get 的 $ref 内联阈值(字节,缺省 1 MiB)。 */
+    refThresholdBytes?: number;
+    /** $ref URL(presign 与 /~ref 中转)有效期秒(缺省 900)。 */
+    refTtlSec?: number;
+    /** remote 联邦透传配置。 */
+    remote: RemoteSettings;
+    /** 追加保留根路径(在内置保留根之外额外声明)。 */
+    reservedRoots?: string[];
+    /** 全局工具搜索索引；缺省或未声明 search capability 时 /~search 不存在。 */
+    search?: SearchIndex;
+    secrets: SecretStoreImpl;
+    state: StateStore;
+    /** mcp/tool 工具缓存 TTL 秒(缺省 300)。 */
+    toolCacheTtlSec?: number;
+    /** healthz 与 system/status 回显的版本号(单一真源:宿主 package.json)。 */
+    version: string;
+}
+/** 请求期变量:认证中间件写入,handler 只读。 */
+type Vars = {
+    ctx: CallContext;
+    store: StateStore;
+};
+
+/**
+ * 构造 tool-bridge 的 Hono app(宿主中立;Workers 适配见 app.ts,SDK 装配见 packages/sdk)。
+ */
+declare function createTbApp(deps: TbAppDeps): Hono<{
+    Variables: Vars;
+}>;
+
+/**
+ * Node 宿主的 env 配置面。变量名与语义对齐 CF 宿主(gateway/src/app.ts 的 Env),
+ * 仅新增宿主形态相关的 TB_PORT / TB_HOST / TB_DATA_DIR / TB_UI_DIR。
+ * 解析函数镜像 app.ts 的 allowInsecure / remoteSettingsFromEnv / positiveIntEnv。
+ */
+
+interface ServerConfig {
+    /** 首次引导的 Admin SK 明文(须经 TB_BOOTSTRAP_ADMIN_SK 预置;缺省且未开 insecure bootstrap 则 fail closed)。 */
+    adminSk?: string;
+    /**
+     * 逃生阀:显式放行"缺 Admin SK 时随机生成并打印明文"的旧行为(仅本地/一次性开发)。
+     * 默认 false → 生产/Docker 缺 TB_BOOTSTRAP_ADMIN_SK 时拒绝启动,不把最高权限凭证写日志。
+     */
+    allowInsecureBootstrap: boolean;
+    allowInsecureHttp: boolean;
+    /**
+     * 规范网关 origin(TB_CANONICAL_ORIGIN):多域名访问时钉死 OAuth redirect_uri。
+     * 与 Workers 宿主同一解析真源(core normalizeCanonicalOrigin);配置了但非法 →
+     * configFromEnv 抛错,进程拒绝启动(fail closed,不静默回退到请求期 origin)。
+     */
+    canonicalOrigin?: string;
+    /** SQLite 库与 fs 对象根所在目录(state.sqlite3 + objects/)。 */
+    dataDir: string;
+    /** 设备断线后未重连的回收秒数(缺省 24h)。 */
+    deviceReclaimSec: number;
+    /** SecretStore 主密钥 + $ref 中转 token 签名密钥(base64url 32B)。 */
+    encryptionKey?: string;
+    host: string;
+    /**
+     * 进程内插件装配表(binding 名 → fetch handler),供程序化嵌入方注入;
+     * `binding:<name>` 的插件经此直调,零网络跳。bin 入口暂不从 env 装配。
+     */
+    pluginBindings?: PluginBindings;
+    port: number;
+    refThresholdBytes?: number;
+    refTtlSec?: number;
+    remote: {
+        allowInsecure: boolean;
+        allowlist: string[];
+        instanceId?: string;
+        maxHops: number;
+    };
+    toolCacheTtlSec?: number;
+    /** Dashboard 静态资源目录覆盖(缺省经 @tool-bridge/dashboard 包解析)。 */
+    uiDir?: string;
+}
+declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
+
+/**
+ * DeviceHub:Node 宿主的设备通道(DeviceChannel 实现,对位 CF 的 DeviceSession DO)。
+ *
+ * WS 升级走 http.Server 'upgrade' 事件 + ws handleUpgrade(不经 fetch handler,
+ * tbApp 的认证中间件天然旁路),认证双点补齐:升级前 identify(401 早失败)+
+ * 共享 processDeviceHello 内的权威判定(与 DO 同一模块,树形态/权限判定序不漂移)。
+ *
+ * 与 DO 的有意分叉:
+ * - requestId 幂等表仅内存(session 内):进程重启 WS 必断、待决调用随进程消亡,
+ *   无 DO hibernation 的跨休眠回放需求;tbApp 每次 invoke 生成新 UUID,跨连接去重无收益。
+ * - 断线回收用进程内 setTimeout + StateStore 持久 meta(devicemeta:<id>),启动时
+ *   sweepOrphans 扫描孤儿排程(对位 DO 的 storage+alarm)。
+ * - 心跳:应用层 ping→pong 已内置于 DeviceGatewaySession.handleFrame;另加 ws 协议层
+ *   探活(isAlive + 周期 ping + terminate)踢半开死连接,避免调用一律吃 60s 超时。
+ */
+
+declare const DEVICE_WS_PATH = "/system/device/ws";
+declare class DeviceHub {
+    private readonly store;
+    private readonly search;
+    private readonly reclaimSec;
+    private readonly wss;
+    private readonly activeByDevice;
+    private readonly connections;
+    private readonly reclaimTimers;
+    private heartbeat;
+    constructor(opts: {
+        heartbeatMs?: number;
+        reclaimSec: number;
+        search?: MutableSearchIndex;
+        store: StateStore;
+    });
+    /** 挂到 http.Server 的 'upgrade' 事件(仅处理 DEVICE_WS_PATH,其余 404)。 */
+    attach(server: http.Server): void;
+    /** DeviceChannel.invoke:HTTP→WS 调用转发(无活连接 → deviceOffline)。 */
+    invoke(deviceId: string, req: DeviceInvokeRequest): Promise<unknown>;
+    /** DeviceChannel.ws:Node 宿主的升级在 http 层处理,永不应命中此路由。 */
+    ws(): Promise<Response>;
+    /**
+     * 启动孤儿扫描:devicemeta: 里无活连接的设备补排回收 timer。
+     * 崩溃时仍在线(无 disconnectedAt)按"此刻断线"起算;已过期立即回收。
+     */
+    sweepOrphans(): Promise<void>;
+    close(): Promise<void>;
+    private handleUpgrade;
+    private acceptConnection;
+    private acceptHello;
+    /** 连接失效收尾(对位 DO markDisconnected):registry 下线 + meta 记断线 + 排回收。 */
+    private onClose;
+    private scheduleReclaim;
+    private cancelReclaim;
+    /** 回收执行(对位 DO alarm):仍无活连接才删子树 + meta。 */
+    private reclaim;
+    /** ws 协议层探活:上一轮未回 pong → terminate(触发 close → markDisconnected)。 */
+    private pingConnections;
+}
+
+/**
+ * createDataObjectStore:平台对象存储('r2' provider 落点)的 Node 实现。
+ *
+ * core FsObjectStore 是多根语义(key 首段必须等于某 root 的 basename),而平台
+ * 对象存储的 key 是平坦任意前缀(默认 ctx/<nodePath>/...)——本模块做薄前缀适配:
+ * 出入口统一加/剥内部根段 'objects/',穿越防护复用 FsObjectStore 的两层防护
+ * (normalizeEntryPath + realpath-in-root),不重写。cursor 是内部形态原样透传
+ * (消费方视 cursor 为不透明串)。无 presign → $ref 走 /~ref 网关中转(现有降级)。
+ */
+
+declare function createDataObjectStore(dataDir: string): ObjectStore;
+
+/** Node 宿主的 better-sqlite3 FTS5/trigram SearchIndex。 */
+declare class SqliteSearchIndex extends SqlSearchIndex {
+    private readonly db;
+    constructor(dbPath: string);
+    close(): void;
+}
+
+/**
+ * SqliteStateStore:better-sqlite3 实现的 StateStore(Docker/Node 宿主)。
+ *
+ * 单表 kv(key TEXT PRIMARY KEY, value TEXT)——StateStore 本身就是 kv 语义,
+ * 拆表只会复制 key 布局知识。值 JSON 序列化存取(与 KvStateStore 同形)。
+ * 强一致:吊销/写入即时可见,无 KV 的最终一致窗口(kvStateStore.ts 的跳 null
+ * 与逐 key get 负担在此宿主不存在)。
+ *
+ * list 用 key 范围扫描(>= prefix AND < successor(prefix)),不用 LIKE/GLOB——
+ * key 里的路径段可含 '_'/'%'/'[',通配符转义是坑。cursor/排序语义与
+ * core MemoryStateStore 对拍(cursor = 上页末 key,仅在还有更多时返回)。
+ * 注意:SQLite TEXT 按 UTF-8 字节序比较,JS 按 UTF-16 code unit 比较,
+ * 二者在 ASCII 与 BMP 码点上一致;key 由本项目生成(ASCII 前缀 + 树路径),
+ * 防御性地对返回行再做 startsWith 过滤。
+ */
+
+declare class SqliteStateStore implements StateStore {
+    private readonly db;
+    private readonly stmtGet;
+    private readonly stmtPut;
+    private readonly stmtDelete;
+    constructor(dbPath: string);
+    get(key: string): Promise<unknown | null>;
+    getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        cursor?: string;
+        items: Array<{
+            key: string;
+            value: unknown;
+        }>;
+    }>;
+    close(): void;
+}
+
+/**
+ * createTbServer:Node 宿主装配(对位 gateway/src/app.ts 的 depsFromEnv)。
+ *
+ * SQLite StateStore + fs ObjectStore + @hono/node-server;引导在 start() 时
+ * 直调宿主中立 runBootstrap(Node 有真实启动点,不需要 Workers 的 per-request once,
+ * 故不注入 deps.ensureReady)。设备通道(DeviceHub)与 /ui 静态托管由后续
+ * 装配点注入(deps.device / deps.assets)。
+ */
+
+interface TbServer {
+    app: ReturnType<typeof createTbApp>;
+    close(): Promise<void>;
+    deviceHub: DeviceHub;
+    search: SqliteSearchIndex;
+    /** 引导(幂等)+ 孤儿设备回收排程 + 监听;返回实际端口(config.port=0 时由系统分配)。 */
+    start(): Promise<{
+        port: number;
+    }>;
+    state: SqliteStateStore;
+}
+declare function createTbServer(config: ServerConfig): TbServer;
+
+export { DEVICE_WS_PATH, DeviceHub, type ServerConfig, SqliteSearchIndex, SqliteStateStore, type TbServer, configFromEnv, createDataObjectStore, createTbServer };