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

package/dist/conversations/conversations.service.js

@@ -1,14 +1,60 @@
+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 { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { visibleTo } from "../agents/agents.service.js";
+import { AgentLookup, visibleTo } from "../agents/agent-lookup.js";
+import { BackgroundTaskStopper } from "../background/stop.js";
+import { unbindConversation } from "../channels/threads.js";
+import { ConversationEnvironments, } from "../environments/conversation-environments.js";
 import { ApiError } from "../errors.js";
-import { NO_SELECTION, planSelection, readSelection, sameModel, sameSelection, } from "./selection.js";
-const notFound = () => new ApiError("conversation.not_found", "Conversation not found");
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { RunControl as RunControlService } from "../runtime/run-control.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+import { SkillInvoker } from "../skills/invoke.js";
+import { ConnectorContent } from "../tools/connector-content.js";
+import { ConversationAccess, parentReachable } from "./access.js";
+import { readAgentTree } from "./agent-tree.js";
+import { AttachmentsService } from "./attachments.service.js";
+import { EventLog } from "./event-log.js";
+import { userMessageIdemKey } from "./idem-keys.js";
+import { readMessageContext, } from "./message-context.js";
+import { NO_SELECTION, planSelection, readSelection } from "./selection.js";
+import { conversationTree } from "./tree.js";
+/** Escapes `\`, `%` and `_` so user text is matched literally by `LIKE … ESCAPE '\'`. */
+export function escapeLike(s) {
+    return s.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
 /**
- * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
- * 避免客户端恰好选中内部键而命中别的事件。
+ * 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`.
  */
-export const userMessageIdemKey = (clientMessageId) => `msg:${clientMessageId}`;
+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 = [
     "id",
     "org_id",
@@ -22,6 +68,8 @@ const COLUMNS = [
     "updated_at",
     "parent_conversation_id",
     "subagent_type",
+    "archived_at",
+    "environment_id",
 ];
 function toView(r) {
     return {
@@ -37,29 +85,18 @@ function toView(r) {
         updatedAt: r.updated_at,
         parentConversationId: r.parent_conversation_id,
         subagentType: r.subagent_type,
+        archivedAt: r.archived_at,
+        environmentId: r.environment_id,
+        activity: r.activity ?? null,
     };
 }
 /** The longest conversation title (characters, after trimming). */
 export const CONVERSATION_TITLE_MAX_CHARS = 120;
 /**
- * A sub-agent's conversation is reached through its parent (sub-agents spec §6.1, review m6, the
- * same rule as its trajectory): the parent is a chat conversation of the same owner whose agent is
- * not deleted and still visible to the viewer. Any other kind passes. The child's own `agent_id`
- * (the dispatched agent for an org agent, §5.5) is checked on top by the callers.
+ * How far back a `before` page of events reaches past its `limit` for the start of a turn (history
+ * paging spec §2); a longer run starts mid-run.
  */
-const parentReachable = (viewerAccountId) => (eb) => eb.or([
-    eb("conversations.kind", "<>", "subagent"),
-    eb.exists(eb
-        .selectFrom("conversations as p")
-        .innerJoin("agents", "agents.id", "p.agent_id")
-        .select(sql `1`.as("one"))
-        .whereRef("p.id", "=", "conversations.parent_conversation_id")
-        .whereRef("p.org_id", "=", "conversations.org_id")
-        .where("p.account_id", "=", viewerAccountId)
-        .where("p.kind", "=", "chat")
-        .where("agents.deleted_at", "is", null)
-        .where(visibleTo(viewerAccountId))),
-]);
+export const EVENTS_TURN_EXTEND = 2000;
 /** The sums of the `usage` events matching `where` (over `conversation_events e`), one row. */
 const usageSums = (where) => sql `
   SELECT
@@ -80,48 +117,76 @@ const toUsage = (r) => ({
  * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
  * 不可用时会话也按不存在处理（`conversation.not_found`）。
  */
-export class ConversationsService {
+let ConversationsService = class ConversationsService {
     db;
     eventLog;
     agents;
+    access;
     runs;
+    providers;
     log;
-    resolveAttachments;
-    bindFiles;
-    models;
+    content;
+    attachments;
     invoker;
-    constructor(db, eventLog, agents, runs, log, resolveAttachments, bindFiles, 
+    background;
+    environments;
+    txHost;
+    constructor(db, eventLog, agents, access, 
+    /** Starts and stops the conversation's runs. */
+    runs, 
     /** Resolves a switched-to model and its declared parameters (UI refresh B). */
-    models, 
-    /** Renders a person's skill invocation (phase D); without it `skill` is refused. */
-    invoker) {
+    providers, log, 
+    /** Reads `@` resources with the sender's credentials. */
+    content, 
+    /** Binds uploaded files to the conversation in the message's transaction. */
+    attachments, 
+    /** Renders a person's skill invocation (phase D). */
+    invoker, 
+    /** Stops a deleted conversation's background tasks. */
+    background, 
+    /** The environment a new conversation is bound to (environments spec §4.1 item 1). */
+    environments, txHost) {
         this.db = db;
         this.eventLog = eventLog;
         this.agents = agents;
+        this.access = access;
         this.runs = runs;
+        this.providers = providers;
         this.log = log;
-        this.resolveAttachments = resolveAttachments;
-        this.bindFiles = bindFiles;
-        this.models = models;
+        this.content = content;
+        this.attachments = attachments;
         this.invoker = invoker;
+        this.background = background;
+        this.environments = environments;
+        this.txHost = txHost;
     }
     /**
      * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
      * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
      */
     kickRun(conversationId) {
-        if (!this.runs)
-            return;
         this.runs
             .ensureRun(conversationId)
-            .catch((err) => this.log?.warn("ensureRun on conversation open failed", { conversationId, err }));
+            .catch((err) => this.log.warn("ensureRun on conversation open failed", { conversationId, err }));
     }
-    /** 新建会话；agent 对该账号不可用 → `agent.not_found`。 */
-    async create(orgId, accountId, agentId) {
+    /**
+     * Creates an empty conversation bound to its environment (`pick`, see
+     * {@link ConversationEnvironments.forNew}); an agent the account cannot use →
+     * `agent.not_found`, an environment it may not use → `environment.not_found` /
+     * `environment.unavailable`, and nothing is created.
+     */
+    async create(orgId, accountId, agentId, pick = {}) {
         await this.agents.get(orgId, agentId, accountId);
+        const environmentId = await this.environments.forNew(orgId, accountId, pick);
         const row = await this.db
             .insertInto("conversations")
-            .values({ id: randomUUID(), org_id: orgId, agent_id: agentId, account_id: accountId })
+            .values({
+            id: randomUUID(),
+            org_id: orgId,
+            agent_id: agentId,
+            account_id: accountId,
+            environment_id: environmentId,
+        })
             .returning(COLUMNS)
             .executeTakeFirstOrThrow();
         return toView(row);
@@ -132,48 +197,56 @@ export 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) {
+    async createWithMessage(orgId, accountId, agentId, input, pick = {}) {
         const agent = await this.agents.get(orgId, agentId, accountId);
         const prior = await this.findCreated(orgId, accountId, agentId, input.clientMessageId);
         if (prior)
             return prior;
-        this.checkFilesSupported(input);
-        const next = await this.planSwitch(agent.definition, NO_SELECTION, input);
+        const environmentId = await this.environments.forNew(orgId, accountId, pick);
+        const next = await this.planSwitch(orgId, agent.definition, NO_SELECTION, input);
         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.db.transaction().execute(async (t) => {
-            const row = await t
-                .insertInto("conversations")
-                .values({
-                id,
-                org_id: orgId,
-                agent_id: agentId,
-                account_id: accountId,
-                create_request_id: input.clientMessageId,
-            })
-                .onConflict((oc) => oc
-                .columns(["org_id", "account_id", "create_request_id"])
-                .where("create_request_id", "is not", null)
-                .doNothing())
-                .returning("id")
-                .executeTakeFirst();
-            // a concurrent retry committed first: answer with its conversation below
-            if (!row)
-                return undefined;
-            const blocks = await this.bindIn(t, orgId, id, accountId, input.files ?? []);
-            return this.writeMessage(t, id, accountId, input, next, extra, blocks, invoked);
-        });
-        if (!written) {
+        const all = await this.createIn({ id, orgId, accountId, agentId, environmentId }, 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");
             return raced;
         }
         await this.eventLog.notify(id, written.seq);
-        await this.runs?.ensureRun(id);
-        return { conversation: await this.rowView(id), event: written, created: true };
+        await this.runs.ensureRun(id);
+        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
+    async createIn(conv, input, next, extra, invoked) {
+        const { id, orgId, accountId } = conv;
+        const row = await this.db
+            .insertInto("conversations")
+            .values({
+            id,
+            org_id: orgId,
+            agent_id: conv.agentId,
+            account_id: accountId,
+            environment_id: conv.environmentId,
+            create_request_id: input.clientMessageId,
+        })
+            .onConflict((oc) => oc
+            .columns(["org_id", "account_id", "create_request_id"])
+            .where("create_request_id", "is not", null)
+            .doNothing())
+            .returning("id")
+            .executeTakeFirst();
+        // a concurrent retry committed first: answer with its conversation below
+        if (!row)
+            return undefined;
+        const blocks = await this.bindIn(orgId, id, accountId, input.files ?? []);
+        return this.writeMessage(orgId, id, accountId, input, next, extra, blocks, invoked);
     }
     /**
      * The conversation (and its first event) an earlier first send with this id created. The id used
@@ -197,8 +270,10 @@ export class ConversationsService {
         const event = await this.eventLog.findByIdem(row.id, userMessageIdemKey(clientMessageId));
         if (!event)
             return null;
-        await this.runs?.ensureRun(row.id);
-        return { conversation: toView(row), event, created: false };
+        // 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, events, created: false };
     }
     async rowView(id) {
         return toView(await this.db
@@ -222,6 +297,65 @@ export 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, 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`), then every active run of its sub-agent tree (agent map spec §10). 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 (super 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);
+        // after the mark, so no finish or delivery of the stops below can start a run on the deleted
+        // root (`ensureRun` refuses it). The sandbox's tasks stop first, so the sub-agents' tasks end
+        // as a deletion; the tree stop then only stops a task a sub-agent started in between
+        // (`stoppedBy: "subagent_end"`, which never wakes either)
+        await this.background.stopForDeletedConversation(conversationId);
+        // the whole tree stops (agent map spec §10)
+        await this.runs.stopTree(conversationId, accountId, { includeSelf: false });
+        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);
@@ -246,6 +380,7 @@ export 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"])
@@ -263,35 +398,9 @@ export class ConversationsService {
         }
         return row;
     }
-    /**
-     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
-     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
-     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
-     */
-    async isAccessible(orgId, conversationId, viewerAccountId) {
-        const row = await this.db
-            .selectFrom("conversations")
-            .select("conversations.id")
-            .where("conversations.id", "=", conversationId)
-            .where("conversations.org_id", "=", orgId)
-            .where("conversations.account_id", "=", viewerAccountId)
-            .where("conversations.kind", "in", ["chat", "subagent"])
-            .where(parentReachable(viewerAccountId))
-            .where((eb) => eb.and([
-            eb.exists(eb
-                .selectFrom("accounts")
-                .select(sql `1`.as("one"))
-                .where("accounts.id", "=", viewerAccountId)
-                .where("accounts.status", "=", "active")),
-            eb.exists(eb
-                .selectFrom("agents")
-                .select(sql `1`.as("one"))
-                .whereRef("agents.id", "=", "conversations.agent_id")
-                .where("agents.deleted_at", "is", null)
-                .where(visibleTo(viewerAccountId))),
-        ]))
-            .executeTakeFirst();
-        return row !== undefined;
+    /** The stream's visibility check ({@link ConversationAccess.isAccessible}). */
+    isAccessible(orgId, conversationId, viewerAccountId) {
+        return this.access.isAccessible(orgId, conversationId, viewerAccountId);
     }
     /**
      * 我的会话，最近更新的在前；只含 agent 仍可用的会话。`after` 为上一页最后一个会话的 id，
@@ -301,10 +410,13 @@ export 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"))
@@ -316,6 +428,12 @@ export 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")}) < (
@@ -339,6 +457,11 @@ export 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) < (
@@ -349,6 +472,7 @@ export 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 (
@@ -359,21 +483,24 @@ export 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.environment_id, 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, c.environment_id, ${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}
       ) cs
       ORDER BY page.latest_at DESC, page.agent_id DESC, cs.updated_at DESC, cs.id DESC
-    `.execute(this.db);
+    `.execute(this.db.db);
         const groups = [];
         let current;
         for (const r of rows) {
@@ -394,7 +521,14 @@ export 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
@@ -459,7 +593,7 @@ export class ConversationsService {
       CROSS JOIN LATERAL (${usageSums(sql `e.conversation_id = c.id`)}) u
       LEFT JOIN described d ON d.id = c.id
       ORDER BY c.created_at DESC, c.id DESC
-    `.execute(this.db);
+    `.execute(this.db.db);
         const subagents = rows.slice(0, opts.limit).map((r) => ({
             id: r.id,
             agentType: r.subagent_type ?? "",
@@ -476,26 +610,38 @@ export class ConversationsService {
         return { subagents, next };
     }
     /**
-     * A conversation's token usage: its own `usage` events (compaction included) plus those of its
-     * sub-agents (sub-agents spec §8.3), whose logs keep their own. Owner only, as {@link get}.
+     * The agent tree of a root conversation (agent map spec §8, §9.2): the root and every sub-agent
+     * below it with status, model, time, tokens and tool calls. Owner only, as {@link isAccessible};
+     * a sub-agent's id (not a root) is `conversation.not_found` too.
+     */
+    async agentTree(orgId, conversationId, viewerAccountId) {
+        if (!(await this.isAccessible(orgId, conversationId, viewerAccountId)))
+            throw notFound();
+        const root = await readAgentTree(this.db.db, orgId, conversationId);
+        if (!root)
+            throw notFound();
+        return { root };
+    }
+    /**
+     * A conversation's token usage: its own `usage` events (compaction included) plus those of every
+     * sub-agent below it, at any depth (sub-agents spec §8.3, agent map spec §6: every descendant
+     * counts toward the root; `conversationTree`), whose logs keep their own. Owner only, as
+     * {@link get}.
      */
     async usage(orgId, conversationId, viewerAccountId) {
         if (!(await this.isAccessible(orgId, conversationId, viewerAccountId)))
             throw notFound();
-        const { rows } = await sql `${usageSums(sql `e.conversation_id IN (
-        SELECT ${conversationId}::text
-        UNION ALL
-        SELECT c.id FROM capybara.conversations c
-        WHERE c.parent_conversation_id = ${conversationId} AND c.kind = 'subagent'
-      )`)}`.execute(this.db);
+        const ids = (await conversationTree(this.db.db, conversationId)).map((c) => c.id);
+        const { rows } = await sql `${usageSums(sql `e.conversation_id IN (${sql.join(ids.length > 0 ? ids : [conversationId])})`)}`.execute(this.db.db);
         const row = rows[0];
         return row
             ? toUsage(row)
             : { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
     }
     /**
-     * The conversation whose sandbox `conversationId` works in: a sub-agent's is its parent's
-     * (sub-agents spec §10.1), any other its own. Call only after an access check.
+     * The conversation whose sandbox `conversationId` works in: a sub-agent's is its root
+     * conversation's at any depth (sub-agents spec §10.1, agent map spec §6), any other its own. Call
+     * only after an access check.
      */
     async sandboxConversationOf(orgId, conversationId) {
         const row = await this.db
@@ -504,7 +650,9 @@ export class ConversationsService {
             .where("id", "=", conversationId)
             .where("org_id", "=", orgId)
             .executeTakeFirst();
-        return row?.parent_conversation_id ?? conversationId;
+        if (!row?.parent_conversation_id)
+            return conversationId;
+        return rootConversationOf(this.db.db, row.parent_conversation_id);
     }
     /** 读事件（先做 `get` 的可见性判定）；顺带不阻塞地 {@link kickRun}。 */
     async listEvents(orgId, conversationId, viewerAccountId, afterSeq, limit) {
@@ -512,6 +660,16 @@ export class ConversationsService {
         this.kickRun(conversationId);
         return this.eventLog.readAfter(conversationId, afterSeq, limit);
     }
+    /**
+     * The turn-aligned page of events before `beforeSeq` (`null`: the log's last page), with how
+     * many runs started before it ({@link EventLog.readTurnPageBefore}; history paging spec §2).
+     * Visibility as {@link get}; kicks a stalled run as {@link listEvents} does.
+     */
+    async listEventsBefore(orgId, conversationId, viewerAccountId, beforeSeq, limit) {
+        await this.get(orgId, conversationId, viewerAccountId);
+        this.kickRun(conversationId);
+        return this.eventLog.readTurnPageBefore(conversationId, beforeSeq, limit, EVENTS_TURN_EXTEND);
+    }
     /**
      * 追加一条用户消息；带 `clientMessageId` 时重复提交返回同一事件。写入后调用 `ensureRun`：
      * 没有进行中的运行时投递一轮；运行中则由当前运行在步骤间隙吸收，或在它结束时再次 `ensureRun`。
@@ -529,13 +687,12 @@ export class ConversationsService {
         const conv = await this.writable(orgId, conversationId, accountId);
         const refs = input.attachments ?? [];
         const files = input.files ?? [];
-        this.checkFilesSupported(input);
         // A retry returns the written event (no resource read, no file check, no skill resolution)
         if ((refs.length > 0 || files.length > 0 || input.skill !== undefined) &&
             input.clientMessageId !== undefined) {
             const existing = await this.eventLog.findByIdem(conversationId, userMessageIdemKey(input.clientMessageId));
             if (existing) {
-                await this.runs?.ensureRun(conversationId);
+                await this.runs.ensureRun(conversationId);
                 return existing;
             }
         }
@@ -545,48 +702,54 @@ export class ConversationsService {
             : undefined;
         const next = agent === undefined || (input.model === undefined && input.effort === undefined)
             ? null
-            : await this.planSwitch(agent, conv.selection, input);
+            : await this.planSwitch(orgId, agent, conv.selection, input);
         const extra = await this.resolveExtra(orgId, accountId, input);
         const invoked = agent === undefined
             ? undefined
             : await this.prepareSkill(orgId, conv.agentId, conversationId, agent, input);
-        let event;
-        if (files.length > 0 || next !== null) {
-            event = await this.db.transaction().execute(async (t) => {
-                const blocks = await this.bindIn(t, orgId, conversationId, accountId, files);
-                return this.writeMessage(t, conversationId, accountId, input, next, extra, blocks, invoked);
-            });
-            await this.eventLog.notify(conversationId, event.seq);
-            if (next !== null)
-                await this.eventLog.publishChanged(conversationId, "selection");
-        }
-        else {
-            [event] = await this.eventLog.append(conversationId, [
-                this.userMessage(accountId, input, extra, [], invoked),
-            ]);
+        // one transaction: the sender, time zone and language are read with the message's write
+        // (run context spec §3.2)
+        const event = await this.postIn(orgId, conversationId, accountId, input, next, extra, invoked);
+        await this.eventLog.notify(conversationId, event.seq);
+        if (next !== null)
+            await this.eventLog.publishChanged(conversationId, "selection");
+        // 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);
+        await this.runs.ensureRun(conversationId);
         return event;
     }
+    /**
+     * Writes a message in one transaction: binds its files, reads its sender context and appends it
+     * (after its `model_switched` when it switches).
+     */
+    // 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 ?? []);
+        const written = await this.writeMessage(orgId, 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
      * agent's means "back to the agent's model" (null); a model change without `effort` resets the
      * effort. The target model must resolve (`agent.model_unavailable`) and declare the effort
-     * (`validation_failed`). Resolving is the agent editor's check: providers are deployment-scoped
-     * and serve chat models only. If per-org provider enablement is added, this check and the run
-     * worker's `fallBackIfUnavailable` must follow it.
+     * (`validation_failed`). Resolving is the agent editor's check, for the org (its effective
+     * provider config, spec B §5.5) and its disabled lists: a model the platform or the org disabled,
+     * or a non-chat model, is refused (spec B §5.3), as the run worker's `fallBackIfUnavailable` falls
+     * back from it.
      */
-    async planSwitch(agent, current, input) {
+    async planSwitch(orgId, agent, current, input) {
         const next = planSelection(agent.model, current, input);
         if (next === null)
             return null;
         const { model, effort } = next;
-        if (!this.models) {
-            throw new ApiError("validation_failed", "Request validation failed", [
-                { path: "model", message: "Model switching is not supported" },
-            ]);
-        }
-        const { info } = await this.models.resolve(model ?? agent.model);
+        const { info } = await this.providers.resolve(orgId, model ?? agent.model);
         if (effort !== null) {
             const knob = info.parameters.find((p) => p.key === "effort");
             const values = knob?.schema?.enum ?? [];
@@ -607,13 +770,14 @@ export class ConversationsService {
         if (pick.model === undefined && pick.effort === undefined)
             return;
         const agent = await this.agents.get(orgId, conv.agentId, accountId);
-        await this.planSwitch(agent.definition, conv.selection, pick);
+        await this.planSwitch(orgId, agent.definition, conv.selection, pick);
     }
     /**
      * 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(t, conversationId, accountId, input, next, extra, blocks, invoked) {
+    async writeMessage(orgId, conversationId, accountId, input, next, extra, blocks, invoked) {
         const events = [];
         if (next !== null) {
             events.push({
@@ -624,9 +788,17 @@ export class ConversationsService {
                 payload: { ...next, byAccountId: accountId, reason: "user" },
             });
         }
-        events.push(this.userMessage(accountId, input, extra, blocks, invoked));
-        const written = await this.eventLog.append(conversationId, events, t);
+        const context = await readMessageContext(this.db.db, {
+            orgId,
+            accountId,
+            senderName: input.senderName,
+            browser: { timeZone: input.timeZone, locale: input.locale },
+            im: input.im,
+        });
+        events.push(this.userMessage(accountId, input, extra, blocks, invoked, context));
+        const written = await this.eventLog.appendIn(conversationId, events);
         if (next !== null) {
+            const t = this.db.db;
             // the cache follows the log (a retried message's switch may be an old, deduped event that a
             // later switch already replaced), read under the row lock append took
             await t
@@ -635,7 +807,7 @@ export 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
@@ -644,11 +816,6 @@ export class ConversationsService {
     async prepareSkill(orgId, agentId, conversationId, agent, input) {
         if (input.skill === undefined)
             return undefined;
-        if (!this.invoker) {
-            throw new ApiError("validation_failed", "Request validation failed", [
-                { path: "skill", message: "Skill invocation is not supported" },
-            ]);
-        }
         return this.invoker.prepare({
             orgId,
             agentId,
@@ -669,14 +836,6 @@ export class ConversationsService {
         const agent = await this.agents.get(orgId, conv.agentId, accountId);
         return this.prepareSkill(orgId, conv.agentId, conv.id, agent.definition, input);
     }
-    /** `files` need the attachments service (shared with the queue). */
-    checkFilesSupported(input) {
-        if ((input.files?.length ?? 0) > 0 && !this.bindFiles) {
-            throw new ApiError("validation_failed", "Request validation failed", [
-                { path: "files", message: "Files are not supported" },
-            ]);
-        }
-    }
     /**
      * Reads the `@` resources with the sender's credentials (nothing when there are none). Shared
      * with the queue, which reads them when a message is queued (decision 15).
@@ -685,20 +844,15 @@ export class ConversationsService {
         const refs = input.attachments ?? [];
         if (refs.length === 0)
             return { blocks: [], attachments: [] };
-        if (!this.resolveAttachments) {
-            throw new ApiError("validation_failed", "Request validation failed", [
-                { path: "attachments", message: "Attachments are not supported" },
-            ]);
-        }
-        return this.resolveAttachments(orgId, accountId, refs);
+        return this.content.resolveAttachments(orgId, accountId, refs);
     }
     /** Binds uploaded files inside the message's (or queue item's) transaction; none → no blocks. */
-    async bindIn(t, orgId, conversationId, accountId, files) {
-        if (files.length === 0 || !this.bindFiles)
+    async bindIn(orgId, conversationId, accountId, files) {
+        if (files.length === 0)
             return [];
-        return this.bindFiles(t, orgId, conversationId, accountId, files);
+        return this.attachments.bindForMessage(orgId, conversationId, accountId, files);
     }
-    userMessage(accountId, input, extra, fileBlocks, invoked) {
+    userMessage(accountId, input, extra, fileBlocks, invoked, context) {
         // a skill invocation's rendered text replaces the typed arguments as content[0]
         const text = invoked?.text ?? input.text;
         return {
@@ -715,6 +869,7 @@ export class ConversationsService {
                 ],
                 ...(extra.attachments.length > 0 && { attachments: extra.attachments }),
                 authorAccountId: accountId,
+                ...context,
                 ...(input.clientMessageId !== undefined && { clientMessageId: input.clientMessageId }),
                 ...(input.retryOf !== undefined && { retryOf: input.retryOf }),
                 ...(invoked !== undefined && { skill: invoked.skill }),
@@ -725,9 +880,26 @@ export class ConversationsService {
      * 中止会话当前的运行（queued / running / waiting）：返回 runId；没有 → `run.not_active`。
      * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
      * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
+     *
+     * A root conversation's stop stops only its own run: its background sub-agents keep working
+     * (agent map spec §6). A sub-agent's conversation (its owner, from the agent map) stops that
+     * sub-agent with every descendant (`RunControl.stopTree`); `run.not_active` when nothing in that
+     * subtree runs, else the sub-agent's latest run id.
      */
     async abort(orgId, conversationId, accountId) {
-        await this.get(orgId, conversationId, accountId);
+        const conv = await this.get(orgId, conversationId, accountId);
+        if (conv.parentConversationId !== null) {
+            const latest = await this.db
+                .selectFrom("runs")
+                .select("id")
+                .where("conversation_id", "=", conversationId)
+                .orderBy("created_at", "desc")
+                .executeTakeFirst();
+            const n = await this.runs.stopTree(conversationId, accountId);
+            if (n === 0 || !latest)
+                throw new ApiError("run.not_active", "No active run to abort");
+            return latest.id;
+        }
         const run = await this.db
             .selectFrom("runs")
             .select(["id", "status"])
@@ -735,20 +907,52 @@ export class ConversationsService {
             .where("status", "in", ["queued", "running", "waiting"])
             .orderBy("created_at", "desc")
             .executeTakeFirst();
-        if (!run || !this.runs)
+        if (!run)
             throw new ApiError("run.not_active", "No active run to abort");
+        const runs = this.runs;
         // 等待中：直接结束；没成功（刚被续跑、已回到 queued）则按下面的常规路径中止。
-        if (run.status === "waiting" &&
-            (await this.runs.abortWaiting(conversationId, run.id, accountId))) {
+        if (run.status === "waiting" && (await runs.abortWaiting(conversationId, run.id, accountId))) {
             this.kickRun(conversationId);
             return run.id;
         }
         // 孤儿运行没有 worker 在听中止广播：直接写成 aborted，之后再看有没有等待中的消息要起新一轮。
-        if (await this.runs.abortIfOrphaned(conversationId, run.id, accountId)) {
+        if (await runs.abortIfOrphaned(conversationId, run.id, accountId)) {
             this.kickRun(conversationId);
             return run.id;
         }
-        await this.runs.requestAbort(run.id, accountId);
+        await runs.requestAbort(run.id, accountId);
         return run.id;
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationsService.prototype, "createIn", null);
+__decorate([
+    Transactional()
+], ConversationsService.prototype, "markDeleted", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationsService.prototype, "postIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ConversationsService.prototype, "writeMessage", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ConversationsService.prototype, "bindIn", null);
+ConversationsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(AgentLookup)),
+    __param(3, Inject(ConversationAccess)),
+    __param(4, Inject(RunControlService)),
+    __param(5, Inject(ProviderRegistry)),
+    __param(6, Inject(KERNEL_LOGGER)),
+    __param(7, Inject(ConnectorContent)),
+    __param(8, Inject(AttachmentsService)),
+    __param(9, Inject(SkillInvoker)),
+    __param(10, Inject(BackgroundTaskStopper)),
+    __param(11, Inject(ConversationEnvironments)),
+    __param(12, Inject(TransactionHost))
+], ConversationsService);
+export { ConversationsService };