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

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 { AgentDefinitionSchema, DisabledToolRef, 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` 事件最多的附件数。 */
@@ -75,12 +85,22 @@ const STOP_REASONS = ["end_turn", "tool_use", "max_tokens", "refusal", "other"];
 const EFFORT_ENUM = ["low", "medium", "high", "xhigh", "max"];
 const seqNo = z.number().int().nonnegative();
 const count = z.number().int().nonnegative();
+/**
+ * The state of a file a `Read` / `Write` / `Edit` saw or left (display only, but the kernel reads it
+ * back from the log to decide read-before-write): the full normalized path, the file's full size and
+ * the sha256 of the bytes handled (the first bytes only for a file over `Read`'s byte limit).
+ */
+const FileStateViewSchema = z.object({
+    path: z.string().max(4096),
+    size: count,
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
 /**
  * Structured view of a builtin tool's result (UI refresh B, spec §5.5 / §5.9): display only, like
- * `display`. `command`: `sandbox_bash` (the model's `description`, the exit code, null when the
+ * `display`. `command`: `Bash` (the model's `description`, the exit code, null when the
  * command was stopped, and whether it timed out; the web shows "Failed" for a non-zero exit even
- * though `isError` stays false); `edit`: `sandbox_edit` / `sandbox_write` (a capped line diff);
- * `read`: `sandbox_read` (the line range shown).
+ * though `isError` stays false); `edit`: `Edit` / `Write` (a capped line diff);
+ * `read`: `Read` (the line range shown).
  */
 export const ToolViewSchema = z.discriminatedUnion("kind", [
     z.object({
@@ -96,6 +116,7 @@ export const ToolViewSchema = z.discriminatedUnion("kind", [
         added: count,
         removed: count,
         truncated: z.boolean(),
+        file: FileStateViewSchema.optional(),
         hunks: z
             .array(z.object({
             oldStart: count,
@@ -114,6 +135,7 @@ export const ToolViewSchema = z.discriminatedUnion("kind", [
         path: z.string().max(TOOL_VIEW_PATH_MAX_CHARS),
         fromLine: count.optional(),
         toLine: count.optional(),
+        file: FileStateViewSchema.optional(),
     }),
 ]);
 const ModelUsageShape = {
@@ -122,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` 校验过，这里只记形状）。 */
@@ -141,6 +176,37 @@ const InputFormSchema = z.object({
 });
 /** 表单答案（plugin-sdk 的 `FormAnswer`）。 */
 const FormAnswerSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]));
+/** The languages a run context names (the org `locale` values). */
+export const RUN_CONTEXT_LOCALES = ["zh", "en"];
+/** `user_message.sender` (run context spec §3.2). */
+export const MessageSenderSchema = z.object({
+    name: z.string().min(1).max(80),
+    /** Absent = no membership. */
+    role: z.enum(ORG_ROLES).optional(),
+    /** An IM sender served as the org's anonymous guest; `name` is the IM profile name. */
+    anonymous: z.literal(true).optional(),
+});
+/** `run_context` (run context spec §3.1): every field optional, a later event holds changes only. */
+export const RunContextSchema = z.object({
+    /** The agent itself: its name and its versioned description collapsed to one line. */
+    agent: z
+        .object({ name: z.string().min(1).max(130), description: z.string().max(200).optional() })
+        .optional(),
+    org: z.object({ name: z.string().min(1).max(200) }).optional(),
+    /** Today in `timeZone`, `YYYY-MM-DD`. */
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional(),
+    /** IANA name. */
+    timeZone: z.string().min(1).max(64).optional(),
+    /** The language of the person whose message started the run. */
+    locale: z.enum(RUN_CONTEXT_LOCALES).optional(),
+    /** Sub-agents only: who dispatched this conversation. */
+    dispatchedBy: z
+        .object({ agent: z.string().min(1).max(130), person: z.string().min(1).max(80) })
+        .optional(),
+});
 const ev = (type, payload) => z.object({ type: z.literal(type), payload });
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
@@ -158,6 +224,21 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             .array(z.object({ appId: z.string(), appName: z.string(), uri: z.string(), name: z.string() }))
             .optional(),
         authorAccountId: z.string(),
+        /**
+         * Who wrote the message, at send time (run context spec §3.2): display name and org role
+         * only (never email or ids). Absent in older logs, on a sub-agent's task or `SendMessage`
+         * message. Model-visible only through the sender line, written when the sender changes
+         * (`senderLines`, runtime/context/run-context.ts).
+         */
+        sender: MessageSenderSchema.optional(),
+        /**
+         * The sender's time zone (IANA) and language at send time (run context spec §3.4): an IM
+         * platform's values, the account setting, the browser's, the person's latest web language,
+         * the org defaults (`readMessageContext`). Not model-visible: the next run's `run_context`
+         * is derived from them.
+         */
+        timeZone: z.string().min(1).max(64).optional(),
+        locale: z.enum(RUN_CONTEXT_LOCALES).optional(),
         clientMessageId: z.string().optional(),
         /**
          * A retry after a failed run (UI refresh B): the seq of the message it repeats. Display only
@@ -192,13 +273,21 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             parentRunId: z.string(),
             callId: z.string(),
             /**
-             * 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
-             * the frozen ones. Absent on a first dispatch and in older logs.
+             * `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 and the current version's
+             * turned-off tools together, and the frozen org skills intersected with the current
+             * ones (`narrowFollowUp`); the child's run uses these instead of the frozen ones.
+             * Absent on a first dispatch and in older logs; logs from before tools were on by
+             * default carry an enabled `tools` list instead of `disabledTools` (read as no tool
+             * narrowing).
              */
             narrowed: z
                 .object({
-                tools: z.array(AgentToolRef),
+                disabledTools: z.array(DisabledToolRef).optional(),
                 skills: z
                     .object({ orgSkills: z.array(z.string()), pinned: z.array(z.string()).optional() })
                     .optional(),
@@ -227,6 +316,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,
@@ -260,13 +361,13 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
              */
             absorbedUpToSeq: seqNo.optional(),
             /**
-             * 本次请求带给模型的工具（按发送顺序：未启用 tool_search 时按 key 排序；启用时为内置工具按 key 排序，
+             * 本次请求带给模型的工具（按发送顺序：未启用 ToolSearch 时按 key 排序；启用时为内置工具按 key 排序，
              * 其后是已加载工具按首次加载顺序）及其定义指纹（`ResolvedTool.specHash`）。
              * 模型不支持工具时为空数组。较早的事件可能没有。
              */
             tools: z.array(z.object({ key: z.string(), specHash: z.string() })).optional(),
             /**
-             * 启用 tool_search 时 system 第二块目录里的工具（按 key 排序）及定义指纹；定义同样存在
+             * 启用 ToolSearch 时 system 第二块目录里的工具（按 key 排序）及定义指纹；定义同样存在
              * `capybara.tool_specs`，目录文本可由它们还原。未启用时不写。
              */
             catalog: z.array(z.object({ key: z.string(), specHash: z.string() })).optional(),
@@ -314,16 +415,48 @@ 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() })),
+    /**
+     * Who the agent is and the facts of the day (run context spec §3.1), written at run start
+     * (`RunContextService.record`): the conversation's first one holds every field that applies, a
+     * later one only the fields that changed. **Model-visible**: rendered at its position as a
+     * system message (`runContextText`); a summary covering it restores the current values.
+     */
+    ev("run_context", RunContextSchema),
+    /**
+     * 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()) })),
+    /**
+     * The directories of the instance a sandbox tool call entered, when they differ from the
+     * defaults (environments spec §13.1: a connected machine's real paths). Written once per
+     * conversation and roots, before that call's result. **Model-visible**: rendered at its position
+     * as a system message (`devicePathsText`); a summary covering it is followed by the latest
+     * one again.
+     */
+    ev("device_paths", z.object({
+        roots: z.object({
+            workspace: z.string().min(1).max(4096),
+            skills: z.string().min(1).max(4096),
+            tmp: z.string().min(1).max(4096),
+        }),
+    })),
     /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
     ev("tool_call_started", z.object({ step: count, callId: z.string(), toolKey: z.string(), specHash: z.string() })),
     /**
@@ -339,7 +472,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         outputId: z.string().optional(),
         contentTypes: z.array(z.string()).optional(),
         /**
-         * `tool_search` 本次加载的工具 key（没有匹配时不写）。已加载集合 = 会话中全部 tool_result 的
+         * `ToolSearch` 本次加载的工具 key（没有匹配时不写）。已加载集合 = 会话中全部 tool_result 的
          * `loadedTools` 并集（含已被摘要覆盖的部分），构建请求时由日志还原，不放进程内存。
          */
         loadedTools: z.array(z.string()).optional(),
@@ -380,6 +513,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({
@@ -395,7 +529,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         reason: z.string().max(APPROVAL_DENY_REASON_MAX_CHARS).optional(),
     })),
     /**
-     * 工具调用需要用户输入（`ask_user`、插件工具的 `input_required`、MCP elicitation）：输入请求已建，
+     * 工具调用需要用户输入（`AskUserQuestion`、插件工具的 `input_required`、MCP elicitation）：输入请求已建，
      * run 暂停等待回答。界面据此显示表单卡片（不进模型请求）。
      */
     ev("question_asked", z.object({
@@ -405,13 +539,18 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         form: InputFormSchema,
         expiresAt: z.string(),
     })),
-    /** 输入请求已结束：回答 / 超时 / 取消（后两者 `answer` 与 `byAccountId` 为 null）。 */
+    /**
+     * An input request ended: answered, skipped (the run's starter sent a message instead; `answer`
+     * null, `byAccountId` the message's author, `skippedBySeq` that `user_message`'s seq, written in
+     * the same transaction), expired or cancelled (`answer` and `byAccountId` null). Not model-visible.
+     */
     ev("question_answered", z.object({
         questionId: z.string(),
         callId: z.string(),
         answer: FormAnswerSchema.nullable(),
         byAccountId: z.string().nullable(),
-        outcome: z.enum(["answered", "expired", "cancelled"]),
+        outcome: z.enum(["answered", "skipped", "expired", "cancelled"]),
+        skippedBySeq: seqNo.optional(),
     })),
     /**
      * 带媒体的模型请求被供应商以不可重试的 `invalid_request` / `context_overflow` 拒绝（Ruling M8）：这些附件
@@ -423,7 +562,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         reason: z.enum(["provider_rejected"]),
     })),
     /**
-     * agent 经 `sandbox_deliver` 把沙箱里的文件交付给用户（M5 T8，C3）：字节在对象存储
+     * agent 经 `Deliver` 把沙箱里的文件交付给用户（M5 T8，C3）：字节在对象存储
      * `kernel/<orgId>/<objectKey>`（`objectKey` = `artifacts/<conversationId>/<artifactId>`，相对内核前缀），
      * 这里只有元数据。网页从日志重建产物列表；不进模型请求（模型看到的是同一调用的 tool_result 确认）。
      */
@@ -439,7 +578,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
     /**
      * 本对话此刻生效的技能（M5 T14，Ruling M17）：运行开始时内核解析生效的技能集合（agent 版本选中的组织技能 +
      * agent 自己的技能，未删除，取 current_version），与日志里上一份快照不同才写。模型看到的技能目录只来自这里：
-     * 第一份（在任何 `model_call` 之前）进 system 缓存段，之后的在所在位置渲染为英文变更提醒；`skill_load` 按最新一份
+     * 第一份（在任何 `model_call` 之前）进 system 缓存段，之后的在所在位置渲染为英文变更提醒；`Skill` 按最新一份
      * 把名字解析为 id 与版本。按 name 排序。
      */
     ev("skills_catalog", z.object({
@@ -451,12 +590,12 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             version: z.number().int().positive(),
             /**
              * 内容来源（对象前缀，T15）：已生成的版本为 `skill_versions.object_prefix`，试用中的草稿为申请的
-             * `object_prefix`。同号的草稿与正式版本靠它区分；`skill_load` 只按它解析。
+             * `object_prefix`。同号的草稿与正式版本靠它区分；`Skill` 只按它解析。
              */
             source: z.string().min(1).max(512),
             /**
              * The catalog item (plugin) name the skill came from (phase B); absent for the org's
-             * own and the agent's skills, and in snapshots written before phase B. `skill_load`
+             * own and the agent's skills, and in snapshots written before phase B. `Skill`
              * resolves `<plugin>:<name>` with it; it is not model-visible otherwise.
              */
             plugin: z.string().min(1).max(64).optional(),
@@ -465,7 +604,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         /**
          * Pinned skills (phase B, spec §9.1) in the agent's order: each a skill of `skills` (same
          * id, version and source) with its SKILL.md body as read at run start or written by
-         * skill_write. Absent means none (every snapshot before phase B).
+         * a skill registration. Absent means none (every snapshot before phase B).
          */
         pinned: z
             .array(z.object({
@@ -518,6 +657,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).
@@ -534,7 +679,7 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         warnings: z.array(z.string()).optional(),
     })),
     /**
-     * Parent log (phase C, spec §14.1): the `agent` call `callId` started (or resumed) the sub-agent
+     * Parent log (phase C, spec §14.1): the `Agent` call `callId` started (or resumed) the sub-agent
      * `subagentId` (its child conversation id) with run `childRunId`. Not model-visible: the model
      * sees the call's tool_call / tool_result pair.
      */
@@ -550,40 +695,78 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         tierFallback: z.boolean().optional(),
         /**
          * Phase D: the seq of the person's fork invocation this dispatch runs (`callId` is
-         * `skill-<seq>`, step 0, no tool call); absent for an `agent` call.
+         * `skill-<seq>`, step 0, no tool call); absent for an `Agent` call.
          */
         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
@@ -597,6 +780,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({
@@ -618,6 +826,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/message-context.d.ts

@@ -0,0 +1,79 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { EventPayload } from "./events.js";
+/** The name of an anonymous IM guest whose IM profile gives none. */
+export declare const ANONYMOUS_SENDER_NAME = "Anonymous guest";
+/** What the browser sent with a message (run context spec §3.4); both optional. */
+export interface BrowserContext {
+    timeZone?: string | undefined;
+    locale?: "zh" | "en" | undefined;
+}
+/**
+ * What an IM platform gave for the sender of a message (channel@1 `sender.timeZone` /
+ * `sender.locale`, normalized by {@link imSenderContext}); both optional.
+ */
+export interface ImSenderContext {
+    timeZone?: string | undefined;
+    locale?: "zh" | "en" | undefined;
+}
+/**
+ * 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 declare function imLocale(tag: unknown): "zh" | "en" | undefined;
+/**
+ * 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 declare function imSenderContext(sender: {
+    timeZone?: unknown;
+    locale?: unknown;
+}): ImSenderContext;
+/** How many of the person's latest web conversations {@link latestWebLocale} looks at. */
+export declare 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 declare function latestWebLocale(t: KernelSchemaDb, orgId: string, accountId: string): Promise<"zh" | "en" | 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 declare function recipientLocale(t: KernelSchemaDb, input: {
+    orgId: string;
+    accountId?: string | null | undefined;
+    im?: "zh" | "en" | undefined;
+}): Promise<"zh" | "en">;
+/** The `user_message` fields {@link readMessageContext} fills. */
+export type MessageContext = Pick<EventPayload<"user_message">, "sender" | "timeZone" | "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 declare function readMessageContext(t: KernelSchemaDb, input: {
+    orgId: string;
+    accountId: string;
+    /** An anonymous IM guest's IM profile name. */
+    senderName?: string | undefined;
+    browser?: BrowserContext | undefined;
+    /** An IM message: what the platform gave for the sender (maintainer decision 2026-11-08). */
+    im?: ImSenderContext | undefined;
+}): Promise<MessageContext>;