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

package/dist/catalog/schema-path.js

@@ -0,0 +1,63 @@
+/** 不改变形状的包装（剥掉后看内层）。 */
+const WRAPPERS = new Set([
+    "optional",
+    "nullable",
+    "default",
+    "prefault",
+    "readonly",
+    "catch",
+    "nonoptional",
+    "success",
+]);
+const defOf = (s) => s._zod.def;
+function unwrap(s, depth) {
+    let node = s;
+    for (let i = 0; i < 50; i++) {
+        const d = defOf(node);
+        if (WRAPPERS.has(d.type) && d.innerType)
+            node = d.innerType;
+        else if (d.type === "pipe" && d.in)
+            node = d.in;
+        else if (d.type === "lazy" && d.getter && depth < 20)
+            node = d.getter();
+        else
+            return node;
+    }
+    return undefined;
+}
+/**
+ * zod schema（v4）里是否有点路径 `segs` 指向的字段（连接器模板的 `editableEndpoint` 用）：对象按 shape（或非 never 的
+ * catchall）、记录类型的任意键、union / 交叉的任一分支；包装（optional、default、pipe 的输入端等）剥掉再看。
+ * 空路径即 schema 本身，恒为 true。叶子之下还有路径 → false。
+ */
+export function schemaHasPath(schema, segs, depth = 0) {
+    if (depth > 40)
+        return false;
+    const node = unwrap(schema, depth);
+    if (!node)
+        return false;
+    if (segs.length === 0)
+        return true;
+    const [head, ...rest] = segs;
+    const d = defOf(node);
+    switch (d.type) {
+        case "object": {
+            const child = d.shape && Object.hasOwn(d.shape, head) ? d.shape[head] : undefined;
+            if (child)
+                return schemaHasPath(child, rest, depth + 1);
+            if (d.catchall && defOf(d.catchall).type !== "never") {
+                return schemaHasPath(d.catchall, rest, depth + 1);
+            }
+            return false;
+        }
+        case "record":
+            return d.valueType ? schemaHasPath(d.valueType, rest, depth + 1) : false;
+        case "union":
+            return (d.options ?? []).some((o) => schemaHasPath(o, segs, depth + 1));
+        case "intersection":
+            return ((d.left !== undefined && schemaHasPath(d.left, segs, depth + 1)) ||
+                (d.right !== undefined && schemaHasPath(d.right, segs, depth + 1)));
+        default:
+            return false;
+    }
+}

package/dist/catalog/upgrade-targets.d.ts

@@ -0,0 +1,59 @@
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+type Trx = Transaction<KernelDatabase>;
+/**
+ * Which versions an org may upgrade an installed plugin to (package ecosystem spec §10, Decision
+ * 10, Ruling 8):
+ * - a plugin with an extension follows the deployment: the only target is the catalog version
+ *   whose extension package (sha256) is the one installed on the deployment, the newest import on
+ *   ties (`1.0.0` and `1.0.0+sha256.x` can share an extension version with different bytes); an
+ *   extension loaded from the startup config (config, no package) is matched by its
+ *   version;
+ * - a purely declarative plugin may move to any other imported version (an older one is a
+ *   rollback).
+ */
+/** The extension the deployment runs for a plugin name. */
+export interface DeployedExtension {
+    /** The installed package's sha256 (null for a config extension). */
+    sha256: string | null;
+    version: string;
+}
+/** A catalog version row as the target rules read it. */
+export interface TargetVersion {
+    version: string;
+    manifest: unknown;
+    extension_sha256: string | null;
+    imported_at: Date;
+}
+/**
+ * The deployment's extension for plugin `name`: its install record (`extension_installs`, the
+ * deployment's desired package; disabled on the deployment counts as none), else the extension
+ * this replica loaded from the startup config; undefined when the deployment runs none (then no
+ * upgrade target and no "upgrade pending").
+ */
+export declare function deployedExtension(db: KernelDb | Trx, host: Pick<ExtensionHost, "manifests">, name: string): Promise<DeployedExtension | undefined>;
+/** Whether catalog version `v` carries the deployment's extension `d`. */
+export declare const runsDeployed: (v: TargetVersion, d: DeployedExtension) => boolean;
+/**
+ * The catalog version an org install of an extension-bearing plugin may move to: the one carrying
+ * the deployment's extension, the newest import on ties; undefined when none does.
+ */
+export declare function deploymentTarget(versions: readonly TargetVersion[], d: DeployedExtension | undefined): TargetVersion | undefined;
+/** What an install view says about upgrades (Decision 10). */
+export interface UpgradeInfo {
+    /** The version an upgrade can move to now (the highest allowed target), null when none. */
+    upgradeAvailable: string | null;
+    /** An extension-bearing plugin whose org version is not the one the deployment runs. */
+    deploymentPending: boolean;
+}
+/**
+ * The upgrade info of org installs (`itemId`, `name`, `version`), keyed by `itemId@version`; reads
+ * the items' catalog versions and the deployment's extensions in a few queries.
+ */
+export declare function upgradeInfo(db: KernelDb, host: Pick<ExtensionHost, "manifests">, installs: readonly {
+    itemId: string;
+    name: string;
+    version: string;
+}[]): Promise<Map<string, UpgradeInfo>>;
+export {};

package/dist/catalog/upgrade-targets.js

@@ -0,0 +1,90 @@
+import { compareVersions } from "./versions.js";
+/**
+ * The deployment's extension for plugin `name`: its install record (`extension_installs`, the
+ * deployment's desired package; disabled on the deployment counts as none), else the extension
+ * this replica loaded from the startup config; undefined when the deployment runs none (then no
+ * upgrade target and no "upgrade pending").
+ */
+export async function deployedExtension(db, host, name) {
+    const row = await db
+        .selectFrom("extension_installs")
+        .select(["sha256", "version", "desired_state"])
+        .where("name", "=", name)
+        .executeTakeFirst();
+    if (row) {
+        return row.desired_state === "enabled"
+            ? { sha256: row.sha256, version: row.version }
+            : undefined;
+    }
+    const loaded = host.manifests().find((m) => m.name === name);
+    return loaded ? { sha256: null, version: loaded.version } : undefined;
+}
+const extensionVersionOf = (v) => v.manifest.extension?.manifest.version;
+/** Whether catalog version `v` carries the deployment's extension `d`. */
+export const runsDeployed = (v, d) => d.sha256 !== null
+    ? v.extension_sha256 === d.sha256
+    : v.manifest.extension !== undefined && extensionVersionOf(v) === d.version;
+/**
+ * The catalog version an org install of an extension-bearing plugin may move to: the one carrying
+ * the deployment's extension, the newest import on ties; undefined when none does.
+ */
+export function deploymentTarget(versions, d) {
+    if (d === undefined)
+        return undefined;
+    let best;
+    for (const v of versions) {
+        if (!runsDeployed(v, d))
+            continue;
+        if (best === undefined ||
+            v.imported_at.getTime() > best.imported_at.getTime() ||
+            (v.imported_at.getTime() === best.imported_at.getTime() && compareVersions(v, best) > 0)) {
+            best = v;
+        }
+    }
+    return best;
+}
+/**
+ * The upgrade info of org installs (`itemId`, `name`, `version`), keyed by `itemId@version`; reads
+ * the items' catalog versions and the deployment's extensions in a few queries.
+ */
+export async function upgradeInfo(db, host, installs) {
+    const out = new Map();
+    if (installs.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("catalog_item_versions")
+        .select(["item_id", "version", "manifest", "extension_sha256", "imported_at"])
+        .where("item_id", "in", [...new Set(installs.map((i) => i.itemId))])
+        .execute();
+    const deployed = new Map();
+    for (const i of installs) {
+        const versions = rows.filter((r) => r.item_id === i.itemId);
+        const current = versions.find((v) => v.version === i.version);
+        if (current && current.manifest.extension !== undefined) {
+            if (!deployed.has(i.name))
+                deployed.set(i.name, await deployedExtension(db, host, i.name));
+            const d = deployed.get(i.name);
+            const target = deploymentTarget(versions, d);
+            out.set(`${i.itemId}@${i.version}`, {
+                upgradeAvailable: target && target.version !== i.version ? target.version : null,
+                deploymentPending: d !== undefined && !runsDeployed(current, d),
+            });
+            continue;
+        }
+        let newest;
+        for (const v of versions) {
+            if (newest === undefined || compareVersions(v, newest) > 0)
+                newest = v;
+        }
+        const newer = newest !== undefined &&
+            newest.version !== i.version &&
+            (current === undefined
+                ? compareVersions(newest.version, i.version) > 0
+                : compareVersions(newest, current) > 0);
+        out.set(`${i.itemId}@${i.version}`, {
+            upgradeAvailable: newer ? newest.version : null,
+            deploymentPending: false,
+        });
+    }
+    return out;
+}

package/dist/catalog/versions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Catalog version order (package ecosystem spec §5.3), shared by every catalog path: semver,
+ * ignoring build metadata; two versions that differ only in build metadata (`1.0.0` and
+ * `1.0.0+git.abc`, a re-import whose content changed at the same version) are ordered by import
+ * time. Range matching ignores build metadata too and includes prereleases (`0.0.0-git.g…`).
+ */
+/** A version with its import time (the tie-break between versions equal but for build metadata). */
+export interface ImportedVersion {
+    version: string;
+    importedAt?: Date | string | null;
+}
+type Versioned = string | ImportedVersion;
+/**
+ * Compares two versions: semver without build metadata, then (when both have one) import time.
+ * Negative when `a` is older.
+ */
+export declare function compareVersions(a: Versioned, b: Versioned): number;
+/** Newest first (for `Array.prototype.sort`). */
+export declare const newestFirst: (a: Versioned, b: Versioned) => number;
+/** The same release: equal once build metadata is dropped (false when either is not semver). */
+export declare const sameRelease: (a: string, b: string) => boolean;
+/** `version` satisfies `range` (build metadata ignored, prereleases included). */
+export declare const satisfiesRange: (version: string, range: string) => boolean;
+/** The newest of `versions` satisfying `range` (see {@link compareVersions}), undefined when none does. */
+export declare function maxSatisfying<T extends Versioned>(versions: readonly T[], range: string): T | undefined;
+/**
+ * `version` with build metadata appended (`1.0.0` + `git.abc` -> `1.0.0+git.abc`; a version that
+ * already has build metadata gets it extended: `1.0.0+b1` -> `1.0.0+b1.git.abc`).
+ */
+export declare const withBuild: (version: string, build: string) => string;
+export {};

package/dist/catalog/versions.js

@@ -0,0 +1,44 @@
+import semver from "semver";
+const versionOf = (v) => (typeof v === "string" ? v : v.version);
+const timeOf = (v) => {
+    if (typeof v === "string" || v.importedAt === undefined || v.importedAt === null) {
+        return undefined;
+    }
+    return new Date(v.importedAt).getTime();
+};
+/**
+ * Compares two versions: semver without build metadata, then (when both have one) import time.
+ * Negative when `a` is older.
+ */
+export function compareVersions(a, b) {
+    const c = semver.compare(versionOf(a), versionOf(b));
+    if (c !== 0)
+        return c;
+    const ta = timeOf(a);
+    const tb = timeOf(b);
+    if (ta === undefined || tb === undefined || ta === tb)
+        return 0;
+    return ta < tb ? -1 : 1;
+}
+/** Newest first (for `Array.prototype.sort`). */
+export const newestFirst = (a, b) => compareVersions(b, a);
+/** The same release: equal once build metadata is dropped (false when either is not semver). */
+export const sameRelease = (a, b) => semver.valid(a) !== null && semver.valid(b) !== null && semver.compare(a, b) === 0;
+/** `version` satisfies `range` (build metadata ignored, prereleases included). */
+export const satisfiesRange = (version, range) => semver.satisfies(version, range, { includePrerelease: true });
+/** The newest of `versions` satisfying `range` (see {@link compareVersions}), undefined when none does. */
+export function maxSatisfying(versions, range) {
+    let best;
+    for (const v of versions) {
+        if (!satisfiesRange(versionOf(v), range))
+            continue;
+        if (best === undefined || compareVersions(v, best) > 0)
+            best = v;
+    }
+    return best;
+}
+/**
+ * `version` with build metadata appended (`1.0.0` + `git.abc` -> `1.0.0+git.abc`; a version that
+ * already has build metadata gets it extended: `1.0.0+b1` -> `1.0.0+b1.git.abc`).
+ */
+export const withBuild = (version, build) => version.includes("+") ? `${version}.${build}` : `${version}+${build}`;

package/dist/channels/actions.d.ts

@@ -0,0 +1,37 @@
+import type { ChannelCard, InboundEvent, InboundSender } from "@capybara-hq/plugin-sdk";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ApprovalsService } from "../tools/approvals.service.js";
+import type { QuestionsService } from "../tools/questions.service.js";
+import type { ChannelConnectionRow, ChannelConnections } from "./connections.service.js";
+import type { ChannelOutboundScheduler } from "./inbound.js";
+import { type ChannelLocale, type ChannelPhrase } from "./phrases.js";
+type CardActionEvent = Extract<InboundEvent, {
+    type: "card_action";
+}>;
+/** 入站处理的第 3 步（发言人 → 账号；失败时已回复并返回 undefined），由 ChannelInbound 提供。 */
+export type SpeakerResolver = (connectionId: string, row: ChannelConnectionRow, sender: InboundSender, isGroup: boolean, locale: ChannelLocale, reply: (key: ChannelPhrase, cards?: ChannelCard[]) => Promise<void>) => Promise<{
+    accountId: string;
+    threadAccount: string | null;
+} | undefined>;
+export interface ChannelCardActionsDeps {
+    db: KernelDb;
+    connections: Pick<ChannelConnections, "row" | "send">;
+    approvals: Pick<ApprovalsService, "decide">;
+    questions: Pick<QuestionsService, "answer">;
+    outbound: ChannelOutboundScheduler;
+    resolveSpeaker: SpeakerResolver;
+}
+/**
+ * IM 卡片上的按钮操作（Review Focus 2）：点击者按入站同样的规则映射到账号（未绑定 → 私聊回绑定卡片、群里只提示去私聊），
+ * 再以该账号调用 `ApprovalsService.decide` / `QuestionsService.answer`——授权完全由它们判定：
+ * 不是审批人 / 不是提问发起人 / 不在该组织 → 回一句「你不能处理这条请求」，卡片不变。
+ * 成功后卡片由出站投递按 `approval_decided` / `question_answered` 更新；这里再投递一个出站任务，让续跑的输出接着投到 IM。
+ * 先核对卡片确实发在点击所在的 chat（否则只回「不能处理」，不解析发言人、不发绑定链接），再按记下的卡片目标
+ * （会话类型、chat、话题）解析发言人与回复——事件里的 `chatType` 只是插件的参考值。
+ */
+export declare class ChannelCardActions {
+    private readonly deps;
+    constructor(deps: ChannelCardActionsDeps);
+    handle(connectionId: string, e: CardActionEvent): Promise<void>;
+}
+export {};

package/dist/channels/actions.js

@@ -0,0 +1,121 @@
+import { ApiError } from "../errors.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { idempotencyKey } from "./outbound.js";
+import { phrase } from "./phrases.js";
+import { findThread, threadKeyOf } from "./threads.js";
+/** 授权 / 状态类失败 → 回给点击者的一句话（不改卡片）；其余错误照常抛出。 */
+const REPLY_FOR = {
+    "approval.not_found": "cannotHandle",
+    "question.not_found": "cannotHandle",
+    forbidden: "cannotHandle",
+    "approval.already_decided": "alreadyHandled",
+    "question.already_answered": "alreadyHandled",
+    validation_failed: "invalidAction",
+};
+/**
+ * IM 卡片上的按钮操作（Review Focus 2）：点击者按入站同样的规则映射到账号（未绑定 → 私聊回绑定卡片、群里只提示去私聊），
+ * 再以该账号调用 `ApprovalsService.decide` / `QuestionsService.answer`——授权完全由它们判定：
+ * 不是审批人 / 不是提问发起人 / 不在该组织 → 回一句「你不能处理这条请求」，卡片不变。
+ * 成功后卡片由出站投递按 `approval_decided` / `question_answered` 更新；这里再投递一个出站任务，让续跑的输出接着投到 IM。
+ * 先核对卡片确实发在点击所在的 chat（否则只回「不能处理」，不解析发言人、不发绑定链接），再按记下的卡片目标
+ * （会话类型、chat、话题）解析发言人与回复——事件里的 `chatType` 只是插件的参考值。
+ */
+export class ChannelCardActions {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async handle(connectionId, e) {
+        const { connections } = this.deps;
+        const row = await connections.row(connectionId);
+        // 连接停用、组织已删除或插件在该组织停用（停用广播与长连接断开之间仍可能有事件到达）：什么都不做
+        if (row?.status !== "active" || !row.pluginEnabled)
+            return;
+        const { locale } = await readOrgSettings(this.deps.db, row.orgId);
+        const a = e.action;
+        // Ruling A13：卡片必须是本连接发在这个 chat 里的（防止伪造卡片 id 去处理别处的请求）。
+        // A `pending` row counts (T5a): delivery records the card before sending it, so a click that
+        // arrives before the send returns is accepted; connection and chat are checked all the same.
+        const card = await this.deps.db
+            .selectFrom("channel_card_messages")
+            .select(["conversation_id", "target"])
+            .where("connection_id", "=", connectionId)
+            .where("card_kind", "=", a.cardKind)
+            .where("card_id", "=", a.cardId)
+            .executeTakeFirst();
+        const cardTarget = card?.target;
+        // 有平台事件 id 时回复带幂等键（任务重试不重复回复）；没有时同一张卡片的不同点击无法区分，不带
+        const key = e.eventId !== undefined ? idempotencyKey(`${connectionId}-${e.eventId}-reply`) : undefined;
+        const replyTo = (t) => async (k, cards) => {
+            await connections.send(connectionId, t, { text: phrase(k, locale), ...(cards !== undefined && { cards }) }, key);
+        };
+        // Ruling A13：卡片必须是本连接发在这个 chat 里的（防止伪造卡片 id 去处理别处的请求）。在解析发言人之前判断：
+        // 卡片 id 被转发 / 重放到别的会话时，绝不在那里发绑定链接或绑定任何人——只回一句「不能处理」，并按群处理
+        // （插件给的会话类型只是参考，不可信）。
+        if (!card || !cardTarget || cardTarget.chatId !== e.target.chatId) {
+            await replyTo({
+                chatId: e.target.chatId,
+                chatType: "group",
+                ...(e.target.threadId !== undefined && { threadId: e.target.threadId }),
+            })("cannotHandle");
+            return;
+        }
+        // 会话类型、chat 与话题取发出该卡片时记下的目标（Ruling A26：点击拿不到话题时同样用记下的话题）
+        const threadId = cardTarget.threadId ?? e.target.threadId;
+        const target = cardTarget.chatType === "group"
+            ? {
+                chatId: cardTarget.chatId,
+                chatType: "group",
+                ...(threadId !== undefined && { threadId }),
+            }
+            : { chatId: cardTarget.chatId, chatType: "dm" };
+        const reply = replyTo(target);
+        const isGroup = target.chatType === "group";
+        const who = await this.deps.resolveSpeaker(connectionId, row, e.sender, isGroup, locale, reply);
+        if (who === undefined)
+            return;
+        // 匿名访客共用一个账号：只能处理自己话题里的卡片，且不能留下「本会话 / 以后都允许」的授权
+        const anonymous = who.threadAccount === null;
+        if (anonymous) {
+            const own = await findThread(this.deps.db, {
+                connectionId,
+                chatId: e.target.chatId,
+                // 点击带了话题就按它判断（更严格），否则用卡片记下的话题
+                threadKey: threadKeyOf(isGroup && e.target.threadId !== undefined
+                    ? { ...target, threadId: e.target.threadId }
+                    : target, e.sender.externalId, e.messageId),
+                accountId: null,
+            });
+            if (own !== card.conversation_id) {
+                await reply("cannotHandle");
+                return;
+            }
+        }
+        try {
+            if (a.cardKind === "approval" && (a.action === "approve" || a.action === "deny")) {
+                const scope = anonymous ? "once" : a.scope;
+                await this.deps.approvals.decide(row.orgId, a.cardId, who.accountId, {
+                    decision: a.action,
+                    ...(scope !== undefined && { scope }),
+                });
+            }
+            else if (a.cardKind === "question" && a.action === "answer") {
+                await this.deps.questions.answer(a.cardId, who.accountId, a.answer ?? {}, row.orgId);
+            }
+            else {
+                await reply("invalidAction");
+                return;
+            }
+        }
+        catch (err) {
+            const key = err instanceof ApiError ? REPLY_FOR[err.code] : undefined;
+            if (key === undefined)
+                throw err;
+            await reply(key);
+            return;
+        }
+        // the delivery of the card's conversation (the thread's): for a sub-agent's card the decided
+        // row is the child's, which has no delivery of its own
+        await this.deps.outbound.enqueue(card.conversation_id);
+    }
+}

package/dist/channels/cards.d.ts

@@ -0,0 +1,44 @@
+import type { ChannelCard, FormAnswer, InputForm, OutboundMessage } from "@capybara-hq/plugin-sdk";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ApprovalsService } from "../tools/approvals.service.js";
+import { type ChannelLocale } from "./phrases.js";
+/** 审批卡片里工具参数预览的最大长度（字符）。 */
+export declare const INPUT_PREVIEW_MAX = 500;
+/**
+ * 看起来是凭据的参数名（按整词判断，避免误伤 `max_tokens` 这类键）：其值在 IM 卡片里打码。
+ * 工具参数由模型生成，内核没有「本次注入的凭据」可比对（那是工具结果的打码方式，见 tools/redact.ts），
+ * 这里按键名兜底，再由调用方按连接密钥的值打码——IM 消息会留在第三方平台上。
+ */
+export declare function isSecretKey(key: string): boolean;
+/** 递归复制，键名像凭据的值替换为 `***`。 */
+export declare function maskSecrets(value: unknown): unknown;
+/**
+ * 工具参数预览：凭据样式的键打码后序列化为 JSON，再经 `redact`（连接密钥的按值打码）处理，
+ * 截断到 {@link INPUT_PREVIEW_MAX} 字符（含省略号）。
+ */
+export declare function inputPreview(input: unknown, redact?: (s: string) => string): string;
+/** 去掉末尾斜杠的 `http.publicUrl`；未配置返回 undefined。 */
+export declare function webBase(publicUrl: string | undefined): string | undefined;
+/** 会话的网页链接（与审批详情的 `conversationPath` 一致：`/chat/<id>`，不含语言前缀）。 */
+export declare const conversationUrl: (base: string, conversationId: string) => string;
+/** 个人连接页里某个连接器的位置（与网页 ConnectCard 的链接一致）。 */
+export declare const connectUrl: (base: string, connectorId: string) => string;
+export interface CardDeps {
+    db: KernelDb;
+    approvals: Pick<ApprovalsService, "describe">;
+}
+/**
+ * 审批卡片（按审批的当前状态）；审批不存在返回 undefined。按角色升级的审批只能「仅此一次」。
+ * `webUrl` = `http.publicUrl` + 会话路径。
+ */
+export declare function approvalCard(d: CardDeps, approvalId: string, base: string, locale: ChannelLocale, redact?: (s: string) => string): Promise<Extract<ChannelCard, {
+    kind: "approval";
+}> | undefined>;
+/** 答案摘要：每个字段的值（多选用逗号连接），多个字段用分号分隔。 */
+export declare function answerSummary(answer: FormAnswer | null): string | undefined;
+/** 提问卡片。不能在 IM 内作答的表单（`questionRenderableInline` 为 false）由渠道只渲染网页链接。 */
+export declare function questionCard(questionId: string, form: InputForm, state: "pending" | "answered" | "expired" | "cancelled", webUrl: string, answer?: FormAnswer | null): Extract<ChannelCard, {
+    kind: "question";
+}>;
+/** 一条只带一张卡片的消息（随附文本为固定话术）。 */
+export declare const cardMessage: (text: string, card: ChannelCard) => OutboundMessage;

package/dist/channels/cards.js

@@ -0,0 +1,156 @@
+import { KEY_SEPARATOR } from "../tools/naming.js";
+import { phrase } from "./phrases.js";
+/** 审批卡片里工具参数预览的最大长度（字符）。 */
+export const INPUT_PREVIEW_MAX = 500;
+/** 打码后替换成的文本。 */
+const MASK = "***";
+/** 出现即视为凭据的整词。 */
+const SECRET_WORDS = new Set([
+    "password",
+    "passwd",
+    "passphrase",
+    "secret",
+    "credential",
+    "credentials",
+    "cookie",
+    "authorization",
+    "apikey",
+]);
+/** 作为最后一个词时视为凭据（`access_token`、`authToken`；`max_tokens`、`token_count` 不算）。 */
+const SECRET_LAST_WORDS = new Set(["token", "secret", "password"]);
+/** 与 `key` / `id` 相邻构成凭据的前一个词（`api_key`、`private-key`、`session_id`）。 */
+const KEY_PREFIXES = new Set(["api", "access", "private", "secret", "signing", "client"]);
+/** 参数名拆成小写单词：驼峰与 `_` `-` `.` 空格都是分隔。 */
+function words(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w !== "");
+}
+/**
+ * 看起来是凭据的参数名（按整词判断，避免误伤 `max_tokens` 这类键）：其值在 IM 卡片里打码。
+ * 工具参数由模型生成，内核没有「本次注入的凭据」可比对（那是工具结果的打码方式，见 tools/redact.ts），
+ * 这里按键名兜底，再由调用方按连接密钥的值打码——IM 消息会留在第三方平台上。
+ */
+export function isSecretKey(key) {
+    const ws = words(key);
+    const last = ws[ws.length - 1];
+    if (ws.some((w) => SECRET_WORDS.has(w)))
+        return true;
+    if (last !== undefined && SECRET_LAST_WORDS.has(last))
+        return true;
+    for (let i = 1; i < ws.length; i++) {
+        const w = ws[i];
+        const prev = ws[i - 1];
+        if (w === "key" && KEY_PREFIXES.has(prev))
+            return true;
+        if (w === "id" && prev === "session")
+            return true;
+    }
+    return false;
+}
+/** 递归复制，键名像凭据的值替换为 `***`。 */
+export function maskSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(maskSecrets);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = isSecretKey(k) ? MASK : maskSecrets(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * 工具参数预览：凭据样式的键打码后序列化为 JSON，再经 `redact`（连接密钥的按值打码）处理，
+ * 截断到 {@link INPUT_PREVIEW_MAX} 字符（含省略号）。
+ */
+export function inputPreview(input, redact = (s) => s) {
+    let s;
+    try {
+        s = redact(JSON.stringify(maskSecrets(input ?? {})) ?? "");
+    }
+    catch {
+        s = "";
+    }
+    return s.length <= INPUT_PREVIEW_MAX ? s : `${s.slice(0, INPUT_PREVIEW_MAX - 1)}…`;
+}
+/** 去掉末尾斜杠的 `http.publicUrl`；未配置返回 undefined。 */
+export function webBase(publicUrl) {
+    return publicUrl ? publicUrl.replace(/\/+$/, "") : undefined;
+}
+/** 会话的网页链接（与审批详情的 `conversationPath` 一致：`/chat/<id>`，不含语言前缀）。 */
+export const conversationUrl = (base, conversationId) => `${base}/chat/${conversationId}`;
+/** 个人连接页里某个连接器的位置（与网页 ConnectCard 的链接一致）。 */
+export const connectUrl = (base, connectorId) => `${base}/settings/connections#connector-${encodeURIComponent(connectorId)}`;
+/** 来源内的工具名：连接器工具去掉 `<slug>__`（审批详情已处理），插件工具去掉 `<插件>__`。 */
+function shortToolName(v) {
+    if (v.connector)
+        return v.toolName;
+    const i = v.toolKey.indexOf(KEY_SEPARATOR);
+    return i > 0 ? v.toolKey.slice(i + KEY_SEPARATOR.length) : v.toolKey;
+}
+/** 账号显示名；不存在返回 undefined。 */
+async function displayName(db, accountId) {
+    if (accountId === null)
+        return undefined;
+    const r = await db
+        .selectFrom("accounts")
+        .select("display_name")
+        .where("id", "=", accountId)
+        .executeTakeFirst();
+    return r?.display_name || undefined;
+}
+/**
+ * 审批卡片（按审批的当前状态）；审批不存在返回 undefined。按角色升级的审批只能「仅此一次」。
+ * `webUrl` = `http.publicUrl` + 会话路径。
+ */
+export async function approvalCard(d, approvalId, base, locale, redact) {
+    const v = await d.approvals.describe(approvalId);
+    if (!v)
+        return undefined;
+    const decidedBy = await displayName(d.db, v.decidedBy);
+    return {
+        kind: "approval",
+        id: v.id,
+        title: phrase("approvalTitle", locale),
+        toolName: shortToolName(v),
+        ...(v.connector && { appName: v.connector.name }),
+        agentName: v.agent.name || "Agent",
+        inputPreview: inputPreview(v.input, redact),
+        scopes: v.requestedFor === null ? ["once"] : ["once", "session", "always"],
+        expiresAt: v.expiresAt,
+        state: v.status,
+        ...(decidedBy !== undefined && { decidedBy }),
+        // a denial's reason, as the web shows it (UI refresh B); redacted like the input
+        ...(v.status === "denied" &&
+            v.denyReason !== null &&
+            v.denyReason !== "" && { denyReason: redact ? redact(v.denyReason) : v.denyReason }),
+        webUrl: `${base}${v.conversationPath}`,
+    };
+}
+/** 答案摘要：每个字段的值（多选用逗号连接），多个字段用分号分隔。 */
+export function answerSummary(answer) {
+    if (answer === null)
+        return undefined;
+    const parts = Object.values(answer).map((v) => (Array.isArray(v) ? v.join(", ") : String(v)));
+    return parts.length === 0 ? undefined : parts.join("; ");
+}
+/** 提问卡片。不能在 IM 内作答的表单（`questionRenderableInline` 为 false）由渠道只渲染网页链接。 */
+export function questionCard(questionId, form, state, webUrl, answer = null) {
+    const summary = answerSummary(answer);
+    return {
+        kind: "question",
+        id: questionId,
+        form,
+        state,
+        ...(summary !== undefined && { answerSummary: summary }),
+        webUrl,
+    };
+}
+/** 一条只带一张卡片的消息（随附文本为固定话术）。 */
+export const cardMessage = (text, card) => ({
+    text,
+    cards: [card],
+});