@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

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 (`environmentPathsText`); a summary covering it is followed by the latest
+     * one again.
+     */
+    ev("environment_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({
@@ -423,7 +557,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 +573,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 +585,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 +599,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).
+         * SkillWrite. Absent means none (every snapshot before phase B).
          */
         pinned: z
             .array(z.object({
@@ -518,6 +652,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 +674,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 +690,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 +775,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 +821,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/files.d.ts

@@ -1,5 +1,6 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
+import { ConversationAccess } from "./access.js";
 /**
  * A conversation's file outputs (UI refresh B, spec §5.8 / §5.9): the files the agent delivered
  * (`artifact_created`), grouped by `sourcePath` into versions, newest first. Read from the log on
@@ -44,17 +45,16 @@ export interface FileContent {
     originalType: string;
     truncated: boolean;
 }
-export interface ConversationFilesDeps {
-    db: KernelDb;
-    storage: Pick<StorageService, "kernel">;
-    /** Same visibility as the event stream (`ConversationsService.isAccessible`). */
-    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
-}
 /** Storage HEADs a files list sends at once (review M1). */
 export declare const HEAD_CONCURRENCY = 8;
 export declare class ConversationFiles {
-    private readonly d;
-    constructor(d: ConversationFilesDeps);
+    private readonly db;
+    private readonly storage;
+    /** Same visibility as the event stream. */
+    private readonly access;
+    constructor(db: KernelDb, storage: Pick<StorageService, "kernel">, 
+    /** Same visibility as the event stream. */
+    access: Pick<ConversationAccess, "isAccessible">);
     private checkAccess;
     /** Every delivery of the conversation in log order. */
     private deliveries;

package/dist/conversations/files.js

@@ -1,6 +1,19 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
 import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
 import { isInlineArtifactType, isTextArtifactType } from "./artifacts.js";
 /**
  * A conversation's file outputs (UI refresh B, spec §5.8 / §5.9): the files the agent delivered
@@ -65,20 +78,26 @@ async function mapLimit(xs, limit, fn) {
     await Promise.all(Array.from({ length: Math.min(limit, xs.length) }, worker));
     return out;
 }
-export class ConversationFiles {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationFiles = class ConversationFiles {
+    db;
+    storage;
+    access;
+    constructor(db, storage, 
+    /** Same visibility as the event stream. */
+    access) {
+        this.db = db;
+        this.storage = storage;
+        this.access = access;
     }
     async checkAccess(orgId, conversationId, viewer) {
         if (!UUID_RE.test(conversationId))
             throw conversationNotFound();
-        if (!(await this.d.isAccessible(orgId, conversationId, viewer)))
+        if (!(await this.access.isAccessible(orgId, conversationId, viewer)))
             throw conversationNotFound();
     }
     /** Every delivery of the conversation in log order. */
     async deliveries(conversationId) {
-        const rows = await this.d.db
+        const rows = await this.db
             .selectFrom("conversation_events")
             .select(["payload", "created_at"])
             .where("conversation_id", "=", conversationId)
@@ -115,7 +134,7 @@ export class ConversationFiles {
             start = at + 1;
         }
         const page = ordered.slice(start, start + opts.limit);
-        const store = this.d.storage.kernel(orgId);
+        const store = this.storage.kernel(orgId);
         const files = await mapLimit(page, HEAD_CONCURRENCY, async (g) => {
             const latest = g.at(-1);
             const head = await store.head(latest.objectKey);
@@ -152,7 +171,7 @@ export class ConversationFiles {
         await this.checkAccess(orgId, conversationId, viewer);
         if (!UUID_RE.test(fileId))
             throw artifactNotFound();
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("conversation_events")
             .select("payload")
             .where("conversation_id", "=", conversationId)
@@ -180,7 +199,7 @@ export class ConversationFiles {
         await this.checkAccess(orgId, conversationId, viewer);
         if (!UUID_RE.test(fileId))
             throw artifactNotFound();
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("conversation_events")
             .select("payload")
             .where("conversation_id", "=", conversationId)
@@ -195,7 +214,7 @@ export class ConversationFiles {
             throw new ApiError("conversation.artifact_not_previewable", "Only text files have content");
         }
         const max = Math.min(limit, FILE_CONTENT_MAX_BYTES);
-        const got = await this.d.storage
+        const got = await this.storage
             .kernel(orgId)
             .get(a.objectKey, { range: { start: 0, end: max - 1 } });
         if (!got)
@@ -210,4 +229,11 @@ export class ConversationFiles {
         const base = (a.contentType.split(";")[0] ?? "").trim().toLowerCase();
         return { body, contentType: "text/plain; charset=utf-8", originalType: base, truncated };
     }
-}
+};
+ConversationFiles = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(ConversationAccess))
+], ConversationFiles);
+export { ConversationFiles };

package/dist/conversations/idem-keys.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
+ * 避免客户端恰好选中内部键而命中别的事件。
+ */
+export declare const userMessageIdemKey: (clientMessageId: string) => string;

package/dist/conversations/idem-keys.js

@@ -0,0 +1,5 @@
+/**
+ * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
+ * 避免客户端恰好选中内部键而命中别的事件。
+ */
+export const userMessageIdemKey = (clientMessageId) => `msg:${clientMessageId}`;

package/dist/conversations/job-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the attachment cleanup had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The retired BullMQ repeatable scheduler of the cleanup (removed from Redis at worker start). */
+export declare const ATTACHMENT_CLEANUP_SCHEDULER_ID = "attachment-cleanup-hourly";

package/dist/conversations/job-ids.js

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the attachment cleanup had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The retired BullMQ repeatable scheduler of the cleanup (removed from Redis at worker start). */
+export const ATTACHMENT_CLEANUP_SCHEDULER_ID = "attachment-cleanup-hourly";