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

package/dist/conversations/conversations.service.js

@@ -13,6 +13,7 @@ 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 { ConversationEnvironments, } from "../environments/conversation-environments.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -20,13 +21,16 @@ 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 { 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}`);
@@ -64,6 +68,7 @@ const COLUMNS = [
     "parent_conversation_id",
     "subagent_type",
     "archived_at",
+    "environment_id",
 ];
 function toView(r) {
     return {
@@ -80,11 +85,17 @@ function toView(r) {
         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;
+/**
+ * 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.
+ */
+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
@@ -117,6 +128,7 @@ let ConversationsService = class ConversationsService {
     attachments;
     invoker;
     background;
+    environments;
     txHost;
     constructor(db, eventLog, agents, access, 
     /** Starts and stops the conversation's runs. */
@@ -130,7 +142,9 @@ let ConversationsService = class ConversationsService {
     /** Renders a person's skill invocation (phase D). */
     invoker, 
     /** Stops a deleted conversation's background tasks. */
-    background, txHost) {
+    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;
@@ -142,6 +156,7 @@ let ConversationsService = class ConversationsService {
         this.attachments = attachments;
         this.invoker = invoker;
         this.background = background;
+        this.environments = environments;
         this.txHost = txHost;
     }
     /**
@@ -153,12 +168,24 @@ let ConversationsService = class ConversationsService {
             .ensureRun(conversationId)
             .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);
@@ -172,16 +199,17 @@ let ConversationsService = class ConversationsService {
      * `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;
-        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 all = await this.createIn(id, orgId, accountId, agentId, input, next, extra, invoked);
+        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);
@@ -195,14 +223,16 @@ let ConversationsService = class ConversationsService {
     }
     /** 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(id, orgId, accountId, agentId, input, next, extra, invoked) {
+    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: agentId,
+            agent_id: conv.agentId,
             account_id: accountId,
+            environment_id: conv.environmentId,
             create_request_id: input.clientMessageId,
         })
             .onConflict((oc) => oc
@@ -284,12 +314,13 @@ let ConversationsService = class ConversationsService {
     /**
      * 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
+     * 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 (enterprise admins still see them).
+     * log, runs and trajectory stay (super admins still see them).
      */
     async remove(orgId, conversationId, accountId) {
         await this.writable(orgId, conversationId, accountId);
@@ -301,7 +332,13 @@ let ConversationsService = class ConversationsService {
                 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
@@ -446,14 +483,14 @@ 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.archived_at, cs.activity
+        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.archived_at, ${activitySql("c")} AS activity
+          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}
@@ -572,26 +609,38 @@ let ConversationsService = 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.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
@@ -600,7 +649,9 @@ let ConversationsService = 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) {
@@ -608,6 +659,16 @@ let ConversationsService = 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`。
@@ -640,7 +701,7 @@ let ConversationsService = 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
@@ -680,16 +741,17 @@ let ConversationsService = class ConversationsService {
      * 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;
-        const { info } = await this.providers.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 ?? [];
@@ -710,7 +772,7 @@ let ConversationsService = 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
@@ -812,9 +874,26 @@ let ConversationsService = 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"])
@@ -867,6 +946,7 @@ ConversationsService = __decorate([
     __param(8, Inject(AttachmentsService)),
     __param(9, Inject(SkillInvoker)),
     __param(10, Inject(BackgroundTaskStopper)),
-    __param(11, Inject(TransactionHost))
+    __param(11, Inject(ConversationEnvironments)),
+    __param(12, Inject(TransactionHost))
 ], ConversationsService);
 export { ConversationsService };

package/dist/conversations/environment-status.d.ts

@@ -0,0 +1,24 @@
+import { EnvironmentsService, type EnvironmentView } from "../environments/environments.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.service.js";
+/**
+ * The environment a conversation works in, for its page (environments spec §9: shown read only):
+ * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
+ * conversation's environment. Null while the conversation is unbound, or when its environment is
+ * deleted or no longer its owner's (its sandbox tools then fail).
+ */
+export declare class ConversationEnvironmentStatus {
+    /** Who may see the conversation (the rule of its event stream). */
+    private readonly access;
+    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
+    private readonly conversations;
+    private readonly environments;
+    private readonly db;
+    constructor(
+    /** Who may see the conversation (the rule of its event stream). */
+    access: Pick<ConversationAccess, "isAccessible">, 
+    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
+    conversations: Pick<ConversationsService, "sandboxConversationOf">, environments: Pick<EnvironmentsService, "get">, db: KernelDb);
+    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<EnvironmentView | null>;
+}

package/dist/conversations/environment-status.js

@@ -0,0 +1,71 @@
+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 { EnvironmentsService } from "../environments/environments.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.service.js";
+/**
+ * The environment a conversation works in, for its page (environments spec §9: shown read only):
+ * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
+ * conversation's environment. Null while the conversation is unbound, or when its environment is
+ * deleted or no longer its owner's (its sandbox tools then fail).
+ */
+let ConversationEnvironmentStatus = class ConversationEnvironmentStatus {
+    access;
+    conversations;
+    environments;
+    db;
+    constructor(
+    /** Who may see the conversation (the rule of its event stream). */
+    access, 
+    /** The conversation whose environment it works in: a sub-agent's root, else itself. */
+    conversations, environments, db) {
+        this.access = access;
+        this.conversations = conversations;
+        this.environments = environments;
+        this.db = db;
+    }
+    async get(orgId, conversationId, viewerAccountId) {
+        if (!UUID_RE.test(conversationId) ||
+            !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
+            throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        // a sub-agent works in its root conversation's environment (at every depth)
+        const root = await this.conversations.sandboxConversationOf(orgId, conversationId);
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select(["account_id", "environment_id"])
+            .where("id", "=", root)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!conv?.environment_id)
+            return null;
+        try {
+            // the environment as its owner sees it (only the owner may use a personal environment)
+            return await this.environments.get(orgId, conv.account_id, conv.environment_id);
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "environment.not_found")
+                return null;
+            throw e;
+        }
+    }
+};
+ConversationEnvironmentStatus = __decorate([
+    Injectable(),
+    __param(0, Inject(ConversationAccess)),
+    __param(1, Inject(ConversationsService)),
+    __param(2, Inject(EnvironmentsService)),
+    __param(3, Inject(KernelDb))
+], ConversationEnvironmentStatus);
+export { ConversationEnvironmentStatus };

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

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

package/dist/conversations/event-log.js

@@ -155,6 +155,66 @@ let EventLog = class EventLog {
             .execute();
         return rows.map(toEvent);
     }
+    /**
+     * The page of the log that ends right before `beforeSeq` (`null`: the log's end), in ascending
+     * seq: the last `limit` events before it, extended back so the first event is the log's first or
+     * the first one after a run's end (`run_finished` / `run_failed` / `run_aborted`), at most
+     * `extend` events further back (a longer run then starts mid-run). `turnsBefore`: how many runs
+     * started (distinct `run_id` of `run_started`) before the page's first event. History paging
+     * spec §2.
+     */
+    async readTurnPageBefore(conversationId, beforeSeq, limit, extend) {
+        let q = this.db
+            .selectFrom("conversation_events")
+            .select(EVENT_COLUMNS)
+            .where("conversation_id", "=", conversationId);
+        if (beforeSeq !== null)
+            q = q.where("seq", "<", String(beforeSeq));
+        const rows = (await q.orderBy("seq", "desc").limit(limit).execute()).reverse();
+        const first = rows[0] === undefined ? null : Number(rows[0].seq);
+        if (first === null)
+            return { events: [], turnsBefore: 0 };
+        let start = first;
+        if (first > 1) {
+            // the latest run end at or before the event just above the page, within the extension
+            const end = await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.max("seq").as("seq"))
+                .where("conversation_id", "=", conversationId)
+                .where("seq", "<", String(first))
+                .where("seq", ">=", String(Math.max(1, first - 1 - extend)))
+                .where("type", "in", ["run_finished", "run_failed", "run_aborted"])
+                .executeTakeFirst();
+            // none within reach: the page starts at the log's start when that is in reach, else mid-run
+            if (end?.seq != null)
+                start = Number(end.seq) + 1;
+            else if (first - 1 <= extend)
+                start = 1;
+        }
+        const head = start < first
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select(EVENT_COLUMNS)
+                .where("conversation_id", "=", conversationId)
+                .where("seq", ">=", String(start))
+                .where("seq", "<", String(first))
+                .orderBy("seq")
+                .execute()
+            : [];
+        const turns = start > 1
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.count("run_id").distinct().as("n"))
+                .where("conversation_id", "=", conversationId)
+                .where("type", "=", "run_started")
+                .where("seq", "<", String(start))
+                .executeTakeFirst()
+            : undefined;
+        return {
+            events: [...head, ...rows].map(toEvent),
+            turnsBefore: Number(turns?.n ?? 0),
+        };
+    }
     /**
      * 读 `afterSeq` 之后、属于 `runIds` 中某次运行的事件，按 seq 升序，最多 `limit` 条（轨迹按运行分页用）。
      * `runIds` 为空时返回空数组。走部分索引 `conversation_events_run_idx (conversation_id, run_id, seq)`（0027）：