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

package/dist/conversations/events.d.ts

@@ -132,6 +132,19 @@ export declare const ToolViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>], "kind">;
 export type ToolView = z.infer<typeof ToolViewSchema>;
+/**
+ * How a sub-agent's run ended (`subagent_finished`, a `subagent_delivery` finish). `timed_out`:
+ * stopped by the parent's sub-agents wait timeout (`run_aborted.detail`).
+ */
+export declare const SubagentFinishStatusSchema: z.ZodEnum<{
+    aborted: "aborted";
+    budget: "budget";
+    completed: "completed";
+    failed: "failed";
+    max_duration: "max_duration";
+    max_steps: "max_steps";
+    timed_out: "timed_out";
+}>;
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
  * 读出时按写入时的形状原样返回。
@@ -223,6 +236,10 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             parentConversationId: z.ZodString;
             parentRunId: z.ZodString;
             callId: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                message: "message";
+                task: "task";
+            }>>;
             narrowed: z.ZodOptional<z.ZodObject<{
                 tools: z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"builtin">;
@@ -275,6 +292,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         trigger: z.ZodOptional<z.ZodEnum<{
             background_task: "background_task";
             message: "message";
+            subagent: "subagent";
         }>>;
         triggerSeq: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
@@ -421,6 +439,13 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         step: z.ZodNumber;
         text: z.ZodString;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tools_changed">;
+    payload: z.ZodObject<{
+        step: z.ZodNumber;
+        added: z.ZodArray<z.ZodString>;
+        removed: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_call_started">;
     payload: z.ZodObject<{
@@ -663,6 +688,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             id: z.ZodOptional<z.ZodString>;
             version: z.ZodOptional<z.ZodNumber>;
             plugin: z.ZodOptional<z.ZodString>;
+            platformTemplateId: z.ZodOptional<z.ZodString>;
             invokedSkill: z.ZodOptional<z.ZodObject<{
                 id: z.ZodString;
                 version: z.ZodNumber;
@@ -747,6 +773,28 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 }, z.core.$strict>>>;
                 dispatchable: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
+            pendingConnectors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodString;
+                source: z.ZodUnion<readonly [z.ZodObject<{
+                    template: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    needs: z.ZodObject<{
+                        protocol: z.ZodEnum<{
+                            mcp: "mcp";
+                            openapi: "openapi";
+                        }>;
+                        endpoint: z.ZodString;
+                        tools: z.ZodArray<z.ZodString>;
+                        label: z.ZodString;
+                    }, z.core.$strict>;
+                }, z.core.$strict>]>;
+                tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                    ask: "ask";
+                    deny: "deny";
+                }>>>;
+            }, z.core.$strict>>>;
         }, z.core.$strip>;
         preamble: z.ZodString;
         maxSteps: z.ZodNumber;
@@ -781,6 +829,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         }>>>;
         subagentId: z.ZodString;
         childRunId: z.ZodString;
+        path: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
             approval: "approval";
             connect: "connect";
@@ -816,6 +865,35 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             cacheWriteTokens: z.ZodNumber;
         }, z.core.$strip>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"subagent_delivery">;
+    payload: z.ZodObject<{
+        subagentId: z.ZodString;
+        childRunId: z.ZodString;
+        description: z.ZodString;
+        kind: z.ZodEnum<{
+            finished: "finished";
+            note: "note";
+            report: "report";
+        }>;
+        text: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            aborted: "aborted";
+            budget: "budget";
+            completed: "completed";
+            failed: "failed";
+            max_duration: "max_duration";
+            max_steps: "max_steps";
+            timed_out: "timed_out";
+        }>>;
+        handedBack: z.ZodOptional<z.ZodBoolean>;
+        errorCode: z.ZodOptional<z.ZodString>;
+        abortedBy: z.ZodOptional<z.ZodEnum<{
+            parent: "parent";
+            user: "user";
+        }>>;
+        triggerAccountId: z.ZodString;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"skill_fork_result">;
     payload: z.ZodObject<{
@@ -845,6 +923,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         stoppedBy: z.ZodOptional<z.ZodEnum<{
             deletion: "deletion";
             person: "person";
+            subagent_end: "subagent_end";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -907,9 +986,12 @@ export type ConversationEvent = ConversationEventBody & {
     runId: string | null;
     createdAt: Date;
 };
-/** An event a run absorbs at a step boundary: a person's message or a finished background task. */
+/**
+ * An event a run absorbs at a step boundary: a person's message, a finished background task or a
+ * sub-agent's delivery.
+ */
 export type AbsorbableEvent = Extract<ConversationEvent, {
-    type: "user_message" | "background_task_finished";
+    type: "user_message" | "background_task_finished" | "subagent_delivery";
 }>;
 /**
  * Whether `e` is absorbed like an interjection (spec 2026-11-05-background-bash-design §2.4): the

package/dist/conversations/events.js

@@ -144,6 +144,19 @@ const ModelUsageShape = {
     cacheReadTokens: count,
     cacheWriteTokens: count,
 };
+/**
+ * How a sub-agent's run ended (`subagent_finished`, a `subagent_delivery` finish). `timed_out`:
+ * stopped by the parent's sub-agents wait timeout (`run_aborted.detail`).
+ */
+export const SubagentFinishStatusSchema = z.enum([
+    "completed",
+    "max_steps",
+    "max_duration",
+    "budget",
+    "aborted",
+    "timed_out",
+    "failed",
+]);
 /** 双语或纯文本（plugin-sdk `InputForm` 的文案字段）。 */
 const FormTextSchema = z.union([z.string(), z.object({ zh: z.string(), en: z.string() })]);
 /** 交互表单（plugin-sdk 的 `InputForm`；字段 schema 已由 `validateInputForm` 校验过，这里只记形状）。 */
@@ -213,6 +226,11 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             parentConversationId: z.string(),
             parentRunId: z.string(),
             callId: z.string(),
+            /**
+             * `message`: sent by the parent agent with `SendMessage` (agent map spec §5.1); absent or
+             * `task`: the task of a dispatch or follow-up.
+             */
+            kind: z.enum(["task", "message"]).optional(),
             /**
              * A follow-up (`resume`, final review I1): the frozen tools and org skills intersected
              * with the current version (`narrowFollowUp`); the child's run uses these instead of
@@ -252,10 +270,14 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         /**
          * What started the run (display only): absent or `message` = a person's message (or a
          * sub-agent's task), `background_task` = a finished background task woke the conversation
-         * (spec 2026-11-05-background-bash-design §3).
+         * (spec 2026-11-05-background-bash-design §3), `subagent` = a sub-agent's delivery woke it
+         * (agent map spec §5.3).
+         */
+        trigger: z.enum(["message", "background_task", "subagent"]).optional(),
+        /**
+         * A wake run's boundary: the seq of the finish or delivery that woke it (full-run replay
+         * seeds from it).
          */
-        trigger: z.enum(["message", "background_task"]).optional(),
-        /** A wake run's boundary: the seq of the finish that woke it (full-run replay seeds from it). */
         triggerSeq: seqNo.optional(),
     })),
     ev("model_call", z.object({
@@ -358,6 +380,13 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         callId: z.string().optional(),
     })),
     ev("reminder", z.object({ step: count, text: z.string() })),
+    /**
+     * The step's resolved tool set differs from the one the conversation's previous model request
+     * offered (`toolSetChange`): tool names as the model sees them, sorted. Written before that
+     * step's request, never before a conversation's first one. **Model-visible**: rendered at its
+     * position as a system message (`toolsChangedText`); dropped once a summary covers it.
+     */
+    ev("tools_changed", z.object({ step: count, added: z.array(z.string()), removed: z.array(z.string()) })),
     /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
     ev("tool_call_started", z.object({ step: count, callId: z.string(), toolKey: z.string(), specHash: z.string() })),
     /**
@@ -553,6 +582,12 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             id: z.string().optional(),
             version: z.number().int().positive().optional(),
             plugin: z.string().optional(),
+            /**
+             * Plugin scope phase 2: the platform template whose content a `plugin` child ran (a
+             * platform template, or an org copy linked to one, recorded under the copy's `id`). Absent
+             * = the org's own template (and in every older event). Eval metadata, not model-visible.
+             */
+            platformTemplateId: z.string().optional(),
             /**
              * Phase D: the child runs a forked skill a person invoked (display and eval metadata, not
              * model-visible).
@@ -589,10 +624,16 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
          */
         invokedSeq: seqNo.optional(),
     })),
-    /** Parent log: a sub-agent waits for a person (approval, input or a connection). Not model-visible. */
+    /**
+     * Root log (agent map spec §7): a sub-agent `subagentId` of the tree, at any depth, waits for a
+     * person (approval, input or a connection). Not model-visible. `path`: the child conversation ids
+     * from the root's child down to `subagentId` (`[subagentId]` for a child of the root); logged under
+     * the root run that last dispatched the root's child on that path.
+     */
     ev("subagent_waiting", z.object({
         subagentId: z.string(),
         childRunId: z.string(),
+        path: z.array(z.string()).min(1).max(16),
         kind: z.enum(["approval", "input", "connect"]),
         approvalId: z.string().optional(),
         questionId: z.string().optional(),
@@ -606,21 +647,51 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         subagentId: z.string(),
         childRunId: z.string(),
         callId: z.string(),
-        /** `timed_out`: stopped by the parent's sub-agents wait timeout (`run_aborted.detail`). */
-        status: z.enum([
-            "completed",
-            "max_steps",
-            "max_duration",
-            "budget",
-            "aborted",
-            "timed_out",
-            "failed",
-        ]),
+        status: SubagentFinishStatusSchema,
         errorCode: z.string().optional(),
         toolCalls: count,
         durationMs: count,
         usage: z.object(ModelUsageShape),
     })),
+    /**
+     * Parent log (agent map spec §4.5, §5.2): a sub-agent `subagentId` (its child conversation id)
+     * handed back a report (`SubagentHandback`), sent a note (`SendMessage to: "parent"`) or its run
+     * `childRunId` finished. **Model-visible**: absorbed like an interjection and rendered as a system
+     * message (`renderSubagentDelivery`). A finish after a handback carries `text: ""` and
+     * `handedBack: true` and renders as one status line, except that a run that handed back and
+     * `completed` writes no finished delivery at all (acceptance 2026-11-07; older logs have one and
+     * keep rendering it); a finish without a handback carries the child's
+     * final reply, a failed finish its error message (`errorCode` the code), an aborted one no text
+     * (`abortedBy` who stopped it), with `subagent_finished`'s vocabulary. `status` is present exactly
+     * on `kind: "finished"`. `triggerAccountId`: the child run's trigger account, the one a wake runs
+     * as (§7).
+     */
+    ev("subagent_delivery", z
+        .object({
+        subagentId: z.string(),
+        childRunId: z.string(),
+        description: z.string(),
+        kind: z.enum(["report", "note", "finished"]),
+        text: z.string().max(200_000),
+        /** `kind: "finished"` only (required there). */
+        status: SubagentFinishStatusSchema.optional(),
+        /** `kind: "finished"` only: a report was handed back before the run finished. */
+        handedBack: z.boolean().optional(),
+        /** `status: "failed"` only: the child run's error code. */
+        errorCode: z.string().optional(),
+        /** `status: "aborted"` only: a person stopped it, or the kernel on its parent's behalf. */
+        abortedBy: z.enum(["user", "parent"]).optional(),
+        triggerAccountId: z.string(),
+    })
+        .superRefine((p, ctx) => {
+        if ((p.kind === "finished") !== (p.status !== undefined)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["status"],
+                message: "status is required on a finished delivery and allowed only there",
+            });
+        }
+    })),
     /**
      * Phase D (spec §6.3): the report of the sub-agent that ran a person's fork invocation
      * (`invokedSeq`), written once (idem `skill_fork_result:<seq>`) before the parent's next model
@@ -654,9 +725,10 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         /**
          * The finish never wakes a run, but the next run absorbs it like any other (background
          * Bash §3): `person`, a person stopped the task (the conversation's background section);
-         * `deletion`, the conversation was being deleted.
+         * `deletion`, the conversation was being deleted; `subagent_end`, the sub-agent that owns it
+         * ended (a fork's run, or a stopped background sub-agent; agent map spec §5.3).
          */
-        stoppedBy: z.enum(["person", "deletion"]).optional(),
+        stoppedBy: z.enum(["person", "deletion", "subagent_end"]).optional(),
     })),
     ev("compaction_summary", z.object({ coversUpToSeq: seqNo, text: z.string() })),
     ev("compaction_failed", z.object({ attempt: count, reason: z.string() })),
@@ -684,7 +756,9 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
  * loop takes it at its next step boundary, `consumed_seq` moves past it, and request building
  * places it where the model call that absorbed it was built.
  */
-export const isAbsorbable = (e) => e.type === "user_message" || e.type === "background_task_finished";
+export const isAbsorbable = (e) => e.type === "user_message" ||
+    e.type === "background_task_finished" ||
+    e.type === "subagent_delivery";
 /**
  * What the person typed for a skill invocation (phase D): `/<plugin>:<name> <arguments>` (no
  * plugin: `/<name>`). Titles and eval case titles use it instead of the rendered skill in

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

@@ -17,7 +17,7 @@ export declare class ConversationQueue {
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill">, 
     /** 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) {
@@ -249,6 +251,7 @@ let ConversationQueue = class ConversationQueue {
             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
@@ -293,6 +296,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,8 +29,10 @@ 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;
 /**
@@ -48,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,8 +47,10 @@ 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;
 /**
@@ -63,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("")}…`;
@@ -75,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
@@ -91,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("");

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

@@ -4,6 +4,8 @@ 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 & {
@@ -48,6 +61,11 @@ 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
@@ -97,7 +115,8 @@ 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

package/dist/ctx/create-ctx.js

@@ -146,6 +146,7 @@ function guardBuilder(builder, plugin) {
 const noProviders = (deps) => ({
     providers: () => [],
     enabledPlugins: (orgId) => queryEnabledPlugins(deps.db, orgId),
+    configOk: async () => true,
 });
 /**
  * 插件实例的部署配置（已校验）：`ctx.config` 是读它的 getter。hot 字段改动时宿主替换 `value`（C10），
@@ -163,7 +164,8 @@ export 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
@@ -217,6 +219,24 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             plugins: async () => [name],
         }).forPlugin(name)
         : undefined;
+    // ctx.models: only with permissions.models; the broker accepts only the purposes declared there
+    // with kind embedding (spec B §5.4), aborted by this instance's signal
+    // a frozen copy: the approved manifest, not an object the extension could change later
+    const declaredModels = Object.freeze(structuredClone(perms.models ?? []).map((m) => Object.freeze(m)));
+    const modelsApi = declaredModels.length > 0
+        ? {
+            embed: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.embed(name, declaredModels, req, lifecycle.signal, deps.hooks);
+            },
+            describe: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.describe(name, declaredModels, req);
+            },
+        }
+        : undefined;
     const declaredRoutes = new Set((perms.http ?? []).map((r) => `${r.method} ${r.path}`));
     const declaredTools = new Set(perms.tools ?? []);
     const declaredHooks = new Set(perms.hooks ?? []);
@@ -260,12 +280,21 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             throw new ExtensionPointUnavailableError(`extension point ${ref} has no provider`);
         return { info, chosen };
     };
-    /** 组织视角过滤提供方：orgScoped 能力只留该组织已启用的（每次查询，不缓存）。 */
+    /**
+     * The org's view of the providers: an orgScoped point keeps only those the org enabled (queried
+     * every time, not cached), and every point drops those whose effective config is not valid in
+     * the org (layering spec A §6: a call on behalf of an org never reaches such a provider).
+     */
     const forOrg = async (orgScoped, orgId, entries) => {
-        if (!orgScoped || entries.length === 0)
+        if (entries.length === 0)
             return entries;
-        const enabled = await extensionPointAccess.enabledPlugins(orgId);
-        return entries.filter((e) => enabled.has(e.plugin));
+        let out = entries;
+        if (orgScoped) {
+            const enabled = await extensionPointAccess.enabledPlugins(orgId);
+            out = out.filter((e) => enabled.has(e.plugin));
+        }
+        const ok = await Promise.all(out.map((e) => extensionPointAccess.configOk(orgId, e.plugin)));
+        return out.filter((_, i) => ok[i]);
     };
     const listAll = (ref) => {
         const info = checkExtensionPoint(ref);
@@ -280,7 +309,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return (async () => {
                 const { info, chosen } = pick(ref, provider);
                 if ((await forOrg(info.orgScoped, orgId, [chosen])).length === 0) {
-                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not enabled in organization ${orgId}`);
+                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not available in organization ${orgId} (not enabled there, or its configuration is not valid there)`);
                 }
                 return chosen.impl;
             })();
@@ -551,7 +580,8 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return closing;
         },
     };
-    // 声明了 secrets / storage 时是普通属性；未声明时是不可枚举的抛错 getter——展开 / 打印 ctx 不会触发越权与审计
+    // secrets / storage / models: a plain property when declared; otherwise a non-enumerable getter
+    // that throws, so spreading or printing ctx triggers no denial and no audit
     const gated = (key, api) => {
         if (api) {
             Object.assign(ctx, { [key]: api });
@@ -565,6 +595,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     };
     gated("secrets", secretsApi);
     gated("storage", storageApi);
+    gated("models", modelsApi);
     return ctx;
 }
 /**