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

package/dist/conversations/event-log.d.ts

@@ -28,13 +28,16 @@ export declare const conversationTopic: (conversationId: string) => string;
  * 会话频道上的总线消息：
  * - `events`：会话日志已推进到 `toSeq`（订阅方据此 `readAfter` 补读，消息本身不携带事件）；
  * - `delta`：运行的流式增量（文本 / 思考 / `step_reset`：丢弃该步此前推出的增量），只是草稿，
- *   最终内容以日志中的 assistant_message 为准。`offset`（仅 text）：本步本次尝试中此前已推出的文本字符数，
- *   中途才订阅的一方据此判断自己是否从头收到了该步的文本（渠道出站投递只在完整时发草稿）；
+ *   最终内容以日志中的 assistant_message 为准。`offset` (text and thinking): the characters of
+ *   that channel this attempt of the step streamed before the delta; a subscriber that joined midway
+ *   tells by it whether it has the step's text from the start (the channel outbound only drafts
+ *   complete text) and drops what a live draft already covers (spec 2026-11-07 §3.2);
  * - `ui`：插件经 `ctx.ui.invalidate` 告知这个会话的某个界面贡献变了（不进日志、不是模型可见内容），
  *   SSE 转发为 `event: ui`，网页据此重新取视图。
- * - `subagent_progress`: after each step of a sub-agent run, on its **parent's** topic (sub-agents
- *   spec §14.2): the child's step and tool call count so far, and its last tool's key. Not in any
- *   log; the SSE forwards it as `event: subagent_progress` (data without `kind`).
+ * - `subagent_progress`: after each step of a sub-agent run, on the topic of **every ancestor**
+ *   (sub-agents spec §14.2, agent map spec §8), `subagentId` the progressing agent: its step and
+ *   tool call count so far, and its last tool's key. Not in any log; the SSE forwards it as
+ *   `event: subagent_progress` (data without `kind`).
  */
 export type ConversationBusMessage = {
     kind: "events";
@@ -64,7 +67,7 @@ export type ConversationBusMessage = {
  * What changed about a conversation outside its event log (UI refresh B): the SSE stream sends it as
  * `event: changed` with `{ what }`, and the web refetches that part. Never model-visible.
  */
-export declare const CONVERSATION_CHANGES: readonly ["title", "queue", "selection", "files"];
+export declare const CONVERSATION_CHANGES: readonly ["title", "queue", "selection", "files", "archived", "deleted", "background"];
 export type ConversationChange = (typeof CONVERSATION_CHANGES)[number];
 /**
  * 会话事件日志：只追加，是 agent 运行的唯一事实来源。
@@ -107,6 +110,18 @@ export declare class EventLog {
     publishChanged(conversationId: string, what: ConversationChange): Promise<void>;
     /** 读 `afterSeq` 之后的事件，按 seq 升序，最多 `limit` 条。 */
     readAfter(conversationId: string, afterSeq: number, limit?: number): Promise<ConversationEvent[]>;
+    /**
+     * The page of the log that ends right before `beforeSeq` (`null`: the log's end), in ascending
+     * seq: the last `limit` events before it, extended back so the first event is the log's first or
+     * the first one after a run's end (`run_finished` / `run_failed` / `run_aborted`), at most
+     * `extend` events further back (a longer run then starts mid-run). `turnsBefore`: how many runs
+     * started (distinct `run_id` of `run_started`) before the page's first event. History paging
+     * spec §2.
+     */
+    readTurnPageBefore(conversationId: string, beforeSeq: number | null, limit: number, extend: number): Promise<{
+        events: ConversationEvent[];
+        turnsBefore: number;
+    }>;
     /**
      * 读 `afterSeq` 之后、属于 `runIds` 中某次运行的事件，按 seq 升序，最多 `limit` 条（轨迹按运行分页用）。
      * `runIds` 为空时返回空数组。走部分索引 `conversation_events_run_idx (conversation_id, run_id, seq)`（0027）：

package/dist/conversations/event-log.js

@@ -41,7 +41,16 @@ export const conversationTopic = (conversationId) => `conv.${conversationId}`;
  * What changed about a conversation outside its event log (UI refresh B): the SSE stream sends it as
  * `event: changed` with `{ what }`, and the web refetches that part. Never model-visible.
  */
-export const CONVERSATION_CHANGES = ["title", "queue", "selection", "files"];
+export const CONVERSATION_CHANGES = [
+    "title",
+    "queue",
+    "selection",
+    "files",
+    "archived",
+    "deleted",
+    // the conversation's background tasks (or its sub-agents')
+    "background",
+];
 const notFound = () => new ApiError("conversation.not_found", "Conversation not found");
 function toEvent(r) {
     return {
@@ -146,6 +155,66 @@ let EventLog = class EventLog {
             .execute();
         return rows.map(toEvent);
     }
+    /**
+     * The page of the log that ends right before `beforeSeq` (`null`: the log's end), in ascending
+     * seq: the last `limit` events before it, extended back so the first event is the log's first or
+     * the first one after a run's end (`run_finished` / `run_failed` / `run_aborted`), at most
+     * `extend` events further back (a longer run then starts mid-run). `turnsBefore`: how many runs
+     * started (distinct `run_id` of `run_started`) before the page's first event. History paging
+     * spec §2.
+     */
+    async readTurnPageBefore(conversationId, beforeSeq, limit, extend) {
+        let q = this.db
+            .selectFrom("conversation_events")
+            .select(EVENT_COLUMNS)
+            .where("conversation_id", "=", conversationId);
+        if (beforeSeq !== null)
+            q = q.where("seq", "<", String(beforeSeq));
+        const rows = (await q.orderBy("seq", "desc").limit(limit).execute()).reverse();
+        const first = rows[0] === undefined ? null : Number(rows[0].seq);
+        if (first === null)
+            return { events: [], turnsBefore: 0 };
+        let start = first;
+        if (first > 1) {
+            // the latest run end at or before the event just above the page, within the extension
+            const end = await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.max("seq").as("seq"))
+                .where("conversation_id", "=", conversationId)
+                .where("seq", "<", String(first))
+                .where("seq", ">=", String(Math.max(1, first - 1 - extend)))
+                .where("type", "in", ["run_finished", "run_failed", "run_aborted"])
+                .executeTakeFirst();
+            // none within reach: the page starts at the log's start when that is in reach, else mid-run
+            if (end?.seq != null)
+                start = Number(end.seq) + 1;
+            else if (first - 1 <= extend)
+                start = 1;
+        }
+        const head = start < first
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select(EVENT_COLUMNS)
+                .where("conversation_id", "=", conversationId)
+                .where("seq", ">=", String(start))
+                .where("seq", "<", String(first))
+                .orderBy("seq")
+                .execute()
+            : [];
+        const turns = start > 1
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.count("run_id").distinct().as("n"))
+                .where("conversation_id", "=", conversationId)
+                .where("type", "=", "run_started")
+                .where("seq", "<", String(start))
+                .executeTakeFirst()
+            : undefined;
+        return {
+            events: [...head, ...rows].map(toEvent),
+            turnsBefore: Number(turns?.n ?? 0),
+        };
+    }
     /**
      * 读 `afterSeq` 之后、属于 `runIds` 中某次运行的事件，按 seq 升序，最多 `limit` 条（轨迹按运行分页用）。
      * `runIds` 为空时返回空数组。走部分索引 `conversation_events_run_idx (conversation_id, run_id, seq)`（0027）：

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">;
@@ -272,6 +289,12 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             model: z.ZodString;
         }, z.core.$strip>;
         triggerAccountId: z.ZodString;
+        trigger: z.ZodOptional<z.ZodEnum<{
+            background_task: "background_task";
+            message: "message";
+            subagent: "subagent";
+        }>>;
+        triggerSeq: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"model_call">;
@@ -406,7 +429,9 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         purpose: z.ZodOptional<z.ZodEnum<{
             compaction: "compaction";
             title: "title";
+            web_fetch: "web_fetch";
         }>>;
+        callId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"reminder">;
@@ -414,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<{
@@ -496,6 +528,13 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"approval_requested">;
     payload: z.ZodObject<{
+        requestedFor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        approverRole: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            admin: "admin";
+            guest: "guest";
+            member: "member";
+            owner: "owner";
+        }>>>;
         step: z.ZodNumber;
         callId: z.ZodString;
         approvalId: z.ZodString;
@@ -649,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;
@@ -659,6 +699,10 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             name: z.ZodString;
             avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
             instructions: z.ZodDefault<z.ZodString>;
+            instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>>>;
             model: z.ZodObject<{
                 provider: z.ZodString;
                 model: z.ZodString;
@@ -729,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;
@@ -754,8 +820,16 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"subagent_waiting">;
     payload: z.ZodObject<{
+        requestedFor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        approverRole: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            admin: "admin";
+            guest: "guest";
+            member: "member";
+            owner: "owner";
+        }>>>;
         subagentId: z.ZodString;
         childRunId: z.ZodString;
+        path: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
             approval: "approval";
             connect: "connect";
@@ -791,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<{
@@ -799,6 +902,30 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         childRunId: z.ZodOptional<z.ZodString>;
         text: z.ZodString;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"background_task_finished">;
+    payload: z.ZodObject<{
+        taskId: z.ZodString;
+        description: z.ZodString;
+        status: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            lost: "lost";
+            stopped: "stopped";
+            timed_out: "timed_out";
+        }>;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        elapsedMs: z.ZodNumber;
+        lastLines: z.ZodString;
+        outputPath: z.ZodString;
+        reported: z.ZodBoolean;
+        lostReason: z.ZodOptional<z.ZodString>;
+        stoppedBy: z.ZodOptional<z.ZodEnum<{
+            deletion: "deletion";
+            person: "person";
+            subagent_end: "subagent_end";
+        }>>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"compaction_summary">;
     payload: z.ZodObject<{
@@ -859,6 +986,19 @@ export type ConversationEvent = ConversationEventBody & {
     runId: string | null;
     createdAt: Date;
 };
+/**
+ * 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" | "subagent_delivery";
+}>;
+/**
+ * Whether `e` is absorbed like an interjection (spec 2026-11-05-background-bash-design §2.4): the
+ * 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 declare const isAbsorbable: (e: ConversationEvent) => e is AbsorbableEvent;
 /**
  * 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/events.js

@@ -1,6 +1,7 @@
 import { DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { AgentDefinitionSchema, AgentToolRef, ModelRef } from "../agents/definition.js";
+import { ORG_ROLES } from "../orgs/roles.js";
 import { TOOL_VIEW_DIFF_MAX_LINES, TOOL_VIEW_LINE_MAX_CHARS, TOOL_VIEW_PATH_MAX_CHARS, } from "../tools/view.js";
 /** 供应商私有数据（`ProviderOpaque`）：原样保存、只回放给同一供应商。 */
 const ProviderOpaqueSchema = z.object({
@@ -17,6 +18,15 @@ const RefMediaSourceSchema = z.object({
     kind: z.literal("ref"),
     attachmentId: AttachmentIdSchema,
 });
+/**
+ * Who may decide an approval, as the approval row says (display only, absent in older logs): the
+ * assigned account (`requestedFor`), else the escalation role (`approverRole`). Pages word the
+ * waiting state with it ("等待 张三 批准") for viewers who cannot decide.
+ */
+const ApproverFields = {
+    requestedFor: z.string().nullable().optional(),
+    approverRole: z.enum(ORG_ROLES).nullable().optional(),
+};
 /** The longest deny reason (characters): the decision route's limit and `approval_decided.reason`'s. */
 export const APPROVAL_DENY_REASON_MAX_CHARS = 500;
 /** 一条 `media_excluded` 事件最多的附件数。 */
@@ -134,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` 校验过，这里只记形状）。 */
@@ -203,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
@@ -239,6 +267,18 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         agentVersion: z.number().int().positive(),
         model: ModelRef,
         triggerAccountId: z.string(),
+        /**
+         * 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), `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).
+         */
+        triggerSeq: seqNo.optional(),
     })),
     ev("model_call", z.object({
         step: count,
@@ -326,16 +366,27 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
      * Usage of one model call. Absent `purpose` = the step's call (written with its
      * `assistant_message`); `compaction` = the compaction call before the step (I-1: billed and
      * reported, but no step consumer may pair it with the step's `model_call`); `title` = the
-     * conversation title call (UI refresh B: no run, `step` 0, not model-visible, billed and reported).
+     * conversation title call (UI refresh B: no run, `step` 0, not model-visible, billed and reported);
+     * `web_fetch` = a `WebFetch` extraction call (web tools spec §5: the tool call's run and step,
+     * `callId` = the call; not model-visible, billed and reported, counted on a sub-agent's parent).
      */
     ev("usage", z.object({
         step: count,
         provider: z.string(),
         model: z.string(),
         ...ModelUsageShape,
-        purpose: z.enum(["compaction", "title"]).optional(),
+        purpose: z.enum(["compaction", "title", "web_fetch"]).optional(),
+        /** The tool call a `web_fetch` usage belongs to. */
+        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() })),
     /**
@@ -392,6 +443,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         expiresAt: z.string(),
         /** Which rule asked (UI refresh B; display only, absent in older logs). */
         policy: z.enum(["agent", "connector", "default", "role", "org", "fixed"]).optional(),
+        ...ApproverFields,
     })),
     /** 审批已处理（批准 / 拒绝 / 超时 / 取消）；`scope` 只在批准时出现，`byAccountId` 为处理人（超时 / 取消为 null）。 */
     ev("approval_decided", z.object({
@@ -530,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).
@@ -566,36 +624,74 @@ 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(),
         toolKey: z.string(),
         expiresAt: z.string().optional(),
+        /** An approval's approver (`kind: "approval"`), as in `approval_requested`. */
+        ...ApproverFields,
     })),
     /** Parent log: a sub-agent's run ended. Not model-visible (its reply is the call's tool_result). */
     ev("subagent_finished", z.object({
         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
@@ -609,6 +705,31 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         childRunId: z.string().optional(),
         text: z.string(),
     })),
+    /**
+     * A background Bash task ended (spec 2026-11-05-background-bash-design §2). Model-visible: it is
+     * absorbed like an interjection and rendered as a system message (`renderBackgroundFinished`).
+     * `reported`: a TaskOutput or TaskStop in the same run already told the model; it is absorbed
+     * like any other, renders as one short line and never wakes a run. `lastLines` is the tail of
+     * the task's output.
+     */
+    ev("background_task_finished", z.object({
+        taskId: z.string().min(1).max(64),
+        description: z.string(),
+        status: z.enum(["completed", "failed", "stopped", "timed_out", "lost"]),
+        exitCode: z.number().int().nullable(),
+        elapsedMs: count,
+        lastLines: z.string().max(4000),
+        outputPath: z.string(),
+        reported: z.boolean(),
+        lostReason: z.string().optional(),
+        /**
+         * 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; `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", "subagent_end"]).optional(),
+    })),
     ev("compaction_summary", z.object({ coversUpToSeq: seqNo, text: z.string() })),
     ev("compaction_failed", z.object({ attempt: count, reason: z.string() })),
     ev("run_finished", z.object({
@@ -630,6 +751,14 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             .optional(),
     })),
 ]);
+/**
+ * Whether `e` is absorbed like an interjection (spec 2026-11-05-background-bash-design §2.4): the
+ * 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" ||
+    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.d.ts

@@ -125,6 +125,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 +146,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>;