@skillfm/local 2.3.0 → 2.5.0

package/dist/skill-tunnel/cli.js

@@ -0,0 +1,205 @@
+// M2 SkillTunnelClient — CLI subcommand
+//
+// `skillfm-local tunnel start|stop|status`
+// 简易实现: start 在当前进程起 tunnel（不 daemon 化），stop/status 通过 PID 文件。
+// daemon 化（launchd / nohup）留给上层部署脚本,这里只提供基础设施。
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { readRegistry } from '../skill-runner/registry.js';
+import { SkillTunnelClient } from './client.js';
+const PID_FILE = join(homedir(), '.skillfm', 'tunnel.pid');
+const DEFAULT_BRAIN_URL = process.env.SKILLFM_BRAIN_TUNNEL_URL ?? 'wss://api.skillfm.ai/v1/skill-tunnel';
+function ensureDir() {
+    const dir = dirname(PID_FILE);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+function parseFlags(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const t = args[i];
+        if (!t.startsWith('--'))
+            continue;
+        const eq = t.indexOf('=');
+        if (eq > 0) {
+            flags[t.slice(2, eq)] = t.slice(eq + 1);
+        }
+        else {
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags[t.slice(2)] = next;
+                i += 1;
+            }
+            else {
+                flags[t.slice(2)] = true;
+            }
+        }
+    }
+    return flags;
+}
+function readConfig() {
+    const path = join(homedir(), '.skillfm', 'config.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function readPackageVersion() {
+    // 只读顶层 package.json 里版本；build 后 dist/ 同级已经没有 package.json,fallback 环境变量
+    return process.env.SKILLFM_LOCAL_VERSION ?? '0.0.0';
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function cmdTunnelStart() {
+    const flags = parseFlags(process.argv.slice(3));
+    const brainUrl = typeof flags['brain-url'] === 'string' ? flags['brain-url'] : DEFAULT_BRAIN_URL;
+    // 检查是否已在跑
+    if (existsSync(PID_FILE)) {
+        const pid = Number.parseInt(readFileSync(PID_FILE, 'utf-8'), 10);
+        if (Number.isFinite(pid) && isProcessAlive(pid)) {
+            console.log(JSON.stringify({
+                ok: false,
+                error: 'ALREADY_RUNNING',
+                message: `tunnel 已在跑 (pid=${pid})`,
+            }));
+            process.exit(1);
+            return;
+        }
+        // PID 文件残留,清理
+        try {
+            rmSync(PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+    }
+    const cfg = readConfig();
+    const agentToken = process.env.SKILLFM_AGENT_TOKEN ?? cfg.agent_token ?? '';
+    const authSecret = process.env.SKILLFM_SKILL_AUTH_SECRET ?? cfg.auth_secret ?? '';
+    if (!agentToken || !authSecret) {
+        console.log(JSON.stringify({
+            ok: false,
+            error: 'MISSING_CREDENTIALS',
+            message: 'agent_token / auth_secret 缺失. 请设 env SKILLFM_AGENT_TOKEN + SKILLFM_SKILL_AUTH_SECRET,或写入 ~/.skillfm/config.json',
+        }));
+        process.exit(1);
+        return;
+    }
+    const registry = readRegistry();
+    const localSkills = Object.values(registry.skills);
+    ensureDir();
+    writeFileSync(PID_FILE, String(process.pid), { mode: 0o600 });
+    const client = new SkillTunnelClient({
+        brainUrl,
+        agentToken,
+        authSecret,
+        localSkills,
+        skillfmLocalVersion: readPackageVersion(),
+        onStatusChange: (s) => {
+            console.error(`[tunnel] status=${s}`);
+        },
+    });
+    const cleanup = async () => {
+        try {
+            await client.stop();
+        }
+        finally {
+            try {
+                rmSync(PID_FILE);
+            }
+            catch {
+                // ignore
+            }
+        }
+    };
+    process.on('SIGINT', () => {
+        void cleanup().then(() => process.exit(0));
+    });
+    process.on('SIGTERM', () => {
+        void cleanup().then(() => process.exit(0));
+    });
+    console.log(JSON.stringify({
+        ok: true,
+        message: `tunnel 启动 pid=${process.pid} brain=${brainUrl} skills=${localSkills.length}`,
+        pid: process.pid,
+    }));
+    await client.start();
+    // 保持进程存活
+    await new Promise(() => { });
+}
+export function cmdTunnelStop() {
+    if (!existsSync(PID_FILE)) {
+        console.log(JSON.stringify({ ok: false, error: 'NOT_RUNNING' }));
+        process.exit(1);
+        return;
+    }
+    const pid = Number.parseInt(readFileSync(PID_FILE, 'utf-8'), 10);
+    if (!Number.isFinite(pid)) {
+        try {
+            rmSync(PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+        console.log(JSON.stringify({ ok: false, error: 'BAD_PID_FILE' }));
+        process.exit(1);
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+        console.log(JSON.stringify({ ok: true, pid, message: 'SIGTERM sent' }));
+    }
+    catch (err) {
+        console.log(JSON.stringify({
+            ok: false,
+            error: 'KILL_FAILED',
+            message: err.message,
+        }));
+        process.exit(1);
+    }
+}
+export function cmdTunnelStatus() {
+    if (!existsSync(PID_FILE)) {
+        console.log(JSON.stringify({ ok: true, running: false }));
+        return;
+    }
+    const pid = Number.parseInt(readFileSync(PID_FILE, 'utf-8'), 10);
+    const alive = Number.isFinite(pid) && isProcessAlive(pid);
+    console.log(JSON.stringify({ ok: true, running: alive, pid }));
+}
+export async function cmdTunnel() {
+    const sub = process.argv[3];
+    switch (sub) {
+        case 'start':
+            // shift argv so parseFlags 看到 `start` 之后的 flags
+            process.argv.splice(3, 1);
+            await cmdTunnelStart();
+            break;
+        case 'stop':
+            cmdTunnelStop();
+            break;
+        case 'status':
+            cmdTunnelStatus();
+            break;
+        default:
+            console.error(JSON.stringify({
+                ok: false,
+                error: 'UNKNOWN_SUBCOMMAND',
+                message: 'Usage: skillfm-local tunnel <start|stop|status> [--brain-url=<url>]',
+            }));
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=cli.js.map

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

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

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

@@ -0,0 +1,56 @@
+import { WebSocket } from 'ws';
+import { TUNNEL_ERROR_CODES } from '@skillfm/contracts/skill-tunnel';
+import type { HeartbeatTunnelResult, JsonRpcSuccessResponse, JsonRpcErrorResponse, SkillUpdateTunnelParams } from '@skillfm/contracts/skill-tunnel';
+import type { LocalSkillRegistryEntry } from '../skill-runner/types.js';
+export type TunnelStatus = 'connecting' | 'connected' | 'disconnected';
+export interface SkillTunnelClientOptions {
+    /** e.g. wss://api.skillfm.ai/v1/skill-tunnel */
+    brainUrl: string;
+    agentToken: string;
+    /** 来自 M1 readRegistry() 的 entries 列表 */
+    localSkills: LocalSkillRegistryEntry[];
+    skillfmLocalVersion: string;
+    /** SKILLFM_SKILL_AUTH_SECRET — HMAC 密钥（handshake + JSON-RPC meta + 本地 skill 调用都用这把）*/
+    authSecret: string;
+    onStatusChange?: (status: TunnelStatus) => void;
+    /** 可选: 注入 fetch 给 LocalBridge（测试用）*/
+    fetch?: typeof fetch;
+    /** 可选: 注入 WebSocket 构造器（测试用）*/
+    webSocketCtor?: typeof WebSocket;
+}
+export declare class SkillTunnelClient {
+    private readonly opts;
+    private readonly bridge;
+    private readonly reconnect;
+    private readonly heartbeat;
+    private ws;
+    private status;
+    private lastConnectedAt;
+    private stopped;
+    private readonly pending;
+    constructor(opts: SkillTunnelClientOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status$(): {
+        connected: boolean;
+        lastConnectedAt: number | null;
+        reconnectAttempts: number;
+    };
+    /** 主动上报 skill lifecycle 事件 */
+    sendSkillUpdate(params: SkillUpdateTunnelParams): Promise<void>;
+    private connectOnce;
+    private onOpen;
+    private onError;
+    private onClose;
+    private onMessage;
+    private handleServerRequest;
+    private handleResponse;
+    private sendFrame;
+    private sendClientRequest;
+    private buildHeartbeatStatus;
+    private handleHeartbeatTimeout;
+    private setStatus;
+}
+export type { JsonRpcSuccessResponse, JsonRpcErrorResponse, HeartbeatTunnelResult };
+export { TUNNEL_ERROR_CODES };
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/skill-tunnel/client.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,SAAS,EAAgB,MAAM,IAAI,CAAC;AAC7C,OAAO,EAGL,kBAAkB,EACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAEV,qBAAqB,EAIrB,sBAAsB,EACtB,oBAAoB,EAEpB,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAMxE,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,CAAC;AAEvE,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,WAAW,EAAE,uBAAuB,EAAE,CAAC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAClC;AAQD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAE1C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;gBAE7C,IAAI,EAAE,wBAAwB;IAkBpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,OAAO,IAAI;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE;IAQ5F,8BAA8B;IACxB,eAAe,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;YAQvD,WAAW;IAyBzB,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,OAAO;IAsBf,OAAO,CAAC,SAAS;YAqBH,mBAAmB;IAKjC,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,SAAS;YASH,iBAAiB;IAsC/B,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,SAAS;CAKlB;AAGD,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/skill-tunnel/client.js

@@ -0,0 +1,260 @@
+// M2 SkillTunnelClient — WebSocket client + JSON-RPC dispatch
+//
+// 职责:
+//   - 连 brain (wss://api.skillfm.ai/v1/skill-tunnel) 带 TunnelHandshakeHeaders
+//   - 收 brain 发来的 skill.* JSON-RPC request → dispatch 到 LocalBridge → HTTP 回转 127.0.0.1
+//   - 主动发 tunnel.heartbeat / tunnel.skill_update（pending map 等 response）
+//   - 断线按 close code 决定是否重连；非致命走 ReconnectScheduler
+//
+// BYOK 纪律:
+//   - 全程 cookie / playwright profile 留本节点,client 只做"brain→本地 loopback"桥接
+//   - 凭证仅 agent_token / authSecret,存 ~/.skillfm/config.json（调用方 CLI 负责读）
+//
+// 反向契约:
+//   输入: LocalSkillRegistryEntry[] 来自 M1 readRegistry()
+//   输出: 对 brain 返回 JsonRpcSuccessResponse | JsonRpcErrorResponse
+//   上游缺数据: 若 localSkills 为空 → 仍 connect,brain 侧 handshake 校验时决定 accept/reject（我们不假设）
+//   下游假设我: handshake 头齐 9 个 + signature 正确
+import { randomUUID } from 'node:crypto';
+import { WebSocket } from 'ws';
+import { TUNNEL_CONSTANTS, TUNNEL_SUBPROTOCOL, TUNNEL_ERROR_CODES, } from '@skillfm/contracts/skill-tunnel';
+import { buildHandshakeHeaders, computeRpcMetaHmac } from './handshake.js';
+import { HeartbeatLoop } from './heartbeat.js';
+import { LocalBridge } from './local-bridge.js';
+import { ReconnectScheduler, isFatalCloseCode } from './reconnect.js';
+export class SkillTunnelClient {
+    opts;
+    bridge;
+    reconnect;
+    heartbeat;
+    ws = null;
+    status = 'disconnected';
+    lastConnectedAt = null;
+    stopped = false;
+    pending = new Map();
+    constructor(opts) {
+        this.opts = opts;
+        const endpointMap = new Map(opts.localSkills.map((s) => [s.slug, s.endpoint]));
+        this.bridge = new LocalBridge({
+            resolveEndpoint: (slug) => endpointMap.get(slug) ?? null,
+            skillAuthSecret: opts.authSecret,
+            fetch: opts.fetch,
+        });
+        this.reconnect = new ReconnectScheduler();
+        this.heartbeat = new HeartbeatLoop({
+            buildStatusSnapshot: () => this.buildHeartbeatStatus(),
+            sendHeartbeat: async (params) => {
+                await this.sendClientRequest('tunnel.heartbeat', params);
+            },
+            onTimeout: () => this.handleHeartbeatTimeout(),
+        });
+    }
+    async start() {
+        this.stopped = false;
+        await this.connectOnce();
+    }
+    async stop() {
+        this.stopped = true;
+        this.reconnect.stop();
+        this.heartbeat.stop();
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error('tunnel stopped'));
+        }
+        this.pending.clear();
+        if (this.ws && this.ws.readyState !== WebSocket.CLOSED) {
+            try {
+                this.ws.close(1000, 'graceful');
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.setStatus('disconnected');
+    }
+    status$() {
+        return {
+            connected: this.status === 'connected',
+            lastConnectedAt: this.lastConnectedAt,
+            reconnectAttempts: this.reconnect.attempts,
+        };
+    }
+    /** 主动上报 skill lifecycle 事件 */
+    async sendSkillUpdate(params) {
+        await this.sendClientRequest('tunnel.skill_update', params);
+    }
+    // ==========================================================================
+    // 内部: 连接 / 事件
+    // ==========================================================================
+    async connectOnce() {
+        if (this.stopped)
+            return;
+        this.setStatus('connecting');
+        const { headers } = buildHandshakeHeaders({
+            agentToken: this.opts.agentToken,
+            authSecret: this.opts.authSecret,
+            localSkills: this.opts.localSkills,
+            skillfmLocalVersion: this.opts.skillfmLocalVersion,
+        });
+        const Ctor = this.opts.webSocketCtor ?? WebSocket;
+        // ws 的 headers 类型是 OutgoingHttpHeaders (index signature)；TunnelHandshakeHeaders 是
+        // 强类型 9 字段对象，需要 cast 到宽类型才能传给 ws 构造器。
+        const ws = new Ctor(this.opts.brainUrl, [TUNNEL_SUBPROTOCOL], {
+            headers: headers,
+        });
+        this.ws = ws;
+        ws.on('open', () => this.onOpen());
+        ws.on('message', (raw) => this.onMessage(raw));
+        ws.on('error', (err) => this.onError(err));
+        ws.on('close', (code, reason) => this.onClose(code, reason));
+    }
+    onOpen() {
+        this.lastConnectedAt = Date.now();
+        this.reconnect.reset();
+        this.heartbeat.start();
+        this.setStatus('connected');
+    }
+    onError(err) {
+        // ws 的 'error' 事件在 close 前先触发,真正的重连判断放 close 里
+        console.error('[skill-tunnel] ws error:', err.message);
+    }
+    onClose(code, reason) {
+        this.heartbeat.stop();
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`ws closed (code=${code})`));
+        }
+        this.pending.clear();
+        this.setStatus('disconnected');
+        if (this.stopped)
+            return;
+        if (isFatalCloseCode(code)) {
+            console.error(`[skill-tunnel] fatal close code ${code}: ${reason.toString('utf-8')} — no reconnect`);
+            return;
+        }
+        this.reconnect.schedule(() => {
+            void this.connectOnce();
+        });
+    }
+    onMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw.toString());
+        }
+        catch {
+            console.error('[skill-tunnel] non-JSON frame dropped');
+            return;
+        }
+        // Response (brain 回我们主动发出的 heartbeat 等)
+        if ('result' in frame || 'error' in frame) {
+            this.handleResponse(frame);
+            return;
+        }
+        // Request (brain → agent, skill.*)
+        if ('method' in frame && 'id' in frame) {
+            void this.handleServerRequest(frame);
+        }
+    }
+    async handleServerRequest(req) {
+        const response = await this.bridge.dispatch(req.id, req.method, req.params);
+        this.sendFrame(response);
+    }
+    handleResponse(res) {
+        const p = this.pending.get(res.id);
+        if (!p) {
+            // heartbeat ack 可能没在 pending（fire-and-forget）,更新 ack 时间就好
+            if ('result' in res) {
+                this.heartbeat.onAck();
+            }
+            return;
+        }
+        this.pending.delete(res.id);
+        clearTimeout(p.timer);
+        if ('error' in res) {
+            p.reject(new Error(`rpc error ${res.error.code}: ${res.error.message}`));
+        }
+        else {
+            this.heartbeat.onAck();
+            p.resolve(res.result);
+        }
+    }
+    // ==========================================================================
+    // 内部: 发送
+    // ==========================================================================
+    sendFrame(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            this.ws.send(JSON.stringify(frame));
+        }
+        catch (err) {
+            console.error('[skill-tunnel] send failed:', err.message);
+        }
+    }
+    async sendClientRequest(method, params) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('tunnel not connected');
+        }
+        const id = randomUUID();
+        const req = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+            meta: {
+                hmac: computeRpcMetaHmac(id, method, params, this.opts.authSecret),
+            },
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`rpc timeout ${method}`));
+            }, TUNNEL_CONSTANTS.RPC_REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function') {
+                timer.unref();
+            }
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+                timer,
+            });
+            this.sendFrame(req);
+        });
+    }
+    // ==========================================================================
+    // Heartbeat 工具
+    // ==========================================================================
+    buildHeartbeatStatus() {
+        const out = {};
+        const now = Date.now();
+        for (const s of this.opts.localSkills) {
+            out[s.slug] = {
+                pid: s.server_pid,
+                rss_mb: 0, // M1 registry 暂不存内存; 后续可通过 process.memoryUsage 读
+                healthy: true,
+                last_check_at: s.last_health_at ?? now,
+            };
+        }
+        return out;
+    }
+    handleHeartbeatTimeout() {
+        console.error('[skill-tunnel] heartbeat timeout — reconnecting');
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            try {
+                this.ws.close(TUNNEL_CONSTANTS.HEARTBEAT_INTERVAL_MS, 'heartbeat timeout');
+            }
+            catch {
+                // ignore
+            }
+        }
+        // close 事件会触发 reconnect 调度
+    }
+    setStatus(s) {
+        if (this.status === s)
+            return;
+        this.status = s;
+        this.opts.onStatusChange?.(s);
+    }
+}
+export { TUNNEL_ERROR_CODES };
+//# sourceMappingURL=client.js.map

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

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

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

@@ -0,0 +1,35 @@
+import type { TunnelHandshakeHeaders } from '@skillfm/contracts/skill-tunnel';
+import type { LocalSkillRegistryEntry } from '../skill-runner/types.js';
+export interface BuildHandshakeInput {
+    agentToken: string;
+    /** SKILLFM_SKILL_AUTH_SECRET — HMAC 共享密钥 */
+    authSecret: string;
+    /** 本地已跑的 skill daemon 列表（来自 M1 readRegistry）*/
+    localSkills: LocalSkillRegistryEntry[];
+    /** @skillfm/local 运行时版本 */
+    skillfmLocalVersion: string;
+}
+export interface HandshakeArtifact {
+    headers: TunnelHandshakeHeaders;
+    /** 本次 nonce（保留供上层重放检测/调试；正式请求不传）*/
+    nonce: string;
+}
+/** 生成 16-byte nonce hex（契约 §5.1 16 byte hex = 32 字符）*/
+export declare function generateNonce(): string;
+export declare function computeAgentId(agentToken: string): string;
+export declare function computeTunnelSignature(agentToken: string, nonce: string, authSecret: string): string;
+/** 组装 `slug@version,slug@version` */
+export declare function formatLocalSkills(skills: LocalSkillRegistryEntry[]): string;
+/** 组装 `slug=http://127.0.0.1:port,slug=http://127.0.0.1:port` */
+export declare function formatLocalSkillEndpoints(skills: LocalSkillRegistryEntry[]): string;
+/**
+ * 构造一次握手所需的全部 9 个头。
+ * 每次 connect / reconnect 必须调用一次（nonce 随机）。
+ */
+export declare function buildHandshakeHeaders(input: BuildHandshakeInput): HandshakeArtifact;
+/**
+ * JSON-RPC meta.hmac 签名: HMAC-SHA256(id || method || JSON.stringify(params), secret)
+ * DELTA §5.4
+ */
+export declare function computeRpcMetaHmac(id: string, method: string, params: unknown, authSecret: string): string;
+//# sourceMappingURL=handshake.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/skill-tunnel/handshake.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,WAAW,EAAE,uBAAuB,EAAE,CAAC;IACvC,2BAA2B;IAC3B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,sBAAsB,CAAC;IAChC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,MAAM,CAIR;AAED,qCAAqC;AACrC,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,EAAE,GAChC,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,GACzB,iBAAiB,CAoBnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,CAGR"}

package/dist/skill-tunnel/handshake.js

@@ -0,0 +1,61 @@
+// M2 SkillTunnelClient — handshake 头构造 & 签名
+//
+// 对应契约: shared/contracts/envelope-v2/skill-tunnel.ts `TunnelHandshakeHeaders`
+// 9 个必填头:
+//   x-agent-token, x-agent-id, x-local-skills, x-local-skill-endpoints,
+//   x-tunnel-nonce, x-tunnel-signature, x-skillfm-local-version
+//
+// 签名算法 (DELTA §5.1):
+//   x-agent-id = SHA-256(agent_token) hex
+//   x-tunnel-signature = HMAC-SHA256(agent_token || nonce, SKILLFM_SKILL_AUTH_SECRET) hex
+//
+// 重放防护: 每次 connect (含 reconnect) 必须重新生成 nonce。
+import { createHash, createHmac, randomBytes } from 'node:crypto';
+/** 生成 16-byte nonce hex（契约 §5.1 16 byte hex = 32 字符）*/
+export function generateNonce() {
+    return randomBytes(16).toString('hex');
+}
+export function computeAgentId(agentToken) {
+    return createHash('sha256').update(agentToken).digest('hex');
+}
+export function computeTunnelSignature(agentToken, nonce, authSecret) {
+    return createHmac('sha256', authSecret)
+        .update(agentToken + nonce)
+        .digest('hex');
+}
+/** 组装 `slug@version,slug@version` */
+export function formatLocalSkills(skills) {
+    return skills.map((s) => `${s.slug}@${s.version}`).join(',');
+}
+/** 组装 `slug=http://127.0.0.1:port,slug=http://127.0.0.1:port` */
+export function formatLocalSkillEndpoints(skills) {
+    return skills.map((s) => `${s.slug}=${s.endpoint}`).join(',');
+}
+/**
+ * 构造一次握手所需的全部 9 个头。
+ * 每次 connect / reconnect 必须调用一次（nonce 随机）。
+ */
+export function buildHandshakeHeaders(input) {
+    const nonce = generateNonce();
+    const agentId = computeAgentId(input.agentToken);
+    const signature = computeTunnelSignature(input.agentToken, nonce, input.authSecret);
+    const headers = {
+        'x-agent-token': input.agentToken,
+        'x-agent-id': agentId,
+        'x-local-skills': formatLocalSkills(input.localSkills),
+        'x-local-skill-endpoints': formatLocalSkillEndpoints(input.localSkills),
+        'x-tunnel-nonce': nonce,
+        'x-tunnel-signature': signature,
+        'x-skillfm-local-version': input.skillfmLocalVersion,
+    };
+    return { headers, nonce };
+}
+/**
+ * JSON-RPC meta.hmac 签名: HMAC-SHA256(id || method || JSON.stringify(params), secret)
+ * DELTA §5.4
+ */
+export function computeRpcMetaHmac(id, method, params, authSecret) {
+    const payload = id + method + JSON.stringify(params ?? {});
+    return createHmac('sha256', authSecret).update(payload).digest('hex');
+}
+//# sourceMappingURL=handshake.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/skill-tunnel/handshake.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,8EAA8E;AAC9E,UAAU;AACV,wEAAwE;AACxE,gEAAgE;AAChE,EAAE;AACF,qBAAqB;AACrB,0CAA0C;AAC1C,0FAA0F;AAC1F,EAAE;AACF,+CAA+C;AAE/C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAoBlE,uDAAuD;AACvD,MAAM,UAAU,aAAa;IAC3B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,KAAa,EACb,UAAkB;IAElB,OAAO,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC;SACpC,MAAM,CAAC,UAAU,GAAG,KAAK,CAAC;SAC1B,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,iBAAiB,CAAC,MAAiC;IACjE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/D,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,yBAAyB,CACvC,MAAiC;IAEjC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA0B;IAE1B,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,sBAAsB,CACtC,KAAK,CAAC,UAAU,EAChB,KAAK,EACL,KAAK,CAAC,UAAU,CACjB,CAAC;IAEF,MAAM,OAAO,GAA2B;QACtC,eAAe,EAAE,KAAK,CAAC,UAAU;QACjC,YAAY,EAAE,OAAO;QACrB,gBAAgB,EAAE,iBAAiB,CAAC,KAAK,CAAC,WAAW,CAAC;QACtD,yBAAyB,EAAE,yBAAyB,CAAC,KAAK,CAAC,WAAW,CAAC;QACvE,gBAAgB,EAAE,KAAK;QACvB,oBAAoB,EAAE,SAAS;QAC/B,yBAAyB,EAAE,KAAK,CAAC,mBAAmB;KACrD,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAU,EACV,MAAc,EACd,MAAe,EACf,UAAkB;IAElB,MAAM,OAAO,GAAG,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC"}