@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.4

package/dist/conversations/titles.d.ts

@@ -33,6 +33,13 @@ export declare const TITLE_MAX_OUTPUT_TOKENS = 32;
 export declare const TITLE_MAX_CHARS = 120;
 /** Each side of the excerpt is cut to this many characters. */
 export declare const TITLE_EXCERPT_CHARS = 1000;
+/**
+ * Parameters of the title call where the target model declares them and the `title` purpose does
+ * not set them: no thinking, so the {@link TITLE_MAX_OUTPUT_TOKENS} budget goes to the title.
+ */
+export declare const TITLE_PARAM_DEFAULTS: {
+    readonly thinking: "off";
+};
 /** Time limit of one title call. */
 export declare const TITLE_TIMEOUT_MS = 60000;
 /** The system prompt of the title call (model-facing, English). */

package/dist/conversations/titles.js

@@ -51,6 +51,11 @@ export const TITLE_MAX_OUTPUT_TOKENS = 32;
 export const TITLE_MAX_CHARS = 120;
 /** Each side of the excerpt is cut to this many characters. */
 export const TITLE_EXCERPT_CHARS = 1000;
+/**
+ * Parameters of the title call where the target model declares them and the `title` purpose does
+ * not set them: no thinking, so the {@link TITLE_MAX_OUTPUT_TOKENS} budget goes to the title.
+ */
+export const TITLE_PARAM_DEFAULTS = { thinking: "off" };
 /** Time limit of one title call. */
 export const TITLE_TIMEOUT_MS = 60_000;
 /** How far into the log the excerpt is looked for (events). */
@@ -204,6 +209,8 @@ export async function runTitleJob(d, conversationId, attempt) {
             maxOutputTokens: TITLE_MAX_OUTPUT_TOKENS,
         }, signal, {
             ...(fallback && { fallback: { model: fallback, params: {} } }),
+            // a thinking model spends the small output budget on thinking and returns no text
+            paramDefaults: TITLE_PARAM_DEFAULTS,
             beforeSend: async (target, request) => {
                 await checkTitleHooks(d, scope, target, request, signal);
                 sent = { ...target, at: Date.now() };
@@ -246,6 +253,14 @@ export async function runTitleJob(d, conversationId, attempt) {
     if (sent && d.hooks)
         observeTitle(d, scope, sent, out, null, signal);
     const title = cleanTitle(textOf(out.content));
+    if (title === null) {
+        d.log.warn("conversation title call returned no title", {
+            conversationId,
+            attempt,
+            stopReason: out.stopReason,
+            outputTokens: out.usage.outputTokens,
+        });
+    }
     const { written, usage } = await d.writes.writeResult(conversationId, attempt, out, title);
     if (usage) {
         await d.eventLog.notify(conversationId, usage.seq);

package/dist/db/kernel-schema.d.ts

@@ -14,6 +14,8 @@ export interface AccountsTable {
     is_enterprise_admin: Generated<boolean>;
     created_at: Ts;
     updated_at: Ts;
+    /** 0064: the org the account last chose as current; a new session starts in it. */
+    last_org_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 export interface IdentitiesTable {
     source: string;
@@ -149,6 +151,11 @@ export interface AgentsTable {
     org_role: Generated<"admin" | "member" | "guest">;
     current_version: number;
     needs_reassignment: Generated<boolean>;
+    /** 0067: the profile (display data, outside the versions). */
+    profile_avatar: ColumnType<Record<string, unknown> | null, string | null | undefined, string | null>;
+    profile_description: Generated<string>;
+    profile_quick_actions: ColumnType<unknown[], string | undefined, string>;
+    profile_updated_at: Ts;
     created_at: Ts;
     updated_at: Ts;
     deleted_at: TsNullable;
@@ -199,6 +206,10 @@ export interface ConversationsTable {
     queue_paused: ColumnType<boolean, boolean | undefined, boolean>;
     /** 0062: why the queue paused (`QueuePauseReason`); null when not paused or not recorded. */
     queue_pause_reason: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0065: when the owner archived it (hidden from the default lists); null = not archived. */
+    archived_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
+    /** 0065: when the owner deleted it (soft delete: hidden everywhere for the owner); null = live. */
+    deleted_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
 }
 /** 0060: an org's order of file-preview@1 previewers (UI refresh B Task 11). */
 export interface FilePreviewersTable {
@@ -208,6 +219,15 @@ export interface FilePreviewersTable {
     position: number;
     disabled: ColumnType<boolean, boolean | undefined, boolean>;
 }
+/** 0073: an org's default provider of an `org-default` extension point. */
+export interface OrgExtensionPointDefaultsTable {
+    org_id: string;
+    /** The extension point name without the major (`web-search`). */
+    point: string;
+    extension: string;
+    updated_at: Ts;
+    updated_by: string | null;
+}
 /** 0059: a queued message (not in the event log until sent). */
 export interface ConversationQueueTable {
     id: string;
@@ -547,9 +567,11 @@ export interface AttachmentsTable {
     expires_at: TsNullable;
     /** 0024：上传用途（技能包不能绑定到消息）。 */
     purpose: ColumnType<AttachmentPurpose, AttachmentPurpose | undefined, AttachmentPurpose>;
+    /** 0068: the agent whose profile uses this avatar upload (set once, when it is saved). */
+    agent_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
-/** 预签名上传的用途：对话附件 / 技能包 zip。 */
-export type AttachmentPurpose = "chat" | "skill-package";
+/** 预签名上传的用途：对话附件 / 技能包 zip / agent avatar image. */
+export type AttachmentPurpose = "chat" | "skill-package" | "agent-avatar";
 /** 技能版本的清单（`skill_versions.manifest`）。 */
 export interface SkillManifest {
     name: string;
@@ -630,6 +652,33 @@ export interface SkillChangeRequestsTable {
     decided_at: TsNullable;
     created_at: Ts;
 }
+/** 0070_background_tasks.sql: a Bash command running in the background in a conversation's sandbox. */
+export interface BackgroundTasksTable {
+    id: string;
+    org_id: string;
+    conversation_id: string;
+    sandbox_conversation_id: string;
+    run_id: string;
+    call_id: string;
+    trigger_account_id: string;
+    description: string;
+    command: string;
+    /** NULL while the launch is reserved but not started (0071). */
+    sid: string | null;
+    output_path: string;
+    status: ColumnType<"running" | "completed" | "failed" | "stopped" | "timed_out" | "lost", string | undefined, string>;
+    lost_reason: ColumnType<string | null, string | null | undefined, string | null>;
+    exit_code: ColumnType<number | null, number | null | undefined, number | null>;
+    started_at: Ts;
+    finished_at: TsNullable;
+    deadline_at: Date | string;
+    /** NULL while the launch is reserved but not started (0071). */
+    sandbox_created_at: Date | string | null;
+    kill_pending: ColumnType<boolean, boolean | undefined, boolean>;
+    read_offset: ColumnType<string, number | string | undefined, number | string>;
+    /** Set while a stop is under way (0072); the poller skips such a task. */
+    stopping_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
+}
 /** 0023_sandboxes.sql：按对话的沙箱（见 sandbox/sandbox.service.ts）。 */
 export interface SandboxesTable {
     conversation_id: string;
@@ -788,6 +837,11 @@ export interface ExtensionPackagesTable {
     source_ref: string;
     uploaded_by: string | null;
     created_at: Ts;
+    /** 0066: the plugin.json `displayName`; null without one and for packages stored before 0066. */
+    display_name: ColumnType<{
+        zh: string;
+        en: string;
+    } | null, string | null | undefined, string | null>;
 }
 /** 0030, renamed in 0041: package bytes when there is no object storage. */
 export interface ExtensionBlobsTable {
@@ -867,6 +921,7 @@ export interface KernelDatabase {
     conversation_events: ConversationEventsTable;
     conversation_queue: ConversationQueueTable;
     file_previewers: FilePreviewersTable;
+    org_extension_point_defaults: OrgExtensionPointDefaultsTable;
     runs: RunsTable;
     subagent_dispatches: SubagentDispatchesTable;
     agent_templates: AgentTemplatesTable;
@@ -890,6 +945,7 @@ export interface KernelDatabase {
     directory_exclusions: DirectoryExclusionsTable;
     attachments: AttachmentsTable;
     sandboxes: SandboxesTable;
+    background_tasks: BackgroundTasksTable;
     skills: SkillsTable;
     skill_versions: SkillVersionsTable;
     skill_change_requests: SkillChangeRequestsTable;

package/dist/db/pool.d.ts

@@ -18,6 +18,11 @@ export declare function pgConnectOptions(cfg: {
  */
 export declare function createDb(url: string, poolMax: number, onError?: (err: Error) => void, opts?: {
     connectTimeoutMs?: number | undefined;
+    /**
+     * How long an idle client stays in the pool (pg's `idleTimeoutMillis`; unset = pg's 10 s).
+     * Every new client costs a TCP + auth handshake, several round trips to a distant database.
+     */
+    idleTimeoutMs?: number | undefined;
     /**
      * Error of a client while it is checked out: pg-pool drops its own listener on checkout, so
      * without this a backend killed between two statements is an uncaught exception.

package/dist/db/pool.js

@@ -22,6 +22,9 @@ export function createDb(url, poolMax, onError = (err) => console.error("[db] id
         connectionString: url,
         max: poolMax,
         ...pgConnectOptions(opts),
+        ...(opts.idleTimeoutMs !== undefined && { idleTimeoutMillis: opts.idleTimeoutMs }),
+        // a client kept idle longer must notice a dead peer (a dropped VPN, a NAT timeout) by itself
+        keepAlive: true,
     });
     pool.on("error", onError);
     pool.on("connect", (client) => client.on("error", opts.onClientError ?? onError));

package/dist/errors.d.ts

@@ -110,7 +110,11 @@ export declare const ERROR_CODES: {
     readonly "setup.token_invalid": 403;
     readonly "agent.not_found": 404;
     readonly "agent.version_conflict": 409;
+    /** The profile was changed since the client read it (`expectedUpdatedAt` is stale). */
+    readonly "agent.profile_conflict": 409;
     readonly "agent.model_unavailable": 400;
+    /** A save gave `instructionFiles` and an `instructions` that is not their join. */
+    readonly "agent.instructions_mismatch": 400;
     /**
      * `skills.pinned` of an agent definition is refused (details: `{ skill, reason, totalBytes? }`;
      * reasons `not_selected`, `not_found`, `duplicate`, `too_many`, `too_large`, `manual_only`).
@@ -130,6 +134,10 @@ export declare const ERROR_CODES: {
     /** A sub-agent's conversation takes no messages from people (sub-agents spec §6.1). */
     readonly "conversation.read_only": 409;
     readonly "run.not_active": 409;
+    /** A background task that is not in this conversation (or its sub-agents), or does not exist. */
+    readonly "background_task.not_found": 404;
+    /** The task's output cannot be read now (its sandbox is not running and no finish recorded it). */
+    readonly "background_task.output_unavailable": 409;
     readonly "connector.not_found": 404;
     readonly "connector.slug_taken": 409;
     readonly "connector.connect_failed": 502;

package/dist/errors.js

@@ -110,7 +110,11 @@ export const ERROR_CODES = {
     "setup.token_invalid": 403,
     "agent.not_found": 404,
     "agent.version_conflict": 409,
+    /** The profile was changed since the client read it (`expectedUpdatedAt` is stale). */
+    "agent.profile_conflict": 409,
     "agent.model_unavailable": 400,
+    /** A save gave `instructionFiles` and an `instructions` that is not their join. */
+    "agent.instructions_mismatch": 400,
     /**
      * `skills.pinned` of an agent definition is refused (details: `{ skill, reason, totalBytes? }`;
      * reasons `not_selected`, `not_found`, `duplicate`, `too_many`, `too_large`, `manual_only`).
@@ -130,6 +134,10 @@ export const ERROR_CODES = {
     /** A sub-agent's conversation takes no messages from people (sub-agents spec §6.1). */
     "conversation.read_only": 409,
     "run.not_active": 409,
+    /** A background task that is not in this conversation (or its sub-agents), or does not exist. */
+    "background_task.not_found": 404,
+    /** The task's output cannot be read now (its sandbox is not running and no finish recorded it). */
+    "background_task.output_unavailable": 409,
     "connector.not_found": 404,
     "connector.slug_taken": 409,
     "connector.connect_failed": 502,

package/dist/evals/run-replay.d.ts

@@ -19,7 +19,10 @@ import type { ResolvedCandidate } from "./step-replay.js";
  *
  * - 种子：原运行 `run_started` 之前的事件按原 seq 插入（`last_seq` 停在其前一位，新的 `run_started` 因此与原来同 seq），
  *   原运行开始时的 `skills_catalog` 照抄；然后写 `runs` 行与 `run_started`，`agent` 用候选定义。
- * - 插话：原运行中途吸收的 user_message，在「原吸收步骤 ≤ 当前步骤」时追加进评测对话并交给 loop。
+ * - 插话：原运行中途吸收的可吸收事件（user_message, and finished background tasks: background Bash
+ *   spec §4.4），在「原吸收步骤 ≤ 当前步骤」时追加进评测对话并交给 loop（a recorded finish is
+ *   appended as recorded: no task starts, polls or stops）。
+ * - A wake run (its boundary a finished background task, not a message) is seeded from that event.
  * - 计费（C7，与单步回放同一套）：每次模型请求（含压缩、重试、兜底）发出前查运行仍在执行、仍持有认领；
  *   收完按真实用量、没收完按估算 `consumeTokens`（越限即 `capped`，下一次请求前停下）。
  * - 附件按快照自己的组织与原对话取（C3）。
@@ -101,7 +104,7 @@ export interface ReplaySeed {
     /** The conversation's `consumed_seq` when the original run started. */
     consumed: number;
     seeds: SnapshotEvent[];
-    /** The run's trigger seq (the last user message before it). */
+    /** The run's trigger seq (its boundary: the last unconsumed message, or the waking finish). */
     trigger: number;
     agentVersion: number;
     model: ModelRef;

package/dist/evals/run-replay.js

@@ -13,6 +13,7 @@ import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { normalizeStoredDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
+import { isAbsorbable, } from "../conversations/events.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -260,6 +261,28 @@ function absorbedByStep(s) {
     }
     return out;
 }
+/**
+ * The replayed run's boundary (`trigger_seq`): a wake run's recorded one (`run_started.triggerSeq`,
+ * background Bash spec §3); otherwise the newest message after `consumed`, else the newest finish
+ * after it that could have woken the run (not reported, no `stoppedBy`), else the last
+ * message (old logs, as before).
+ */
+function replayTrigger(started, seeds, consumed) {
+    const recorded = started;
+    if (recorded.trigger === "background_task" && recorded.triggerSeq !== undefined) {
+        return recorded.triggerSeq;
+    }
+    const lastMessage = seeds.findLast((e) => e.type === "user_message")?.seq;
+    if (lastMessage !== undefined && lastMessage > consumed)
+        return lastMessage;
+    const wake = seeds.findLast((e) => {
+        if (e.type !== "background_task_finished" || e.seq <= consumed)
+            return false;
+        const p = e.payload;
+        return !p.reported && p.stoppedBy === undefined;
+    })?.seq;
+    return wake ?? lastMessage ?? 0;
+}
 const readAll = async (eventLog, conversationId) => {
     const out = [];
     let after = 0;
@@ -294,7 +317,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
             consumed = Math.max(consumed, e.payload.consumedUpToSeq);
         }
     }
-    const trigger = seeds.findLast((e) => e.type === "user_message")?.seq ?? 0;
+    const trigger = replayTrigger(start.payload, seeds, consumed);
     const catalog = s.events.find((e) => e.runId === s.runId && e.type === "skills_catalog" && e.seq > R);
     // a sub-agent's case (spec §15.3) runs the effective definition frozen in its subagent_started
     // (the request renders that event's preamble and instructions; its tools come from it too), with
@@ -427,7 +450,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
             return "stop";
         },
     });
-    // 插话：原运行开始之后到达、且被原运行某一步吸收的 user_message
+    // 插话：原运行开始之后到达、且被原运行某一步吸收的可吸收事件（user_message / background_task_finished）
     const absorbed = absorbedByStep(s);
     const stepsInOrder = [...absorbed.keys()].sort((a, b) => a - b);
     /** 第 k 步（含）之前原运行吸收到的最大位置；原运行没有模型调用时不设限。 */
@@ -442,7 +465,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
         return cap;
     };
     const interjections = s.events
-        .filter((e) => e.type === "user_message" && e.seq > R)
+        .filter((e) => (e.type === "user_message" || e.type === "background_task_finished") && e.seq > R)
         .flatMap((e) => {
         const step = stepsInOrder.find((k) => absorbed.get(k) >= e.seq);
         return step === undefined ? [] : [{ event: e, step }];
@@ -450,7 +473,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
     /** 已追加的插话：原 seq → 评测对话里的 seq。 */
     const fed = new Map();
     let prepared = 0;
-    const pendingUserMessages = async (afterSeq) => {
+    const pendingAbsorbable = async (afterSeq) => {
         prepared++;
         // loop 的步骤从 1 起（与运行时相同），每步的 prepare 调用一次：第 n 次调用即第 n 步
         const k = prepared;
@@ -459,7 +482,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
                 continue;
             const [w] = await eventLog.append(conversationId, [
                 {
-                    type: "user_message",
+                    type: x.event.type,
                     idemKey: `replay_interjection:${runId}:${x.event.seq}`,
                     payload: x.event.payload,
                 },
@@ -471,7 +494,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
         const fedSeqs = new Set(fed.values());
         const out = [];
         for (const e of await readAll(eventLog, conversationId)) {
-            if (e.type !== "user_message" || e.seq <= afterSeq)
+            if (!isAbsorbable(e) || e.seq <= afterSeq)
                 continue;
             if (fedSeqs.has(e.seq) || (e.seq < R && e.seq <= cap))
                 out.push(e);
@@ -502,7 +525,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
             signal: loopSignal,
             shutdown: new AbortController().signal,
             sink: () => { },
-            pendingUserMessages,
+            pendingAbsorbable,
             limits: {
                 maxSteps: subagent === undefined ? runtime.maxSteps : Math.min(subagent.maxSteps, runtime.maxSteps),
                 deadline,

package/dist/evals/step-replay.js

@@ -54,10 +54,9 @@ subagent) {
                 ? { ...(from.modelParams ?? {}) }
                 : {});
     const definition = {
-        ...from,
+        ...withInstructions(from, c.instructions),
         model,
         modelParams: params,
-        ...(c.instructions !== undefined && { instructions: c.instructions }),
     };
     const changed = agentVersion !== base.agentVersion ||
         !sameModel(model, base.definition.model) ||
@@ -73,13 +72,20 @@ subagent) {
         changed,
         overridesSwitch,
         ...(otherVersion && {
-            subagentVersion: {
-                ...versionDef,
-                ...(c.instructions !== undefined && { instructions: c.instructions }),
-            },
+            subagentVersion: withInstructions(versionDef, c.instructions),
         }),
     };
 }
+/**
+ * A candidate's `instructions` override: the prompt files it was joined from no longer describe
+ * it, so they are dropped (never model-visible either way).
+ */
+function withInstructions(def, instructions) {
+    if (instructions === undefined)
+        return def;
+    const { instructionFiles: _files, ...rest } = def;
+    return { ...rest, instructions };
+}
 /**
  * 候选请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是这次尝试应计入预算的估算用量，
  * `cause` 是原始错误（调用方按它分类重试）。请求发出之前的失败（解析模型、取附件）原样抛出，不计费。

package/dist/evals/trajectory.js

@@ -130,7 +130,7 @@ function buildRun({ started, events }, prices, forks) {
                 assistants.set(e.payload.step, [...(assistants.get(e.payload.step) ?? []), e]);
                 break;
             case "usage":
-                // a compaction or title call's usage is not a step call's: counted in the totals only (I-1)
+                // a compaction, title or web_fetch call's usage is not a step call's: counted in the totals only (I-1)
                 if (e.payload.purpose !== undefined) {
                     compactions.push(e);
                     break;

package/dist/extensions/admin-ops.js

@@ -396,6 +396,8 @@ export { ExtensionAdminOps };
 function fallbackView(name, known, err) {
     return {
         name,
+        // the degraded item reads nothing more (the read that failed may be the database)
+        displayName: null,
         version: known.version,
         source: "install",
         sha256: known.sha256,

package/dist/extensions/admin-view.d.ts

@@ -5,6 +5,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
 import { ExtensionApprovals } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC } from "./lifecycle.js";
@@ -41,6 +42,7 @@ export declare class ExtensionAdmin {
     private readonly config;
     private readonly bus;
     private readonly log;
+    private readonly displayNames;
     private readonly packageSets;
     constructor(kdb: KernelDb, txHost: TransactionHost, 
     /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
@@ -48,7 +50,7 @@ export declare class ExtensionAdmin {
     /** The config-declared extensions (this replica's host; the CLI fills it from its inspection). */
     host: ExtensionHost, 
     /** This replica's reconcile after an approval (a no-op where the lifecycle never started: the CLI). */
-    lifecycle: ExtensionLifecycle, config: KernelConfigService, bus: PublishBus, log: KernelLogger);
+    lifecycle: ExtensionLifecycle, config: KernelConfigService, bus: PublishBus, log: KernelLogger, displayNames: ExtensionDisplayNames);
     private get db();
     /** 全部插件（配置声明 → 安装记录，各自按名字）。 */
     list(): Promise<AdminExtensionView[]>;

package/dist/extensions/admin-view.js

@@ -19,6 +19,7 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { ExtensionApprovals, snapshotCovers, writeSnapshot, } from "./approvals.js";
 import { ExtensionBlobs } from "./blobs.js";
+import { ExtensionDisplayNames } from "./display-name.js";
 import { ExtensionHost } from "./host.js";
 import { ExtensionInstalls } from "./installs.js";
 import { ExtensionLifecycle, PLUGINS_CHANGED_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle.js";
@@ -63,6 +64,7 @@ let ExtensionAdmin = class ExtensionAdmin {
     config;
     bus;
     log;
+    displayNames;
     packageSets = new Map();
     constructor(kdb, txHost, 
     /** The enterprise admin lock (identity/enterprise-admin.ts): joins the transaction. */
@@ -70,7 +72,7 @@ let ExtensionAdmin = class ExtensionAdmin {
     /** The config-declared extensions (this replica's host; the CLI fills it from its inspection). */
     host, 
     /** This replica's reconcile after an approval (a no-op where the lifecycle never started: the CLI). */
-    lifecycle, config, bus, log) {
+    lifecycle, config, bus, log, displayNames) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -83,6 +85,7 @@ let ExtensionAdmin = class ExtensionAdmin {
         this.config = config;
         this.bus = bus;
         this.log = log;
+        this.displayNames = displayNames;
     }
     get db() {
         return this.kdb.db;
@@ -278,6 +281,7 @@ let ExtensionAdmin = class ExtensionAdmin {
             return [];
         const names = subjects.map((s) => s.name);
         const snapshots = await this.approvals.all();
+        const displayNames = await this.displayNames.many(names);
         const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
         const rows = await this.db
             .selectFrom("extension_replica_status")
@@ -294,9 +298,11 @@ let ExtensionAdmin = class ExtensionAdmin {
             const configValid = s.configValid ??
                 !replicas.some((r) => r.state === "pending" && r.reason === "config" && r.sha256 === target);
             const install = s.install;
+            const displayName = displayNames.get(s.name) ?? null;
             if (s.broken !== undefined) {
                 return {
                     name: s.name,
+                    displayName,
                     version: s.version,
                     source: s.source,
                     sha256: target,
@@ -326,6 +332,7 @@ let ExtensionAdmin = class ExtensionAdmin {
             const permissions = permissionGroups(s.set);
             return {
                 name: s.name,
+                displayName,
                 version: s.version,
                 source: s.source,
                 sha256: target,
@@ -376,7 +383,8 @@ ExtensionAdmin = __decorate([
     __param(8, Inject(ExtensionLifecycle)),
     __param(9, Inject(KernelConfigService)),
     __param(10, Inject(KERNEL_BUS)),
-    __param(11, Inject(KERNEL_LOGGER))
+    __param(11, Inject(KERNEL_LOGGER)),
+    __param(12, Inject(ExtensionDisplayNames))
 ], ExtensionAdmin);
 export { ExtensionAdmin };
 const replicaView = (r) => ({

package/dist/extensions/blobs.js

@@ -123,6 +123,7 @@ let ExtensionBlobs = class ExtensionBlobs {
             source: src.source,
             source_ref: src.ref,
             uploaded_by: src.actor,
+            display_name: p.displayName === undefined ? null : JSON.stringify(p.displayName),
         })
             .onConflict((oc) => oc.column("sha256").doNothing())
             .returning("sha256")

package/dist/extensions/config-issues.d.ts

@@ -1,7 +1,19 @@
 import type { z } from "zod";
 /** 校验失败的单条原因：只含路径与按 issue 类型生成的说明，不回显字段值。 */
 export interface ConfigIssue {
+    /** The path joined with dots (`""` = the root); ambiguous when a key contains a dot. */
     path: string;
+    /** The zod path unjoined (record keys such as endpoint names may contain dots). */
+    segments: (string | number)[];
     message: string;
+    /**
+     * A custom issue whose `params.ui` names a key of the schema's root `x-ui.messages`: the form
+     * shows that localized message (spec §4.4). Never zod's own custom text.
+     */
+    messageKey?: string;
 }
-export declare function toIssues(error: z.ZodError): ConfigIssue[];
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export declare function toIssues(error: z.ZodError, messages?: Record<string, unknown>): ConfigIssue[];

package/dist/extensions/config-issues.js

@@ -23,9 +23,26 @@ function issueMessage(i) {
             return "invalid value";
     }
 }
-export function toIssues(error) {
-    return error.issues.map((i) => ({
-        path: i.path.map(String).join("."),
-        message: issueMessage(i),
-    }));
+/** The `params.ui` of a custom issue when it names one of `messages` (own keys only). */
+function messageKeyOf(i, messages) {
+    if (i.code !== "custom" || messages === undefined)
+        return undefined;
+    const key = i.params?.ui;
+    return typeof key === "string" && Object.hasOwn(messages, key) ? key : undefined;
+}
+/**
+ * The issues of a failed config parse. `messages` is the root `x-ui.messages` of the schema's
+ * form JSON Schema (`configMessages`): custom issues naming one of its keys get `messageKey`.
+ */
+export function toIssues(error, messages) {
+    return error.issues.map((i) => {
+        const segments = i.path.map((s) => (typeof s === "number" ? s : String(s)));
+        const messageKey = messageKeyOf(i, messages);
+        return {
+            path: segments.join("."),
+            segments,
+            message: issueMessage(i),
+            ...(messageKey !== undefined && { messageKey }),
+        };
+    });
 }

package/dist/extensions/config-json-schema.d.ts

@@ -1,9 +1,45 @@
-import { z } from "zod";
-export type JsonSchema = Record<string, unknown>;
 /**
- * 把插件配置 schema 转成 JSON Schema（供界面渲染表单）：
- * - `secret()` 字段带 `"x-secret": true`（去掉 zod 附带的 `secret` 元数据键）；
- * - 无法表达的类型为 `{ "x-unsupported": true }`，不抛错；
- * - 以输入侧形态输出（含 default），不带 `$schema`。
+ * Config schema → JSON Schema for forms. The conversion (and the secret scrub) lives in the SDK
+ * (`configJsonSchema`, extension config forms spec §4.1) so the packer, the checks and the kernel
+ * share one implementation; the kernel keeps no copy.
  */
-export declare function configToJsonSchema(schema: z.ZodType): JsonSchema;
+import { type ConfigUiProblem, type JsonSchema } from "@capybara-hq/plugin-sdk";
+import type { z } from "zod";
+export { configJsonSchema as configToJsonSchema, type JsonSchema } from "@capybara-hq/plugin-sdk";
+/** The config level a schema belongs to (which hints `validateConfigUi` allows). */
+export type ConfigLevel = "deployment" | "org" | "connection";
+/** A config schema as served to forms, with the problems of its hints (empty = kept). */
+export interface ConfigFormSchema {
+    /** Shared by every caller: clone it before handing it out or changing it. */
+    readonly schema: JsonSchema;
+    readonly problems: ConfigUiProblem[];
+}
+/**
+ * Removes every `x-ui` from a JSON Schema in place (a property named `x-ui` is kept, and so are
+ * values: `default`, `const`, `enum` and `examples` are left as they are).
+ */
+export declare function stripConfigUi(node: unknown): void;
+/**
+ * Validates the hints of a JSON Schema at a level and strips every `x-ui` when there is any
+ * problem (in place): invalid hints never reach a form, and never fail a load (spec §4.1).
+ */
+export declare function checkConfigUi(schema: JsonSchema, level: ConfigLevel): ConfigUiProblem[];
+/** A config schema's form JSON Schema ({@link checkConfigUi} applied), cached per schema object. */
+export declare function configFormSchema(schema: z.ZodTypeAny, level: ConfigLevel): ConfigFormSchema;
+/**
+ * {@link configFormSchema} that never throws, for every caller that serves a form schema or reads
+ * its messages (deployment, org, connection, issues). A hint conversion that throws (a hand-made
+ * package, e.g. hints that won't serialize as JSON) drops the hints: the plain schema with every
+ * `x-ui` stripped, else `null` when even the plain conversion fails. `onFallback` runs once per
+ * schema object and level on this replica (the caller's one warning); later calls reuse the result.
+ */
+export declare function safeConfigFormSchema(schema: z.ZodTypeAny, level: ConfigLevel, onFallback: (err: unknown, fallback: "plain" | "none") => void): ConfigFormSchema | null;
+/**
+ * The secret record paths some `x-ui.secrets[].path` of a form schema names (spec §4.3), anywhere in
+ * the schema. Read from a checked schema: one whose hints were invalid was stripped and names none.
+ */
+export declare function hintedSecretPaths(node: unknown, out?: Set<string>): Set<string>;
+/** The root `x-ui.messages` of a form schema (the localized texts of custom issues), if any. */
+export declare function configMessages(schema: JsonSchema | null | undefined): Record<string, unknown> | undefined;
+/** A short text of hint problems for a status detail or a log (the first few). */
+export declare function describeConfigUiProblems(level: ConfigLevel, problems: ConfigUiProblem[]): string;