@sokel-dev/plugin-sdk 0.2.0

package/dist/src/events.js

@@ -0,0 +1,180 @@
+/**
+ * 事件源：插件主动把外部事件推给平台起 workflow（协议 §7）。
+ *
+ * 与操作的区别：操作是 request/reply（平台调插件），事件是 fire-and-forget（插件推平台）。
+ *
+ * 多 bot 单实例（协议 v1.3）：平台每次注册/心跳下发「分配给本副本的凭证子集」，
+ * supervisor 按它 reconcile —— 每个凭证一套源实例，凭证被移除就取消，字段变了就重启。
+ */
+import { toVars } from "./runtime.js";
+export const TRIGGER_SUBJECT = "sokel.trigger";
+export const CREDENTIAL_UPDATE_SUBJECT = "sokel.credential.update";
+/** 注册回包 credentials 列表项 —— 分配给本副本的一个 bot 身份。 */
+export class CredEntry {
+    id;
+    fields;
+    constructor(id = "", fields = {}) {
+        this.id = id;
+        this.fields = fields;
+    }
+    /** 字段的稳定签名：reconcile 据此判定「字段变更 → 重启该源实例」。 */
+    sig() {
+        return Object.keys(this.fields)
+            .sort()
+            .map((k) => `${k}=${this.fields[k]}`)
+            .join("\n");
+    }
+}
+/** 源实例运行态（源 × 凭证）。随注册/心跳上报，面板据此展示每个 bot。 */
+export class StateBoard {
+    now;
+    m = new Map();
+    constructor(now = () => new Date().toISOString()) {
+        this.now = now;
+    }
+    set(sourceId, credId, status, error = "") {
+        const st = { source_id: sourceId, status, since: this.now() };
+        if (credId)
+            st.credential_id = credId;
+        if (error)
+            st.error = error;
+        this.m.set(`${sourceId}|${credId}`, st);
+    }
+    /**
+     * 只在该实例仍是 running 时改写。
+     *
+     * 源自报过状态（如 auth_required）之后正常返回，收尾时不该把那句话盖掉——
+     * 盖掉之后面板上只剩一个「已退出」，而「为什么退出」正是要看的那一半。
+     */
+    setIfRunning(sourceId, credId, status, error = "") {
+        const cur = this.m.get(`${sourceId}|${credId}`);
+        if (!cur || cur.status === "running")
+            this.set(sourceId, credId, status, error);
+    }
+    removeCred(credId) {
+        for (const [k, v] of this.m) {
+            if ((v.credential_id ?? "") === credId)
+                this.m.delete(k);
+        }
+    }
+    snapshot() {
+        return [...this.m.values()].sort((a, b) => a.source_id === b.source_id
+            ? (a.credential_id ?? "").localeCompare(b.credential_id ?? "")
+            : a.source_id.localeCompare(b.source_id));
+    }
+}
+/** 常驻事件源 / webhook 的上下文：推事件、读凭证、回写凭证、上传附件、自报状态。 */
+export class SourceCtx {
+    credential;
+    credentialId;
+    sourceId;
+    /** stopped：该源实例被 reconcile 停止时置真。长轮询循环 while (!ctx.stopped)。 */
+    stopped = false;
+    token;
+    publish;
+    validEvents;
+    board;
+    files;
+    constructor(opts) {
+        this.token = opts.token;
+        this.publish = opts.publish;
+        this.validEvents = new Set(opts.validEvents ?? []);
+        this.credential = opts.credential ?? {};
+        this.credentialId = opts.credentialId ?? "";
+        this.sourceId = opts.sourceId ?? "";
+        this.board = opts.board;
+        this.files = opts.files;
+    }
+    /** 凭证按类型化形状读出（与操作侧 Ctx.credentialAs 同义）。 */
+    credentialAs() {
+        return this.credential;
+    }
+    /**
+     * 推一条事件（fire-and-forget）。
+     *
+     * event 必须是已声明的事件 id —— 拼错在这里当场报错，而不是变成一条平台侧无人认领的
+     * 消息（那种失败没有任何症状：插件日志正常，工作流就是不起）。
+     * eventId 是幂等键，平台按 (plugin, event, eventId) 去重。
+     */
+    async trigger(event, eventId, payload) {
+        if (this.validEvents.size > 0 && !this.validEvents.has(event)) {
+            throw new Error(`未声明的事件 "${event}"（先在 sokel.yaml 的 events 里声明）`);
+        }
+        const msg = {
+            token: this.token,
+            event,
+            payload: toVars(payload),
+        };
+        if (eventId)
+            msg.event_id = eventId;
+        if (this.credentialId)
+            msg.credential_id = this.credentialId;
+        await this.publish(TRIGGER_SUBJECT, encode(msg));
+    }
+    /**
+     * 把 patch 回写到本实例绑定的平台凭证（会话型凭证运行中刷新用）。
+     * 平台是唯一凭证存储方，插件本地从不落地凭证。
+     */
+    async updateCredential(patch) {
+        if (!this.credentialId)
+            throw new Error("本源实例未绑定凭证，无可回写目标");
+        if (Object.keys(patch).length === 0)
+            return;
+        Object.assign(this.credential, patch);
+        await this.publish(CREDENTIAL_UPDATE_SUBJECT, encode({ token: this.token, credential_id: this.credentialId, patch }));
+    }
+    /** 自报运行态（如 session 失效 → auth_required），随心跳上报，面板亮「待登录」。 */
+    reportStatus(status, msg = "") {
+        this.board?.set(this.sourceId, this.credentialId, status, msg);
+    }
+    async upload(name, mime, data) {
+        if (!this.files)
+            return { name, mime, size: data.length, data };
+        return this.files.store(name, mime, data);
+    }
+    async fetch(f) {
+        if (f.data)
+            return f.data;
+        if (!this.files)
+            throw new Error("文件运行时未就绪");
+        return this.files.fetch(f);
+    }
+}
+function encode(v) {
+    return new TextEncoder().encode(JSON.stringify(v));
+}
+/** per-credential 源实例监督器：按平台下发的凭证集合起停/重启。 */
+export class SourceSupervisor {
+    start;
+    running = new Map();
+    constructor(start) {
+        this.start = start;
+    }
+    reconcile(desired) {
+        const want = new Map(desired.map((c) => [c.id, c]));
+        // 停：不在期望集合，或字段变更（先停后起 = 重启）
+        for (const [id, r] of [...this.running]) {
+            const c = want.get(id);
+            if (c && c.sig() === r.sig)
+                continue;
+            r.stop();
+            this.running.delete(id);
+        }
+        // 起：期望但未运行
+        for (const [id, c] of want) {
+            if (this.running.has(id))
+                continue;
+            this.running.set(id, { stop: this.start(c), sig: c.sig() });
+        }
+    }
+    stopAll() {
+        for (const r of this.running.values())
+            r.stop();
+        this.running.clear();
+    }
+}
+/** 空（无凭证插件）→ 一个空凭证裸实例，与有凭证时同一条代码路径。 */
+export function desiredSourceCreds(creds) {
+    return creds.length > 0 ? creds : [new CredEntry()];
+}
+//# sourceMappingURL=events.js.map

package/dist/src/events.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Sokel plugin SDK for Node.js / TypeScript.
+ *
+ * 契约在 sokel.yaml 里声明（语言中立），`sokel-gen generate` 生成类型化的接口与注册口；
+ * 本包提供运行时：注册握手、心跳、调用分发、文件分块、事件触发、webhook、协作式认证。
+ *
+ * ```ts
+ * import { Plugin } from "@sokel-dev/plugin-sdk";
+ * import { CONTRACT, onIssuesList } from "./sokel.gen.js";
+ *
+ * const p = new Plugin({ contract: CONTRACT, name: "gitlab" });
+ * onIssuesList(p, async (ctx, in_) => ({ issues: [], count: 0 }));
+ * await p.run();
+ * ```
+ */
+export { Plugin } from "./plugin.js";
+export type { Call, Config, Invoke, WebhookHandler } from "./plugin.js";
+export { Contract, CAP_WEBHOOK, OP_WEBHOOK } from "./contract.js";
+export type { ContractData, EventSpec, Field, OperationSpec } from "./contract.js";
+export { BufferSink, Ctx, Emitter } from "./runtime.js";
+export type { FileRuntime, Frame, Sink, SokelFile } from "./runtime.js";
+export { CredEntry, SourceCtx, SourceSupervisor, StateBoard, desiredSourceCreds } from "./events.js";
+export type { Source } from "./events.js";
+export { WebhookRequest, ok, text } from "./webhook.js";
+export type { WebhookFrame, WebhookResponse } from "./webhook.js";
+export { CONFIRMED, EXPIRED, PENDING, SCANNED } from "./auth.js";
+export type { AuthChallenge, AuthHandlers, AuthState } from "./auth.js";
+export { env, envOr } from "./env.js";
+export { NatsTransport, QUEUE_GROUP, discover, stableInstanceId } from "./nats.js";

package/dist/src/index.js

@@ -0,0 +1,24 @@
+/**
+ * Sokel plugin SDK for Node.js / TypeScript.
+ *
+ * 契约在 sokel.yaml 里声明（语言中立），`sokel-gen generate` 生成类型化的接口与注册口；
+ * 本包提供运行时：注册握手、心跳、调用分发、文件分块、事件触发、webhook、协作式认证。
+ *
+ * ```ts
+ * import { Plugin } from "@sokel-dev/plugin-sdk";
+ * import { CONTRACT, onIssuesList } from "./sokel.gen.js";
+ *
+ * const p = new Plugin({ contract: CONTRACT, name: "gitlab" });
+ * onIssuesList(p, async (ctx, in_) => ({ issues: [], count: 0 }));
+ * await p.run();
+ * ```
+ */
+export { Plugin } from "./plugin.js";
+export { Contract, CAP_WEBHOOK, OP_WEBHOOK } from "./contract.js";
+export { BufferSink, Ctx, Emitter } from "./runtime.js";
+export { CredEntry, SourceCtx, SourceSupervisor, StateBoard, desiredSourceCreds } from "./events.js";
+export { WebhookRequest, ok, text } from "./webhook.js";
+export { CONFIRMED, EXPIRED, PENDING, SCANNED } from "./auth.js";
+export { env, envOr } from "./env.js";
+export { NatsTransport, QUEUE_GROUP, discover, stableInstanceId } from "./nats.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAErG,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/nats.d.ts

@@ -0,0 +1,35 @@
+/**
+ * NATS 承载：插件**出站**连 broker（无入站端口、无公网 IP、无防火墙洞）。
+ *
+ * 流程与 Go / Python SDK 逐条对齐（协议 §1-§7）：发现 → 连接 → 注册（上报契约）→
+ * 订阅（队列组）→ 心跳续约 → 分发调用 → 优雅下线。事件源插件另有 per-credential supervisor。
+ */
+import type { NatsConnection } from "nats";
+import type { Plugin } from "./plugin.js";
+import type { FileRuntime, SokelFile } from "./runtime.js";
+/** 同组多副本共享队列组 → 每次调用只投一个副本（真·负载均衡）。 */
+export declare const QUEUE_GROUP = "sokel-workers";
+/** 回包/流帧自报副本身份。 */
+export declare const INSTANCE_HEADER = "Sokel-Instance";
+/** 经同一条 NATS 连接与平台交换文件字节。不要求插件可达平台 HTTP —— 内网插件同样可用。 */
+export declare class NatsFiles implements FileRuntime {
+    private readonly nc;
+    private readonly token;
+    constructor(nc: NatsConnection, token: string);
+    fetch(f: SokelFile): Promise<Uint8Array>;
+    store(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
+}
+export declare class NatsTransport {
+    run(p: Plugin): Promise<void>;
+    private dispatch;
+}
+/**
+ * 统一 https 端点 → 经平台 /connect-info 发现真实承载地址。
+ * 直填 nats:// / tls:// 时跳过发现（本地开发 / 离线场景）。
+ */
+export declare function discover(endpoint: string, token: string): Promise<string>;
+/**
+ * 副本的稳定身份：重启复用，否则平台侧每次重启都多出一行永远 offline 的幽灵实例。
+ * 1) SOKEL_INSTANCE_ID；2) 工作目录里按 token 指纹命名的落盘文件；3) 落盘失败 → host-pid。
+ */
+export declare function stableInstanceId(token: string): string;

package/dist/src/nats.js

@@ -0,0 +1,363 @@
+/**
+ * NATS 承载：插件**出站**连 broker（无入站端口、无公网 IP、无防火墙洞）。
+ *
+ * 流程与 Go / Python SDK 逐条对齐（协议 §1-§7）：发现 → 连接 → 注册（上报契约）→
+ * 订阅（队列组）→ 心跳续约 → 分发调用 → 优雅下线。事件源插件另有 per-credential supervisor。
+ */
+import { connect, headers as natsHeaders } from "nats";
+import { hostname } from "node:os";
+import { readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { OP_WEBHOOK } from "./contract.js";
+import { env } from "./env.js";
+import { CredEntry, SourceCtx, SourceSupervisor, desiredSourceCreds } from "./events.js";
+/** 同组多副本共享队列组 → 每次调用只投一个副本（真·负载均衡）。 */
+export const QUEUE_GROUP = "sokel-workers";
+/** 回包/流帧自报副本身份。 */
+export const INSTANCE_HEADER = "Sokel-Instance";
+/** 1 MiB：字节不走操作 reply（受 max_payload 约束），走专用分块通道。 */
+const FILE_CHUNK = 1 << 20;
+const HEARTBEAT_MS = 20_000;
+const RETRY_MS = 8_000;
+const REQUEST_TIMEOUT_MS = 8_000;
+const FILE_TIMEOUT_MS = 30_000;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+/** 经同一条 NATS 连接与平台交换文件字节。不要求插件可达平台 HTTP —— 内网插件同样可用。 */
+export class NatsFiles {
+    nc;
+    token;
+    constructor(nc, token) {
+        this.nc = nc;
+        this.token = token;
+    }
+    async fetch(f) {
+        const id = f.id || (f.url ? f.url.split("/").pop() : "");
+        if (!id)
+            throw new Error("文件引用缺少 id/url");
+        const chunks = [];
+        for (let seq = 0;; seq++) {
+            const resp = await this.nc.request("sokel.file.get", enc.encode(JSON.stringify({ token: this.token, id, seq })), { timeout: FILE_TIMEOUT_MS });
+            const r = JSON.parse(dec.decode(resp.data));
+            if (r.error)
+                throw new Error(r.error);
+            chunks.push(Buffer.from(r.data ?? "", "base64"));
+            if (r.last)
+                return Buffer.concat(chunks);
+        }
+    }
+    async store(name, mime, data) {
+        const buf = Buffer.from(data);
+        let uploadId = "";
+        for (let seq = 0;; seq++) {
+            const chunk = buf.subarray(seq * FILE_CHUNK, (seq + 1) * FILE_CHUNK);
+            const last = (seq + 1) * FILE_CHUNK >= buf.length;
+            const resp = await this.nc.request("sokel.file.put", enc.encode(JSON.stringify({
+                token: this.token,
+                upload_id: uploadId,
+                name,
+                mime,
+                seq,
+                last,
+                data: chunk.toString("base64"),
+            })), { timeout: FILE_TIMEOUT_MS });
+            const r = JSON.parse(dec.decode(resp.data));
+            if (r.error)
+                throw new Error(r.error);
+            if (r.upload_id)
+                uploadId = r.upload_id;
+            if (last) {
+                if (!r.file)
+                    throw new Error("平台未返回文件引用");
+                return r.file;
+            }
+        }
+    }
+}
+export class NatsTransport {
+    async run(p) {
+        const target = await discover(p.endpoint, p.token);
+        // broker 的传输层鉴权优先用 SOKEL_NATS_TOKEN；缺省回退接入 token（无鉴权 broker 会忽略它）
+        const token = env("NATS_TOKEN") || p.token;
+        const ca = env("NATS_CA");
+        const nc = await connectForever({
+            servers: [target],
+            name: p.name,
+            token: token || undefined,
+            maxReconnectAttempts: -1, // 无限重连；订阅在重连后自动恢复
+            reconnectTimeWait: 2_000,
+            waitOnFirstConnect: true, // broker 未就绪时挂起等它，而不是启动失败退出
+            ...(ca ? { tls: { caFile: ca } } : {}),
+        });
+        const host = hostname();
+        const instanceId = stableInstanceId(p.token);
+        const startedAt = new Date().toISOString();
+        const files = new NatsFiles(nc, p.token);
+        let notifySubject = "";
+        const register = async () => {
+            const body = p.registerPayload(instanceId, host, startedAt);
+            const resp = await nc.request("sokel.register", enc.encode(JSON.stringify(body)), {
+                timeout: REQUEST_TIMEOUT_MS,
+            });
+            const reg = JSON.parse(dec.decode(resp.data));
+            if (!reg.ok || !reg.subject)
+                throw new Error(`注册被拒：${reg.error ?? "平台未给 subject"}`);
+            if (reg.notify_subject)
+                notifySubject = reg.notify_subject;
+            let creds = (reg.credentials ?? []).map((c) => new CredEntry(c.id ?? "", c.fields ?? {}));
+            // 旧平台只有单数形态 → 折算成单元素集合（行为与旧版一致）
+            if (creds.length === 0 && (reg.credential_id || reg.credential)) {
+                creds = [new CredEntry(reg.credential_id ?? "", reg.credential ?? {})];
+            }
+            return { subject: reg.subject, name: reg.name || p.name, creds };
+        };
+        // 启动注册失败不退出（broker / 平台可能尚未就绪），固定间隔重试直到成功
+        let first;
+        for (;;) {
+            try {
+                first = await register();
+                break;
+            }
+            catch (e) {
+                console.warn(`[sokel] 注册失败（${errText(e)}），${RETRY_MS / 1000}s 后重试…`);
+                await sleep(RETRY_MS);
+            }
+        }
+        const sub = nc.subscribe(first.subject, { queue: QUEUE_GROUP });
+        void (async () => {
+            for await (const msg of sub) {
+                void this.dispatch(p, nc, msg, files, instanceId);
+            }
+        })();
+        console.log(`[sokel] 已接入平台：插件「${first.name}」就绪，副本 ${instanceId} 监听 ${first.subject}`);
+        let supervisor;
+        if (p.sources.length > 0) {
+            supervisor = makeSupervisor(p, nc, files);
+            supervisor.reconcile(desiredSourceCreds(first.creds));
+            if (notifySubject) {
+                // 凭证变更即时通知：普通订阅（非队列组），组内每个副本都要收——各自的分配集合都可能变
+                const debounced = debounce(300, async () => {
+                    try {
+                        const { creds } = await register();
+                        supervisor.reconcile(desiredSourceCreds(creds));
+                    }
+                    catch (e) {
+                        console.warn(`[sokel] 凭证变更 re-register 失败: ${errText(e)}`);
+                    }
+                });
+                const notifySub = nc.subscribe(notifySubject);
+                void (async () => {
+                    for await (const _ of notifySub)
+                        debounced();
+                })();
+            }
+        }
+        // 心跳续约保持副本在线；SIGINT/SIGTERM（docker stop / Ctrl-C）→ 优雅下线：
+        // 通知平台立即标记 offline（秒级感知），而非等心跳超时清扫（45s+）
+        await new Promise((resolve) => {
+            const timer = setInterval(async () => {
+                try {
+                    const { creds } = await register();
+                    // 每拍按最新分配集合 reconcile：分片迁移 / 凭证增删 / 字段刷新 → 起停或重启源实例
+                    supervisor?.reconcile(desiredSourceCreds(creds));
+                }
+                catch (e) {
+                    console.warn(`[sokel] 心跳续约失败: ${errText(e)}`);
+                }
+            }, HEARTBEAT_MS);
+            const bye = (sig) => {
+                clearInterval(timer);
+                supervisor?.stopAll();
+                nc.publish("sokel.unregister", enc.encode(JSON.stringify({ token: p.token, instance_id: instanceId })));
+                void nc
+                    .flush() // 确保下线通知先于断连送达
+                    .then(() => nc.drain())
+                    .catch(() => undefined)
+                    .then(() => {
+                    console.log(`[sokel] 收到 ${sig}，已通知平台下线，退出`);
+                    resolve();
+                });
+            };
+            process.once("SIGINT", () => bye("SIGINT"));
+            process.once("SIGTERM", () => bye("SIGTERM"));
+        });
+    }
+    async dispatch(p, nc, msg, files, instanceId) {
+        if (!msg.reply)
+            return;
+        let call;
+        try {
+            call = JSON.parse(dec.decode(msg.data));
+        }
+        catch {
+            nc.publish(msg.reply, enc.encode(JSON.stringify({ error: "调用帧解不开" })));
+            return;
+        }
+        const op = call.operation ?? "";
+        const tag = traceTag(call.trace ?? {});
+        // 平台代收 webhook 的特殊帧：分发前拦截（老 SDK 没这段会走 unknown operation，
+        // 平台把它翻译成「插件未注册 webhook 处理器」）
+        if (op === OP_WEBHOOK) {
+            console.log(`[sokel] ← webhook 入站${tag}`);
+            const sctx = new SourceCtx({
+                token: p.token,
+                publish: (subject, data) => nc.publish(subject, data),
+                validEvents: p.contract.eventIds(),
+                credential: call.credential,
+                credentialId: call.credential_id ?? "",
+                sourceId: "webhook",
+                files,
+            });
+            const out = await p.handleWebhook(sctx, call.input ?? {});
+            nc.publish(msg.reply, enc.encode(JSON.stringify(out)));
+            return;
+        }
+        const h = natsHeaders();
+        h.set(INSTANCE_HEADER, instanceId);
+        const started = Date.now();
+        console.log(`[sokel] ← ${op} 开始${tag}`);
+        if (p.contract.isStream(op)) {
+            // 流式：逐帧发布到回复通道，末尾必发终止帧
+            const publishFrame = (f) => nc.publish(msg.reply, enc.encode(JSON.stringify(f)), { headers: h });
+            try {
+                await p.dispatch(call, publishFrame, files);
+                console.log(`[sokel] ✓ ${op} 完成(${Date.now() - started}ms)${tag}`);
+            }
+            catch (e) {
+                console.warn(`[sokel] ✗ ${op} 失败(${Date.now() - started}ms)${tag}: ${errText(e)}`);
+                publishFrame({ kind: "error", text: errText(e) });
+            }
+            publishFrame({ kind: "end" });
+            return;
+        }
+        try {
+            const vars = await p.dispatchBuffered(call, files);
+            console.log(`[sokel] ✓ ${op} 完成(${Date.now() - started}ms)${tag}`);
+            nc.publish(msg.reply, enc.encode(JSON.stringify(vars)), { headers: h });
+        }
+        catch (e) {
+            console.warn(`[sokel] ✗ ${op} 失败(${Date.now() - started}ms)${tag}: ${errText(e)}`);
+            nc.publish(msg.reply, enc.encode(JSON.stringify({ error: errText(e) })), { headers: h });
+        }
+    }
+}
+/** 每个凭证一套源实例：ctx 绑定该凭证，trigger 自动回带其 credential_id。 */
+function makeSupervisor(p, nc, files) {
+    return new SourceSupervisor((cred) => {
+        const ctxs = [];
+        for (const src of p.sources) {
+            const sctx = new SourceCtx({
+                token: p.token,
+                publish: (subject, data) => nc.publish(subject, data),
+                validEvents: p.contract.eventIds(),
+                credential: cred.fields,
+                credentialId: cred.id,
+                sourceId: src.id,
+                board: p.board,
+                files,
+            });
+            ctxs.push(sctx);
+            console.log(`[sokel] 事件源「${src.id}」启动（credential=${cred.id || "(无凭证)"}）`);
+            p.board.set(src.id, cred.id, "running");
+            void src
+                .fn(sctx)
+                .then(() => {
+                if (!sctx.stopped)
+                    p.board.setIfRunning(src.id, cred.id, "exited");
+            })
+                .catch((e) => {
+                if (sctx.stopped)
+                    return; // reconcile 停止：状态已由 stop() 整体移除
+                console.warn(`[sokel] 事件源「${src.id}」退出（credential=${cred.id || "(无凭证)"}）: ${errText(e)}`);
+                p.board.set(src.id, cred.id, "error", errText(e));
+            });
+        }
+        return () => {
+            // JS 没有任务取消：约定由源循环自己看 ctx.stopped 退出（长轮询在下一拍即感知）
+            for (const c of ctxs)
+                c.stopped = true;
+            p.board.removeCred(cred.id);
+        };
+    });
+}
+/**
+ * 统一 https 端点 → 经平台 /connect-info 发现真实承载地址。
+ * 直填 nats:// / tls:// 时跳过发现（本地开发 / 离线场景）。
+ */
+export async function discover(endpoint, token) {
+    const ep = (endpoint ?? "").trim();
+    if (ep.startsWith("nats://") || ep.startsWith("tls://"))
+        return ep;
+    if (!ep.startsWith("http://") && !ep.startsWith("https://")) {
+        throw new Error(`端点 "${endpoint}" 不合法：应为平台地址（https://…）或 nats://`);
+    }
+    const url = ep.replace(/\/+$/, "") + "/api/v1/connect-info";
+    const resp = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+    if (!resp.ok)
+        throw new Error(`平台发现失败 ${url}: HTTP ${resp.status}`);
+    const info = (await resp.json());
+    const target = info.transports?.nats;
+    if (!target)
+        throw new Error("平台未提供可用承载（connect-info.transports 为空）");
+    return target;
+}
+/**
+ * 副本的稳定身份：重启复用，否则平台侧每次重启都多出一行永远 offline 的幽灵实例。
+ * 1) SOKEL_INSTANCE_ID；2) 工作目录里按 token 指纹命名的落盘文件；3) 落盘失败 → host-pid。
+ */
+export function stableInstanceId(token) {
+    const explicit = env("INSTANCE_ID");
+    if (explicit)
+        return explicit;
+    let file = ".sokel-instance-id";
+    if (token)
+        file += "." + createHash("sha256").update(token).digest("hex").slice(0, 8);
+    try {
+        const existing = readFileSync(file, "utf8").trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        /* 首次运行：往下走，生成并落盘 */
+    }
+    const id = `${hostname()}-${randomBytes(4).toString("hex")}`;
+    try {
+        writeFileSync(file, id + "\n");
+    }
+    catch {
+        return `${hostname()}-${process.pid}`;
+    }
+    return id;
+}
+async function connectForever(opts) {
+    for (;;) {
+        try {
+            return await connect(opts);
+        }
+        catch (e) {
+            console.warn(`[sokel] 连接平台失败（${errText(e)}），${RETRY_MS / 1000}s 后重试…`);
+            await sleep(RETRY_MS);
+        }
+    }
+}
+function debounce(ms, fn) {
+    let timer;
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(fn, ms);
+    };
+}
+function traceTag(trace) {
+    const parts = [["run_id", "run"], ["workflow_id", "wf"], ["node_id", "node"]]
+        .filter(([key]) => trace[key])
+        .map(([key, label]) => `${label}=${trace[key]}`);
+    return parts.length > 0 ? ` [${parts.join(" ")}]` : "";
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=nats.js.map