@evilstar9527/tool-bridge 0.1.0

package/dist/types/worker/tb/errors.d.ts

@@ -0,0 +1,34 @@
+export interface ErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export declare const RETRYABLE_CODES: ReadonlySet<string>;
+export declare function isRetryable(code: string): boolean;
+export declare class TBError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(code: string, status: number, message: string, details?: unknown);
+    get retryable(): boolean;
+}
+export declare class NotFoundError extends TBError {
+    constructor(message: string, details?: unknown);
+}
+export declare class UpstreamError extends TBError {
+    constructor(message: string, details?: unknown);
+}
+export declare class EndpointUnavailableError extends TBError {
+    constructor(message: string, details?: unknown);
+}
+export declare class ForbiddenError extends TBError {
+    constructor(message: string, details?: unknown);
+}
+export declare class BadRequestError extends TBError {
+    constructor(message: string, details?: unknown);
+}
+export declare function errorEnvelope(code: string, message: string, details?: unknown): ErrorEnvelope;
+export declare function errorResponse(status: number, code: string, message: string, details?: unknown): Response;
+export declare function errorResponseOf(error: unknown): Response;

package/dist/types/worker/tb/help.d.ts

@@ -0,0 +1,2 @@
+import { HelpPayload } from './types';
+export declare function buildTextHelp(payload: HelpPayload, resourcePath: string, auth: 'none' | 'bearer'): string;

package/dist/types/worker/tb/host-api.d.ts

@@ -0,0 +1,12 @@
+import { ApiPrincipal } from './provider-api';
+import { AppEnv } from './types';
+export interface HostRecord {
+    id: string;
+    tenantId: string;
+    providerId: string;
+    confirmDelegated?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function getHost(env: AppEnv, id: string): Promise<HostRecord | null>;
+export declare function routeHostApi(request: Request, env: AppEnv, principal: ApiPrincipal): Promise<Response | undefined>;

package/dist/types/worker/tb/materialize.d.ts

@@ -0,0 +1,4 @@
+import { AppEnv } from './types';
+export declare function materializeHeaders(env: AppEnv, headers: Record<string, string> | undefined): Record<string, string>;
+export declare function requireSecureUrl(env: AppEnv, rawUrl: string, label: string): string;
+export declare function assertRemoteHostAllowed(env: AppEnv, rawUrl: string): void;

package/dist/types/worker/tb/mcp-client.d.ts

@@ -0,0 +1,17 @@
+import { AppEnv, McpNode } from './types';
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: unknown;
+}
+export interface ResolvedMcpServer {
+    id: string;
+    endpoint: string;
+    allowedTools?: string[];
+    resolvedHeaders: Record<string, string>;
+}
+export declare function resolveMcpServer(env: AppEnv, node: McpNode): ResolvedMcpServer;
+export declare function listMcpTools(server: ResolvedMcpServer): Promise<McpTool[]>;
+export declare function callMcpTool(server: ResolvedMcpServer, toolName: string, args: unknown): Promise<unknown>;

package/dist/types/worker/tb/provider-api.d.ts

@@ -0,0 +1,11 @@
+import { PrincipalKind } from './tenant';
+import { AppEnv } from './types';
+export interface ApiPrincipal {
+    isAdmin: boolean;
+    principal?: PrincipalKind;
+    providerId?: string;
+    hostId?: string;
+    tenantId?: string;
+    subject?: string;
+}
+export declare function routeProviderApi(request: Request, env: AppEnv, principal: ApiPrincipal): Promise<Response | undefined>;

package/dist/types/worker/tb/registry.d.ts

@@ -0,0 +1,11 @@
+import { AppEnv, DirectoryNode, TreeNode } from './types';
+export declare const TREE_PREFIX = "/htbp";
+export declare function parseTree(env: AppEnv): DirectoryNode;
+export declare function parseTreeFromJson(raw: string): DirectoryNode;
+export declare function normalizeNodeConfig(value: unknown, label: string): TreeNode;
+export declare function linkParents(node: TreeNode): void;
+export declare function nodePath(node: TreeNode): string;
+export declare function findNode(root: DirectoryNode, segments: string[]): {
+    node: TreeNode;
+    sub: string[];
+} | undefined;

package/dist/types/worker/tb/remote-client.d.ts

@@ -0,0 +1,3 @@
+import { AppEnv, HelpPayload } from './types';
+export declare function fetchRemoteHelp(env: AppEnv, helpUrl: string, headers: Record<string, string> | undefined): Promise<HelpPayload>;
+export declare function parseHelpPayload(body: string): HelpPayload;

package/dist/types/worker/tb/resolve.d.ts

@@ -0,0 +1,8 @@
+import { AppEnv, AuthMode, BuiltinHandlerRegistry, DirectoryNode, HelpPayload } from './types';
+export interface ResolvedHelp {
+    payload: HelpPayload;
+    resourcePath: string;
+}
+export declare function resolveHelp(env: AppEnv, root: DirectoryNode, segments: string[], authMode: AuthMode, accept: string, builtinHandlers?: BuiltinHandlerRegistry): Promise<Response>;
+export declare function resolveCall(env: AppEnv, root: DirectoryNode, segments: string[], authMode: AuthMode, input: unknown, builtinHandlers?: BuiltinHandlerRegistry): Promise<Response>;
+export { NotFoundError } from './util';

package/dist/types/worker/tb/storage-r2.d.ts

@@ -0,0 +1,2 @@
+import { AppEnv, StorageProvider } from './types';
+export declare function r2Provider(env: AppEnv, bucketBinding: string): StorageProvider;

package/dist/types/worker/tb/tenant.d.ts

@@ -0,0 +1,28 @@
+import { AppEnv, DirectoryNode } from './types';
+export type PrincipalKind = 'agent' | 'provider' | 'host' | 'admin' | 'service';
+export interface PrincipalRecord {
+    principal: PrincipalKind;
+    tenantId?: string;
+    providerId?: string;
+    hostId?: string;
+    label?: string;
+    createdAt?: string;
+    expiresAt?: string;
+}
+export interface PrincipalContext extends PrincipalRecord {
+    root?: DirectoryNode;
+}
+export interface TenantContext {
+    tenantId: string;
+    root: DirectoryNode;
+}
+export declare function tenantModeEnabled(env: AppEnv): boolean;
+export declare function sha256Hex(value: string): Promise<string>;
+export declare function resolvePrincipal(env: AppEnv, token: string): Promise<PrincipalContext | null>;
+export declare function resolveTenant(env: AppEnv, token: string): Promise<TenantContext | null>;
+export declare function generateKey(prefix: 'tbk' | 'tbp' | 'tbs'): string;
+export declare function storeApiKey(env: AppEnv, rawKey: string, record: PrincipalRecord): Promise<void>;
+export declare function listApiKeyRecords(env: AppEnv): Promise<Array<{
+    hash: string;
+    record: PrincipalRecord;
+}>>;

package/dist/types/worker/tb/testing/fake-kv.d.ts

@@ -0,0 +1,20 @@
+export interface FakeKV {
+    get(key: string, type?: 'json' | 'text'): Promise<unknown>;
+    put(key: string, value: string, opts?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(opts?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+    dump(): Record<string, string>;
+}
+export declare function fakeKV(seed?: Record<string, string>): FakeKV;

package/dist/types/worker/tb/types.d.ts

@@ -0,0 +1,155 @@
+export type NodeKind = 'directory' | 'mcp' | 'http' | 'remote' | 'mount' | 'builtin';
+export type ToolEffect = 'read' | 'write' | 'destructive' | 'external';
+export type AuthMode = 'none' | 'bearer' | 'oauth';
+export type AppEnv = Env & {
+    AUTH_BEARER_TOKEN?: string;
+    OAUTH_ISSUER?: string;
+    OAUTH_JWKS_URI?: string;
+    ALLOW_INSECURE_MCP_HTTP?: string;
+    HTBP_REMOTE_ALLOWLIST?: string;
+    TENANT_MODE?: string;
+};
+export interface ResourceRef {
+    name: string;
+    path: string;
+    description?: string;
+}
+export interface ToolSpec {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface EndpointSpec {
+    method: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    example?: unknown;
+    tools?: ToolSpec[];
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface HelpPayload {
+    htbp: 'draft';
+    kind: NodeKind;
+    title: string;
+    description?: string;
+    cachable?: boolean;
+    resources?: ResourceRef[];
+    endpoint?: EndpointSpec;
+}
+export interface BaseNode {
+    kind: NodeKind;
+    id: string;
+    title: string;
+    summary?: string;
+    parent?: TreeNode;
+}
+export interface DirectoryNode extends BaseNode {
+    kind: 'directory';
+    children: TreeNode[];
+}
+export interface ToolOverride {
+    hide?: boolean;
+    rename?: string;
+    description?: string;
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface McpNode extends BaseNode {
+    kind: 'mcp';
+    endpoint: string;
+    description?: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[];
+    namespace?: string;
+    toolOverrides?: Record<string, ToolOverride>;
+}
+export interface HttpEndpointConfig {
+    name: string;
+    method: string;
+    url: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    example?: unknown;
+    headers?: Record<string, string>;
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface HttpNode extends BaseNode {
+    kind: 'http';
+    endpoints: HttpEndpointConfig[];
+}
+export interface RemoteNode extends BaseNode {
+    kind: 'remote';
+    helpUrl: string;
+    headers?: Record<string, string>;
+}
+export interface MountNode extends BaseNode {
+    kind: 'mount';
+    bucket: string;
+    prefix?: string;
+    description?: string;
+}
+export type TreeNode = DirectoryNode | McpNode | HttpNode | RemoteNode | MountNode | BuiltinNode;
+export interface BuiltinToolConfig {
+    name: string;
+    description?: string;
+    handler: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    effect?: ToolEffect;
+    scope?: string;
+    confirm?: boolean;
+}
+export interface BuiltinNode extends BaseNode {
+    kind: 'builtin';
+    description?: string;
+    tools: BuiltinToolConfig[];
+}
+export type BuiltinHandler = (input: unknown, ctx: AdapterContext) => Promise<unknown> | unknown;
+export type BuiltinHandlerRegistry = Record<string, BuiltinHandler>;
+export interface StorageEntry {
+    name: string;
+    key: string;
+    isDir: boolean;
+}
+export interface StorageObject {
+    key: string;
+    body: string;
+    contentType?: string;
+    size?: number;
+}
+export interface StorageProvider {
+    list(prefix: string): Promise<StorageEntry[]>;
+    get(key: string): Promise<StorageObject | null>;
+}
+export interface AdapterContext {
+    env: AppEnv;
+    authMode: AuthMode;
+    basePath: string;
+    builtinHandlers?: BuiltinHandlerRegistry;
+}
+export interface TBAdapter<TNode extends TreeNode = TreeNode> {
+    kind: NodeKind;
+    describe(node: TNode, ctx: AdapterContext, sub: string[]): Promise<HelpPayload>;
+    call(node: TNode, ctx: AdapterContext, sub: string[], input: unknown): Promise<unknown>;
+}
+export interface CrawlNode {
+    kind: NodeKind;
+    path: string;
+    title?: string;
+    description?: string;
+    helpUrl: string;
+    children: CrawlNode[];
+    endpoint?: EndpointSpec;
+    error?: string;
+    truncated?: boolean;
+}

package/dist/types/worker/tb/util.d.ts

@@ -0,0 +1,18 @@
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+export declare const CLIENT_NAME = "tool-bridge";
+export declare const CLIENT_VERSION = "draft";
+export declare const MAX_JSON_BYTES = 1000000;
+export declare const MAX_SSE_BYTES = 4000000;
+export declare const REMOTE_FETCH_TIMEOUT_MS = 5000;
+export type JsonObject = Record<string, unknown>;
+export declare function json(data: unknown, init?: ResponseInit): Response;
+export declare function text(data: string, init?: ResponseInit): Response;
+export { errorResponse, NotFoundError } from './errors';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function stringField(value: Record<string, unknown>, key: string): string | undefined;
+export declare function recordOfStrings(value: unknown): Record<string, string> | undefined;
+export declare function arrayOfStrings(value: unknown): string[] | undefined;
+export declare function oneLine(value: string): string;
+export declare function messageOf(error: unknown): string;
+export declare function readBoundedText(response: Response, maxBytes: number): Promise<string>;
+export declare function safeErrorText(response: Response): Promise<string>;

package/dist/types/worker/tb/virtualize.d.ts

@@ -0,0 +1,7 @@
+import { McpNode, ToolSpec } from './types';
+export interface Virtualized {
+    exposed: ToolSpec[];
+    reverse: Map<string, string>;
+}
+export declare function virtualizeTools(node: McpNode, upstream: ToolSpec[]): Virtualized;
+export declare function resolveUpstreamTool(node: McpNode, upstream: ToolSpec[], virtualName: string): string;

package/docs/sdk.md

@@ -0,0 +1,149 @@
+# Tool Bridge SDK（单包多入口）— API 与 curl 等价表
+
+SPEC-001 §8.1 不变量：wire contract 是产品本体，SDK 只是便利层——**不存在只有 SDK
+能做的事**。下表给出每个 SDK 方法对应的公开 API 与 curl 复现方式。conformance
+测试（`src/sdk/host/host.test.ts`、`src/worker/tb/provider-api.test.ts`）对 SDK 与
+原始请求跑同一断言集。
+
+约定：`$TB` = bridge base URL；`$ADMIN` = admin key；`$HOST` = 宿主 S2S key
+（`tbk_`）；`$TBP` = provider key（`tbp_`）。所有 token 一律走 `Authorization:
+Bearer`，绝不进 query string（§8.2）。
+
+## 错误契约（M0）
+
+所有错误统一信封：`{"error":{"code":"...","message":"...","details":...}}`。
+
+| code | HTTP | retryable |
+| --- | --- | --- |
+| `UpstreamError`（上游传输/供给方失败） | 502 | ✅ |
+| `EndpointUnavailable`（保留给 Tunnel/Device） | 503 | ✅ |
+| `Forbidden`（已认证但无权限） | 403 | ❌ |
+| `not_found` / `bad_request` / `unauthorized` / `method_not_allowed` / `internal_error` | 404/400/401/405/500 | ❌ |
+
+retryable 语义按 code 判定（`RETRYABLE_CODES`），wire 信封不变；SDK 侧暴露为
+`TBApiError.retryable`。
+
+## 发布形态：一个包，多个入口
+
+当前 SDK 作为同一个 npm 包发布/接入，不拆成 `tb-host`、`tb-admin`、
+`tb-tunnel-agent` 三个包。npm 包名为 `@evilstar9527/tool-bridge`，不同角色通过 subpath exports 选择入口：
+
+| 入口 | 用途 |
+| --- | --- |
+| `@evilstar9527/tool-bridge/host` | Host SDK：宿主嵌入、builtin 注入、mounts.sync、树调用 |
+| `@evilstar9527/tool-bridge/admin` | Admin SDK：provider、host、endpoint、audit 等管理面 |
+| `@evilstar9527/tool-bridge/tunnel-agent` | Tunnel Agent Kit skeleton |
+| `@evilstar9527/tool-bridge/transport` | `https` / `serviceBinding` transport |
+| `@evilstar9527/tool-bridge/worker` | Worker bridge embedding surface |
+
+这样保持一个版本号和一个安装包，同时避免 API 混在同一个顶层 namespace 里。
+
+## Host SDK（M1）
+
+```ts
+import { createToolBridgeHost, https, serviceBinding } from '@evilstar9527/tool-bridge/host';
+
+const tb = createToolBridgeHost({
+  transport: serviceBinding(env.TOOLBRIDGE), // 或 https('https://bridge.example.com')
+  credential: env.TB_HOST_KEY,               // 浅档 S2S key（principal=host）
+  hostId: 'watt',
+});
+```
+
+| SDK 调用 | 等价请求 |
+| --- | --- |
+| `tb.tree.help('watt/websearch')` | `curl -H "Authorization: Bearer $HOST" -H "Accept: application/json" $TB/htbp/watt/websearch/~help` |
+| `tb.tree.help(path, {accept:'text'})` | 同上，`Accept: text/plain` |
+| `tb.tree.call('watt/websearch/search', {arguments:{q:'x'}}, {as:'user-42'})` | `curl -X POST -H "Authorization: Bearer $HOST" -H "X-TB-On-Behalf-Of: user-42" -H "Content-Type: application/json" -d '{"arguments":{"q":"x"}}' $TB/htbp/watt/websearch/search` |
+| `tb.mounts.sync(mounts)` | `curl -X POST -H "Authorization: Bearer $HOST" -H "Content-Type: application/json" -d '{"mounts":[{"path":"watt/websearch","binding":{"type":"builtin","tools":[{"name":"search","handler":"websearch"}]}}]}' "$TB/api/hosts/watt/mounts:sync"` |
+| `tb.builtins.register(name, fn)` | 无运行时 API——builtin 注入是**部署期代码行为**：`export default createBridge({ builtinHandlers: tb.builtins.registry() })` 随宿主 Worker 部署 |
+| `tb.adapters.wattError()` | 纯本地映射：401→`unauthenticated`、403→`permission_denied`、404→`not_found`、409→`confirmation_required`、502/503→`unavailable(retryable)` |
+| `tb.adapters.effectMap({external:'destructive'})` | 纯本地映射：平台 `effect` 四值 → 宿主方言（未申报默认 `external`，保守映射） |
+
+`as` / `traceId` / `reason` 分别对应 `X-TB-On-Behalf-Of` / `X-TB-Trace-Id` /
+`X-TB-Reason` 头：**审计标注，不是凭据**，不参与授权。
+
+### 宿主注册（admin）
+
+| 操作 | 请求 |
+| --- | --- |
+| 注册宿主 | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"id":"watt","confirmDelegated":true}' $TB/api/hosts` （同时创建 first-party provider `watt` 与空租户树 `tenant:watt`） |
+| 签发 S2S key | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"label":"watt-gateway"}' $TB/api/hosts/watt/keys` （raw key 只返回一次） |
+| 查看宿主 | `curl -H "Authorization: Bearer $ADMIN" $TB/api/hosts/watt` |
+
+## Admin SDK（M1/M2/M3/M4 管理面）
+
+```ts
+import { createToolBridgeAdmin } from '@evilstar9527/tool-bridge/admin';
+import { https } from '@evilstar9527/tool-bridge/transport';
+
+const admin = createToolBridgeAdmin({ transport: https(baseUrl), credential: adminKey });
+```
+
+| SDK 调用 | 等价请求 |
+| --- | --- |
+| `admin.providers.list()` | `curl -H "Authorization: Bearer $ADMIN" $TB/api/providers` |
+| `admin.providers.create({id:'acme'})` | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"id":"acme"}' $TB/api/providers` |
+| `admin.providers.get/update/delete('acme')` | `GET/PUT/DELETE $TB/api/providers/acme` |
+| `admin.providers.createKey('acme')` | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{}' $TB/api/providers/acme/keys` → `tbp_` key，只返回一次 |
+| `admin.publications.create('acme', pub)` | `curl -X POST -H "Authorization: Bearer $TBP" -d '{"pubId":"search","binding":{...}}' $TB/api/providers/acme/pubs` （tbp_ key 只能写自己名下） |
+| `admin.publications.publish('acme','search')` | `curl -X POST -d '{}' $TB/api/providers/acme/pubs/search/publish` |
+| `admin.placements.list('a')` | `curl -H "Authorization: Bearer $ADMIN" "$TB/api/placements?tenant=a"` |
+| `admin.placements.dryRun(p)` | `curl -X POST -d '{...,"dryRun":true}' $TB/api/placements` → 受影响 grant/path 预检报告，不落库 |
+| `admin.placements.put(p)` | `curl -X POST -d '{"tenantId":"a","path":"tools/search","pubRef":{"providerId":"acme","pubId":"search"}}' $TB/api/placements` |
+| `admin.placements.delete(id,'a',{dryRun})` | `curl -X DELETE "$TB/api/placements/{id}?tenant=a[&dryRun=true]"` |
+| `admin.hosts.create({id:'watt'})` | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"id":"watt"}' $TB/api/hosts` |
+| `admin.hosts.get/createKey('watt')` | `GET /api/hosts/watt` / `POST /api/hosts/watt/keys` |
+| `admin.endpoints.list/create/get/update/revoke()` | `GET/POST /api/endpoints`、`GET/PUT/DELETE /api/endpoints/{id}` |
+| `admin.commandPolicies.list/create/get/update/delete()` | `GET/POST /api/command-policies`、`GET/PUT/DELETE /api/command-policies/{id}` |
+| `admin.audit.events({tenant:'a',limit:50})` | `curl -H "Authorization: Bearer $ADMIN" "$TB/api/audit/events?tenant=a&limit=50"` |
+| `admin.servers.list/create/delete()` | `GET/POST /api/servers`、`DELETE /api/servers/{id}`（legacy MCP server 兼容层，写入 provider/publication/placement） |
+| `admin.servers.tools/help/skill/call(id, tool)` | `GET /api/servers/{id}/tools`、`GET /api/servers/{id}/~help`、`GET /api/servers/{id}/~skill`、`POST /api/servers/{id}/tools/{tool}` |
+| `admin.bridge.tools/call({endpoint}, tool)` | `POST /api/bridge/tools`、`POST /api/bridge/call`（ad-hoc MCP server） |
+| `admin.tree.get/crawl/help/call()` | `GET /api/tree`、`POST /api/crawl`、`GET /htbp/<path>/~help`、`POST /htbp/<path>` |
+
+## Tunnel / Device（M2）
+
+M2 使用占位接口边界：`/tunnel/*` 只处理已注册 endpoint 的最小 session 形状；
+不实现凭据加密、token 轮换、deep verifier、OAuth 或 S2S key 生命周期。
+
+| 操作 | 请求 |
+| --- | --- |
+| 注册 endpoint | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"id":"sbx_1","tenantId":"a","kind":"sandbox","capabilities":["exec.run","fs.read","logs.tail"]}' $TB/api/endpoints` |
+| 注册命令策略 | `curl -X POST -H "Authorization: Bearer $ADMIN" -d '{"id":"safe","defaultMode":"deny","allowCommands":["npm","pnpm"],"maxTimeoutMs":30000}' $TB/api/command-policies` |
+| endpoint 建连 | `curl -X POST -d '{"endpointId":"sbx_1"}' $TB/tunnel/connect` → `{sessionId}` |
+| 能力上报 | `curl -X POST -d '{"endpointId":"sbx_1","sessionId":"...","capabilities":["exec.run"]}' $TB/tunnel/capabilities`（只能收窄预注册能力） |
+| device help | `curl -H "Authorization: Bearer $TBK" $TB/htbp/~device/sbx_1/~help` |
+| argv 执行 | `curl -X POST -H "Authorization: Bearer $TBK" -d '{"argv":["npm","test"],"timeoutMs":30000}' $TB/htbp/~device/sbx_1/exec.run` |
+| 文件读取 | `curl -X POST -H "Authorization: Bearer $TBK" -d '{"path":"/workspace/README.md"}' $TB/htbp/~device/sbx_1/fs.read` |
+
+`exec.run` 只接受结构化 `argv`，`shell.run` 默认不暴露；全局策略会在 broker
+dispatch 前拒绝危险命令模式。离线 endpoint 返回 `EndpointUnavailable → 503`。
+
+Tunnel Agent Kit skeleton：
+
+```ts
+import { createTunnelAgent } from '@evilstar9527/tool-bridge/tunnel-agent';
+
+const agent = createTunnelAgent({
+  transport,
+  endpointId: 'sbx_1',
+  dispatch: async (request) => runLocalCapability(request),
+});
+
+const { sessionId } = await agent.connect();
+await agent.heartbeat();
+await agent.reportCapabilities(['exec.run']);
+```
+
+## 审计（M4）
+
+| 操作 | 请求 |
+| --- | --- |
+| 最近事件 | `curl -H "Authorization: Bearer $ADMIN" "$TB/api/audit/events?limit=50"`（租户 key 只能看本租户事件） |
+
+每次 `describe`/`call`（含 401/403/404 拒绝路径）产生一条结构化事件：
+`actor / tenant / path / tool / provider / effect / scope / decision / result /
+status / errorCode / traceId / latencyMs`，并预留 SPEC-005 计量字段（`usage`）。
+脱敏红线：绝不落 key、凭据、token、原始入参/出参（只记录字节数与顶层键名）。
+响应携带 `X-TB-Trace-Id`（可用同名请求头传入既有 traceId）。

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@evilstar9527/tool-bridge",
+  "version": "0.1.0",
+  "description": "Tool Bridge SDK and Cloudflare Worker bridge for HTBP/MCP tool routing.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/sdk/index.js",
+  "types": "./dist/types/sdk/index.d.ts",
+  "files": [
+    "dist/sdk",
+    "dist/types",
+    "README.md",
+    "docs/sdk.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
+    },
+    "./admin": {
+      "types": "./dist/types/sdk/admin/index.d.ts",
+      "import": "./dist/sdk/admin.js"
+    },
+    "./host": {
+      "types": "./dist/types/sdk/host/index.d.ts",
+      "import": "./dist/sdk/host.js"
+    },
+    "./tunnel-agent": {
+      "types": "./dist/types/sdk/tunnel-agent/index.d.ts",
+      "import": "./dist/sdk/tunnel-agent.js"
+    },
+    "./transport": {
+      "types": "./dist/types/sdk/transport.d.ts",
+      "import": "./dist/sdk/transport.js"
+    },
+    "./worker": {
+      "types": "./dist/types/worker/index.d.ts",
+      "import": "./dist/sdk/worker.js"
+    },
+    "./tb": {
+      "types": "./dist/types/worker/tb/types.d.ts",
+      "import": "./dist/sdk/tb.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "npm run build && wrangler dev --ip 127.0.0.1 --port 8787",
+    "dev:ui": "vite --host 127.0.0.1",
+    "build": "vite build",
+    "build:sdk": "rm -rf dist/sdk dist/types && vite build --config vite.sdk.config.ts && tsc -p tsconfig.sdk.json",
+    "typecheck": "tsc --noEmit",
+    "worker:dev": "wrangler dev --ip 127.0.0.1 --port 8787",
+    "deploy": "npm run build && wrangler deploy",
+    "check": "npm run typecheck && npm run build && npm run build:sdk",
+    "prepack": "npm run build:sdk",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.90.12",
+    "@tanstack/react-router": "^1.140.0",
+    "jose": "^6.2.0",
+    "lucide-react": "^0.562.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260625.1",
+    "@types/node": "^25.0.2",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^3.2.6",
+    "wrangler": "^4.56.0"
+  }
+}