@sokel-dev/plugin-sdk 0.3.0 → 0.5.3

package/README.md

@@ -1,7 +1,11 @@
 # Sokel Plugin SDK — Node.js / TypeScript
 
-用 TypeScript 写 [Sokel](https://github.com/sokel-dev) 插件。契约写在 `sokel.yaml` 里（语言中立），
-`sokel-gen` 把它生成成 TS 接口与类型化的注册口；SDK 负责注册、传输、凭证、文件、心跳与重连。
+[简体中文](README.zh-CN.md)
+
+Write [Sokel](https://github.com/sokel-dev) plugins in TypeScript. The contract lives in a
+language-neutral `manifest.yml`; `sokel-gen` turns it into TypeScript interfaces and typed
+registration functions, and the SDK handles registration, transport, credentials, files, heartbeats
+and reconnects.
 
 ```ts
 onIssuesList(p, async (ctx, in_) => {
@@ -10,72 +14,83 @@ onIssuesList(p, async (ctx, in_) => {
 });
 ```
 
-`in_.project` 拼错是编译错误，不是线上的一次失败调用——代码里没有任何 `any`。
+A typo in `in_.project` is a compile error, not a failed call in production — there is no `any`
+anywhere in your code.
 
-## 装
+## Install
 
 ```bash
 npm install @sokel-dev/plugin-sdk
-go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest   # 生成器
+go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest   # the generator
 ```
 
-`sokel-gen` 是个单文件二进制（Go 写的），只在**生成时**用到；跑插件时不需要它。
+`sokel-gen` is a single binary (written in Go) used **only at generation time**; running a plugin
+does not need it.
 
-## 四步
+## Four steps
 
 ```bash
 sokel-gen init -lang ts ./my-plugin
-cd my-plugin
-npm install
-sokel-gen generate .     # sokel.yaml → src/sokel.gen.ts
+cd my-plugin && npm install
+sokel-gen generate .     # manifest.yml → src/sokel.gen.ts
 npm run build && npm start
 ```
 
-1. **声明** —— `sokel.yaml`：操作、事件、凭证、认证方式。格式见 [docs/manifest.md](../docs/manifest.md)。
-2. **生成** —— `sokel-gen generate .` 产出 `src/sokel.gen.ts`：每个操作一对 `XxxIn` / `XxxOut` 接口
-   和一个 `onXxx(p, fn)`；每个事件一个 payload 接口和一个 `triggerXxx(ctx, eventId, payload)`。
-3. **实现** —— handler 签名完全具体，返回值可以是对象也可以是 Promise。
-4. **连接** —— `await p.run()`。插件**出站**连平台：无入站端口、无公网 IP、无防火墙洞。
+1. **Declare** — `manifest.yml`: operations, events, credentials, authentication. Format:
+   [docs/manifest.md](../docs/manifest.md), or run `sokel-gen docs`.
+2. **Generate** — `sokel-gen generate .` writes `src/sokel.gen.ts`: an `XxxIn` / `XxxOut` interface
+   pair and an `onXxx(p, fn)` per operation; a payload interface and a
+   `triggerXxx(ctx, eventId, payload)` per event.
+3. **Implement** — handler signatures are fully concrete; return a value or a promise.
+4. **Connect** — `await p.run()`. A plugin **dials out**: no inbound port, no public IP, no firewall
+   hole.
 
-## 为什么不是 zod
+## Why not zod
 
-zod schema 是运行时对象：用它声明契约意味着「契约只有跑起来才知道」，而且每种语言都得
-自己解释一遍那套 DSL。声明留在 `sokel.yaml`，TS 这边只要类型——类型在编译期，运行时零开销。
+A zod schema is a runtime object, so declaring the contract in zod means the contract only exists
+once the process is running — and every language would have to interpret that DSL for itself. The
+declaration stays in `manifest.yml`; TypeScript takes only the types, which is what TypeScript is good
+at: compile-time checks, zero runtime cost.
 
-## 能力一览
+## What you can do
 
-| 要做的事 | 怎么写 |
+| Task | How |
 |---|---|
-| 读凭证 | `ctx.credentialAs<Credential>()` |
-| 取入参文件的字节 | `await ctx.fetch(in_.file)` |
-| 产出文件 | `await ctx.upload(name, mime, bytes)` → 放进出参 |
-| 流式产出 | `out.text(...)` 逐帧给人看，`out.vars({...})` 给下游 |
-| 推事件 | `await triggerMessage(ctx, eventId, {...})` |
-| 常驻事件源 | `p.registerSource(id, label, fn)`，循环里判 `ctx.stopped` |
-| 平台代收 webhook | `p.registerWebhook(fn)`，返回 `ok()` / `text(401, "...")` |
-| 协作式认证 | `p.registerAuth({ start, poll, submit })` |
-| 会话型凭证刷新 | `await ctx.updateCredential({ session: "…" })` |
-| 自报运行态 | `ctx.reportStatus("auth_required", "…")` |
-
-## 配置
-
-SDK 读 `SOKEL_` 前缀的环境变量：
-
-| 变量 | 必填 | 含义 |
+| Read credentials | `ctx.credentialAs<Credential>()` |
+| Read an input file's bytes | `await ctx.fetch(in_.file)` |
+| Produce a file | `await ctx.upload(name, mime, bytes)`, or `await ctx.uploadFile(path)` for large files |
+| Stream output | `out.text(...)` frame by frame for humans, `out.vars({...})` for downstream nodes |
+| Push an event | `await triggerMessage(ctx, eventId, {...})` |
+| Long-running event source | `p.registerSource(id, label, fn)`; loop while `!ctx.stopped` |
+| Handle a platform-relayed webhook | `p.registerWebhook(fn)`, return `ok()` / `text(401, "...")` |
+| Collaborative authentication | `p.registerAuth({ start, poll, submit })` |
+| Refresh a session credential | `await ctx.updateCredential({ session: "…" })` |
+| Report runtime state | `ctx.reportStatus("auth_required", "…")` |
+
+`uploadFile(path)` streams from disk: memory stays at one chunk (1 MiB) regardless of file size.
+Anything above a few hundred megabytes should use it — `upload(bytes)` reads the whole file into
+memory first, and the symptom of that is a container mysteriously killed by the OOM reaper.
+
+## Configuration
+
+The SDK reads `SOKEL_`-prefixed environment variables:
+
+| Variable | Required | Meaning |
 |---|---|---|
-| `SOKEL_ENDPOINT` | 是 | `nats://broker:4222`，或 `https://` 平台地址（经 `/connect-info` 发现 broker） |
-| `SOKEL_TOKEN` | 是 | 接入组 token（`skp_…`），平台据此认「插件 + 工作空间」 |
-| `SOKEL_NATS_TOKEN` | 否 | broker 的传输层鉴权 |
-| `SOKEL_NATS_CA` | 否 | `tls://` broker 的自定义 CA |
-| `SOKEL_INSTANCE_ID` | 否 | 固定副本身份（默认按 token 指纹落盘复用） |
-| `SOKEL_REGION` | 否 | 副本的地域标注 |
+| `SOKEL_ENDPOINT` | yes | `nats://broker:4222`, or an `https://` platform URL to discover the broker from |
+| `SOKEL_TOKEN` | yes | Access-group token (`skp_…`) identifying plugin + workspace |
+| `SOKEL_NATS_TOKEN` | no | Broker-level auth |
+| `SOKEL_NATS_CA` | no | Custom CA bundle for `tls://` brokers |
+| `SOKEL_INSTANCE_ID` | no | Pin a replica identity (otherwise derived from the token and cached on disk) |
+| `SOKEL_REGION` | no | Region label for the replica |
 
-凭证从不由插件存储：平台随每次调用把解析后的字段下发下来。
+Credentials are never stored by the plugin: the platform injects the resolved fields with each call.
 
-## 例子
+## Example
 
-[`examples/kitchen-sink`](../examples/kitchen-sink) 覆盖了全部形态——每种字段、文件、流式、
-事件、webhook、协作式认证各一份，Node 与 Python 实现的是同一份声明。
+[`examples/kitchen-sink`](../examples/kitchen-sink) covers every shape — each field type, files,
+streaming, events, webhooks, collaborative auth — and the Node and Python implementations share one
+declaration.
 
 ```bash
 cd examples/kitchen-sink/node
@@ -83,7 +98,7 @@ npm install && npm run build
 SOKEL_ENDPOINT=nats://localhost:4222 SOKEL_TOKEN=skp_xxx npm start
 ```
 
-## 开发本 SDK
+## Developing this SDK
 
 ```bash
 pnpm install

package/README.zh-CN.md

@@ -0,0 +1,95 @@
+# Sokel Plugin SDK — Node.js / TypeScript
+
+用 TypeScript 写 [Sokel](https://github.com/sokel-dev) 插件。契约写在 `manifest.yml` 里（语言中立），
+`sokel-gen` 把它生成成 TS 接口与类型化的注册口；SDK 负责注册、传输、凭证、文件、心跳与重连。
+
+```ts
+onIssuesList(p, async (ctx, in_) => {
+  const issues = await client.listIssues(in_.project, in_.state);
+  return { issues, count: issues.length };
+});
+```
+
+`in_.project` 拼错是编译错误，不是线上的一次失败调用——代码里没有任何 `any`。
+
+## 装
+
+```bash
+npm install @sokel-dev/plugin-sdk
+go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest   # 生成器
+```
+
+`sokel-gen` 是个单文件二进制（Go 写的），只在**生成时**用到；跑插件时不需要它。
+
+## 四步
+
+```bash
+sokel-gen init -lang ts ./my-plugin
+cd my-plugin
+npm install
+sokel-gen generate .     # manifest.yml → src/sokel.gen.ts
+npm run build && npm start
+```
+
+1. **声明** —— `manifest.yml`：操作、事件、凭证、认证方式。格式见 [docs/manifest.md](../docs/manifest.md)。
+2. **生成** —— `sokel-gen generate .` 产出 `src/sokel.gen.ts`：每个操作一对 `XxxIn` / `XxxOut` 接口
+   和一个 `onXxx(p, fn)`；每个事件一个 payload 接口和一个 `triggerXxx(ctx, eventId, payload)`。
+3. **实现** —— handler 签名完全具体，返回值可以是对象也可以是 Promise。
+4. **连接** —— `await p.run()`。插件**出站**连平台：无入站端口、无公网 IP、无防火墙洞。
+
+## 为什么不是 zod
+
+zod schema 是运行时对象：用它声明契约意味着「契约只有跑起来才知道」，而且每种语言都得
+自己解释一遍那套 DSL。声明留在 `manifest.yml`，TS 这边只要类型——类型在编译期，运行时零开销。
+
+## 能力一览
+
+| 要做的事 | 怎么写 |
+|---|---|
+| 读凭证 | `ctx.credentialAs<Credential>()` |
+| 取入参文件的字节 | `await ctx.fetch(in_.file)` |
+| 产出文件 | `await ctx.upload(name, mime, bytes)` → 放进出参 |
+| 流式产出 | `out.text(...)` 逐帧给人看，`out.vars({...})` 给下游 |
+| 推事件 | `await triggerMessage(ctx, eventId, {...})` |
+| 常驻事件源 | `p.registerSource(id, label, fn)`，循环里判 `ctx.stopped` |
+| 平台代收 webhook | `p.registerWebhook(fn)`，返回 `ok()` / `text(401, "...")` |
+| 协作式认证 | `p.registerAuth({ start, poll, submit })` |
+| 会话型凭证刷新 | `await ctx.updateCredential({ session: "…" })` |
+| 自报运行态 | `ctx.reportStatus("auth_required", "…")` |
+
+## 配置
+
+SDK 读 `SOKEL_` 前缀的环境变量：
+
+| 变量 | 必填 | 含义 |
+|---|---|---|
+| `SOKEL_ENDPOINT` | 是 | `nats://broker:4222`，或 `https://` 平台地址（经 `/connect-info` 发现 broker） |
+| `SOKEL_TOKEN` | 是 | 接入组 token（`skp_…`），平台据此认「插件 + 工作空间」 |
+| `SOKEL_NATS_TOKEN` | 否 | broker 的传输层鉴权 |
+| `SOKEL_NATS_CA` | 否 | `tls://` broker 的自定义 CA |
+| `SOKEL_INSTANCE_ID` | 否 | 固定副本身份（默认按 token 指纹落盘复用） |
+| `SOKEL_REGION` | 否 | 副本的地域标注 |
+
+凭证从不由插件存储：平台随每次调用把解析后的字段下发下来。
+
+## 例子
+
+[`examples/kitchen-sink`](../examples/kitchen-sink) 覆盖了全部形态——每种字段、文件、流式、
+事件、webhook、协作式认证各一份，Node 与 Python 实现的是同一份声明。
+
+```bash
+cd examples/kitchen-sink/node
+npm install && npm run build
+SOKEL_ENDPOINT=nats://localhost:4222 SOKEL_TOKEN=skp_xxx npm start
+```
+
+## 开发本 SDK
+
+```bash
+pnpm install
+pnpm test        # tsc + node --test
+```
+
+## License
+
+Apache-2.0.

package/dist/src/auth.d.ts

@@ -1,27 +1,31 @@
 /**
- * 协作式凭证认证：有些凭证没法让人填——扫码、验证码回填、OAuth 同意页。
+ * Collaborative credential authentication: some credentials cannot be typed in by hand — a QR scan,
+ * a verification code, an OAuth consent page.
  *
- * 面板点「登录」→ start 拿挑战 →（扫码 / 回填）→ 2s 轮询 poll → confirmed。
+ * the panel's "log in" button -> start returns a challenge -> (scan / type it back)
+ * -> poll every 2s -> confirmed
  *
- * 形态写在 sokel.yaml 的 credential.auth 里（声明式），处理器挂在保留操作 id
- * auth.start / auth.poll / auth.submit 上——**不要**自己注册叫 auth_start 的业务操作：
- * 那三个名字从来不是保留字，任何插件的同名业务操作都会让面板的按钮凭空出现。
+ * The shape is declared in manifest.yml under credential.auth; the handlers hang off the reserved
+ * operation ids auth.start / auth.poll / auth.submit. **Do not** register a business operation named
+ * auth_start: those three names were never reserved, so any plugin with an operation of that name
+ * made the panel's button appear out of nowhere.
  */
 import type { Ctx } from "./runtime.js";
 export declare const PENDING = "pending";
 export declare const SCANNED = "scanned";
 export declare const CONFIRMED = "confirmed";
 export declare const EXPIRED = "expired";
-/** start 交出的挑战。面板按 kind 渲染：qr 画二维码，input 显示 prompt 与输入框。 */
+/** What start hands back. The panel renders by kind: qr draws a code, input shows the prompt. */
 export interface AuthChallenge {
     authId?: string;
     kind?: "qr" | "input";
-    /** data-uri 形态的二维码图片。 */
+    /** The QR image as a data-uri. */
     qrImage?: string;
     prompt?: string;
     expiresIn?: number;
 }
-/** poll 的结果。session 只在 confirmed 时带上——中途带出去等于让平台反复覆写凭证行。 */
+/** The result of poll. Carry `session` only once confirmed — handing it over earlier makes the
+ * platform rewrite the credential row again and again. */
 export interface AuthState {
     status: string;
     session?: Record<string, unknown>;

package/dist/src/auth.js

@@ -1,12 +1,5 @@
-/**
- * 协作式凭证认证：有些凭证没法让人填——扫码、验证码回填、OAuth 同意页。
- *
- * 面板点「登录」→ start 拿挑战 →（扫码 / 回填）→ 2s 轮询 poll → confirmed。
- *
- * 形态写在 sokel.yaml 的 credential.auth 里（声明式），处理器挂在保留操作 id
- * auth.start / auth.poll / auth.submit 上——**不要**自己注册叫 auth_start 的业务操作：
- * 那三个名字从来不是保留字，任何插件的同名业务操作都会让面板的按钮凭空出现。
- */
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 export const PENDING = "pending";
 export const SCANNED = "scanned";
 export const CONFIRMED = "confirmed";

package/dist/src/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAiBtC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC;AACjC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC"}

package/dist/src/contract.d.ts

@@ -1,10 +1,11 @@
 /**
- * 契约的运行时视图（线协议 §5）。
+ * The runtime view of a contract (wire protocol §5).
  *
- * 契约本身是**数据**：`sokel-gen` 从 sokel.yaml 生成一份 CONTRACT 常量，运行时只是查它、上报它。
- * 所以这里不重新定义一套 Field 校验器——那会变成契约的第二份定义，而两份定义迟早会漂。
+ * A contract is **data**: `sokel-gen` renders a CONTRACT constant from manifest.yml, and the runtime
+ * only looks things up in it and reports it. So there is no second Field validator here — that
+ * would be a second definition of the contract, and two definitions drift.
  */
-/** 一个入/出参字段（协议 §5 的 Field）。这里只声明形状，不做校验——校验在 sokel-gen。 */
+/** One input/output field (protocol §5's Field). Shape only; validation lives in sokel-gen. */
 export interface Field {
     name: string;
     label?: string;
@@ -36,6 +37,11 @@ export interface OperationSpec {
     stream?: boolean;
     internal?: boolean;
     timeoutSec?: number;
+    /** Which platform capability slot this operation fills ("rowstore.query" comes from
+     * `implements:` in manifest.yml). Absent on ordinary operations. It is reported as-is; the
+     * platform routes on it. Missing it here made every generated shell that declares `implements:`
+     * fail to compile. */
+    capability?: string;
     inputs: Field[];
     outputs: Field[];
 }
@@ -49,9 +55,12 @@ export interface AuthFlowSpec {
     kind: "qr" | "input" | "oauth";
     steps?: string[];
 }
-/** 生成物 CONTRACT 的形状。键名与注册载荷（协议 §3）同名，直接上报，不做转换。 */
+/** The shape of the generated CONTRACT. Keys match the registration payload (protocol §3)
+ * verbatim, so they are reported as-is with no translation step. */
 export interface ContractData {
     name?: string;
+    /** Publisher identity: `<org>/<name>` is how the plugin is addressed in the marketplace. */
+    org?: string;
     label?: string;
     desc?: string;
     version?: string;
@@ -65,16 +74,24 @@ export interface ContractData {
         scopes?: string[];
     };
     capabilities?: Record<string, boolean>;
+    /** Translations of the human-facing strings, keyed by locale then by the source string
+     * (`{"zh-CN": {"Row query": "按行查询"}}`). Generated from `locales/<lang>.json` next to the
+     * manifest; the platform renders whichever locale the viewer is in. */
+    locales?: Record<string, Record<string, string>>;
     doc?: string;
     doc_url?: string;
 }
-/** 保留操作 id（认证流）。带点号，业务 id 产生不出来（业务 id 限定 ^[a-z][a-z0-9_]*$）。 */
+/** Reserved operation ids (the auth flow).
+ *
+ * A **plain** business id cannot contain a dot (it must match ^[a-z][a-z0-9_]*$), but a capability
+ * slot's id does — `implements:` produces "rowstore.query" — so "has a dot" no longer means
+ * "reserved". Compare against these constants rather than looking for a dot. */
 export declare const OP_AUTH_START = "auth.start";
 export declare const OP_AUTH_POLL = "auth.poll";
 export declare const OP_AUTH_SUBMIT = "auth.submit";
-/** 平台代收 webhook 的特殊操作名（复用调用帧，见协议 §7b）。 */
+/** The special operation name for platform-relayed webhooks (it reuses the call frame, §7b). */
 export declare const OP_WEBHOOK = "__webhook__";
-/** 能力位：注册了 webhook 处理器就是支持，不靠作者手动声明。 */
+/** Capability bit: registering a webhook handler *is* the declaration; the author does not repeat it. */
 export declare const CAP_WEBHOOK = "webhook";
 export declare class Contract {
     readonly data: ContractData;
@@ -83,6 +100,7 @@ export declare class Contract {
     operation(id: string): OperationSpec | undefined;
     isStream(id: string): boolean;
     eventIds(): string[];
-    /** 契约部分的注册载荷。空值一律省略（协议：新字段一律 optional）。 */
+    /** The contract half of the registration payload. Empty values are omitted (the protocol makes
+     * every new field optional). */
     payload(): Record<string, unknown>;
 }

package/dist/src/contract.js

@@ -1,16 +1,16 @@
-/**
- * 契约的运行时视图（线协议 §5）。
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
+/** Reserved operation ids (the auth flow).
  *
- * 契约本身是**数据**：`sokel-gen` 从 sokel.yaml 生成一份 CONTRACT 常量，运行时只是查它、上报它。
- * 所以这里不重新定义一套 Field 校验器——那会变成契约的第二份定义，而两份定义迟早会漂。
- */
-/** 保留操作 id（认证流）。带点号，业务 id 产生不出来（业务 id 限定 ^[a-z][a-z0-9_]*$）。 */
+ * A **plain** business id cannot contain a dot (it must match ^[a-z][a-z0-9_]*$), but a capability
+ * slot's id does — `implements:` produces "rowstore.query" — so "has a dot" no longer means
+ * "reserved". Compare against these constants rather than looking for a dot. */
 export const OP_AUTH_START = "auth.start";
 export const OP_AUTH_POLL = "auth.poll";
 export const OP_AUTH_SUBMIT = "auth.submit";
-/** 平台代收 webhook 的特殊操作名（复用调用帧，见协议 §7b）。 */
+/** The special operation name for platform-relayed webhooks (it reuses the call frame, §7b). */
 export const OP_WEBHOOK = "__webhook__";
-/** 能力位：注册了 webhook 处理器就是支持，不靠作者手动声明。 */
+/** Capability bit: registering a webhook handler *is* the declaration; the author does not repeat it. */
 export const CAP_WEBHOOK = "webhook";
 export class Contract {
     data;
@@ -29,7 +29,8 @@ export class Contract {
     eventIds() {
         return (this.data.events ?? []).map((e) => e.id);
     }
-    /** 契约部分的注册载荷。空值一律省略（协议：新字段一律 optional）。 */
+    /** The contract half of the registration payload. Empty values are omitted (the protocol makes
+     * every new field optional). */
     payload() {
         const out = { operations: this.operations() };
         const d = this.data;

package/dist/src/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4DH,gEAAgE;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,0CAA0C;AAC1C,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AAExC,wCAAwC;AACxC,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,MAAM,OAAO,QAAQ;IACE;IAArB,YAAqB,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAE3C,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IACpC,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,2CAA2C;IAC3C,OAAO;QACL,MAAM,GAAG,GAA4B,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,CAAC,iBAAiB,EAAE,MAAM;YAAE,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAAC;QAC7E,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM;YAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,CAAC,CAAC,aAAa,EAAE,MAAM;YAAE,GAAG,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;QACjE,IAAI,CAAC,CAAC,SAAS;YAAE,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;QAC7C,IAAI,CAAC,CAAC,KAAK;YAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACjC,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;QAC5F,IAAI,CAAC,CAAC,GAAG;YAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,CAAC,OAAO;YAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QACvC,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAgFtC;;;;gFAIgF;AAChF,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAC;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AAExC,yGAAyG;AACzG,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,MAAM,OAAO,QAAQ;IACE;IAArB,YAAqB,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAE3C,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;IACpC,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IAED;oCACgC;IAChC,OAAO;QACL,MAAM,GAAG,GAA4B,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,CAAC,iBAAiB,EAAE,MAAM;YAAE,GAAG,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAAC;QAC7E,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM;YAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,CAAC,CAAC,aAAa,EAAE,MAAM;YAAE,GAAG,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;QACjE,IAAI,CAAC,CAAC,SAAS;YAAE,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;QAC7C,IAAI,CAAC,CAAC,KAAK;YAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACjC,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM;YAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;QAC5F,IAAI,CAAC,CAAC,GAAG;YAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;QAC3B,IAAI,CAAC,CAAC,OAAO;YAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QACvC,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/src/env.d.ts

@@ -1,8 +1,3 @@
-/**
- * 插件侧环境变量的统一读法：把 SOKEL_ 前缀收在一处（对齐 Go 侧 pluginenv）。
- *
- * 没有第二个前缀的兼容层——认第二个前缀省下的是一次重新部署，换来的是一个没人敢摘的包袱。
- */
-/** 读 SOKEL_<name>。name 不带前缀，如 env("TOKEN")。 */
+/** Read SOKEL_<name>. `name` carries no prefix, e.g. env("TOKEN"). */
 export declare function env(name: string): string;
 export declare function envOr(name: string, fallback: string): string;

package/dist/src/env.js

@@ -1,10 +1,13 @@
+// Copyright 2026 The Sokel Authors
+// SPDX-License-Identifier: Apache-2.0
 /**
- * 插件侧环境变量的统一读法：把 SOKEL_ 前缀收在一处（对齐 Go 侧 pluginenv）。
+ * One place to read the plugin's environment variables (mirrors pluginenv on the Go side).
  *
- * 没有第二个前缀的兼容层——认第二个前缀省下的是一次重新部署，换来的是一个没人敢摘的包袱。
+ * There is no compatibility layer for a second prefix: accepting one saves a single redeploy and
+ * buys a piece of history nobody dares remove.
  */
 const PREFIX = "SOKEL_";
-/** 读 SOKEL_<name>。name 不带前缀，如 env("TOKEN")。 */
+/** Read SOKEL_<name>. `name` carries no prefix, e.g. env("TOKEN"). */
 export function env(name) {
     return (process.env[PREFIX + name] ?? "").trim();
 }

package/dist/src/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB,+CAA+C;AAC/C,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,QAAgB;IAClD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC;;;;;GAKG;AAEH,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB,sEAAsE;AACtE,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,QAAgB;IAClD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC;AAC/B,CAAC"}

package/dist/src/events.d.ts

@@ -1,20 +1,22 @@
 /**
- * 事件源：插件主动把外部事件推给平台起 workflow（协议 §7）。
+ * Event sources: the plugin pushes external events to the platform to start workflows (protocol §7).
  *
- * 与操作的区别：操作是 request/reply（平台调插件），事件是 fire-and-forget（插件推平台）。
+ * How this differs from operations: an operation is request/reply (the platform calls the plugin);
+ * an event is fire-and-forget (the plugin pushes to the platform).
  *
- * 多 bot 单实例（协议 v1.3）：平台每次注册/心跳下发「分配给本副本的凭证子集」，
- * supervisor 按它 reconcile —— 每个凭证一套源实例，凭证被移除就取消，字段变了就重启。
+ * Many bots, one replica (protocol v1.3): every registration and heartbeat returns "the subset of
+ * credentials assigned to this replica", and the supervisor reconciles against it — one source
+ * instance per credential, cancelled when the credential goes away, restarted when its fields change.
  */
 import type { FileRuntime, SokelFile } from "./runtime.js";
 export declare const TRIGGER_SUBJECT = "sokel.trigger";
 export declare const CREDENTIAL_UPDATE_SUBJECT = "sokel.credential.update";
-/** 注册回包 credentials 列表项 —— 分配给本副本的一个 bot 身份。 */
+/** One entry of the registration reply's credentials list — a bot identity assigned here. */
 export declare class CredEntry {
     readonly id: string;
     readonly fields: Record<string, string>;
     constructor(id?: string, fields?: Record<string, string>);
-    /** 字段的稳定签名：reconcile 据此判定「字段变更 → 重启该源实例」。 */
+    /** A stable signature of the fields; reconcile uses it to decide "fields changed -> restart". */
     sig(): string;
 }
 export interface SourceState {
@@ -24,29 +26,32 @@ export interface SourceState {
     error?: string;
     since: string;
 }
-/** 源实例运行态（源 × 凭证）。随注册/心跳上报，面板据此展示每个 bot。 */
+/** Runtime state per source × credential. Reported with each registration/heartbeat so the panel
+ * can show every bot. */
 export declare class StateBoard {
     private readonly now;
     private readonly m;
     constructor(now?: () => string);
     set(sourceId: string, credId: string, status: string, error?: string): void;
     /**
-     * 只在该实例仍是 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: string, credId: string, status: string, error?: string): void;
     removeCred(credId: string): void;
     snapshot(): SourceState[];
 }
 export type Publish = (subject: string, data: Uint8Array) => void | Promise<void>;
-/** 常驻事件源 / webhook 的上下文：推事件、读凭证、回写凭证、上传附件、自报状态。 */
+/** The context for a long-running source or a webhook: push events, read and write back
+ * credentials, upload attachments, report state. */
 export declare class SourceCtx {
     readonly credential: Record<string, string>;
     readonly credentialId: string;
     readonly sourceId: string;
-    /** stopped：该源实例被 reconcile 停止时置真。长轮询循环 while (!ctx.stopped)。 */
+    /** Set to true when reconcile stops this instance. Long-poll loops run `while (!ctx.stopped)`. */
     stopped: boolean;
     private readonly token;
     private readonly publish;
@@ -63,33 +68,36 @@ export declare class SourceCtx {
         board?: StateBoard;
         files?: FileRuntime;
     });
-    /** 凭证按类型化形状读出（与操作侧 Ctx.credentialAs 同义）。 */
+    /** Read the credential into a typed shape (same as Ctx.credentialAs on the operation side). */
     credentialAs<T extends object>(): Partial<T>;
     /**
-     * 推一条事件（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).
      */
     trigger(event: string, eventId: string, payload: unknown): Promise<void>;
     /**
-     * 把 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.
      */
     updateCredential(patch: Record<string, string>): Promise<void>;
-    /** 自报运行态（如 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: string, msg?: string): void;
     upload(name: string, mime: string, data: Uint8Array): Promise<SokelFile>;
     fetch(f: SokelFile): Promise<Uint8Array>;
 }
-/** 一个常驻事件源。fn 在 SDK 起的任务里跑，内部用 ctx.trigger 推事件。 */
+/** A long-running event source. The SDK runs fn in its own task; inside, ctx.trigger pushes. */
 export interface Source {
     id: string;
     label: string;
     fn: (ctx: SourceCtx) => Promise<void>;
 }
-/** per-credential 源实例监督器：按平台下发的凭证集合起停/重启。 */
+/** Per-credential supervisor: starts, stops and restarts instances to match the assigned set. */
 export declare class SourceSupervisor {
     private readonly start;
     private readonly running;
@@ -97,5 +105,6 @@ export declare class SourceSupervisor {
     reconcile(desired: CredEntry[]): void;
     stopAll(): void;
 }
-/** 空（无凭证插件）→ 一个空凭证裸实例，与有凭证时同一条代码路径。 */
+/** Empty (a plugin with no credentials) becomes one bare instance, so both cases take the same
+ * code path. */
 export declare function desiredSourceCreds(creds: CredEntry[]): CredEntry[];