@tool-bridge/server 0.15.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 {
@@ -482,7 +440,19 @@ interface ObjectPresignPutOptions {
     /** `*` 表示仅当对象不存在时写入；必须随 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<{
@@ -495,9 +465,71 @@ interface ObjectStore {
     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 帧协议的类型与编解码。
  *
@@ -524,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;
+    };
 }
 
 /**
@@ -917,6 +959,26 @@ 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)。 */
@@ -972,7 +1034,7 @@ interface ServerConfig {
     encryptionKey?: string;
     host: string;
     /**
-     * 平台对象存储(context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
+     * 平台对象存储(default Store + context `$ref` 大对象落点)。给出则用 S3/R2 兼容端点,
      * 缺省回退 dataDir 下的本地 FS。配 S3 后容器可无状态横向扩容 —— FS 落点
      * 在多副本间互不可见、容器重建即丢。
      */
@@ -1021,6 +1083,28 @@ 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;
@@ -1247,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?: {
@@ -1349,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-NLPTB3IL.js";
-import "./chunk-DXXYNIXV.js";
+} from "./chunk-BB6ZLMTU.js";
+import "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 export {
   DEVICE_FORWARD_TIMEOUT_MS,

package/dist/{ip2proxy-GPBQZKKG.js → ip2proxy-DAYO7EKZ.js}

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

package/dist/{ipgeolocation_io-YNTOLOFH.js → ipgeolocation_io-XD4PSLII.js}

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

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

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

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

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

package/dist/{jira-2DKTIWHK.js → jira-ZDSXGQ6W.js}

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

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

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

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

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

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

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

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

@@ -2,14 +2,14 @@ import {
   createProviderPlugin,
   requireApiKey,
   upstreamError
-} from "./chunk-NQ67PIIS.js";
+} from "./chunk-VK3V2WTY.js";
 import {
   guardedFetch
-} from "./chunk-KH663T3A.js";
-import "./chunk-UI4E4T5Q.js";
+} from "./chunk-2O27H4Y2.js";
+import "./chunk-GKX72JMJ.js";
 import {
   external_exports
-} from "./chunk-DXXYNIXV.js";
+} from "./chunk-YB2FLNWI.js";
 import "./chunk-MLKGABMK.js";
 
 // ../plugins/src/logsnag/api.ts