@skillfm/local 2.2.0 → 2.5.0

package/dist/skill-tunnel/local-bridge.js

@@ -0,0 +1,224 @@
+// M2 SkillTunnelClient — local bridge
+//
+// 职责: 把 brain → agent 的 JSON-RPC request 转成本地 skill daemon 的 HTTP 调用。
+// 跑在 127.0.0.1 loopback，cookie/profile 全部留在本节点 → 守 BYOK 红线。
+//
+// 映射规则 (对齐 BRAIN-SKILL-CONTRACT §3 HTTP 接口):
+//   skill.run               → POST /v1/skill/run         body = params.request
+//   skill.contribute_ctx    → POST /v1/skill/contribute-ctx
+//   skill.declare_must_relay→ POST /v1/skill/declare-must-relay
+//   skill.manifest          → GET  /v1/skill/manifest
+//   skill.tool.invoke       → POST /v1/skill/tool/<tool_name>
+//   skill.continuation.abort→ POST /v1/skill/continuation/abort
+//   skill.health            → GET  /health
+//
+// 认证: 给本地 skill daemon 发请求时带 X-Skill-Auth (HMAC) 头,
+// 按现有 §3 auth_mode: hmac_shared_secret 规约。
+//
+// 失败路径: fetch 抛 ECONNREFUSED 或 timeout → 返回 TUNNEL_DEGRADED JSON-RPC error,
+// 绝不 hang,绝不吞。
+import { createHmac } from 'node:crypto';
+import { TUNNEL_ERROR_CODES } from '@skillfm/contracts/skill-tunnel';
+export class LocalBridge {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 把 server→agent 的 JSON-RPC request 转发到本地 skill daemon。
+     * 返回 JsonRpcSuccessResponse 或 JsonRpcErrorResponse(本地不可达等)。
+     * 异常不抛出,一律封装成 error response —— 上层 client 按 id 回传。
+     */
+    async dispatch(id, method, params) {
+        // 1. 白名单校验
+        if (!this.isKnownServerMethod(method)) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `unknown method: ${method}`);
+        }
+        // 2. 按 method 路由
+        try {
+            const m = method;
+            switch (m) {
+                case 'skill.run':
+                    return await this.handleSkillRun(id, params);
+                case 'skill.contribute_ctx':
+                    return await this.handleSkillPost(id, params, '/v1/skill/contribute-ctx');
+                case 'skill.declare_must_relay':
+                    return await this.handleSkillPost(id, params, '/v1/skill/declare-must-relay');
+                case 'skill.manifest':
+                    return await this.handleSkillGet(id, params, '/v1/skill/manifest');
+                case 'skill.tool.invoke':
+                    return await this.handleToolInvoke(id, params);
+                case 'skill.continuation.abort':
+                    return await this.handleSkillPost(id, params, '/v1/skill/continuation/abort');
+                case 'skill.health':
+                    return await this.handleSkillGet(id, params, '/health');
+                default: {
+                    // 穷尽检查 —— TS 会在新加 method 时报错
+                    const _exhaustive = m;
+                    void _exhaustive;
+                    return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `unroutable method: ${method}`);
+                }
+            }
+        }
+        catch (err) {
+            const e = err;
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.INTERNAL_ERROR, `local-bridge dispatch error: ${e.message}`);
+        }
+    }
+    isKnownServerMethod(method) {
+        return [
+            'skill.run',
+            'skill.contribute_ctx',
+            'skill.declare_must_relay',
+            'skill.manifest',
+            'skill.tool.invoke',
+            'skill.continuation.abort',
+            'skill.health',
+        ].includes(method);
+    }
+    async handleSkillRun(id, params) {
+        if (!params?.skill_slug) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.INVALID_PARAMS, 'missing skill_slug');
+        }
+        const endpoint = this.deps.resolveEndpoint(params.skill_slug);
+        if (!endpoint) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `skill not registered locally: ${params.skill_slug}`);
+        }
+        return this.httpJson(id, 'POST', `${endpoint}/v1/skill/run`, params.request);
+    }
+    async handleToolInvoke(id, params) {
+        if (!params?.skill_slug || !params?.tool_name) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.INVALID_PARAMS, 'missing skill_slug or tool_name');
+        }
+        const endpoint = this.deps.resolveEndpoint(params.skill_slug);
+        if (!endpoint) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `skill not registered locally: ${params.skill_slug}`);
+        }
+        const path = `/v1/skill/tool/${encodeURIComponent(params.tool_name)}`;
+        return this.httpJson(id, 'POST', `${endpoint}${path}`, {
+            args: params.args,
+            context: params.context,
+            request_id: params.request_id,
+        });
+    }
+    async handleSkillPost(id, params, path) {
+        if (!params?.skill_slug) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.INVALID_PARAMS, 'missing skill_slug');
+        }
+        const endpoint = this.deps.resolveEndpoint(params.skill_slug);
+        if (!endpoint) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `skill not registered locally: ${params.skill_slug}`);
+        }
+        return this.httpJson(id, 'POST', `${endpoint}${path}`, params);
+    }
+    async handleSkillGet(id, params, path) {
+        if (!params?.skill_slug) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.INVALID_PARAMS, 'missing skill_slug');
+        }
+        const endpoint = this.deps.resolveEndpoint(params.skill_slug);
+        if (!endpoint) {
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.METHOD_NOT_FOUND, `skill not registered locally: ${params.skill_slug}`);
+        }
+        return this.httpJson(id, 'GET', `${endpoint}${path}`, null);
+    }
+    async httpJson(id, httpMethod, url, body) {
+        const fetchImpl = this.deps.fetch ?? globalThis.fetch;
+        const timeoutMs = this.deps.fetchTimeoutMs ?? 30_000;
+        const headers = {};
+        let payload;
+        if (httpMethod === 'POST') {
+            headers['content-type'] = 'application/json';
+            payload = JSON.stringify(body ?? {});
+            if (this.deps.skillAuthSecret) {
+                // HMAC 对 raw body 签名 —— 与 platform §3 auth 规约保持一致
+                headers['x-skill-auth'] = createHmac('sha256', this.deps.skillAuthSecret)
+                    .update(payload)
+                    .digest('hex');
+            }
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(url, {
+                method: httpMethod,
+                headers,
+                body: payload,
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                // 非 JSON —— 把 raw 包进 data,不视为致命错
+                data = { raw: text };
+            }
+            if (!res.ok) {
+                return this.errorResponse(id, TUNNEL_ERROR_CODES.SKILL_APP_ERROR, `local skill returned HTTP ${res.status}`, { http_status: res.status, data });
+            }
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: data,
+            };
+        }
+        catch (err) {
+            const e = err;
+            const isAbort = e.name === 'AbortError';
+            // undici fetch wraps underlying socket error into `cause`; walk the chain
+            // to find ECONNREFUSED / ENOTFOUND / ECONNRESET / EHOSTUNREACH.
+            const isUnreachable = detectUnreachable(e);
+            const msg = isAbort
+                ? `local skill timeout after ${timeoutMs}ms (${url})`
+                : isUnreachable
+                    ? `local skill unreachable: ${url} (${describeUnreachable(e)})`
+                    : `local skill unreachable: ${url} (${e.message})`;
+            // 所有 fetch 网络层失败都映射为 TUNNEL_DEGRADED —— 契约 §4b 要求不 hang
+            return this.errorResponse(id, TUNNEL_ERROR_CODES.TUNNEL_DEGRADED, msg);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    errorResponse(id, code, message, data) {
+        return {
+            jsonrpc: '2.0',
+            id,
+            error: { code, message, data },
+        };
+    }
+}
+const UNREACHABLE_CODES = new Set([
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'ECONNRESET',
+    'EHOSTUNREACH',
+    'EAI_AGAIN',
+    'UND_ERR_SOCKET',
+]);
+function detectUnreachable(err) {
+    let cur = err;
+    let depth = 0;
+    while (cur && depth < 6) {
+        const c = cur;
+        if (c.code && UNREACHABLE_CODES.has(c.code))
+            return true;
+        cur = c.cause;
+        depth += 1;
+    }
+    return false;
+}
+function describeUnreachable(err) {
+    let cur = err;
+    let depth = 0;
+    while (cur && depth < 6) {
+        const c = cur;
+        if (c.code && UNREACHABLE_CODES.has(c.code))
+            return c.code;
+        cur = c.cause;
+        depth += 1;
+    }
+    return 'ECONNREFUSED';
+}
+//# sourceMappingURL=local-bridge.js.map

package/dist/skill-tunnel/local-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-bridge.js","sourceRoot":"","sources":["../../src/skill-tunnel/local-bridge.ts"],"names":[],"mappings":"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"}

package/dist/skill-tunnel/reconnect.d.ts

@@ -0,0 +1,21 @@
+/** 不应重连的 close code 集合 */
+export declare const FATAL_CLOSE_CODES: Set<number>;
+export declare function isFatalCloseCode(code: number | null | undefined): boolean;
+/**
+ * 给定第 N 次重试（0-indexed），返回延迟 ms。
+ * 可注入 jitterFn 方便测试（默认 Math.random）。
+ */
+export declare function computeReconnectDelayMs(attempt: number, jitterFn?: () => number): number;
+/**
+ * 简易调度器 —— 包装 setTimeout,便于测试时可注入 fake clock。
+ */
+export declare class ReconnectScheduler {
+    private timer;
+    private attempt;
+    private stopped;
+    schedule(fn: () => void): void;
+    reset(): void;
+    stop(): void;
+    get attempts(): number;
+}
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/skill-tunnel/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../../src/skill-tunnel/reconnect.ts"],"names":[],"mappings":"AAaA,0BAA0B;AAC1B,eAAO,MAAM,iBAAiB,aAK5B,CAAC;AAEH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,MAAoB,GACnC,MAAM,CASR;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAS;IAExB,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAc9B,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAQZ,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF"}

package/dist/skill-tunnel/reconnect.js

@@ -0,0 +1,72 @@
+// M2 SkillTunnelClient — 指数退避重连调度
+//
+// 策略 (DELTA §5 + TUNNEL_CONSTANTS):
+//   delay = INITIAL × 2^attempt, 上限 MAX
+//   jitter ±30% (避免多 agent 同时重连导致 brain 侧抖动)
+//   致命 close code (4001/4002/4003/4101) 不重连 —— 要么签名错,要么 token 吊销,要么版本不兼容,
+//   这些情况重连只会继续失败,必须人工介入 → 输出到 stderr 供 agent 看到。
+import { TUNNEL_CLOSE_CODES, TUNNEL_CONSTANTS, } from '@skillfm/contracts/skill-tunnel';
+/** 不应重连的 close code 集合 */
+export const FATAL_CLOSE_CODES = new Set([
+    TUNNEL_CLOSE_CODES.AUTH_BAD_SIGNATURE,
+    TUNNEL_CLOSE_CODES.AUTH_NONCE_REUSED,
+    TUNNEL_CLOSE_CODES.AGENT_TOKEN_REVOKED,
+    TUNNEL_CLOSE_CODES.VERSION_UNSUPPORTED,
+]);
+export function isFatalCloseCode(code) {
+    if (typeof code !== 'number')
+        return false;
+    return FATAL_CLOSE_CODES.has(code);
+}
+/**
+ * 给定第 N 次重试（0-indexed），返回延迟 ms。
+ * 可注入 jitterFn 方便测试（默认 Math.random）。
+ */
+export function computeReconnectDelayMs(attempt, jitterFn = Math.random) {
+    const base = Math.min(TUNNEL_CONSTANTS.RECONNECT_INITIAL_DELAY_MS * 2 ** attempt, TUNNEL_CONSTANTS.RECONNECT_MAX_DELAY_MS);
+    // jitter ±30%
+    const jitterRange = base * 0.3;
+    const jitter = (jitterFn() * 2 - 1) * jitterRange;
+    return Math.max(0, Math.round(base + jitter));
+}
+/**
+ * 简易调度器 —— 包装 setTimeout,便于测试时可注入 fake clock。
+ */
+export class ReconnectScheduler {
+    timer = null;
+    attempt = 0;
+    stopped = false;
+    schedule(fn) {
+        if (this.stopped)
+            return;
+        const delay = computeReconnectDelayMs(this.attempt);
+        this.attempt += 1;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            if (!this.stopped)
+                fn();
+        }, delay);
+        // 不让 reconnect timer 阻塞 node exit
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+    reset() {
+        this.attempt = 0;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    get attempts() {
+        return this.attempt;
+    }
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/skill-tunnel/reconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.js","sourceRoot":"","sources":["../../src/skill-tunnel/reconnect.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,oCAAoC;AACpC,wCAAwC;AACxC,6CAA6C;AAC7C,0EAA0E;AAC1E,iDAAiD;AAEjD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AAEzC,0BAA0B;AAC1B,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IAC/C,kBAAkB,CAAC,kBAAkB;IACrC,kBAAkB,CAAC,iBAAiB;IACpC,kBAAkB,CAAC,mBAAmB;IACtC,kBAAkB,CAAC,mBAAmB;CACvC,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAA+B;IAC9D,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,WAAyB,IAAI,CAAC,MAAM;IAEpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CACnB,gBAAgB,CAAC,0BAA0B,GAAG,CAAC,IAAI,OAAO,EAC1D,gBAAgB,CAAC,sBAAsB,CACxC,CAAC;IACF,cAAc;IACd,MAAM,WAAW,GAAG,IAAI,GAAG,GAAG,CAAC;IAC/B,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC;IAClD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACrB,KAAK,GAA0B,IAAI,CAAC;IACpC,OAAO,GAAG,CAAC,CAAC;IACZ,OAAO,GAAG,KAAK,CAAC;IAExB,QAAQ,CAAC,EAAc;QACrB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,EAAE,EAAE,CAAC;QAC1B,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,kCAAkC;QAClC,IAAI,OAAQ,IAAI,CAAC,KAA2C,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACjF,IAAI,CAAC,KAA0C,CAAC,KAAK,EAAE,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillfm/local",
-  "version": "2.2.0",
+  "version": "2.5.0",
   "description": "SkillFM local sidecar — a tiny localhost HTTP proxy that lets any AI agent activate and run SkillFM skills in the current conversation without restarting its MCP runtime. Writes ~/.skillfm/local.json for service discovery.",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,17 +40,20 @@
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js start",
     "prepublishOnly": "npm run build",
-    "test": "tsx --test src/harness/detector.test.ts src/harness/priming.test.ts src/harness/writers.test.ts src/guard/state.test.ts src/soul.test.ts src/soul-security.test.ts src/harness/kernels/registry.test.ts src/harness/kernels/deny-pipeline.test.ts src/mcp-output/builder.test.ts src/mcp-output/deny-review.test.ts src/mcp-output/integration.test.ts src/skill-md/template.test.ts src/skill-md/writer.test.ts src/mcp-stdio/smoke.test.ts src/mcp-stdio/render-flow.contract.test.ts src/mcp-stdio/render-aha.test.ts src/mcp-stdio/sse-progress-client.test.ts src/mcp-stdio/parse-tolerant-json.test.ts src/self-upgrade.test.ts",
+    "test": "tsx --test src/harness/detector.test.ts src/harness/priming.test.ts src/harness/writers.test.ts src/guard/state.test.ts src/soul.test.ts src/soul-security.test.ts src/harness/kernels/registry.test.ts src/harness/kernels/deny-pipeline.test.ts src/mcp-output/builder.test.ts src/mcp-output/deny-review.test.ts src/mcp-output/integration.test.ts src/skill-md/template.test.ts src/skill-md/writer.test.ts src/mcp-stdio/smoke.test.ts src/mcp-stdio/render-flow.contract.test.ts src/mcp-stdio/render-aha.test.ts src/mcp-stdio/sse-progress-client.test.ts src/mcp-stdio/parse-tolerant-json.test.ts src/self-upgrade.test.ts src/skill-tunnel/local-bridge.test.ts src/skill-tunnel/client.test.ts src/skill-runner/discovery.test.ts src/skill-installer/index.test.ts",
     "test:acceptance": "npm run build && bash scripts/acceptance-matrix.sh",
     "postpublish": "curl -sS -m 10 -X PUT 'https://registry.npmmirror.com/-/package/@skillfm/local/syncs?sync_upstream=true' > /dev/null && echo '✓ npmmirror sync triggered' || echo '⚠ npmmirror sync failed (非阻塞，可手动触发)'"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "tar": "^7.5.0",
+    "ws": "^8.20.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@skillfm/contracts": "*",
     "@types/node": "^22.19.17",
+    "@types/ws": "^8.5.10",
     "tsx": "^4.0.0",
     "typescript": "^5.4.0"
   },