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

package/dist/conversations/conversations.service.js

@@ -11,6 +11,8 @@ import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { AgentLookup, visibleTo } from "../agents/agent-lookup.js";
+import { BackgroundTaskStopper } from "../background/stop.js";
+import { unbindConversation } from "../channels/threads.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -25,6 +27,27 @@ import { AttachmentsService } from "./attachments.service.js";
 import { EventLog } from "./event-log.js";
 import { userMessageIdemKey } from "./idem-keys.js";
 import { NO_SELECTION, planSelection, readSelection } from "./selection.js";
+/** Escapes `\`, `%` and `_` so user text is matched literally by `LIKE … ESCAPE '\'`. */
+export function escapeLike(s) {
+    return s.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * SQL for the activity of the conversation row aliased/named `ref` (a correlated subquery).
+ * A run waiting on its sub-agents (status waiting with `wait_expires_at`, set only for a
+ * `subagents` wait) is still working, so it reports `running`; only a wait for a person
+ * (approval, input) reports `waiting`.
+ */
+function activitySql(ref) {
+    const id = sql.ref(`${ref}.id`);
+    return sql `(
+    SELECT CASE
+      WHEN lr.status IN ('queued', 'running') THEN 'running'
+      WHEN lr.status = 'waiting' AND lr.wait_expires_at IS NOT NULL THEN 'running'
+      WHEN lr.status = 'waiting' THEN 'waiting' END
+    FROM capybara.runs lr WHERE lr.conversation_id = ${id}
+    ORDER BY lr.created_at DESC, lr.id DESC LIMIT 1
+  )`;
+}
 const notFound = () => new ApiError("conversation.not_found", "Conversation not found");
 export { userMessageIdemKey } from "./idem-keys.js";
 const COLUMNS = [
@@ -40,6 +63,7 @@ const COLUMNS = [
     "updated_at",
     "parent_conversation_id",
     "subagent_type",
+    "archived_at",
 ];
 function toView(r) {
     return {
@@ -55,6 +79,8 @@ function toView(r) {
         updatedAt: r.updated_at,
         parentConversationId: r.parent_conversation_id,
         subagentType: r.subagent_type,
+        archivedAt: r.archived_at,
+        activity: r.activity ?? null,
     };
 }
 /** The longest conversation title (characters, after trimming). */
@@ -90,6 +116,7 @@ let ConversationsService = class ConversationsService {
     content;
     attachments;
     invoker;
+    background;
     txHost;
     constructor(db, eventLog, agents, access, 
     /** Starts and stops the conversation's runs. */
@@ -101,7 +128,9 @@ let ConversationsService = class ConversationsService {
     /** Binds uploaded files to the conversation in the message's transaction. */
     attachments, 
     /** Renders a person's skill invocation (phase D). */
-    invoker, txHost) {
+    invoker, 
+    /** Stops a deleted conversation's background tasks. */
+    background, txHost) {
         this.db = db;
         this.eventLog = eventLog;
         this.agents = agents;
@@ -112,6 +141,7 @@ let ConversationsService = class ConversationsService {
         this.content = content;
         this.attachments = attachments;
         this.invoker = invoker;
+        this.background = background;
         this.txHost = txHost;
     }
     /**
@@ -139,6 +169,8 @@ let ConversationsService = class ConversationsService {
      * message's `clientMessageId` (`create_request_id`), so a retried send returns the same
      * conversation and event with `created: false`. An agent the caller cannot use →
      * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
+     * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
+     * the message when the send switched), so a client can seed the new conversation's log whole.
      */
     async createWithMessage(orgId, accountId, agentId, input) {
         const agent = await this.agents.get(orgId, agentId, accountId);
@@ -149,8 +181,9 @@ let ConversationsService = class ConversationsService {
         const extra = await this.resolveExtra(orgId, accountId, input);
         const invoked = await this.prepareSkill(orgId, agentId, undefined, agent.definition, input);
         const id = randomUUID();
-        const written = await this.createIn(id, orgId, accountId, agentId, input, next, extra, invoked);
-        if (!written) {
+        const all = await this.createIn(id, orgId, accountId, agentId, input, next, extra, invoked);
+        const written = all?.at(-1);
+        if (!all || !written) {
             const raced = await this.findCreated(orgId, accountId, agentId, input.clientMessageId);
             if (!raced)
                 throw new ApiError("conflict", "The conversation is being created; retry");
@@ -158,7 +191,7 @@ let ConversationsService = class ConversationsService {
         }
         await this.eventLog.notify(id, written.seq);
         await this.runs.ensureRun(id);
-        return { conversation: await this.rowView(id), event: written, created: true };
+        return { conversation: await this.rowView(id), event: written, events: all, created: true };
     }
     /** The conversation row and its first message (undefined: a concurrent retry committed first). */
     // its own transaction: the caller notifies and publishes after the commit
@@ -206,8 +239,10 @@ let ConversationsService = class ConversationsService {
         const event = await this.eventLog.findByIdem(row.id, userMessageIdemKey(clientMessageId));
         if (!event)
             return null;
+        // what the first send wrote: the log from its start up to the message
+        const events = (await this.eventLog.readAfter(row.id, 0, event.seq)).filter((e) => e.seq <= event.seq);
         await this.runs.ensureRun(row.id);
-        return { conversation: toView(row), event, created: false };
+        return { conversation: toView(row), event, events, created: false };
     }
     async rowView(id) {
         return toView(await this.db
@@ -231,6 +266,58 @@ let ConversationsService = class ConversationsService {
         await this.eventLog.publishChanged(conversationId, "title");
         return toView(row);
     }
+    /**
+     * Archives or unarchives a conversation (owner only, as {@link rename}). An archived
+     * conversation leaves the default lists but stays readable. Publishes `changed: archived`.
+     */
+    async setArchived(orgId, conversationId, accountId, archived) {
+        await this.writable(orgId, conversationId, accountId);
+        const row = await this.db
+            .updateTable("conversations")
+            .set({ archived_at: archived ? sql `now()` : null })
+            .where("id", "=", conversationId)
+            .returning(COLUMNS)
+            .executeTakeFirstOrThrow();
+        await this.eventLog.publishChanged(conversationId, "archived");
+        return toView(row);
+    }
+    /**
+     * Soft-deletes a conversation (owner only; a sub-agent's conversation is `conversation.read_only`):
+     * stops an active run, hides the conversation everywhere for its owner and drops its channel
+     * bindings, then stops every running background task in its sandbox (its sub-agents' too;
+     * outside the delete's transaction, a task whose sandbox cannot be reached ends `lost` with
+     * `kill_pending`). The tasks are stopped after the conversation is marked deleted, so no finish
+     * (the stops' own, or one the poller writes meanwhile) can wake a run on it: `ensureRun` refuses a
+     * deleted conversation (the stops' finishes carry `stoppedBy: "deletion"` as well). The event
+     * log, runs and trajectory stay (enterprise admins still see them).
+     */
+    async remove(orgId, conversationId, accountId) {
+        await this.writable(orgId, conversationId, accountId);
+        try {
+            await this.abort(orgId, conversationId, accountId);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "run.not_active"))
+                throw e;
+        }
+        await this.markDeleted(conversationId);
+        await this.background.stopForDeletedConversation(conversationId);
+        await this.eventLog.publishChanged(conversationId, "deleted");
+    }
+    // the publish happens after the commit, in the caller
+    async markDeleted(conversationId) {
+        await this.db
+            .updateTable("conversations")
+            .set({ deleted_at: sql `now()` })
+            .where("id", "=", conversationId)
+            .execute();
+        // Queued messages must not start a run on a deleted conversation
+        await this.db
+            .deleteFrom("conversation_queue")
+            .where("conversation_id", "=", conversationId)
+            .execute();
+        await unbindConversation(this.db.db, conversationId);
+    }
     /** 读会话：非所有者、或 agent 已对所有者不可用 → `conversation.not_found`。 */
     async get(orgId, conversationId, viewerAccountId) {
         const { kind: _kind, ...row } = await this.readable(orgId, conversationId, viewerAccountId);
@@ -255,6 +342,7 @@ let ConversationsService = class ConversationsService {
             .where("id", "=", conversationId)
             .where("org_id", "=", orgId)
             .where("account_id", "=", viewerAccountId)
+            .where("deleted_at", "is", null)
             // Hidden eval replay conversations (kind 'eval') are not reachable here (only the trajectory
             // viewer shows them); a sub-agent's conversation is, for its owner (sub-agents spec §6.1)
             .where("kind", "in", ["chat", "subagent"])
@@ -284,10 +372,13 @@ let ConversationsService = class ConversationsService {
         let q = this.db
             .selectFrom("conversations")
             .select(COLUMNS)
+            .select(activitySql("conversations").as("activity"))
             .where("org_id", "=", orgId)
             .where("account_id", "=", accountId)
             // 评测回放的隐藏对话（kind = 'eval'）不在「我的对话」里
             .where("kind", "=", "chat")
+            .where("deleted_at", "is", null)
+            .where("archived_at", opts.archived === true ? "is not" : "is", null)
             .where((eb) => eb.exists(eb
             .selectFrom("agents")
             .select(sql `1`.as("one"))
@@ -299,6 +390,12 @@ let ConversationsService = class ConversationsService {
             .limit(opts.limit);
         if (opts.agentId !== undefined)
             q = q.where("agent_id", "=", opts.agentId);
+        if (opts.q !== undefined) {
+            q = q.where(sql `conversations.title ILIKE ${`%${escapeLike(opts.q)}%`} ESCAPE '\\'`);
+        }
+        if (opts.state !== undefined) {
+            q = q.where(sql `${activitySql("conversations")} = ${opts.state}`);
+        }
         if (opts.after !== undefined) {
             const after = opts.after;
             q = q.where((eb) => sql `(${eb.ref("updated_at")}, ${eb.ref("id")}) < (
@@ -322,6 +419,11 @@ let ConversationsService = class ConversationsService {
             .where("agents.org_id", "=", orgId)
             .where("agents.deleted_at", "is", null)
             .where(visibleTo(accountId));
+        const archivedFilter = opts.archived === true ? sql `c.archived_at IS NOT NULL` : sql `c.archived_at IS NULL`;
+        const searchFilter = opts.q === undefined
+            ? sql ``
+            : sql `AND c.title ILIKE ${`%${escapeLike(opts.q)}%`} ESCAPE '\\'`;
+        const stateFilter = opts.state === undefined ? sql `` : sql `AND ${activitySql("c")} = ${opts.state}`;
         const cursor = opts.after === undefined
             ? sql ``
             : sql `WHERE (g.latest_at, g.agent_id) < (
@@ -332,6 +434,7 @@ let ConversationsService = class ConversationsService {
         SELECT c.agent_id, max(c.updated_at) AS latest_at
         FROM capybara.conversations c
         WHERE c.org_id = ${orgId} AND c.account_id = ${accountId} AND c.kind = 'chat'
+          AND c.deleted_at IS NULL AND ${archivedFilter} ${searchFilter} ${stateFilter}
           AND c.agent_id IN ${visibleAgents}
         GROUP BY c.agent_id
       ), page AS (
@@ -342,15 +445,18 @@ let ConversationsService = class ConversationsService {
       )
       SELECT page.agent_id, page.latest_at, v.definition ->> 'name' AS agent_name,
         cs.id, cs.org_id, cs.account_id, cs.title, cs.title_source, cs.selection, cs.last_seq,
-        cs.created_at, cs.updated_at, cs.parent_conversation_id, cs.subagent_type
+        cs.created_at, cs.updated_at, cs.parent_conversation_id, cs.subagent_type,
+        cs.archived_at, cs.activity
       FROM page
       JOIN capybara.agents a ON a.id = page.agent_id
       JOIN capybara.agent_versions v ON v.agent_id = a.id AND v.version = a.current_version
       CROSS JOIN LATERAL (
         SELECT c.id, c.org_id, c.account_id, c.title, c.title_source, c.selection, c.last_seq,
-          c.created_at, c.updated_at, c.parent_conversation_id, c.subagent_type
+          c.created_at, c.updated_at, c.parent_conversation_id, c.subagent_type,
+          c.archived_at, ${activitySql("c")} AS activity
         FROM capybara.conversations c
         WHERE c.org_id = ${orgId} AND c.account_id = ${accountId} AND c.kind = 'chat'
+          AND c.deleted_at IS NULL AND ${archivedFilter} ${searchFilter} ${stateFilter}
           AND c.agent_id = page.agent_id
         ORDER BY c.updated_at DESC, c.id DESC
         LIMIT ${opts.perGroup + 1}
@@ -377,7 +483,14 @@ let ConversationsService = class ConversationsService {
         }
         const page = groups.slice(0, opts.limit);
         const next = groups.length > opts.limit ? (page.at(-1)?.agent.id ?? null) : null;
-        return { groups: page, next };
+        // The archived entry's count ignores `q` and `state`
+        const counted = await sql `
+      SELECT count(*) AS n FROM capybara.conversations c
+      WHERE c.org_id = ${orgId} AND c.account_id = ${accountId} AND c.kind = 'chat'
+        AND c.deleted_at IS NULL AND c.archived_at IS NOT NULL
+        AND c.agent_id IN ${visibleAgents}
+    `.execute(this.db.db);
+        return { groups: page, next, archivedCount: Number(counted.rows[0]?.n ?? 0) };
     }
     /**
      * The sub-agents of a conversation, newest first (sub-agents spec §14.3); owner only, as
@@ -544,6 +657,15 @@ let ConversationsService = class ConversationsService {
                 this.userMessage(accountId, input, extra, [], invoked),
             ]);
         }
+        // The message is written: it brings an archived conversation back into the default lists
+        if (conv.archivedAt !== null) {
+            await this.db
+                .updateTable("conversations")
+                .set({ archived_at: null })
+                .where("id", "=", conversationId)
+                .execute();
+            await this.eventLog.publishChanged(conversationId, "archived");
+        }
         await this.runs.ensureRun(conversationId);
         return event;
     }
@@ -551,7 +673,8 @@ let ConversationsService = class ConversationsService {
     // its own transaction: the caller notifies and publishes after the commit
     async postIn(orgId, conversationId, accountId, input, next, extra, invoked) {
         const blocks = await this.bindIn(orgId, conversationId, accountId, input.files ?? []);
-        return this.writeMessage(conversationId, accountId, input, next, extra, blocks, invoked);
+        const written = await this.writeMessage(conversationId, accountId, input, next, extra, blocks, invoked);
+        return written.at(-1);
     }
     /**
      * The selection a message switches to, or null when it changes nothing. A model equal to the
@@ -591,7 +714,8 @@ let ConversationsService = class ConversationsService {
     }
     /**
      * Writes the message (preceded by its `model_switched` when it switches) inside `t` and updates
-     * `conversations.selection`; returns the `user_message` event. The caller notifies after commit.
+     * `conversations.selection`; returns the events written, in seq order (the `user_message`
+     * last). The caller notifies after commit.
      */
     async writeMessage(conversationId, accountId, input, next, extra, blocks, invoked) {
         const events = [];
@@ -616,7 +740,7 @@ let ConversationsService = class ConversationsService {
                 .where("id", "=", conversationId)
                 .execute();
         }
-        return written.at(-1);
+        return written;
     }
     /**
      * Renders the message's skill invocation (phase D), or undefined when it has none. Resolved
@@ -718,6 +842,9 @@ let ConversationsService = class ConversationsService {
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ConversationsService.prototype, "createIn", null);
+__decorate([
+    Transactional()
+], ConversationsService.prototype, "markDeleted", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], ConversationsService.prototype, "postIn", null);
@@ -739,6 +866,7 @@ ConversationsService = __decorate([
     __param(7, Inject(ConnectorContent)),
     __param(8, Inject(AttachmentsService)),
     __param(9, Inject(SkillInvoker)),
-    __param(10, Inject(TransactionHost))
+    __param(10, Inject(BackgroundTaskStopper)),
+    __param(11, Inject(TransactionHost))
 ], ConversationsService);
 export { ConversationsService };

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

@@ -64,7 +64,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 运行的唯一事实来源。

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 {

package/dist/conversations/events.d.ts

@@ -272,6 +272,11 @@ 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";
+        }>>;
+        triggerSeq: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"model_call">;
@@ -406,7 +411,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">;
@@ -496,6 +503,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;
@@ -659,6 +673,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;
@@ -754,6 +772,13 @@ 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;
         kind: z.ZodEnum<{
@@ -799,6 +824,29 @@ 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";
+        }>>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"compaction_summary">;
     payload: z.ZodObject<{
@@ -859,6 +907,16 @@ export type ConversationEvent = ConversationEventBody & {
     runId: string | null;
     createdAt: Date;
 };
+/** An event a run absorbs at a step boundary: a person's message or a finished background task. */
+export type AbsorbableEvent = Extract<ConversationEvent, {
+    type: "user_message" | "background_task_finished";
+}>;
+/**
+ * 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` 事件最多的附件数。 */
@@ -239,6 +249,14 @@ 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).
+         */
+        trigger: z.enum(["message", "background_task"]).optional(),
+        /** A wake run's boundary: the seq of the finish that woke it (full-run replay seeds from it). */
+        triggerSeq: seqNo.optional(),
     })),
     ev("model_call", z.object({
         step: count,
@@ -326,14 +344,18 @@ 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() })),
     /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
@@ -392,6 +414,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({
@@ -575,6 +598,8 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         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({
@@ -609,6 +634,30 @@ 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.
+         */
+        stoppedBy: z.enum(["person", "deletion"]).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 +679,12 @@ 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";
 /**
  * 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>;

package/dist/conversations/queue.js

@@ -129,7 +129,18 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
             .where("id", "=", conversationId)
             .execute();
     }
-    return { event: written.at(-1), switched: next !== null };
+    // As a direct send: the message brings an archived conversation back into the default lists
+    const unarchived = await t
+        .updateTable("conversations")
+        .set({ archived_at: null })
+        .where("id", "=", conversationId)
+        .where("archived_at", "is not", null)
+        .executeTakeFirst();
+    return {
+        event: written.at(-1),
+        switched: next !== null,
+        unarchived: Number(unarchived.numUpdatedRows) > 0,
+    };
 }
 /** The model of the conversation agent's current version (inside `t`). */
 async function agentModel(t, conversationId) {
@@ -206,7 +217,7 @@ export const queueFull = () => new ApiError("conversation.queue_full", `A conver
  * when the queue is empty. An item whose message is already in the log (a retried enqueue after it
  * was sent) is dropped and the next one is taken. A head item whose skill can no longer be invoked
  * stays queued and the queue pauses (`skill_not_invocable`): `{ paused }`. The caller notifies
- * after commit.
+ * after commit (and publishes `archived` when the send unarchived the conversation).
  */
 export async function dispatchQueuedIn(t, eventLog, conversationId) {
     for (;;) {

package/dist/conversations/queue.service.js

@@ -240,11 +240,13 @@ let ConversationQueue = class ConversationQueue {
      */
     async sendNow(orgId, conversationId, accountId, itemId) {
         await this.conversations.writable(orgId, conversationId, accountId);
-        const { event, fresh, switched } = await this.sendNowIn(conversationId, itemId);
+        const { event, fresh, switched, unarchived } = await this.sendNowIn(conversationId, itemId);
         if (fresh)
             await this.eventLog.notify(conversationId, event.seq);
         if (switched)
             await this.eventLog.publishChanged(conversationId, "selection");
+        if (unarchived)
+            await this.eventLog.publishChanged(conversationId, "archived");
         await this.eventLog.publishChanged(conversationId, "queue");
         await this.runs.ensureRun(conversationId);
         return event;