@tool-bridge/server 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -68,8 +68,24 @@ interface Scope {
  *   sys:bootstrapped  → true(Admin SK 引导幂等标志)
  *   annotation:<path> → { text, updatedAt, updatedBy }(管理员 Path 补充说明)
  *   feedback:<path>   → FeedbackEntry[](Agent 使用反馈,单 key 整存)
+ *   store:object:<id>  → StoreObject(revision CAS)
+ *   store:upload:<id>  → UploadSession(revision CAS)
+ *   store:call-capability:<id> → CallUploadCapability(token 仅存 hash)
+ *   store:share:<id>   → ShareGrant(token 仅存 hash)
  */
 interface StateStore {
+    /**
+     * 可选原子 compare-and-swap 原语，供带 `revision` 的权威记录做跨副本状态转换。
+     *
+     * - `expectedRevision === null`：仅当 key 不存在时写入；
+     * - 数字：仅当现存值是对象且其 `revision` 严格等于该值时替换或删除；
+     * - `value === null`：命中后删除，否则替换为 value。
+     *
+     * 调用方负责让新值的 revision 从 expectedRevision 单调加一。实现必须把比较与
+     * 写入/删除放在同一条原子存储操作中，不能用 get→put 或进程内锁模拟。
+     * StoreService 等依赖并发状态机的能力会在缺少此原语时 fail closed。
+     */
+    compareAndSwap?(key: string, expectedRevision: number | null, value: unknown | null): Promise<boolean>;
     delete(key: string): Promise<void>;
     get(key: string): Promise<unknown | null>;
     /** 批量读取，返回值只包含当前存在的 key；单次最多 100 keys。 */
@@ -358,66 +374,6 @@ interface BuiltinCatalogEntry {
 /** binding 名 → 目录项。 */
 type BuiltinCatalog = Record<string, BuiltinCatalogEntry>;
 
-/**
- * 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:对象存储抽象。
  *
@@ -456,6 +412,8 @@ interface ObjectPutOptions {
     contentType?: string;
     /** 与现存对象 etag 不符(含对象不存在)→ TBError conflict。 */
     ifMatchEtag?: string;
+    /** `*` 表示仅当对象不存在时创建；命中现存对象 → TBError conflict。 */
+    ifNoneMatch?: '*';
     metadata?: Record<string, string>;
 }
 interface ObjectListOptions {
@@ -471,7 +429,30 @@ interface ObjectListResult {
         prefix: string;
     }>;
 }
+interface ObjectPresignedPut {
+    /** 上传时必须原样携带的请求头。 */
+    headers: Record<string, string>;
+    method: 'PUT';
+    url: string;
+}
+interface ObjectPresignPutOptions {
+    contentType: string;
+    /** `*` 表示仅当对象不存在时写入；必须随 PUT 一同签名并发送。 */
+    ifNoneMatch?: '*';
+}
+/**
+ * 定长直传契约：实现必须把 Content-Length 纳入签名，让存储端拒绝
+ * 任何与声明字节数不同的请求。普通 `presignPut` 没有这个安全保证。
+ */
+interface ObjectPresignPutExactOptions extends ObjectPresignPutOptions {
+    contentLength: number;
+}
 interface ObjectStore {
+    /**
+     * 可选宿主钩子：清理 prefix 下早于 olderThan 的未落位 staging 临时文件。
+     * staging 不进入 list，且命名/mtime 属于 driver 私有实现；返回实际删除数量。
+     */
+    cleanupStaging?(prefix: string, olderThan: string): Promise<number>;
     /** 幂等:不存在静默。 */
     delete(key: string): Promise<void>;
     get(key: string): Promise<{
@@ -482,9 +463,73 @@ interface ObjectStore {
     list(prefix: string, opts?: ObjectListOptions): Promise<ObjectListResult>;
     /** 生成限时直连 URL;后端不支持则缺省(provider 退化到 relayRefUrl)。 */
     presign?(key: string, ttlSec: number): Promise<string>;
+    /** 生成限时、定路径的直传 PUT 请求；后端或凭证不支持时缺省。 */
+    presignPut?(key: string, ttlSec: number, opts: ObjectPresignPutOptions): Promise<ObjectPresignedPut>;
+    /** 仅当 backend 能在签名中强制精确 Content-Length 时提供。 */
+    presignPutExact?(key: string, ttlSec: number, opts: ObjectPresignPutExactOptions): Promise<ObjectPresignedPut>;
     put(key: string, body: ObjectBody, opts?: ObjectPutOptions): Promise<ObjectMeta>;
 }
 
+/**
+ * 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>;
+}
+
 /**
  * DeviceFrame:设备 WS 帧协议的类型与编解码。
  *
@@ -511,6 +556,16 @@ interface DeviceCallContext {
     expiresAt: Timestamp;
     /** 全链路观测,与 call id 同源。 */
     traceId: string;
+    /**
+     * 本次 call 独享的 Store 上传能力。token 是短期 bearer，只由 SDK 消费并放入
+     * capability-only 请求 header，设备 handler 不应把它写入结果或日志。
+     */
+    upload?: {
+        expiresAt: Timestamp;
+        maxBytes: number;
+        maxObjects: number;
+        token: string;
+    };
 }
 
 /**
@@ -904,8 +959,30 @@ interface TbAppDeps {
     search?: SearchIndex;
     secrets: SecretStoreImpl;
     state: StateStore;
+    /** call capability 允许的 MIME pattern；缺省 `*\/*`。 */
+    storeCallAllowedContentTypes?: string[];
+    /** 单次 device call 的聚合上传字节预算。 */
+    storeCallMaxBytes?: number;
+    /** 单次 device call 的单对象字节预算。 */
+    storeCallMaxObjectBytes?: number;
+    /** 单次 device call 最多创建的 Store 对象数。 */
+    storeCallMaxObjects?: number;
+    /** default Store 的单对象部署级上限。 */
+    storeMaxObjectBytes?: number;
+    /** owner read `$ref` 有效期秒；缺省 refTtlSec 或 900。 */
+    storeReadTtlSec?: number;
+    /** relay transport 的有效 request-body 上限；direct 不受此值收紧。 */
+    storeRelayMaxBytes?: number;
+    /** 短期 share 的缺省有效期秒。 */
+    storeShareTtlSec?: number;
+    /** Store capability HMAC secret；缺省由 StateStore 原子生成并持久化。 */
+    storeTokenSecret?: string;
+    /** Store upload session 有效期秒。 */
+    storeUploadTtlSec?: number;
     /** mcp/tool 工具缓存 TTL 秒(缺省 300)。 */
     toolCacheTtlSec?: number;
+    /** create_upload 写入 grant 有效期秒；缺省 min(refTtlSec, 900)。 */
+    uploadGrantTtlSec?: number;
     /** healthz 与 system/status 回显的版本号(单一真源:宿主 package.json)。 */
     version: string;
 }
@@ -957,7 +1034,7 @@ interface ServerConfig {
     encryptionKey?: string;
     host: string;
     /**
-     * 平台对象存储(context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
+     * 平台对象存储(default Store + context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
      * 缺省回退 dataDir 下的本地 FS。配 S3 后容器可无状态横向扩容 —— FS 落点
      * 在多副本间互不可见、容器重建即丢。
      */
@@ -1006,9 +1083,33 @@ interface ServerConfig {
      * 请求吃闭门羹;单机/本地开发保持 0,关停立即进行。
      */
     shutdownDrainSec?: number;
+    /** 设备调用允许上传的 MIME pattern；缺省由应用使用安全默认值。 */
+    storeCallAllowedContentTypes?: string[];
+    /** 设备调用所签发 Store capability 的总字节上限。 */
+    storeCallMaxBytes?: number;
+    /** 设备调用单个 Store 对象的字节上限。 */
+    storeCallMaxObjectBytes?: number;
+    /** 设备调用最多可创建的 Store 对象数。 */
+    storeCallMaxObjects?: number;
+    /** Store 孤儿字节、过期 session/share/call capability 的周期清理间隔。 */
+    storeCleanupIntervalSec: number;
+    /** Store 对象统一上限；direct upload 可使用完整值。 */
+    storeMaxObjectBytes?: number;
+    /** Store owner read ref 的有效期。 */
+    storeReadTtlSec?: number;
+    /** relay upload 的宿主有效上限；缺省等于对象统一上限。 */
+    storeRelayMaxBytes?: number;
+    /** Store 匿名可撤销 share 的有效期。 */
+    storeShareTtlSec?: number;
+    /** 显式 Store token 根密钥；缺省由应用在 StateStore 原子生成并持久化。 */
+    storeTokenSecret?: string;
+    /** Store upload session 的有效期。 */
+    storeUploadTtlSec?: number;
     toolCacheTtlSec?: number;
     /** Dashboard 静态资源目录覆盖(缺省经 @tool-bridge/dashboard 包解析)。 */
     uiDir?: string;
+    /** create_upload 写入 grant 有效期秒；缺省 min(refTtlSec, 900)。 */
+    uploadGrantTtlSec?: number;
 }
 declare function configFromEnv(env?: NodeJS.ProcessEnv): ServerConfig;
 
@@ -1230,6 +1331,7 @@ declare class PgStateStore implements StateStore {
     get(key: string): Promise<unknown | null>;
     getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
     put(key: string, value: unknown): Promise<void>;
+    compareAndSwap(key: string, expectedRevision: number | null, value: unknown | null): Promise<boolean>;
     putIfAbsent(key: string, value: unknown): Promise<boolean>;
     delete(key: string): Promise<void>;
     list(prefix: string, opts?: {
@@ -1332,6 +1434,7 @@ declare class SqliteStateStore implements StateStore {
     get(key: string): Promise<unknown | null>;
     getMany(keys: readonly string[]): Promise<Map<string, unknown>>;
     put(key: string, value: unknown): Promise<void>;
+    compareAndSwap(key: string, expectedRevision: number | null, value: unknown | null): Promise<boolean>;
     putIfAbsent(key: string, value: unknown): Promise<boolean>;
     delete(key: string): Promise<void>;
     list(prefix: string, opts?: {

package/dist/index.js

@@ -12,8 +12,8 @@ import {
   configFromEnv,
   createDataObjectStore,
   createTbServer
-} from "./chunk-X6LLG5OZ.js";
-import "./chunk-ABHHWYEV.js";
+} from "./chunk-BB6ZLMTU.js";
+import "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 export {
   DEVICE_FORWARD_TIMEOUT_MS,

package/dist/{ip2proxy-4SAYDJPQ.js → ip2proxy-DAYO7EKZ.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ip2proxy/schema.ts

package/dist/{ipgeolocation_io-4WT2WKHF.js → ipgeolocation_io-XD4PSLII.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ipgeolocation_io/api.ts

package/dist/{ipqualityscore-VGZCROJJ.js → ipqualityscore-K27QEAWK.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/ipqualityscore/api.ts

package/dist/{jina_ai-X5VJVORK.js → jina_ai-E6UXFV2P.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/jina_ai/api.ts

package/dist/{jira-XUAF2UPM.js → jira-ZDSXGQ6W.js}

@@ -2,16 +2,16 @@ import {
   createProviderPlugin,
   requireCredential,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   assertPublicHttpUrl,
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/jira/api.ts

package/dist/{langsmith-RRLFNL6D.js → langsmith-TIFJRREW.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/langsmith/api.ts

package/dist/{lemlist-KQKG6JHM.js → lemlist-DASEMJMA.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/lemlist/api.ts

package/dist/{linear-I32UBCBL.js → linear-KE6UP4SP.js}

@@ -2,15 +2,15 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   TBError,
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/linear/api.ts

package/dist/{logsnag-TVNUQEM7.js → logsnag-IMNDN4R5.js}

@@ -2,14 +2,14 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-BWGAV3MR.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-HGIPJFHA.js";
-import "./chunk-CDOWN2AB.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   external_exports
-} from "./chunk-ABHHWYEV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/logsnag/api.ts