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

package/dist/conversations/conversations.controller.js

@@ -19,10 +19,10 @@ import { MAX_ATTACHMENTS } from "../tools/connector-content.js";
 import { ConversationToolInfo, TOOL_INFO_KEY_MAX, TOOL_INFO_MAX_KEYS, } from "../tools/info.js";
 import { ARTIFACT_DOWNLOAD_CACHE_SECONDS, ConversationArtifacts, } from "./artifacts.js";
 import { CONVERSATION_TITLE_MAX_CHARS, ConversationsService, } from "./conversations.service.js";
+import { ConversationEnvironmentStatus } from "./environment-status.js";
 import { ConversationFiles, FILE_CONTENT_MAX_BYTES, FILES_PAGE_MAX, } from "./files.js";
 import { ConversationOutputs, OUTPUT_PAGE_MAX_CHARS } from "./outputs-read.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus } from "./sandbox-status.js";
 /** Shared by the list and groups queries: title search, run activity and the archived list. */
 const searchFields = {
     q: z.string().min(1).max(100).optional(),
@@ -48,9 +48,16 @@ const SubagentsQuery = z.object({
     after: z.string().min(1).max(100).optional(),
     limit: z.coerce.number().int().min(1).max(100).default(50),
 });
-const EventsQuery = z.object({
-    after: z.coerce.number().int().min(0).default(0),
+const EventsQuery = z
+    .object({
+    after: z.coerce.number().int().min(0).optional(),
+    /** The page before this seq, or the log's last page (`end`); exclusive with `after`. */
+    before: z.union([z.literal("end"), z.coerce.number().int().min(1)]).optional(),
     limit: z.coerce.number().int().min(1).max(500).default(500),
+})
+    .refine((q) => q.after === undefined || q.before === undefined, {
+    message: "after and before are exclusive",
+    path: ["before"],
 });
 /** `?keys=a,b`: 1–100 comma-separated tool keys of 1–200 characters each. */
 const ToolsQuery = z.object({
@@ -125,10 +132,13 @@ const MessageBody = MessageFields.strict().refine(...textRule);
  * `POST /conversations`: `message` creates the conversation with its first message (create on
  * first send; `clientMessageId` is required and makes a retry return the same conversation).
  * Without it the conversation is created empty (API clients; the web never does).
+ * `environmentId` binds it to one of the caller's environments; without it the caller's default
+ * environment (environments spec §4.1 item 1).
  */
 const CreateBody = z
     .object({
     agentId: z.string().min(1).max(100),
+    environmentId: z.string().min(1).max(100).optional(),
     message: MessageFields.omit({ retryOf: true })
         .extend({ clientMessageId: z.string().min(1).max(200) })
         .strict()
@@ -137,9 +147,7 @@ const CreateBody = z
 })
     .strict();
 /**
- * `POST …/queue`: the message fields that can be queued (no retry). A model / effort pick is checked
- * now and applied when the message is sent (final review I1). A skill invocation is rendered now
- * and checked again when sent (phase D Task 9).
+ * `POST …/queue` (deprecated, behaves as `POST …/messages`): the message fields (no retry).
  */
 const QueueBody = MessageFields.omit({ retryOf: true })
     .extend({ clientMessageId: z.string().min(1).max(200) })
@@ -205,15 +213,15 @@ let ConversationsController = class ConversationsController {
     conversations;
     outputs;
     artifacts;
-    sandboxStatus;
+    environmentStatus;
     toolInfo;
     queue;
     files;
-    constructor(conversations, outputs, artifacts, sandboxStatus, toolInfo, queue, files) {
+    constructor(conversations, outputs, artifacts, environmentStatus, toolInfo, queue, files) {
         this.conversations = conversations;
         this.outputs = outputs;
         this.artifacts = artifacts;
-        this.sandboxStatus = sandboxStatus;
+        this.environmentStatus = environmentStatus;
         this.toolInfo = toolInfo;
         this.queue = queue;
         this.files = files;
@@ -225,9 +233,10 @@ let ConversationsController = class ConversationsController {
      */
     async create(principal, org, body, reply) {
         const p = requireUser(principal);
+        const pick = body.environmentId === undefined ? {} : { environmentId: body.environmentId };
         if (body.message === undefined) {
             return {
-                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId),
+                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick),
             };
         }
         const m = body.message;
@@ -239,7 +248,7 @@ let ConversationsController = class ConversationsController {
             ...(m.model !== undefined && { model: m.model }),
             ...(m.effort !== undefined && { effort: m.effort }),
             ...(m.skill !== undefined && { skill: m.skill }),
-        });
+        }, pick);
         reply.status(out.created ? 201 : 200);
         return { conversation: out.conversation, event: out.event, events: out.events };
     }
@@ -302,11 +311,19 @@ let ConversationsController = class ConversationsController {
         const p = requireUser(principal);
         return { conversation: await this.conversations.get(org.orgId, id, p.account.id) };
     }
-    /** `after` 之后的事件（seq 升序，最多 `limit` 条）；客户端以最后一条的 seq 作为下一次的 `after`。 */
+    /**
+     * Events in ascending seq. `after`: those after it (at most `limit`; the client passes the last
+     * seq back as the next `after`). `before` (a seq, or `end` for the log's last page): the
+     * turn-aligned page before it, `{ events, turnsBefore }` (history paging spec §2).
+     */
     async events(principal, org, id, q) {
         const p = requireUser(principal);
+        if (q.before !== undefined) {
+            const before = q.before === "end" ? null : q.before;
+            return this.conversations.listEventsBefore(org.orgId, id, p.account.id, before, q.limit);
+        }
         return {
-            events: await this.conversations.listEvents(org.orgId, id, p.account.id, q.after, q.limit),
+            events: await this.conversations.listEvents(org.orgId, id, p.account.id, q.after ?? 0, q.limit),
         };
     }
     /**
@@ -321,6 +338,15 @@ let ConversationsController = class ConversationsController {
             ...(q.after !== undefined && { after: q.after }),
         });
     }
+    /**
+     * The agent tree of a root conversation (agent map spec §8, §9.2): `{ root }`, each node with its
+     * status, model, time, tokens, tool calls and children. Owner only; a sub-agent's id is
+     * `conversation.not_found`.
+     */
+    async agentTree(principal, org, { id }) {
+        const p = requireUser(principal);
+        return this.conversations.agentTree(org.orgId, id, p.account.id);
+    }
     /**
      * The conversation's token usage, its sub-agents' included (sub-agents spec §8.3):
      * `{ usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } }`. Owner only.
@@ -389,13 +415,13 @@ let ConversationsController = class ConversationsController {
         await reply.send(c.body);
     }
     /**
-     * 对话沙箱的状态。响应体**不套外层键**，直接是 `{ status: "running" | "suspended", lastUsedAt }`
-     * （不同于 `{ preview }`、`{ conversation }` 等；网页 `getSandboxStatus` 按此解析）；
-     * 没有可用的沙箱（未创建、已销毁）→ 404 `sandbox.not_found`。可见性与会话流相同。
+     * The environment the conversation works in (a sub-agent: its root's), as its owner sees it,
+     * with its instance state; `null` while unbound, or when the environment was deleted. Same
+     * visibility as the event stream.
      */
-    async sandbox(principal, org, id) {
+    async environment(principal, org, id) {
         const p = requireUser(principal);
-        return this.sandboxStatus.get(org.orgId, id, p.account.id);
+        return { environment: await this.environmentStatus.get(org.orgId, id, p.account.id) };
     }
     /**
      * Display metadata (title, kind, key arguments, source) of the tools a conversation's calls name,
@@ -429,22 +455,23 @@ let ConversationsController = class ConversationsController {
         return this.queue.list(org.orgId, id, p.account.id);
     }
     /**
-     * Queues a message (201). The same `clientMessageId` again: 200 with the queued item, or with
-     * `item: null` and the sent `event` once it went out. An idle conversation sends it at once.
+     * Deprecated: behaves as `POST …/messages` (202 `{ event }`): an interjection while a run is
+     * active, a new run otherwise; nothing is queued any more. Kept for older clients for one release;
+     * the leftover-item routes below keep working until the queue table is dropped (contract step).
      */
-    async enqueue(principal, org, id, body, reply) {
+    async enqueue(principal, org, id, body) {
         const p = requireUser(principal);
-        const out = await this.queue.add(org.orgId, id, p.account.id, {
-            text: body.text,
-            clientMessageId: body.clientMessageId,
-            ...(body.attachments !== undefined && { attachments: body.attachments }),
-            ...(body.files !== undefined && { files: body.files }),
-            ...(body.model !== undefined && { model: body.model }),
-            ...(body.effort !== undefined && { effort: body.effort }),
-            ...(body.skill !== undefined && { skill: body.skill }),
-        });
-        reply.status(out.created ? 201 : 200);
-        return { item: out.item, ...(out.event !== undefined && { event: out.event }) };
+        return {
+            event: await this.conversations.postUserMessage(org.orgId, id, p.account.id, {
+                text: body.text,
+                clientMessageId: body.clientMessageId,
+                ...(body.attachments !== undefined && { attachments: body.attachments }),
+                ...(body.files !== undefined && { files: body.files }),
+                ...(body.model !== undefined && { model: body.model }),
+                ...(body.effort !== undefined && { effort: body.effort }),
+                ...(body.skill !== undefined && { skill: body.skill }),
+            }),
+        };
     }
     /** "Continue sending" after a pause (202). Declared before `:itemId` routes. */
     async resumeQueue(principal, org, id) {
@@ -465,7 +492,13 @@ let ConversationsController = class ConversationsController {
         const p = requireUser(principal);
         return { event: await this.queue.sendNow(org.orgId, id, p.account.id, itemId) };
     }
-    /** 中止当前运行（会话所有者）：202 `{ runId }`；没有活跃运行 → 409 `run.not_active`。 */
+    /**
+     * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
+     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
+     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
+     * which may already be finished when only its descendants were working (agent map spec §6).
+     */
     async abort(principal, org, id) {
         const p = requireUser(principal);
         return { runId: await this.conversations.abort(org.orgId, id, p.account.id) };
@@ -533,6 +566,14 @@ __decorate([
     __param(2, Param("id")),
     __param(3, ZQuery(ConversationSubagentsQueryDto))
 ], ConversationsController.prototype, "subagents", null);
+__decorate([
+    Get(":id/agent-tree"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ConversationIdParamsDto))
+], ConversationsController.prototype, "agentTree", null);
 __decorate([
     Get(":id/usage"),
     Header("cache-control", "private, no-store"),
@@ -589,13 +630,13 @@ __decorate([
     __param(5, Res())
 ], ConversationsController.prototype, "fileContent", null);
 __decorate([
-    Get(":id/sandbox"),
+    Get(":id/environment"),
     Header("cache-control", "private, no-store"),
     OrgAction("agents.use"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id"))
-], ConversationsController.prototype, "sandbox", null);
+], ConversationsController.prototype, "environment", null);
 __decorate([
     Get(":id/tools"),
     Header("cache-control", "private, no-store"),
@@ -624,12 +665,12 @@ __decorate([
 ], ConversationsController.prototype, "listQueue", null);
 __decorate([
     Post(":id/queue"),
+    HttpCode(202),
     OrgAction("agents.use"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, ZBody(ConversationQueueBodyDto)),
-    __param(4, Res({ passthrough: true }))
+    __param(3, ZBody(ConversationQueueBodyDto))
 ], ConversationsController.prototype, "enqueue", null);
 __decorate([
     Post(":id/queue/resume"),
@@ -679,7 +720,7 @@ ConversationsController = __decorate([
     __param(0, Inject(ConversationsService)),
     __param(1, Inject(ConversationOutputs)),
     __param(2, Inject(ConversationArtifacts)),
-    __param(3, Inject(ConversationSandboxStatus)),
+    __param(3, Inject(ConversationEnvironmentStatus)),
     __param(4, Inject(ConversationToolInfo)),
     __param(5, Inject(ConversationQueue)),
     __param(6, Inject(ConversationFiles))

package/dist/conversations/conversations.module.d.ts

@@ -1,7 +1,7 @@
 /**
  * Conversations: the one {@link ConversationsService} (messages, model switches, skill
  * invocations, sub-agent views, abort), the queue, the file / artifact / output reads and the
- * sandbox status. The event log, the access check and the attachments are their own modules (the
+ * conversation's environment. The event log, the access check and the attachments are their own modules (the
  * skills and tools use them too) and are re-exported here.
  */
 export declare class ConversationsModule {

package/dist/conversations/conversations.module.js

@@ -7,9 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Module } from "@nestjs/common";
 import { AgentLookupModule } from "../agents/agent-lookup.js";
 import { BackgroundModule } from "../background/background.module.js";
+import { EnvironmentsModule } from "../environments/environments.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
-import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
@@ -17,15 +17,15 @@ import { ConversationAccessModule } from "./access.js";
 import { ConversationArtifacts } from "./artifacts.js";
 import { AttachmentsModule } from "./attachments.module.js";
 import { ConversationsService } from "./conversations.service.js";
+import { ConversationEnvironmentStatus } from "./environment-status.js";
 import { EventLogModule } from "./event-log.js";
 import { ConversationFiles } from "./files.js";
 import { ConversationOutputs } from "./outputs-read.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus } from "./sandbox-status.js";
 /**
  * Conversations: the one {@link ConversationsService} (messages, model switches, skill
  * invocations, sub-agent views, abort), the queue, the file / artifact / output reads and the
- * sandbox status. The event log, the access check and the attachments are their own modules (the
+ * conversation's environment. The event log, the access check and the attachments are their own modules (the
  * skills and tools use them too) and are re-exported here.
  */
 let ConversationsModule = class ConversationsModule {
@@ -43,8 +43,8 @@ ConversationsModule = __decorate([
             // the run control (start a run after a message, stop runs) and the model provider registry
             RuntimeModule,
             ProvidersModule,
-            // the sandbox status
-            SandboxModule,
+            // the environment a conversation is bound to, and its view
+            EnvironmentsModule,
             // the stop of a deleted conversation's background tasks
             BackgroundModule,
         ],
@@ -54,7 +54,7 @@ ConversationsModule = __decorate([
             ConversationOutputs,
             ConversationArtifacts,
             ConversationFiles,
-            ConversationSandboxStatus,
+            ConversationEnvironmentStatus,
         ],
         exports: [
             EventLogModule,
@@ -65,7 +65,7 @@ ConversationsModule = __decorate([
             ConversationOutputs,
             ConversationArtifacts,
             ConversationFiles,
-            ConversationSandboxStatus,
+            ConversationEnvironmentStatus,
         ],
     })
 ], ConversationsModule);

package/dist/conversations/conversations.service.d.ts

@@ -2,6 +2,7 @@ import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
 import { BackgroundTaskStopper } from "../background/stop.js";
 import type { TitleSource } from "../db/kernel-schema.js";
+import { ConversationEnvironments, type NewConversationEnvironment } from "../environments/conversation-environments.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
@@ -9,6 +10,7 @@ import { ProviderRegistry } from "../runtime/providers.js";
 import { type RenderedInvocation, SkillInvoker } from "../skills/invoke.js";
 import { ConnectorContent } from "../tools/connector-content.js";
 import { ConversationAccess } from "./access.js";
+import { type AgentTreeNode } from "./agent-tree.js";
 import { AttachmentsService } from "./attachments.service.js";
 import { EventLog } from "./event-log.js";
 import type { ConversationEvent, LogContentBlock } from "./events.js";
@@ -34,6 +36,12 @@ export interface ConversationView {
     subagentType: string | null;
     /** When the owner archived it; null = not archived (hidden from the default lists). */
     archivedAt: Date | null;
+    /**
+     * The environment it works in (environments spec §4.1 item 1); null while unbound (no sandbox
+     * provider when it was created, an anonymous IM sender's, or created before environments). A
+     * sub-agent's is null: it works in its root conversation's.
+     */
+    environmentId: string | null;
     /**
      * What the latest run is doing: `running` (queued or running), `waiting` (an approval or a
      * question), else null. Only the list queries compute it; other responses carry null.
@@ -85,6 +93,8 @@ export interface SubagentView {
 export interface RunControl {
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId: string): Promise<string | null>;
+    /** After a root's queue was unpaused: the wakes it held for its tree (agent map spec §5.3). */
+    wakeHeldTree(rootId: string): Promise<void>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。
@@ -97,6 +107,13 @@ export interface RunControl {
     abortWaiting(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId: string, byAccountId: string): Promise<void>;
+    /**
+     * Stops a sub-agent with its descendants (with `includeSelf: false` only the sub-agent
+     * conversations below); the number of runs asked to stop (agent map spec §6).
+     */
+    stopTree(conversationId: string, byAccountId: string, opts?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
 }
 /** 消息附件引用（连接器 + 资源 URI）。 */
 export interface AttachmentRef {
@@ -120,6 +137,11 @@ export interface ResolvedExtra {
 export { userMessageIdemKey } from "./idem-keys.js";
 /** The longest conversation title (characters, after trimming). */
 export declare 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 declare const EVENTS_TURN_EXTEND = 2000;
 /** A user message as posted (`POST …/messages`, or the first message of `POST /conversations`). */
 export interface UserMessageInput {
     text: string;
@@ -162,6 +184,8 @@ export declare class ConversationsService {
     private readonly invoker;
     /** Stops a deleted conversation's background tasks. */
     private readonly background;
+    /** The environment a new conversation is bound to (environments spec §4.1 item 1). */
+    private readonly environments;
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, eventLog: EventLog, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, 
     /** Starts and stops the conversation's runs. */
@@ -175,14 +199,21 @@ export declare class ConversationsService {
     /** Renders a person's skill invocation (phase D). */
     invoker: Pick<SkillInvoker, "prepare">, 
     /** Stops a deleted conversation's background tasks. */
-    background: Pick<BackgroundTaskStopper, "stopForDeletedConversation">, txHost: TransactionHost);
+    background: Pick<BackgroundTaskStopper, "stopForDeletedConversation">, 
+    /** The environment a new conversation is bound to (environments spec §4.1 item 1). */
+    environments: Pick<ConversationEnvironments, "forNew">, txHost: TransactionHost);
     /**
      * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
      * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
      */
     kickRun(conversationId: string): void;
-    /** 新建会话；agent 对该账号不可用 → `agent.not_found`。 */
-    create(orgId: string, accountId: string, agentId: string): Promise<ConversationView>;
+    /**
+     * 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.
+     */
+    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationEnvironment): Promise<ConversationView>;
     /**
      * Creates a conversation together with its first message (UI refresh B, create on first send):
      * the conversation row and the `user_message` are written in one transaction, keyed by the
@@ -194,7 +225,7 @@ export declare class ConversationsService {
      */
     createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
         clientMessageId: string;
-    }): Promise<{
+    }, pick?: NewConversationEnvironment): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
         events: ConversationEvent[];
@@ -222,12 +253,13 @@ export declare 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).
      */
     remove(orgId: string, conversationId: string, accountId: string): Promise<void>;
     private markDeleted;
@@ -289,17 +321,37 @@ export declare class ConversationsService {
         next: string | null;
     }>;
     /**
-     * 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.
+     */
+    agentTree(orgId: string, conversationId: string, viewerAccountId: string): Promise<{
+        root: AgentTreeNode;
+    }>;
+    /**
+     * 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}.
      */
     usage(orgId: string, conversationId: string, viewerAccountId: string): Promise<UsageTotals>;
     /**
-     * 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.
      */
     sandboxConversationOf(orgId: string, conversationId: string): Promise<string>;
     /** 读事件（先做 `get` 的可见性判定）；顺带不阻塞地 {@link kickRun}。 */
     listEvents(orgId: string, conversationId: string, viewerAccountId: string, afterSeq: number, limit: number): Promise<ConversationEvent[]>;
+    /**
+     * 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.
+     */
+    listEventsBefore(orgId: string, conversationId: string, viewerAccountId: string, beforeSeq: number | null, limit: number): Promise<{
+        events: ConversationEvent[];
+        turnsBefore: number;
+    }>;
     /**
      * 追加一条用户消息；带 `clientMessageId` 时重复提交返回同一事件。写入后调用 `ensureRun`：
      * 没有进行中的运行时投递一轮；运行中则由当前运行在步骤间隙吸收，或在它结束时再次 `ensureRun`。
@@ -360,6 +412,11 @@ export declare 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.
      */
     abort(orgId: string, conversationId: string, accountId: string): Promise<string>;
 }