@sokel-dev/plugin-sdk 0.3.0 → 0.4.0

package/dist/src/events.js

@@ -1,15 +1,9 @@
-/**
- * 事件源：插件主动把外部事件推给平台起 workflow（协议 §7）。
- *
- * 与操作的区别：操作是 request/reply（平台调插件），事件是 fire-and-forget（插件推平台）。
- *
- * 多 bot 单实例（协议 v1.3）：平台每次注册/心跳下发「分配给本副本的凭证子集」，
- * supervisor 按它 reconcile —— 每个凭证一套源实例，凭证被移除就取消，字段变了就重启。
- */
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 import { toVars } from "./runtime.js";
 export const TRIGGER_SUBJECT = "sokel.trigger";
 export const CREDENTIAL_UPDATE_SUBJECT = "sokel.credential.update";
-/** 注册回包 credentials 列表项 —— 分配给本副本的一个 bot 身份。 */
+/** One entry of the registration reply's credentials list — a bot identity assigned here. */
 export class CredEntry {
     id;
     fields;
@@ -17,7 +11,7 @@ export class CredEntry {
         this.id = id;
         this.fields = fields;
     }
-    /** 字段的稳定签名：reconcile 据此判定「字段变更 → 重启该源实例」。 */
+    /** A stable signature of the fields; reconcile uses it to decide "fields changed -> restart". */
     sig() {
         return Object.keys(this.fields)
             .sort()
@@ -25,7 +19,8 @@ export class CredEntry {
             .join("\n");
     }
 }
-/** 源实例运行态（源 × 凭证）。随注册/心跳上报，面板据此展示每个 bot。 */
+/** Runtime state per source × credential. Reported with each registration/heartbeat so the panel
+ * can show every bot. */
 export class StateBoard {
     now;
     m = new Map();
@@ -41,10 +36,11 @@ export class StateBoard {
         this.m.set(`${sourceId}|${credId}`, st);
     }
     /**
-     * 只在该实例仍是 running 时改写。
+     * Overwrite only while the instance is still `running`.
      *
-     * 源自报过状态（如 auth_required）之后正常返回，收尾时不该把那句话盖掉——
-     * 盖掉之后面板上只剩一个「已退出」，而「为什么退出」正是要看的那一半。
+     * A source that reported its own status (auth_required, say) and then returned normally should not
+     * have that sentence overwritten on the way out: all the panel would show is "exited", and *why*
+     * it exited is the half that matters.
      */
     setIfRunning(sourceId, credId, status, error = "") {
         const cur = this.m.get(`${sourceId}|${credId}`);
@@ -63,12 +59,13 @@ export class StateBoard {
             : a.source_id.localeCompare(b.source_id));
     }
 }
-/** 常驻事件源 / webhook 的上下文：推事件、读凭证、回写凭证、上传附件、自报状态。 */
+/** The context for a long-running source or a webhook: push events, read and write back
+ * credentials, upload attachments, report state. */
 export class SourceCtx {
     credential;
     credentialId;
     sourceId;
-    /** stopped：该源实例被 reconcile 停止时置真。长轮询循环 while (!ctx.stopped)。 */
+    /** Set to true when reconcile stops this instance. Long-poll loops run `while (!ctx.stopped)`. */
     stopped = false;
     token;
     publish;
@@ -85,20 +82,21 @@ export class SourceCtx {
         this.board = opts.board;
         this.files = opts.files;
     }
-    /** 凭证按类型化形状读出（与操作侧 Ctx.credentialAs 同义）。 */
+    /** Read the credential into a typed shape (same as Ctx.credentialAs on the operation side). */
     credentialAs() {
         return this.credential;
     }
     /**
-     * 推一条事件（fire-and-forget）。
+     * Push one event (fire-and-forget).
      *
-     * event 必须是已声明的事件 id —— 拼错在这里当场报错，而不是变成一条平台侧无人认领的
-     * 消息（那种失败没有任何症状：插件日志正常，工作流就是不起）。
-     * eventId 是幂等键，平台按 (plugin, event, eventId) 去重。
+     * `event` must be a declared event id: a typo fails here rather than turning into a message nobody
+     * on the platform claims. That failure mode has no symptoms — the plugin log looks fine and the
+     * workflow simply never starts. `eventId` is the idempotency key; the platform deduplicates on
+     * (plugin, event, eventId).
      */
     async trigger(event, eventId, payload) {
         if (this.validEvents.size > 0 && !this.validEvents.has(event)) {
-            throw new Error(`未声明的事件 "${event}"（先在 sokel.yaml 的 events 里声明）`);
+            throw new Error(`undeclared event "${event}" — declare it under events in sokel.yaml`);
         }
         const msg = {
             token: this.token,
@@ -112,18 +110,20 @@ export class SourceCtx {
         await this.publish(TRIGGER_SUBJECT, encode(msg));
     }
     /**
-     * 把 patch 回写到本实例绑定的平台凭证（会话型凭证运行中刷新用）。
-     * 平台是唯一凭证存储方，插件本地从不落地凭证。
+     * Write a patch back to the credential bound to this instance (how a session-style credential
+     * refreshes itself while running).
+     * The platform is the only store for credentials; a plugin never persists them locally.
      */
     async updateCredential(patch) {
         if (!this.credentialId)
-            throw new Error("本源实例未绑定凭证，无可回写目标");
+            throw new Error("this source instance has no bound credential to write back to");
         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），随心跳上报，面板亮「待登录」。 */
+    /** Report state (an expired session becomes auth_required); it rides the heartbeat and lights up
+     * "needs login" in the panel. */
     reportStatus(status, msg = "") {
         this.board?.set(this.sourceId, this.credentialId, status, msg);
     }
@@ -136,14 +136,14 @@ export class SourceCtx {
         if (f.data)
             return f.data;
         if (!this.files)
-            throw new Error("文件运行时未就绪");
+            throw new Error("file runtime not ready");
         return this.files.fetch(f);
     }
 }
 function encode(v) {
     return new TextEncoder().encode(JSON.stringify(v));
 }
-/** per-credential 源实例监督器：按平台下发的凭证集合起停/重启。 */
+/** Per-credential supervisor: starts, stops and restarts instances to match the assigned set. */
 export class SourceSupervisor {
     start;
     running = new Map();
@@ -152,7 +152,7 @@ export class SourceSupervisor {
     }
     reconcile(desired) {
         const want = new Map(desired.map((c) => [c.id, c]));
-        // 停：不在期望集合，或字段变更（先停后起 = 重启）
+        // Stop: not in the desired set, or its fields changed (stop then start = restart)
         for (const [id, r] of [...this.running]) {
             const c = want.get(id);
             if (c && c.sig() === r.sig)
@@ -160,7 +160,7 @@ export class SourceSupervisor {
             r.stop();
             this.running.delete(id);
         }
-        // 起：期望但未运行
+        // Start: desired but not running
         for (const [id, c] of want) {
             if (this.running.has(id))
                 continue;
@@ -173,7 +173,8 @@ export class SourceSupervisor {
         this.running.clear();
     }
 }
-/** 空（无凭证插件）→ 一个空凭证裸实例，与有凭证时同一条代码路径。 */
+/** Empty (a plugin with no credentials) becomes one bare instance, so both cases take the same
+ * code path. */
 export function desiredSourceCreds(creds) {
     return creds.length > 0 ? creds : [new CredEntry()];
 }

package/dist/src/events.js.map

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

package/dist/src/index.d.ts

@@ -1,8 +1,10 @@
 /**
  * Sokel plugin SDK for Node.js / TypeScript.
  *
- * 契约在 sokel.yaml 里声明（语言中立），`sokel-gen generate` 生成类型化的接口与注册口；
- * 本包提供运行时：注册握手、心跳、调用分发、文件分块、事件触发、webhook、协作式认证。
+ * The contract is declared in a language-neutral sokel.yaml; `sokel-gen generate` turns it into
+ * typed interfaces and registration functions. This package is the runtime: registration handshake,
+ * heartbeat, call dispatch, chunked file transfer, event triggering, webhooks and collaborative
+ * authentication.
  *
  * ```ts
  * import { Plugin } from "@sokel-dev/plugin-sdk";

package/dist/src/index.js

@@ -1,8 +1,12 @@
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Sokel plugin SDK for Node.js / TypeScript.
  *
- * 契约在 sokel.yaml 里声明（语言中立），`sokel-gen generate` 生成类型化的接口与注册口；
- * 本包提供运行时：注册握手、心跳、调用分发、文件分块、事件触发、webhook、协作式认证。
+ * The contract is declared in a language-neutral sokel.yaml; `sokel-gen generate` turns it into
+ * typed interfaces and registration functions. This package is the runtime: registration handshake,
+ * heartbeat, call dispatch, chunked file transfer, event triggering, webhooks and collaborative
+ * authentication.
  *
  * ```ts
  * import { Plugin } from "@sokel-dev/plugin-sdk";

package/dist/src/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC;;;;;;;;;;;;;;;;GAgBG;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

@@ -1,25 +1,21 @@
-/**
- * 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";
-/** 同组多副本共享队列组 → 每次调用只投一个副本（真·负载均衡）。 */
+/** Replicas of a group share one queue: each call goes to exactly one of them. */
 export declare const QUEUE_GROUP = "sokel-workers";
-/** 回包/流帧自报副本身份。 */
+/** Replies and stream frames report which replica answered. */
 export declare const INSTANCE_HEADER = "Sokel-Instance";
-/** 经同一条 NATS 连接与平台交换文件字节。不要求插件可达平台 HTTP —— 内网插件同样可用。 */
+/** Exchange file bytes with the platform over the same NATS connection. The plugin never needs HTTP
+ * access to the platform, so a plugin behind NAT works the same way. */
 export declare class NatsFiles implements FileRuntime {
     private readonly nc;
     private readonly token;
     constructor(nc: NatsConnection, token: string);
     fetch(f: SokelFile): Promise<Uint8Array>;
-    /** 整块字节。走 storeStream —— 分块协议只该有一份实现。 */
+    /** Whole bytes. Delegates to storeStream: the chunking protocol should have one implementation. */
     store(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
-    /** **边读边传**，内存占用恒为一个块。平台那侧本来就是逐块写进 blob 的。 */
+    /** **Stream while reading**; memory stays at one chunk. The platform already writes into blob
+     * storage chunk by chunk. */
     storeStream(name: string, mime: string, src: AsyncIterable<Uint8Array>): Promise<SokelFile>;
     private putChunk;
 }
@@ -28,12 +24,14 @@ export declare class NatsTransport {
     private dispatch;
 }
 /**
- * 统一 https 端点 → 经平台 /connect-info 发现真实承载地址。
- * 直填 nats:// / tls:// 时跳过发现（本地开发 / 离线场景）。
+ * A single https endpoint becomes the real transport address via the platform's /connect-info.
+ * A literal nats:// or tls:// URL skips discovery (local development, offline setups).
  */
 export declare function discover(endpoint: string, token: string): Promise<string>;
 /**
- * 副本的稳定身份：重启复用，否则平台侧每次重启都多出一行永远 offline 的幽灵实例。
- * 1) SOKEL_INSTANCE_ID；2) 工作目录里按 token 指纹命名的落盘文件；3) 落盘失败 → host-pid。
+ * A stable replica identity, reused across restarts. Without it every restart leaves the platform
+ * holding another ghost row that stays offline forever.
+ * In order: 1) SOKEL_INSTANCE_ID; 2) a file in the working directory named after the token's
+ * fingerprint; 3) if writing that file fails, host-pid.
  */
 export declare function stableInstanceId(token: string): string;

package/dist/src/nats.js

@@ -1,8 +1,12 @@
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 /**
- * NATS 承载：插件**出站**连 broker（无入站端口、无公网 IP、无防火墙洞）。
+ * The NATS transport: the plugin **dials out** to the broker (no inbound port, no public IP, no
+ * firewall hole).
  *
- * 流程与 Go / Python SDK 逐条对齐（协议 §1-§7）：发现 → 连接 → 注册（上报契约）→
- * 订阅（队列组）→ 心跳续约 → 分发调用 → 优雅下线。事件源插件另有 per-credential supervisor。
+ * The flow matches the Go and Python SDKs step for step (protocol §1-§7): discover, connect,
+ * register (reporting the contract), subscribe (as a queue group), renew by heartbeat, dispatch
+ * calls, shut down gracefully. Event-source plugins additionally run a per-credential supervisor.
  */
 import { connect, headers as natsHeaders } from "nats";
 import { hostname } from "node:os";
@@ -11,11 +15,11 @@ 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";
-/** 同组多副本共享队列组 → 每次调用只投一个副本（真·负载均衡）。 */
+/** Replicas of a group share one queue: each call goes to exactly one of them. */
 export const QUEUE_GROUP = "sokel-workers";
-/** 回包/流帧自报副本身份。 */
+/** Replies and stream frames report which replica answered. */
 export const INSTANCE_HEADER = "Sokel-Instance";
-/** 1 MiB：字节不走操作 reply（受 max_payload 约束），走专用分块通道。 */
+/** 1 MiB. Bytes never ride the operation reply (max_payload); they go through the chunk channel. */
 const FILE_CHUNK = 1 << 20;
 const HEARTBEAT_MS = 20_000;
 const RETRY_MS = 8_000;
@@ -23,7 +27,8 @@ const REQUEST_TIMEOUT_MS = 8_000;
 const FILE_TIMEOUT_MS = 30_000;
 const enc = new TextEncoder();
 const dec = new TextDecoder();
-/** 经同一条 NATS 连接与平台交换文件字节。不要求插件可达平台 HTTP —— 内网插件同样可用。 */
+/** Exchange file bytes with the platform over the same NATS connection. The plugin never needs HTTP
+ * access to the platform, so a plugin behind NAT works the same way. */
 export class NatsFiles {
     nc;
     token;
@@ -34,7 +39,7 @@ export class NatsFiles {
     async fetch(f) {
         const id = f.id || (f.url ? f.url.split("/").pop() : "");
         if (!id)
-            throw new Error("文件引用缺少 id/url");
+            throw new Error("the file reference has neither id nor 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 });
@@ -46,19 +51,20 @@ export class NatsFiles {
                 return Buffer.concat(chunks);
         }
     }
-    /** 整块字节。走 storeStream —— 分块协议只该有一份实现。 */
+    /** Whole bytes. Delegates to storeStream: the chunking protocol should have one implementation. */
     async store(name, mime, data) {
         return this.storeStream(name, mime, (async function* () { yield data; })());
     }
-    /** **边读边传**，内存占用恒为一个块。平台那侧本来就是逐块写进 blob 的。 */
+    /** **Stream while reading**; memory stays at one chunk. The platform already writes into blob
+     * storage chunk by chunk. */
     async storeStream(name, mime, src) {
         let uploadId = "";
         let seq = 0;
         let pending = Buffer.alloc(0);
         let done = false;
         const it = src[Symbol.asyncIterator]();
-        // 攒够一块再发：上游给的分片大小由它自己定（fs 流默认 64KB），
-        // 直接照发的话块数会翻十几倍，每块都是一次 request-reply。
+        // Fill a whole chunk before sending: the source decides its own slice size (a fs stream gives
+        // 64KB by default), and forwarding those as-is would multiply the round trips more than tenfold.
         while (!done) {
             while (pending.length < FILE_CHUNK) {
                 const r = await it.next();
@@ -76,12 +82,12 @@ export class NatsFiles {
                 uploadId = f.uploadId;
             if (last) {
                 if (!f.file)
-                    throw new Error("平台未返回文件引用");
+                    throw new Error("the platform returned no file reference");
                 return f.file;
             }
             seq += 1;
         }
-        throw new Error("上传未收到末块应答（不该发生）");
+        throw new Error("the upload never got a final-chunk reply (should not happen)");
     }
     async putChunk(name, mime, uploadId, seq, last, chunk) {
         {
@@ -106,16 +112,17 @@ export class NatsFiles {
 export class NatsTransport {
     async run(p) {
         const target = await discover(p.endpoint, p.token);
-        // broker 的传输层鉴权优先用 SOKEL_NATS_TOKEN；缺省回退接入 token（无鉴权 broker 会忽略它）
+        // Transport-level auth prefers SOKEL_NATS_TOKEN and falls back to the access token; a broker
+        // without auth ignores it either way.
         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, // 无限重连；订阅在重连后自动恢复
+            maxReconnectAttempts: -1, // reconnect forever; subscriptions restore themselves
             reconnectTimeWait: 2_000,
-            waitOnFirstConnect: true, // broker 未就绪时挂起等它，而不是启动失败退出
+            waitOnFirstConnect: true, // wait for a broker that is not up yet instead of exiting
             ...(ca ? { tls: { caFile: ca } } : {}),
         });
         const host = hostname();
@@ -130,17 +137,18 @@ export class NatsTransport {
             });
             const reg = JSON.parse(dec.decode(resp.data));
             if (!reg.ok || !reg.subject)
-                throw new Error(`注册被拒：${reg.error ?? "平台未给 subject"}`);
+                throw new Error(`registration refused: ${reg.error ?? "the platform returned no subject"}`);
             if (reg.notify_subject)
                 notifySubject = reg.notify_subject;
             let creds = (reg.credentials ?? []).map((c) => new CredEntry(c.id ?? "", c.fields ?? {}));
-            // 旧平台只有单数形态 → 折算成单元素集合（行为与旧版一致）
+            // An older platform only sends the singular form; fold it into a one-element set.
             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 / 平台可能尚未就绪），固定间隔重试直到成功
+        // A failed first registration is not fatal (broker or platform may still be starting): retry at
+        // a fixed interval until it succeeds.
         let first;
         for (;;) {
             try {
@@ -148,7 +156,7 @@ export class NatsTransport {
                 break;
             }
             catch (e) {
-                console.warn(`[sokel] 注册失败（${errText(e)}），${RETRY_MS / 1000}s 后重试…`);
+                console.warn(`[sokel] registration failed (${errText(e)}), retrying in ${RETRY_MS / 1000}s…`);
                 await sleep(RETRY_MS);
             }
         }
@@ -158,20 +166,21 @@ export class NatsTransport {
                 void this.dispatch(p, nc, msg, files, instanceId);
             }
         })();
-        console.log(`[sokel] 已接入平台：插件「${first.name}」就绪，副本 ${instanceId} 监听 ${first.subject}`);
+        console.log(`[sokel] connected: plugin "${first.name}" ready, replica ${instanceId} listening on ${first.subject}`);
         let supervisor;
         if (p.sources.length > 0) {
             supervisor = makeSupervisor(p, nc, files);
             supervisor.reconcile(desiredSourceCreds(first.creds));
             if (notifySubject) {
-                // 凭证变更即时通知：普通订阅（非队列组），组内每个副本都要收——各自的分配集合都可能变
+                // Credential-change notifications use a plain subscription (not a queue group): every
+                // replica in the group must hear it, since any assignment may have changed.
                 const debounced = debounce(300, async () => {
                     try {
                         const { creds } = await register();
                         supervisor.reconcile(desiredSourceCreds(creds));
                     }
                     catch (e) {
-                        console.warn(`[sokel] 凭证变更 re-register 失败: ${errText(e)}`);
+                        console.warn(`[sokel] re-register after a credential change failed: ${errText(e)}`);
                     }
                 });
                 const notifySub = nc.subscribe(notifySubject);
@@ -181,17 +190,19 @@ export class NatsTransport {
                 })();
             }
         }
-        // 心跳续约保持副本在线；SIGINT/SIGTERM（docker stop / Ctrl-C）→ 优雅下线：
-        // 通知平台立即标记 offline（秒级感知），而非等心跳超时清扫（45s+）
+        // The heartbeat keeps the replica online. On SIGINT/SIGTERM (docker stop, Ctrl-C) it shuts down
+        // gracefully: tell the platform to mark this replica offline right away (seconds), instead of
+        // waiting for the heartbeat sweep (45s+).
         await new Promise((resolve) => {
             const timer = setInterval(async () => {
                 try {
                     const { creds } = await register();
-                    // 每拍按最新分配集合 reconcile：分片迁移 / 凭证增删 / 字段刷新 → 起停或重启源实例
+                    // Reconcile against the latest assignment each tick: shard moves, credentials added or
+                    // removed, fields refreshed.
                     supervisor?.reconcile(desiredSourceCreds(creds));
                 }
                 catch (e) {
-                    console.warn(`[sokel] 心跳续约失败: ${errText(e)}`);
+                    console.warn(`[sokel] heartbeat renewal failed: ${errText(e)}`);
                 }
             }, HEARTBEAT_MS);
             const bye = (sig) => {
@@ -199,11 +210,11 @@ export class NatsTransport {
                 supervisor?.stopAll();
                 nc.publish("sokel.unregister", enc.encode(JSON.stringify({ token: p.token, instance_id: instanceId })));
                 void nc
-                    .flush() // 确保下线通知先于断连送达
+                    .flush() // make sure the goodbye lands before the connection drops
                     .then(() => nc.drain())
                     .catch(() => undefined)
                     .then(() => {
-                    console.log(`[sokel] 收到 ${sig}，已通知平台下线，退出`);
+                    console.log(`[sokel] got ${sig}, told the platform we are going offline, exiting`);
                     resolve();
                 });
             };
@@ -219,15 +230,16 @@ export class NatsTransport {
             call = JSON.parse(dec.decode(msg.data));
         }
         catch {
-            nc.publish(msg.reply, enc.encode(JSON.stringify({ error: "调用帧解不开" })));
+            nc.publish(msg.reply, enc.encode(JSON.stringify({ error: "could not parse the call frame" })));
             return;
         }
         const op = call.operation ?? "";
         const tag = traceTag(call.trace ?? {});
-        // 平台代收 webhook 的特殊帧：分发前拦截（老 SDK 没这段会走 unknown operation，
-        // 平台把它翻译成「插件未注册 webhook 处理器」）
+        // The platform-relayed webhook frame is intercepted before dispatch. An older SDK without this
+        // branch falls through to "unknown operation", which the platform translates into "the plugin
+        // registered no webhook handler".
         if (op === OP_WEBHOOK) {
-            console.log(`[sokel] ← webhook 入站${tag}`);
+            console.log(`[sokel] ← webhook inbound${tag}`);
             const sctx = new SourceCtx({
                 token: p.token,
                 publish: (subject, data) => nc.publish(subject, data),
@@ -244,16 +256,16 @@ export class NatsTransport {
         const h = natsHeaders();
         h.set(INSTANCE_HEADER, instanceId);
         const started = Date.now();
-        console.log(`[sokel] ← ${op} 开始${tag}`);
+        console.log(`[sokel] ← ${op} started${tag}`);
         if (p.contract.isStream(op)) {
-            // 流式：逐帧发布到回复通道，末尾必发终止帧
+            // Streaming: publish frame by frame to the reply subject; the end frame is mandatory.
             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}`);
+                console.log(`[sokel] ✓ ${op} done (${Date.now() - started}ms)${tag}`);
             }
             catch (e) {
-                console.warn(`[sokel] ✗ ${op} 失败(${Date.now() - started}ms)${tag}: ${errText(e)}`);
+                console.warn(`[sokel] ✗ ${op} failed (${Date.now() - started}ms)${tag}: ${errText(e)}`);
                 publishFrame({ kind: "error", text: errText(e) });
             }
             publishFrame({ kind: "end" });
@@ -261,16 +273,17 @@ export class NatsTransport {
         }
         try {
             const vars = await p.dispatchBuffered(call, files);
-            console.log(`[sokel] ✓ ${op} 完成(${Date.now() - started}ms)${tag}`);
+            console.log(`[sokel] ✓ ${op} done (${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)}`);
+            console.warn(`[sokel] ✗ ${op} failed (${Date.now() - started}ms)${tag}: ${errText(e)}`);
             nc.publish(msg.reply, enc.encode(JSON.stringify({ error: errText(e) })), { headers: h });
         }
     }
 }
-/** 每个凭证一套源实例：ctx 绑定该凭证，trigger 自动回带其 credential_id。 */
+/** One source instance per credential: its ctx is bound to that credential, and trigger carries the
+ * credential_id back automatically. */
 function makeSupervisor(p, nc, files) {
     return new SourceSupervisor((cred) => {
         const ctxs = [];
@@ -286,7 +299,7 @@ function makeSupervisor(p, nc, files) {
                 files,
             });
             ctxs.push(sctx);
-            console.log(`[sokel] 事件源「${src.id}」启动（credential=${cred.id || "(无凭证)"}）`);
+            console.log(`[sokel] event source "${src.id}" started (credential=${cred.id || "(none)"})`);
             p.board.set(src.id, cred.id, "running");
             void src
                 .fn(sctx)
@@ -296,13 +309,14 @@ function makeSupervisor(p, nc, files) {
             })
                 .catch((e) => {
                 if (sctx.stopped)
-                    return; // reconcile 停止：状态已由 stop() 整体移除
-                console.warn(`[sokel] 事件源「${src.id}」退出（credential=${cred.id || "(无凭证)"}）: ${errText(e)}`);
+                    return; // stopped by reconcile: stop() already removed the state
+                console.warn(`[sokel] event source "${src.id}" exited (credential=${cred.id || "(none)"}): ${errText(e)}`);
                 p.board.set(src.id, cred.id, "error", errText(e));
             });
         }
         return () => {
-            // JS 没有任务取消：约定由源循环自己看 ctx.stopped 退出（长轮询在下一拍即感知）
+            // JS has no task cancellation: by convention the source loop watches ctx.stopped and exits
+            // (a long poll notices on its next tick).
             for (const c of ctxs)
                 c.stopped = true;
             p.board.removeCred(cred.id);
@@ -310,29 +324,31 @@ function makeSupervisor(p, nc, files) {
     });
 }
 /**
- * 统一 https 端点 → 经平台 /connect-info 发现真实承载地址。
- * 直填 nats:// / tls:// 时跳过发现（本地开发 / 离线场景）。
+ * A single https endpoint becomes the real transport address via the platform's /connect-info.
+ * A literal nats:// or tls:// URL skips discovery (local development, offline setups).
  */
 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://`);
+        throw new Error(`invalid endpoint "${endpoint}": expected a platform URL (https://…) or 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}`);
+        throw new Error(`discovery failed at ${url}: HTTP ${resp.status}`);
     const info = (await resp.json());
     const target = info.transports?.nats;
     if (!target)
-        throw new Error("平台未提供可用承载（connect-info.transports 为空）");
+        throw new Error("the platform offers no transport (connect-info.transports is empty)");
     return target;
 }
 /**
- * 副本的稳定身份：重启复用，否则平台侧每次重启都多出一行永远 offline 的幽灵实例。
- * 1) SOKEL_INSTANCE_ID；2) 工作目录里按 token 指纹命名的落盘文件；3) 落盘失败 → host-pid。
+ * A stable replica identity, reused across restarts. Without it every restart leaves the platform
+ * holding another ghost row that stays offline forever.
+ * In order: 1) SOKEL_INSTANCE_ID; 2) a file in the working directory named after the token's
+ * fingerprint; 3) if writing that file fails, host-pid.
  */
 export function stableInstanceId(token) {
     const explicit = env("INSTANCE_ID");
@@ -347,7 +363,7 @@ export function stableInstanceId(token) {
             return existing;
     }
     catch {
-        /* 首次运行：往下走，生成并落盘 */
+        /* first run: fall through, generate one and write it out */
     }
     const id = `${hostname()}-${randomBytes(4).toString("hex")}`;
     try {
@@ -364,7 +380,7 @@ async function connectForever(opts) {
             return await connect(opts);
         }
         catch (e) {
-            console.warn(`[sokel] 连接平台失败（${errText(e)}），${RETRY_MS / 1000}s 后重试…`);
+            console.warn(`[sokel] could not connect to the platform (${errText(e)}), retrying in ${RETRY_MS / 1000}s…`);
             await sleep(RETRY_MS);
         }
     }