@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/conversations/message-context.js

@@ -0,0 +1,145 @@
+import { sql } from "kysely";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { sanitizeSenderName } from "../runtime/context/run-context.js";
+import { isTimeZone } from "../time-zone.js";
+/** The name of an anonymous IM guest whose IM profile gives none. */
+export const ANONYMOUS_SENDER_NAME = "Anonymous guest";
+/**
+ * An IM sender's language tag as a run-context language: `zh` and `zh-*` / `zh_*` (any case) are
+ * Chinese, any other non-empty tag English; not a string or blank: undefined.
+ */
+export function imLocale(tag) {
+    if (typeof tag !== "string")
+        return undefined;
+    const t = tag.trim().toLowerCase();
+    if (t === "" || t.length > 64)
+        return undefined;
+    return t === "zh" || t.startsWith("zh-") || t.startsWith("zh_") ? "zh" : "en";
+}
+/**
+ * The time zone and language an inbound channel event's sender carries (values from an extension,
+ * so checked here): a time zone the runtime knows, the language normalized by {@link imLocale}.
+ */
+export function imSenderContext(sender) {
+    const tz = sender.timeZone;
+    const locale = imLocale(sender.locale);
+    return {
+        ...(typeof tz === "string" && isTimeZone(tz) && { timeZone: tz }),
+        ...(locale !== undefined && { locale }),
+    };
+}
+/** How many of the person's latest web conversations {@link latestWebLocale} looks at. */
+export const WEB_LOCALE_CONVERSATIONS = 20;
+/**
+ * The UI language of the person's most recent web message in the org (run context spec §3.4):
+ * the latest `user_message` they wrote in each of their {@link WEB_LOCALE_CONVERSATIONS} most
+ * recently updated chat conversations that are not IM threads, the newest one with a recorded
+ * `locale`. Bounded and index-friendly: `conversations_account_idx`, then one backwards primary-key
+ * walk per conversation that stops at its latest user message. Undefined when none.
+ */
+export async function latestWebLocale(t, orgId, accountId) {
+    const r = await sql `
+    SELECT m.locale FROM (
+      SELECT c.id FROM capybara.conversations c
+      WHERE c.org_id = ${orgId} AND c.account_id = ${accountId} AND c.kind = 'chat'
+        AND c.deleted_at IS NULL
+        AND NOT EXISTS (SELECT 1 FROM capybara.channel_threads th WHERE th.conversation_id = c.id)
+      ORDER BY c.updated_at DESC
+      LIMIT ${WEB_LOCALE_CONVERSATIONS}
+    ) c
+    CROSS JOIN LATERAL (
+      SELECT e.payload->>'locale' AS locale, e.created_at FROM capybara.conversation_events e
+      WHERE e.conversation_id = c.id AND e.type = 'user_message'
+        AND e.payload->>'authorAccountId' = ${accountId}
+      ORDER BY e.seq DESC
+      LIMIT 1
+    ) m
+    WHERE m.locale IN ('zh', 'en')
+    ORDER BY m.created_at DESC
+    LIMIT 1`.execute(t);
+    const locale = r.rows[0]?.locale;
+    return locale === "zh" || locale === "en" ? locale : undefined;
+}
+/**
+ * The language of kernel-generated IM text for one person (run context spec §3.4, maintainer
+ * decision 2026-11-08: in IM, language is per person): `im` (what the IM platform gave for the
+ * sender, already normalized by {@link imLocale}), else the UI language of the person's most recent
+ * web message in the org ({@link latestWebLocale}; no account, e.g. a speaker not resolved yet or
+ * the shared anonymous guest: skipped), else the org's `locale`. Read from PG on every call: no
+ * cache, so every replica answers the same.
+ */
+export async function recipientLocale(t, input) {
+    if (input.im !== undefined)
+        return input.im;
+    if (input.accountId) {
+        const web = await latestWebLocale(t, input.orgId, input.accountId);
+        if (web !== undefined)
+            return web;
+    }
+    return (await readOrgSettings(t, input.orgId)).locale;
+}
+/**
+ * Who wrote a message and in which time zone and language (run context spec §3.2, §3.4), read in
+ * the message's transaction (`t`):
+ * - `sender`: the account's display name and org role at send time; the org's anonymous guest
+ *   account (`org_anonymous_accounts`) is `{ name: <senderName, else "Anonymous guest">, role:
+ *   "guest", anonymous: true }`. Names are sanitised; an empty one leaves `sender` out.
+ * - `timeZone`: what the IM platform gave for the sender (`im`, when valid), else the account's
+ *   setting, else the browser's (when valid), else the org default, else UTC. The anonymous guest
+ *   account has no setting of its own, so it gets the IM value or the org default.
+ * - `locale`: the IM platform's value, else the browser's UI language, else the UI language of the
+ *   person's most recent web message in the org ({@link latestWebLocale}; not for the shared
+ *   anonymous guest account), else the org's `locale`.
+ *
+ * The values used are recorded on the message, so the run context is derived from the log.
+ */
+export async function readMessageContext(t, input) {
+    const row = await t
+        .selectFrom("accounts")
+        .leftJoin("memberships", (j) => j
+        .onRef("memberships.account_id", "=", "accounts.id")
+        .on("memberships.org_id", "=", input.orgId))
+        .leftJoin("org_anonymous_accounts as anon", (j) => j.onRef("anon.account_id", "=", "accounts.id").on("anon.org_id", "=", input.orgId))
+        .select([
+        "accounts.display_name",
+        "accounts.time_zone",
+        "memberships.role",
+        "anon.account_id as anonymous",
+    ])
+        .where("accounts.id", "=", input.accountId)
+        .executeTakeFirst();
+    const org = await readOrgSettings(t, input.orgId);
+    const anonymous = row?.anonymous !== null && row?.anonymous !== undefined;
+    let sender;
+    if (row !== undefined) {
+        const name = anonymous
+            ? sanitizeSenderName(input.senderName ?? "") || ANONYMOUS_SENDER_NAME
+            : sanitizeSenderName(row.display_name);
+        if (name !== "") {
+            sender = anonymous
+                ? { name, role: "guest", anonymous: true }
+                : { name, ...(row.role !== null && { role: row.role }) };
+        }
+    }
+    const im = input.im?.timeZone;
+    const own = row?.time_zone ?? null;
+    const browser = input.browser?.timeZone;
+    const timeZone = im !== undefined && isTimeZone(im)
+        ? im
+        : own !== null && isTimeZone(own)
+            ? own
+            : browser !== undefined && isTimeZone(browser)
+                ? browser
+                : (org.timeZone ?? "UTC");
+    const locale = input.im?.locale ??
+        input.browser?.locale ??
+        (row !== undefined && !anonymous
+            ? await latestWebLocale(t, input.orgId, input.accountId)
+            : undefined) ??
+        org.locale;
+    return {
+        ...(sender !== undefined && { sender }),
+        timeZone,
+        locale,
+    };
+}

package/dist/conversations/queue.d.ts

@@ -5,6 +5,7 @@ import { type InvocationRecord, type RenderedInvocation } from "../skills/invoke
 import type { AttachmentRef } from "./conversations.service.js";
 import { type AppendEvent, type EventLog } from "./event-log.js";
 import type { ConversationEvent, LogContentBlock } from "./events.js";
+import { type MessageContext } from "./message-context.js";
 /**
  * Queued messages (UI refresh B, spec §5.7): messages a person queued while a run was going. They
  * are conversation state in PG, not events: the model has not seen them, so they enter the log only
@@ -113,7 +114,7 @@ export declare function storedSkill(invokedAs: string, invoked: RenderedInvocati
     first: LogContentBlock;
 };
 /** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
-export declare function queuedUserMessage(r: QueueRow): AppendEvent;
+export declare function queuedUserMessage(r: QueueRow, context?: MessageContext): AppendEvent;
 /**
  * Appends a queued item inside `t` (the caller holds the conversation row lock): its pick, re-planned
  * against the selection in effect now, becomes a `model_switched` before the `user_message`, as a
@@ -125,6 +126,7 @@ export declare function queuedUserMessage(r: QueueRow): AppendEvent;
 export declare function appendQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "appendIn">, conversationId: string, r: QueueRow): Promise<{
     event: ConversationEvent;
     switched: boolean;
+    unarchived: boolean;
 }>;
 /**
  * Why a queued item's skill can no longer be invoked, or null (also null for a plain message).
@@ -145,11 +147,12 @@ export declare const queueFull: () => ApiError;
  * when the queue is empty. An item whose message is already in the log (a retried enqueue after it
  * was sent) is dropped and the next one is taken. A head item whose skill can no longer be invoked
  * stays queued and the queue pauses (`skill_not_invocable`): `{ paused }`. The caller notifies
- * after commit.
+ * after commit (and publishes `archived` when the send unarchived the conversation).
  */
 export declare function dispatchQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "appendIn">, conversationId: string): Promise<{
     event: ConversationEvent;
     switched: boolean;
+    unarchived: boolean;
 } | {
     paused: QueuePauseReason;
 } | null>;

package/dist/conversations/queue.js

@@ -4,6 +4,7 @@ import { ApiError } from "../errors.js";
 import { recordedSkillBlocked, } from "../skills/invoke.js";
 import { payloadJson } from "./event-log.js";
 import { userMessageIdemKey } from "./idem-keys.js";
+import { readMessageContext } from "./message-context.js";
 import { planSelection, readSelection } from "./selection.js";
 /**
  * Queued messages (UI refresh B, spec §5.7): messages a person queued while a run was going. They
@@ -77,7 +78,7 @@ export function storedSkill(invokedAs, invoked) {
     return { skill: payloadJson(skill), first: { type: "text", text: invoked.text } };
 }
 /** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
-export function queuedUserMessage(r) {
+export function queuedUserMessage(r, context = {}) {
     const attachments = r.attachments;
     const skill = r.skill;
     return {
@@ -91,6 +92,7 @@ export function queuedUserMessage(r) {
             ],
             ...(attachments.length > 0 && { attachments }),
             authorAccountId: r.account_id,
+            ...context,
             clientMessageId: r.client_message_id,
             ...(skill !== null && { skill: skill.record }),
         },
@@ -120,7 +122,14 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
             payload: { ...next, byAccountId: r.account_id, reason: "user" },
         });
     }
-    events.push(queuedUserMessage(r));
+    // run context spec §3.4: no browser values were stored with a leftover row
+    const org = await t
+        .selectFrom("conversations")
+        .select("org_id")
+        .where("id", "=", conversationId)
+        .executeTakeFirstOrThrow();
+    const context = await readMessageContext(t, { orgId: org.org_id, accountId: r.account_id });
+    events.push(queuedUserMessage(r, context));
     const written = await eventLog.appendIn(conversationId, events);
     if (next !== null) {
         await t
@@ -129,7 +138,18 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
             .where("id", "=", conversationId)
             .execute();
     }
-    return { event: written.at(-1), switched: next !== null };
+    // As a direct send: the message brings an archived conversation back into the default lists
+    const unarchived = await t
+        .updateTable("conversations")
+        .set({ archived_at: null })
+        .where("id", "=", conversationId)
+        .where("archived_at", "is not", null)
+        .executeTakeFirst();
+    return {
+        event: written.at(-1),
+        switched: next !== null,
+        unarchived: Number(unarchived.numUpdatedRows) > 0,
+    };
 }
 /** The model of the conversation agent's current version (inside `t`). */
 async function agentModel(t, conversationId) {
@@ -206,7 +226,7 @@ export const queueFull = () => new ApiError("conversation.queue_full", `A conver
  * when the queue is empty. An item whose message is already in the log (a retried enqueue after it
  * was sent) is dropped and the next one is taken. A head item whose skill can no longer be invoked
  * stays queued and the queue pauses (`skill_not_invocable`): `{ paused }`. The caller notifies
- * after commit.
+ * after commit (and publishes `archived` when the send unarchived the conversation).
  */
 export async function dispatchQueuedIn(t, eventLog, conversationId) {
     for (;;) {

package/dist/conversations/queue.service.d.ts

@@ -15,9 +15,9 @@ export declare class ConversationQueue {
     /** Starts the conversation's next run (`ensureRun`). */
     private readonly runs;
     readonly txHost: TransactionHost;
-    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill">, 
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill" | "skipQuestionsIn" | "announceSkipped">, 
     /** Starts the conversation's next run (`ensureRun`). */
-    runs: Pick<RunControl, "ensureRun">, txHost: TransactionHost);
+    runs: Pick<RunControl, "ensureRun" | "wakeHeldTree">, txHost: TransactionHost);
     list(orgId: string, conversationId: string, accountId: string): Promise<{
         items: QueueItem[];
         paused: boolean;

package/dist/conversations/queue.service.js

@@ -218,6 +218,8 @@ let ConversationQueue = class ConversationQueue {
         await this.conversations.writable(orgId, conversationId, accountId);
         await this.removeIn(conversationId, itemId);
         await this.eventLog.publishChanged(conversationId, "queue");
+        // removing the last item unpauses the queue: the wakes it held for the tree go out
+        await this.runs.wakeHeldTree(conversationId);
     }
     // its own transaction: the caller notifies and publishes after the commit
     async removeIn(conversationId, itemId) {
@@ -240,13 +242,17 @@ let ConversationQueue = class ConversationQueue {
      */
     async sendNow(orgId, conversationId, accountId, itemId) {
         await this.conversations.writable(orgId, conversationId, accountId);
-        const { event, fresh, switched } = await this.sendNowIn(conversationId, itemId);
+        const { event, fresh, switched, unarchived, skipped, toSeq } = await this.sendNowIn(conversationId, itemId);
         if (fresh)
-            await this.eventLog.notify(conversationId, event.seq);
+            await this.eventLog.notify(conversationId, toSeq);
+        await this.conversations.announceSkipped(skipped);
         if (switched)
             await this.eventLog.publishChanged(conversationId, "selection");
+        if (unarchived)
+            await this.eventLog.publishChanged(conversationId, "archived");
         await this.eventLog.publishChanged(conversationId, "queue");
         await this.runs.ensureRun(conversationId);
+        await this.runs.wakeHeldTree(conversationId);
         return event;
     }
     // its own transaction: the caller notifies and publishes after the commit
@@ -279,7 +285,17 @@ let ConversationQueue = class ConversationQueue {
         const sent = await alreadySent(t, conversationId, row.client_message_id);
         const out = await appendQueuedIn(t, this.eventLog, conversationId, row);
         await unpauseIfEmpty(t, conversationId);
-        return { ...out, fresh: !sent };
+        // sent during the run, the item is the author's message like a direct send: it skips the
+        // pending questions they may answer (reply-while-question spec §4.2)
+        const skips = sent
+            ? { records: [], toSeq: null }
+            : await this.conversations.skipQuestionsIn(conversationId, row.account_id, out.event.seq);
+        return {
+            ...out,
+            fresh: !sent,
+            skipped: skips.records,
+            toSeq: Math.max(out.event.seq, skips.toSeq ?? 0),
+        };
     }
     /** "Continue sending": clears the pause and lets `ensureRun` send the head item. */
     async resume(orgId, conversationId, accountId) {
@@ -291,6 +307,8 @@ let ConversationQueue = class ConversationQueue {
             .execute();
         await this.eventLog.publishChanged(conversationId, "queue");
         await this.runs.ensureRun(conversationId);
+        // a paused root holds the wakes of its whole tree (agent map spec §5.3)
+        await this.runs.wakeHeldTree(conversationId);
     }
     /** A queued item or a sent message for this client id (outside any transaction). */
     async prior(conversationId, clientMessageId) {

package/dist/conversations/titles.d.ts

@@ -29,10 +29,19 @@ export declare const titleJobId: (conversationId: string, attempt: number) => st
 export declare const TITLE_MAX_ATTEMPTS = 3;
 /** Output cap of the title call. */
 export declare const TITLE_MAX_OUTPUT_TOKENS = 32;
-/** The longest generated title (characters); a rename has the same limit. */
+/** The longest title a person can give by renaming (characters). */
 export declare const TITLE_MAX_CHARS = 120;
+/** The longest generated title by display width (CJK and emoji count 2: ~24 CJK / 48 Latin). */
+export declare const TITLE_MAX_WIDTH = 48;
 /** 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). */
@@ -41,8 +50,8 @@ export declare const TITLE_PROMPT: string;
 export declare function titleExcerpt(firstUser: string, firstReply: string): string;
 /**
  * The title from a model reply: the first non-empty line, without control or format characters,
- * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_CHARS} characters; null when
- * nothing is left.
+ * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_WIDTH} display width (cut on a
+ * character boundary, no ellipsis); null when nothing is left.
  */
 export declare function cleanTitle(reply: string): string | null;
 export interface TitleDeps {

package/dist/conversations/titles.js

@@ -47,10 +47,17 @@ export const titleJobId = (conversationId, attempt) => `title-${conversationId}-
 export const TITLE_MAX_ATTEMPTS = 3;
 /** Output cap of the title call. */
 export const TITLE_MAX_OUTPUT_TOKENS = 32;
-/** The longest generated title (characters); a rename has the same limit. */
+/** The longest title a person can give by renaming (characters). */
 export const TITLE_MAX_CHARS = 120;
+/** The longest generated title by display width (CJK and emoji count 2: ~24 CJK / 48 Latin). */
+export const TITLE_MAX_WIDTH = 48;
 /** 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). */
@@ -58,8 +65,13 @@ const EXCERPT_SCAN_EVENTS = 2000;
 const PAGE = 500;
 const JOB = "title";
 /** The system prompt of the title call (model-facing, English). */
-export const TITLE_PROMPT = "Write a title of at most 8 words for this conversation, in the language the user writes in. " +
+export const TITLE_PROMPT = "Write a short topic of what the user asked, not the reply, as a title for this conversation, " +
+    "in the language the user writes in. Use a noun phrase of at most 6 words or about 16 CJK " +
+    "characters: no sentence, no list. " +
     "Reply with the title only, no quotes or punctuation at the end.";
+const WIDE_RE = /[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]|\p{Extended_Pictographic}|[\u{20000}-\u{3FFFD}]/u;
+/** Display width of a character: 2 for CJK, fullwidth forms and emoji, else 1. */
+const widthOf = (ch) => (WIDE_RE.test(ch) ? 2 : 1);
 const cut = (s) => {
     const cps = Array.from(s);
     return cps.length <= TITLE_EXCERPT_CHARS ? s : `${cps.slice(0, TITLE_EXCERPT_CHARS).join("")}…`;
@@ -70,8 +82,8 @@ export function titleExcerpt(firstUser, firstReply) {
 }
 /**
  * The title from a model reply: the first non-empty line, without control or format characters,
- * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_CHARS} characters; null when
- * nothing is left.
+ * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_WIDTH} display width (cut on a
+ * character boundary, no ellipsis); null when nothing is left.
  */
 export function cleanTitle(reply) {
     const line = reply
@@ -86,10 +98,16 @@ export function cleanTitle(reply) {
         .replace(/^["'“”‘’「」《》`*]+|["'“”‘’「」《》`*]+$/gu, "")
         .replace(/[.。!！?？,，;；:：]+$/u, "")
         .trim();
-    // counted in code points, so a cut never splits a surrogate pair
-    const cps = Array.from(t);
-    if (cps.length > TITLE_MAX_CHARS)
-        t = cps.slice(0, TITLE_MAX_CHARS).join("").trimEnd();
+    // cut by display width over code points, so a cut never splits a surrogate pair
+    let width = 0;
+    let out = "";
+    for (const ch of t) {
+        width += widthOf(ch);
+        if (width > TITLE_MAX_WIDTH)
+            break;
+        out += ch;
+    }
+    t = out.trimEnd();
     return t === "" ? null : t;
 }
 const textOf = (content) => content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
@@ -204,6 +222,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 +266,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);
@@ -500,20 +528,16 @@ TitleQueue = __decorate([
     __param(3, Inject(KERNEL_LOGGER))
 ], TitleQueue);
 export { TitleQueue };
+/** The title queue's registration (re-exported: the admin health reads its counts). */
+const TITLE_QUEUE_MODULE = QueueModule.registerQueue(TITLE_QUEUE);
 /** Conversation titles: the queue and the job (consumed on the worker role). */
 let TitlesModule = class TitlesModule {
 };
 TitlesModule = __decorate([
     Module({
-        imports: [
-            EventLogModule,
-            ModelsModule,
-            ExtensionsModule,
-            UsageReportModule,
-            QueueModule.registerQueue(TITLE_QUEUE),
-        ],
+        imports: [EventLogModule, ModelsModule, ExtensionsModule, UsageReportModule, TITLE_QUEUE_MODULE],
         providers: [TitleGenerator, TitleQueue],
-        exports: [TitleQueue],
+        exports: [TitleQueue, TITLE_QUEUE_MODULE],
     })
 ], TitlesModule);
 export { TitlesModule };

package/dist/conversations/tree.d.ts

@@ -0,0 +1,17 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * A conversation and every sub-agent conversation below it (agent map spec §6: its children,
+ * grandchildren and so on, through `conversations.parent_conversation_id`), each with its level
+ * below `conversationId` (0 for the conversation itself), shallowest first. Deleted conversations
+ * are included (a deleted root's tree is still stopped); an unknown id yields nothing.
+ */
+export declare function conversationTree(db: KernelSchemaDb, conversationId: string): Promise<{
+    id: string;
+    level: number;
+}[]>;
+/**
+ * The ancestors of a conversation (agent map spec §8: live progress reaches every level above a
+ * sub-agent), nearest first: its parent, the parent's parent and so on up to the root, through
+ * `conversations.parent_conversation_id`. Empty for a root or an unknown id.
+ */
+export declare function conversationAncestors(db: KernelSchemaDb, conversationId: string): Promise<string[]>;

package/dist/conversations/tree.js

@@ -0,0 +1,42 @@
+import { sql } from "kysely";
+/**
+ * How many levels below a conversation the tree reads walk at most: far above
+ * `subagents.maxDepth`'s bound of 5, so a corrupt parent chain cannot loop forever.
+ */
+const TREE_MAX_LEVELS = 16;
+/**
+ * A conversation and every sub-agent conversation below it (agent map spec §6: its children,
+ * grandchildren and so on, through `conversations.parent_conversation_id`), each with its level
+ * below `conversationId` (0 for the conversation itself), shallowest first. Deleted conversations
+ * are included (a deleted root's tree is still stopped); an unknown id yields nothing.
+ */
+export async function conversationTree(db, conversationId) {
+    const r = await sql `
+    WITH RECURSIVE tree(id, level) AS (
+      SELECT c.id, 0 FROM capybara.conversations c WHERE c.id = ${conversationId}
+      UNION ALL
+      SELECT c.id, t.level + 1
+      FROM capybara.conversations c JOIN tree t ON c.parent_conversation_id = t.id
+      WHERE c.kind = 'subagent' AND t.level < ${TREE_MAX_LEVELS}
+    )
+    SELECT id, level FROM tree ORDER BY level, id`.execute(db);
+    return r.rows;
+}
+/**
+ * The ancestors of a conversation (agent map spec §8: live progress reaches every level above a
+ * sub-agent), nearest first: its parent, the parent's parent and so on up to the root, through
+ * `conversations.parent_conversation_id`. Empty for a root or an unknown id.
+ */
+export async function conversationAncestors(db, conversationId) {
+    const r = await sql `
+    WITH RECURSIVE up(id, parent, level) AS (
+      SELECT c.id, c.parent_conversation_id, 0 FROM capybara.conversations c
+      WHERE c.id = ${conversationId}
+      UNION ALL
+      SELECT c.id, c.parent_conversation_id, up.level + 1
+      FROM capybara.conversations c JOIN up ON c.id = up.parent
+      WHERE up.level < ${TREE_MAX_LEVELS}
+    )
+    SELECT id FROM up WHERE level > 0 ORDER BY level`.execute(db);
+    return r.rows.map((row) => row.id);
+}

package/dist/ctx/create-ctx.d.ts

@@ -1,9 +1,11 @@
-import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type ExtensionContext, type ExtensionManifest, type ExtensionPointRef, type Logger, resolveUiSlots, type SetupCheckArgs, type SetupGuidePlace, type ToolHandler, type ToolSpec } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { Kysely } from "kysely";
 import { type RegisteredHook } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
 import type { LockService } from "../infra/lock/lock.service.js";
+import type { ModelEmbeddings } from "../models/embeddings.js";
+import type { HookRunner } from "../runtime/hook-calls.js";
 import type { EmbedTokens } from "../ui/embed-token.js";
 import { type UiActionHandler, type UiRender } from "../ui/registry.js";
 import { type BusSubscriber } from "./bus.js";
@@ -22,6 +24,17 @@ export interface KernelDeps {
     keyring: Keyring;
     /** Verifies embed tokens (`ctx.ui` embed requests; the one `EmbedTokens` provider). */
     embedTokens: Pick<EmbedTokens, "verify">;
+    /**
+     * The `ctx.models` broker (the one `ModelEmbeddings` provider). Absent (a ctx built alone in a
+     * test): `ctx.models` calls reject.
+     */
+    models?: Pick<ModelEmbeddings, "embed" | "describe">;
+    /**
+     * The host's hook registry: `ctx.models.embed` fires `model.request` through it (spec B §5.4).
+     * A required key, so no builder leaves policy hooks out by omission (fail closed by
+     * construction); only a ctx built alone in a test passes `undefined` (no hooks fire).
+     */
+    hooks: HookRunner | undefined;
     runWorkers: boolean;
     /** 内核 logger（`debug` 可选：插件 Logger 没有它，测试可不给）。 */
     log: Logger & {
@@ -39,6 +52,15 @@ export type RegisteredTool = {
     spec: ToolSpec;
     handler: ToolHandler;
 };
+/**
+ * A setup check registered through `ctx.setup.check`: `place` and `run` read once from the
+ * definition at registration and frozen, so the extension cannot swap them afterwards (a getter
+ * on the definition runs once, at registration, never when a check runs).
+ */
+export type RegisteredSetupCheck = Readonly<{
+    place: SetupGuidePlace;
+    run: (args: SetupCheckArgs) => Promise<unknown>;
+}>;
 /** 插件经 `ctx.extensionPoints` 取用其他插件能力时，内核注入的访问接口。 */
 export interface ExtensionPointAccess {
     /** 已加载（setup 完成）的提供方，按加载顺序；按完整引用（含主版本）精确匹配。 */
@@ -48,14 +70,26 @@ export interface ExtensionPointAccess {
     }[];
     /** Names of the extensions enabled in the organization (`extension_org_configs.enabled` plus required bootstrap plugins, `enabled.ts`); queried every time, not cached. */
     enabledPlugins(orgId: string): Promise<Set<string>>;
+    /**
+     * Whether the extension's effective config is valid in the organization (layering spec A §6):
+     * a provider that is not is excluded from point resolution for that org.
+     */
+    configOk(orgId: string, plugin: string): Promise<boolean>;
 }
 /**
  * Queries the names of the extensions enabled in the organization (org config rows plus the
  * required bootstrap plugins, see `extensions/enabled.ts`), not cached.
  */
 export declare function queryEnabledPlugins(db: Kysely<any>, orgId: string): Promise<Set<string>>;
+/**
+ * Whether the account is, right now, an active super admin (one query): what a platform embed
+ * token and the platform refresh stream re-check.
+ */
+export declare function currentPlatformAccount(db: KernelDeps["db"], accountId: string): Promise<boolean>;
 /** 插件的 PG schema 名：`plugin_<name>`，name 中的 `-` 换成 `_`。 */
 export declare function pluginSchemaName(name: string): string;
+/** What {@link resolveUiSlots} returns for a manifest. */
+export type UiResolution = ReturnType<typeof resolveUiSlots>;
 /** 内核视角的插件 ctx：插件契约之外还带宿主要用的登记信息与关闭方法。 */
 export type KernelExtensionContext = ExtensionContext & {
     /** 本实例的登记账（C17）：每次登记记一笔，撤销时逐项撤销。 */
@@ -74,11 +108,17 @@ export type KernelExtensionContext = ExtensionContext & {
     registeredTools: RegisteredTool[];
     /** Hooks registered through `ctx.hooks.on` (registration order). */
     registeredHooks: RegisteredHook[];
+    /** The manifest's `ui` resolved against the slot catalog once per load (UI slots spec §3.2). */
+    uiResolution: UiResolution;
     /** 经 `ctx.ui.view` 注册的视图（按贡献 id）。 */
     uiViews: ReadonlyMap<string, UiRender>;
     /** 经 `ctx.ui.action` 注册的动作处理函数（按贡献 id）。 */
     uiActions: ReadonlyMap<string, UiActionHandler>;
-    /** setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on` 抛错。 */
+    /** Setup checks registered through `ctx.setup.check`, by id. */
+    setupChecks: ReadonlyMap<string, RegisteredSetupCheck>;
+    /**
+     * setup 结束后调用：此后 `tools.register`、`ui.view`、`ui.action`、`hooks.on`、`setup.check` 抛错。
+     */
     sealTools(): void;
     /** 中止 signal、封账并逐项撤销仍在账上的登记、关闭队列连接（幂等）。 */
     close(): Promise<void>;
@@ -97,10 +137,13 @@ export declare class LiveConfig {
  * `deploymentConfig` may be a {@link LiveConfig} (shared by the instance, replaceable in place);
  * otherwise a fixed value is wrapped.
  * - Granted automatically: `kv`, `lock`, `bus`, `queue`, `log`, `db`, `config`, `provide`;
- * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`; `http.route`
+ * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
+ *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
- *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
- *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
+ *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` or
+ *   `permissions.ui.components` (a component's server view; during setup only); `setup.check` only
+ *   ids declared in `permissions.setupChecks` (during setup only, `place` and `run` read once and
+ *   frozen); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
  *   replicas; `ui.verifyEmbedToken` checks an embed token the kernel signed: `claims.plugin` must be
  *   this extension, the extension still enabled in that org and the caller still an active member of
  *   the org (org not deleted); returns the current role;