@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/tools/validate.js

@@ -0,0 +1,183 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { canonicalJson } from "./registry.js";
+/**
+ * 编译结果缓存的上限：超过后整体丢弃（工具定义每步从库里重新读出，缓存不能无限增长）。
+ * 缓存的是由定义推导出的只读数据，不是跨进程状态。
+ */
+const CACHE_MAX = 500;
+/** 不受信任的 schema（连接器工具，来自连接器）JSON 序列化后的字节上限：超过不编译、不校验。 */
+export const UNTRUSTED_SCHEMA_MAX_BYTES = 64 * 1024;
+/** 不受信任的 schema 的嵌套层数上限（对象 / 数组层数）：超过不编译、不校验。 */
+export const UNTRUSTED_SCHEMA_MAX_DEPTH = 32;
+/** 缓存键 → 编译结果（null = 不校验：无法编译或超限）。 */
+const compiled = new Map();
+/**
+ * 每个 schema 用自己的 Ajv 实例：不同工具的 schema 声明同一个 `$id` 时不会在共享实例里冲突
+ * （共享实例会报「schema with key or id already exists」，后者就校验不了）。
+ */
+const newAjv = () => new Ajv2020({ strict: false, allErrors: true });
+/** 值是「名字 → 子 schema」映射的关键字（键是属性名 / 定义名，不是关键字，不能按关键字剥）。 */
+const SCHEMA_MAPS = new Set(["properties", "$defs", "definitions", "dependentSchemas"]);
+/** 值是数据而不是 schema 的关键字：原样保留。 */
+const LITERALS = new Set(["enum", "const", "default", "examples", "required"]);
+/** 子 schema 处于否定 / 条件位置的关键字：在其中剥离约束不一定放宽，可能反而收紧（拒掉合法调用）。 */
+const NON_POSITIVE = new Set(["not", "oneOf", "if", "then", "else"]);
+/**
+ * 不受信任的 schema 去掉 Ajv 中有风险或不可控的部分：
+ * - `pattern`（正则可能灾难性回溯，拖住事件循环）、`format`（未知格式 / 昂贵校验）直接去掉；
+ * - `patternProperties` 去掉，并按 additionalProperties 语义放宽：原本 `additionalProperties: false` 时
+ *   额外属性须符合其中某个模式的 schema，原本是 schema 时与之取 anyOf，原本缺省 / true 时不变。
+ * 只在正向位置去掉约束才是放宽；在 `not` / `oneOf` / `if` / `then` / `else` 之下，或 schema 用了
+ * `unevaluatedProperties` / `unevaluatedItems`（剥 patternProperties 会改变「已评估」集合）时，
+ * 剥离可能收紧，调用方据 {@link SanitizeState} 放弃校验。
+ */
+function sanitize(node, state, nonPositive = false) {
+    if (Array.isArray(node))
+        return node.map((x) => sanitize(x, state, nonPositive));
+    if (node === null || typeof node !== "object")
+        return node;
+    const src = node;
+    const out = {};
+    for (const [k, v] of Object.entries(src)) {
+        if (k === "pattern" || k === "format" || k === "patternProperties") {
+            state.stripped = true;
+            if (nonPositive)
+                state.strippedNonPositive = true;
+            continue;
+        }
+        if (k === "unevaluatedProperties" || k === "unevaluatedItems")
+            state.unevaluated = true;
+        const childNeg = nonPositive || NON_POSITIVE.has(k);
+        if (LITERALS.has(k))
+            out[k] = v;
+        else if (SCHEMA_MAPS.has(k) && v !== null && typeof v === "object" && !Array.isArray(v)) {
+            out[k] = Object.fromEntries(Object.entries(v).map(([name, sub]) => [name, sanitize(sub, state, childNeg)]));
+        }
+        else
+            out[k] = sanitize(v, state, childNeg);
+    }
+    const pp = src.patternProperties;
+    if (pp !== null && typeof pp === "object" && !Array.isArray(pp)) {
+        const subs = Object.values(pp).map((x) => sanitize(x, state, nonPositive));
+        const ap = src.additionalProperties;
+        if (subs.length > 0 && ap === false)
+            out.additionalProperties = { anyOf: subs };
+        else if (subs.length > 0 && ap !== undefined && ap !== true) {
+            out.additionalProperties = { anyOf: [out.additionalProperties, ...subs] };
+        }
+    }
+    return out;
+}
+/** 剥离后的 schema；剥离不能保证只放宽时返回跳过原因。 */
+function sanitizeOrSkip(schema) {
+    const state = { stripped: false, strippedNonPositive: false, unevaluated: false };
+    const out = sanitize(schema, state);
+    if (state.strippedNonPositive) {
+        return { skip: "constraints stripped under not/oneOf/if/then/else" };
+    }
+    if (state.stripped && state.unevaluated) {
+        return {
+            skip: "constraints stripped in a schema using unevaluatedProperties/unevaluatedItems",
+        };
+    }
+    return { schema: out };
+}
+/** 嵌套层数（对象 / 数组），超过 `limit` 即停止计算并返回 `limit + 1`。 */
+function depthOf(v, limit, d = 0) {
+    if (d > limit || v === null || typeof v !== "object")
+        return d;
+    let max = d + 1;
+    for (const x of Array.isArray(v) ? v : Object.values(v)) {
+        max = Math.max(max, depthOf(x, limit, d + 1));
+        if (max > limit)
+            return max;
+    }
+    return max;
+}
+/** 不受信任的 schema 超限的原因；不超限为 null。 */
+function limitIssue(schema) {
+    let bytes;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(schema), "utf8");
+    }
+    catch {
+        return "schema is not serializable";
+    }
+    if (bytes > UNTRUSTED_SCHEMA_MAX_BYTES) {
+        return `schema larger than ${UNTRUSTED_SCHEMA_MAX_BYTES} bytes`;
+    }
+    if (depthOf(schema, UNTRUSTED_SCHEMA_MAX_DEPTH) > UNTRUSTED_SCHEMA_MAX_DEPTH) {
+        return `schema nested deeper than ${UNTRUSTED_SCHEMA_MAX_DEPTH} levels`;
+    }
+    return null;
+}
+function remember(key, fn) {
+    if (compiled.size >= CACHE_MAX)
+        compiled.clear();
+    compiled.set(key, fn);
+    return fn;
+}
+/**
+ * 编译工具的 inputSchema；去掉 `$schema`（MCP 服务常声明 draft-07，Ajv 2020 实例不认它的元 schema）。
+ * 不受信任的先查大小 / 层数（超限 → null，记一次 warn），再 {@link sanitize}
+ * （剥离不能保证只放宽 → null，记一次 warn）。
+ * 定义本身无法编译 → null（不拦截调用，交给工具自己校验），按缓存键只 warn 一次（缓存命中不再记）。
+ */
+function compile(toolKey, schema, untrusted, log) {
+    const { $schema: _ignored, ...rest } = schema;
+    const raw = `${untrusted ? "u" : "t"}:${canonicalJson(rest)}`;
+    if (compiled.has(raw))
+        return compiled.get(raw) ?? null;
+    if (untrusted) {
+        const issue = limitIssue(rest);
+        if (issue !== null) {
+            log?.warn("tool input schema not validated", { toolKey, reason: issue });
+            return remember(raw, null);
+        }
+    }
+    let target = rest;
+    if (untrusted) {
+        const r = sanitizeOrSkip(rest);
+        if ("skip" in r) {
+            log?.warn("tool input schema not validated", { toolKey, reason: r.skip });
+            return remember(raw, null);
+        }
+        target = r.schema;
+    }
+    let fn;
+    try {
+        fn = newAjv().compile(target);
+    }
+    catch (err) {
+        log?.warn("tool input schema failed to compile; validation skipped", {
+            toolKey,
+            reason: err instanceof Error ? err.message.slice(0, 200) : String(err),
+        });
+        fn = null;
+    }
+    return remember(raw, fn);
+}
+function describe(e) {
+    const at = e.instancePath === "" ? "/" : e.instancePath;
+    let msg = `${at} ${e.message ?? "is invalid"}`;
+    const p = e.params;
+    if (e.keyword === "additionalProperties" && typeof p.additionalProperty === "string") {
+        msg += ` (${p.additionalProperty})`;
+    }
+    else if (e.keyword === "enum" && Array.isArray(p.allowedValues)) {
+        msg += ` ${JSON.stringify(p.allowedValues)}`;
+    }
+    return msg;
+}
+/**
+ * 管线第 2 阶段：按工具的 inputSchema 校验参数（ajv，JSON Schema 2020-12，`strict: false`，`allErrors: true`）。
+ * 合法 → null；不合法 → 给模型的英文说明：全部错误路径 + 完整 inputSchema（spec 6.3「给事实，不猜」）。
+ * schema 自身无法编译或超限时不拦截（返回 null）。
+ */
+export function validateInput(key, spec, input, opts = {}) {
+    const fn = compile(key, spec.inputSchema, opts.untrusted === true, opts.log);
+    if (!fn || fn(input))
+        return null;
+    const errors = (fn.errors ?? []).map(describe);
+    return `Invalid arguments for ${key}: ${errors.join("; ")}\nInput schema: ${JSON.stringify(spec.inputSchema)}`;
+}

package/dist/tools/view.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Structured tool views (UI refresh B, spec §5.5 / §5.9): the line diff behind the `edit` view of
+ * `tool_result.view`. Display only: the view is never sent to the model.
+ */
+/** At most this many diff lines (context + added + removed) go into one view. */
+export declare const TOOL_VIEW_DIFF_MAX_LINES = 2000;
+/** A diff line longer than this is cut (the `tool_result.view` schema limit). */
+export declare const TOOL_VIEW_LINE_MAX_CHARS = 2000;
+/** Above this size (bytes, either side) no hunks are computed, only counts. */
+export declare const TOOL_VIEW_DIFF_MAX_BYTES: number;
+/**
+ * The most diff text (UTF-8 bytes, all lines together) one view carries; beyond it the rest is left
+ * out with `truncated: true`. The view sits in an event row that every events fetch re-reads.
+ */
+export declare const TOOL_VIEW_DIFF_MAX_TEXT_BYTES: number;
+export interface DiffLine {
+    kind: "ctx" | "add" | "del";
+    text: string;
+}
+export interface Hunk {
+    /** First old line of the hunk (1-based; 0 when the hunk has no old lines, as in unified diffs). */
+    oldStart: number;
+    /** First new line of the hunk (1-based; 0 when the hunk has no new lines). */
+    newStart: number;
+    lines: DiffLine[];
+}
+export interface LineDiff {
+    hunks: Hunk[];
+    added: number;
+    removed: number;
+    /** Hunks were left out (the line cap) or not computed (a side over 1 MB). */
+    truncated: boolean;
+}
+/**
+ * The line diff from `before` to `after` as unified-diff hunks with `context` lines around each
+ * change. Output is capped at {@link TOOL_VIEW_DIFF_MAX_LINES} lines (`truncated: true` beyond);
+ * when either side is over 1 MB no hunks are computed and the counts come from comparing line sets.
+ */
+export declare function lineDiff(before: string, after: string, context?: number): LineDiff;
+/** The longest path in a view (the `tool_result.view` schema limit, UTF-16 units). */
+export declare const TOOL_VIEW_PATH_MAX_CHARS = 1024;
+/** A path cut to fit a view (kept whole when it fits; the row shows it as given). */
+export declare function viewPath(path: string): string;

package/dist/tools/view.js

@@ -0,0 +1,225 @@
+/**
+ * Structured tool views (UI refresh B, spec §5.5 / §5.9): the line diff behind the `edit` view of
+ * `tool_result.view`. Display only: the view is never sent to the model.
+ */
+/** At most this many diff lines (context + added + removed) go into one view. */
+export const TOOL_VIEW_DIFF_MAX_LINES = 2000;
+/** A diff line longer than this is cut (the `tool_result.view` schema limit). */
+export const TOOL_VIEW_LINE_MAX_CHARS = 2000;
+/** Above this size (bytes, either side) no hunks are computed, only counts. */
+export const TOOL_VIEW_DIFF_MAX_BYTES = 1024 * 1024;
+/**
+ * The most diff text (UTF-8 bytes, all lines together) one view carries; beyond it the rest is left
+ * out with `truncated: true`. The view sits in an event row that every events fetch re-reads.
+ */
+export const TOOL_VIEW_DIFF_MAX_TEXT_BYTES = 256 * 1024;
+/**
+ * The most edits the Myers search looks for in the part that differs; beyond it the part is shown as
+ * removed then added (still a correct diff, just not minimal), so time and memory stay bounded.
+ */
+const MAX_EDITS = 1000;
+/** Lines of a text; a final newline does not start another line. */
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+const byteLength = (s) => Buffer.byteLength(s, "utf8");
+/** Added / removed counts by comparing the line multisets (no alignment). */
+function countOnly(a, b) {
+    const left = new Map();
+    for (const l of a)
+        left.set(l, (left.get(l) ?? 0) + 1);
+    let added = 0;
+    for (const l of b) {
+        const n = left.get(l) ?? 0;
+        if (n > 0)
+            left.set(l, n - 1);
+        else
+            added++;
+    }
+    let removed = 0;
+    for (const n of left.values())
+        removed += n;
+    return { added, removed };
+}
+/**
+ * Myers' O(ND) edit script between `a` and `b` (both already stripped of their common prefix and
+ * suffix): the list of operations in order. Null when more than {@link MAX_EDITS} edits are needed.
+ */
+function myers(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = Math.min(n + m, MAX_EDITS);
+    const offset = max + 1;
+    let v = new Int32Array(2 * max + 3);
+    const trace = [];
+    for (let d = 0; d <= max; d++) {
+        trace.push(v);
+        const next = v.slice();
+        for (let k = -d; k <= d; k += 2) {
+            let x;
+            if (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])) {
+                x = v[offset + k + 1];
+            }
+            else {
+                x = v[offset + k - 1] + 1;
+            }
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            next[offset + k] = x;
+            if (x >= n && y >= m)
+                return backtrack(trace, d, n, m, offset);
+        }
+        v = next;
+    }
+    return null;
+}
+function backtrack(trace, dEnd, n, m, offset) {
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = dEnd; d > 0; d--) {
+        const v = trace[d];
+        const k = x - y;
+        const down = k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]);
+        const prevK = down ? k + 1 : k - 1;
+        const prevX = v[offset + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push("ctx");
+            x--;
+            y--;
+        }
+        ops.push(down ? "add" : "del");
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        ops.push("ctx");
+        x--;
+        y--;
+    }
+    return ops.reverse();
+}
+/** A diff line as the view keeps it: cut to the schema limit, NUL as U+FFFD (jsonb rejects it). */
+const cut = (s) => (s.length > TOOL_VIEW_LINE_MAX_CHARS ? s.slice(0, TOOL_VIEW_LINE_MAX_CHARS) : s).replaceAll("\0", "\uFFFD");
+/**
+ * The line diff from `before` to `after` as unified-diff hunks with `context` lines around each
+ * change. Output is capped at {@link TOOL_VIEW_DIFF_MAX_LINES} lines (`truncated: true` beyond);
+ * when either side is over 1 MB no hunks are computed and the counts come from comparing line sets.
+ */
+export function lineDiff(before, after, context = 3) {
+    const a = splitLines(before);
+    const b = splitLines(after);
+    if (byteLength(before) > TOOL_VIEW_DIFF_MAX_BYTES ||
+        byteLength(after) > TOOL_VIEW_DIFF_MAX_BYTES) {
+        return { hunks: [], ...countOnly(a, b), truncated: true };
+    }
+    // common prefix and suffix first: most edits change one small region
+    let pre = 0;
+    while (pre < a.length && pre < b.length && a[pre] === b[pre])
+        pre++;
+    let suf = 0;
+    while (suf < a.length - pre &&
+        suf < b.length - pre &&
+        a[a.length - 1 - suf] === b[b.length - 1 - suf]) {
+        suf++;
+    }
+    const midA = a.slice(pre, a.length - suf);
+    const midB = b.slice(pre, b.length - suf);
+    const mid = myers(midA, midB) ?? [
+        ...midA.map(() => "del"),
+        ...midB.map(() => "add"),
+    ];
+    const ops = [
+        ...Array(pre).fill("ctx"),
+        ...mid,
+        ...Array(suf).fill("ctx"),
+    ];
+    const all = [];
+    let ai = 0;
+    let bi = 0;
+    let added = 0;
+    let removed = 0;
+    for (const kind of ops) {
+        all.push({ kind, ai, bi });
+        if (kind === "ctx") {
+            ai++;
+            bi++;
+        }
+        else if (kind === "del") {
+            ai++;
+            removed++;
+        }
+        else {
+            bi++;
+            added++;
+        }
+    }
+    // group changes into hunks: a change starts or extends a hunk when within 2 * context of the last
+    const ranges = [];
+    for (let i = 0; i < all.length; i++) {
+        if (all[i].kind === "ctx")
+            continue;
+        const start = Math.max(0, i - context);
+        const end = Math.min(all.length, i + context + 1);
+        const lastRange = ranges.at(-1);
+        if (lastRange && start <= lastRange[1])
+            lastRange[1] = end;
+        else
+            ranges.push([start, end]);
+    }
+    const hunks = [];
+    let emitted = 0;
+    let textBytes = 0;
+    let truncated = false;
+    for (const [start, end] of ranges) {
+        if (emitted >= TOOL_VIEW_DIFF_MAX_LINES || textBytes >= TOOL_VIEW_DIFF_MAX_TEXT_BYTES) {
+            truncated = true;
+            break;
+        }
+        const slice = all.slice(start, end);
+        const room = TOOL_VIEW_DIFF_MAX_LINES - emitted;
+        const lines = [];
+        let first;
+        for (const o of slice.length > room ? slice.slice(0, room) : slice) {
+            const text = cut((o.kind === "add" ? b[o.bi] : a[o.ai]));
+            const size = byteLength(text);
+            if (textBytes + size > TOOL_VIEW_DIFF_MAX_TEXT_BYTES)
+                break;
+            textBytes += size;
+            first ??= o;
+            lines.push({ kind: o.kind, text });
+        }
+        if (lines.length < slice.length)
+            truncated = true;
+        if (first === undefined)
+            break;
+        const hasOld = lines.some((l) => l.kind !== "add");
+        const hasNew = lines.some((l) => l.kind !== "del");
+        hunks.push({
+            oldStart: hasOld ? first.ai + 1 : first.ai,
+            newStart: hasNew ? first.bi + 1 : first.bi,
+            lines,
+        });
+        emitted += lines.length;
+    }
+    return { hunks, added, removed, truncated };
+}
+/** The longest path in a view (the `tool_result.view` schema limit, UTF-16 units). */
+export const TOOL_VIEW_PATH_MAX_CHARS = 1024;
+/** A path cut to fit a view (kept whole when it fits; the row shows it as given). */
+export function viewPath(path) {
+    if (path.length <= TOOL_VIEW_PATH_MAX_CHARS)
+        return path;
+    const head = path.slice(0, TOOL_VIEW_PATH_MAX_CHARS - 1);
+    // never end on half a surrogate pair
+    return `${/[\uD800-\uDBFF]$/.test(head) ? head.slice(0, -1) : head}…`;
+}

package/dist/ui/embed-token.d.ts

@@ -0,0 +1,31 @@
+import type { EmbedClaims } from "@capybara-hq/plugin-sdk";
+import type { Keyring } from "../ctx/secrets.js";
+/** 嵌入令牌的有效期（秒）。网页在过期前 60 秒续期。 */
+export declare const EMBED_TOKEN_TTL_SECONDS = 300;
+/** 校验 `exp` 时容许的副本间时钟偏差（秒）。 */
+export declare const EMBED_TOKEN_SKEW_SECONDS = 30;
+/** HKDF 用途（keyring 派生时 info 为 `capybara:capybara-embed/1`），也是签名输入的域前缀。 */
+export declare const EMBED_KEY_INFO = "capybara-embed/1";
+/**
+ * 嵌入令牌：`base64url(JSON 声明).base64url(HMAC-SHA256(key, "capybara-embed/1." + 第一段))`。
+ * - 格式固定、没有头（没有 alg 可混淆）；密钥由主密钥环经 HKDF 派生，轮换后上一把主密钥签的令牌仍可校验到过期；
+ * - 校验：严格 base64url、常量时间比较签名、逐字段核对声明、`exp` 容许 {@link EMBED_TOKEN_SKEW_SECONDS} 秒偏差、
+ *   `exp` 不得超过「现在 + 有效期 + 偏差」、`plugin` 必须是调用方插件；任何一项不过都返回 null（不说明原因）。
+ * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。
+ */
+export declare class EmbedTokens {
+    private readonly current;
+    private readonly keys;
+    private readonly now;
+    constructor(keyring: Keyring, opts?: {
+        now?: () => number;
+    });
+    /** 签发：`exp` = 现在 + {@link EMBED_TOKEN_TTL_SECONDS}。 */
+    issue(c: Omit<EmbedClaims, "exp">): {
+        token: string;
+        claims: EmbedClaims;
+        expiresAt: Date;
+    };
+    /** 校验令牌并要求它签给 `plugin`；不通过返回 null。 */
+    verify(token: unknown, plugin: string): EmbedClaims | null;
+}

package/dist/ui/embed-token.js

@@ -0,0 +1,132 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { ORG_ROLES } from "../orgs/roles.js";
+/** 嵌入令牌的有效期（秒）。网页在过期前 60 秒续期。 */
+export const EMBED_TOKEN_TTL_SECONDS = 300;
+/** 校验 `exp` 时容许的副本间时钟偏差（秒）。 */
+export const EMBED_TOKEN_SKEW_SECONDS = 30;
+/** HKDF 用途（keyring 派生时 info 为 `capybara:capybara-embed/1`），也是签名输入的域前缀。 */
+export const EMBED_KEY_INFO = "capybara-embed/1";
+/** 令牌总长上限：声明有界（id ≤ 100 字符），远小于此。 */
+const TOKEN_MAX = 2048;
+const MAC_LEN = 32;
+const B64URL = /^[A-Za-z0-9_-]+$/;
+const PLUGIN_RE = /^[a-z][a-z0-9-]{1,40}$/;
+const CLAIM_KEYS = new Set([
+    "plugin",
+    "orgId",
+    "accountId",
+    "role",
+    "conversationId",
+    "fileId",
+    "contribution",
+    "exp",
+]);
+const ROLES = new Set(ORG_ROLES);
+const isId = (v) => typeof v === "string" && v !== "" && v.length <= 100;
+/**
+ * 严格解码 base64url：只允许字母表内字符、不带填充，且必须是规范编码（解码后再编码与原文相同），
+ * 同一份字节只有一种写法。
+ */
+function decodeStrict(s) {
+    if (!B64URL.test(s))
+        return null;
+    const buf = Buffer.from(s, "base64url");
+    return buf.toString("base64url") === s ? buf : null;
+}
+/** 逐字段核对声明：只认已知字段、类型正确，返回只含已知字段的新对象。 */
+function parseClaims(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return null;
+    const c = v;
+    if (Object.keys(c).some((k) => !CLAIM_KEYS.has(k)))
+        return null;
+    if (typeof c.plugin !== "string" || !PLUGIN_RE.test(c.plugin))
+        return null;
+    if (!isId(c.orgId) || !isId(c.accountId) || !isId(c.contribution))
+        return null;
+    if (!ROLES.has(c.role))
+        return null;
+    if (c.conversationId !== undefined && !isId(c.conversationId))
+        return null;
+    if (c.fileId !== undefined && (!isId(c.fileId) || c.conversationId === undefined))
+        return null;
+    if (typeof c.exp !== "number" || !Number.isSafeInteger(c.exp))
+        return null;
+    return {
+        plugin: c.plugin,
+        orgId: c.orgId,
+        accountId: c.accountId,
+        role: c.role,
+        ...(c.conversationId !== undefined && { conversationId: c.conversationId }),
+        ...(c.fileId !== undefined && { fileId: c.fileId }),
+        contribution: c.contribution,
+        exp: c.exp,
+    };
+}
+/**
+ * 嵌入令牌：`base64url(JSON 声明).base64url(HMAC-SHA256(key, "capybara-embed/1." + 第一段))`。
+ * - 格式固定、没有头（没有 alg 可混淆）；密钥由主密钥环经 HKDF 派生，轮换后上一把主密钥签的令牌仍可校验到过期；
+ * - 校验：严格 base64url、常量时间比较签名、逐字段核对声明、`exp` 容许 {@link EMBED_TOKEN_SKEW_SECONDS} 秒偏差、
+ *   `exp` 不得超过「现在 + 有效期 + 偏差」、`plugin` 必须是调用方插件；任何一项不过都返回 null（不说明原因）。
+ * 无状态（不落库、不进 Redis）：各副本用同一主密钥即可校验，不需要共享状态。
+ */
+export class EmbedTokens {
+    current;
+    keys;
+    now;
+    constructor(keyring, opts = {}) {
+        const derived = keyring.deriveKey(EMBED_KEY_INFO);
+        const ids = [derived.currentId, ...keyring.toJSON().previousIds];
+        this.current = derived.current;
+        this.keys = ids.map((id) => derived.byId(id)).filter((k) => k !== undefined);
+        this.now = opts.now ?? Date.now;
+    }
+    /** 签发：`exp` = 现在 + {@link EMBED_TOKEN_TTL_SECONDS}。 */
+    issue(c) {
+        const exp = Math.floor(this.now() / 1000) + EMBED_TOKEN_TTL_SECONDS;
+        const claims = parseClaims({ ...c, exp });
+        if (claims === null)
+            throw new Error("embed token claims are invalid");
+        const payload = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
+        const token = `${payload}.${mac(this.current, payload).toString("base64url")}`;
+        return { token, claims, expiresAt: new Date(exp * 1000) };
+    }
+    /** 校验令牌并要求它签给 `plugin`；不通过返回 null。 */
+    verify(token, plugin) {
+        if (typeof token !== "string" || token.length > TOKEN_MAX)
+            return null;
+        const dot = token.indexOf(".");
+        if (dot <= 0 || dot !== token.lastIndexOf("."))
+            return null;
+        const payload = token.slice(0, dot);
+        const sig = decodeStrict(token.slice(dot + 1));
+        const body = decodeStrict(payload);
+        if (sig === null || body === null || sig.length !== MAC_LEN)
+            return null;
+        // 每把候选密钥都算一遍、常量时间比较（不因第一把匹配就提前返回）
+        let ok = false;
+        for (const key of this.keys)
+            ok = timingSafeEqual(mac(key, payload), sig) || ok;
+        if (!ok)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(body.toString("utf8"));
+        }
+        catch {
+            return null;
+        }
+        const claims = parseClaims(parsed);
+        if (claims === null || claims.plugin !== plugin)
+            return null;
+        const nowSec = this.now() / 1000;
+        if (claims.exp + EMBED_TOKEN_SKEW_SECONDS <= nowSec)
+            return null;
+        if (claims.exp > nowSec + EMBED_TOKEN_TTL_SECONDS + EMBED_TOKEN_SKEW_SECONDS)
+            return null;
+        return claims;
+    }
+}
+function mac(key, payload) {
+    return createHmac("sha256", key).update(`${EMBED_KEY_INFO}.${payload}`).digest();
+}

package/dist/ui/registry.d.ts

@@ -0,0 +1,58 @@
+import type { ExtensionManifest, UiActionArgs, UiActionResult, UiContribution, UiRenderArgs, UiView } from "@capybara-hq/plugin-sdk";
+import { type OrgRole } from "../orgs/roles.js";
+/** 会话 id 的格式（UUID）。 */
+export declare const UUID_RE: RegExp;
+/** 组织页面（`place: "page"`）所需的最低角色（A38）：guest 只用对话位置的贡献。 */
+export declare const PAGE_MIN_ROLE: OrgRole;
+/** Places on the conversation page (everything but an org page): they need a `conversationId`. */
+export declare const isConversationPlace: (place: UiContribution["place"]) => boolean;
+/** 该角色能否使用这个位置的贡献。 */
+export declare const canUsePlace: (place: UiContribution["place"], role: OrgRole) => boolean;
+/** 插件视图的 render 函数（`ctx.ui.view` 注册）。 */
+export type UiRender = (args: UiRenderArgs) => Promise<UiView>;
+/** 插件视图的动作处理函数（`ctx.ui.action` 注册）。 */
+export type UiActionHandler = (args: UiActionArgs) => Promise<UiActionResult>;
+/**
+ * 组织级界面刷新的内核 bus 主题（命名空间 `kernel`）：`org-ui.<orgId>`。
+ * 对话视图的刷新走会话主题 `conv.<id>`（与事件、增量共用），见 `conversationTopic`。
+ */
+export declare const orgUiTopic: (orgId: string) => string;
+/** 界面刷新消息：`conv.<id>` 与 `org-ui.<orgId>` 上的 `{ kind: "ui", plugin, contribution }`。 */
+export interface UiBusMessage {
+    kind: "ui";
+    plugin: string;
+    contribution: string;
+}
+/** 是否为界面刷新消息（bus 上的消息来自其他副本，按形状核对）。 */
+export declare function isUiBusMessage(m: unknown): m is UiBusMessage;
+/** SSE 帧 `event: ui`，数据 `{ plugin, contribution }`。 */
+export declare const uiFrame: (m: UiBusMessage) => string;
+/**
+ * 单个插件在 setup 期间注册的视图与动作：进程内的静态登记（同 `ctx.tools.register`），
+ * 不是跨请求的共享状态——各副本加载同一插件得到同样的登记。
+ * id 必须是 `permissions.ui.views` 里的（与清单 `ui` 里 kind view 的贡献一一对应，`defineExtension` 已交叉核对）。
+ */
+export declare class PluginUiRegistration {
+    private readonly manifest;
+    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    private readonly deny;
+    readonly views: Map<string, UiRender>;
+    readonly actions: Map<string, UiActionHandler>;
+    private readonly declaredViews;
+    private readonly contributions;
+    private sealed;
+    constructor(manifest: ExtensionManifest, 
+    /** 越权（id 未在 `permissions.ui.views` 声明）：抛 ExtensionPermissionError 并写审计。 */
+    deny: (item: string) => never);
+    /** setup 结束后调用：此后 view / action 抛错。 */
+    seal(): void;
+    view(id: string, render: UiRender): void;
+    action(id: string, handler: UiActionHandler): void;
+    /** 校验 invalidate 的目标，返回规范化后的 `{ orgId, conversationId?, contribution }`。 */
+    target(t: unknown): {
+        orgId: string;
+        conversationId?: string;
+        contribution: string;
+    };
+    private register;
+}