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

package/dist/config/schema.js

@@ -332,7 +332,7 @@ export const KernelConfigSchema = z.object({
                 description: "Mirror URLs of the official marketplace's marketplace.json (https), tried in order when the main URL fails; only for a marketplace.json URL (a git marketplace has no mirrors: point url at a mirror repository instead)",
             })),
         })
-            // Same rule as an enterprise marketplace: a git marketplace has no mirrors.
+            // Same rule as a custom marketplace: a git marketplace has no mirrors.
             .refine((o) => o.mirrors.length === 0 || !isGitMarketplaceUrl(o.url), {
             message: "a git marketplace has no mirrors (point marketplaces.official.url at a mirror repository instead)",
             path: ["mirrors"],
@@ -580,7 +580,7 @@ export const KernelConfigSchema = z.object({
             .boolean()
             .default(true)
             .meta(meta({
-            description: "Whether the finish of a background Bash task starts a run on an idle conversation (the person who started the task's run is the trigger); an organization can override it in its settings. When false the event is only logged and shown, and the next message picks it up",
+            description: "Whether the finish of a background Bash task or a sub-agent's delivery starts a run on an idle conversation or sub-agent (the person who started the task's or the sub-agent's run is the trigger); an organization can override it in its settings. When false the event is only logged and shown, and the next message picks it up",
         })),
         maxRunSeconds: z
             .number()
@@ -930,7 +930,17 @@ export const KernelConfigSchema = z.object({
         .prefault({}),
     subagents: z
         .object({
-        maxConcurrentPerRun: z
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .default(3)
+            .meta(meta({
+            hot: true,
+            description: "Levels of sub-agents below the conversation's own agent; 1 means sub-agents cannot dispatch sub-agents of their own. Organizations can be given their own value in the deployment setting subagentLimitOverrides",
+        })),
+        maxConcurrentPerConversation: z
             .number()
             .int()
             .min(1)
@@ -938,26 +948,27 @@ export const KernelConfigSchema = z.object({
             .default(4)
             .meta(meta({
             hot: true,
-            description: "Sub-agents one run may have running at the same time; agent calls beyond it in one response are refused. Organizations can be given their own value in the deployment setting subagentLimitOverrides",
+            description: "Sub-agents one conversation may have running at the same time, whichever of its runs dispatched them; agent calls beyond it are refused. Organizations can be given their own value in subagentLimitOverrides",
         })),
         maxDispatchesPerRun: z
             .number()
             .int()
-            .min(1)
+            .min(0)
             .max(500)
             .default(50)
             .meta(meta({
             hot: true,
-            description: "Sub-agents one run may dispatch in total, follow-ups included; later agent calls are refused. Organizations can be given their own value in subagentLimitOverrides",
+            description: "Sub-agents the whole tree under a person's message may dispatch in total, counted across every level (nested dispatches and SendMessage messages that restart an idle sub-agent included); later agent calls and such messages are refused. 0 means no limit. Organizations can be given their own value in subagentLimitOverrides",
         })),
         maxTokensPerRun: z
             .number()
             .int()
-            .min(10_000)
+            .min(0)
+            .refine((n) => n === 0 || n >= 10_000, "0 (no limit) or at least 10,000")
             .default(5_000_000)
             .meta(meta({
             hot: true,
-            description: "Tokens (input, output and cache) the sub-agents of one run may use together; at the cap running sub-agents stop and new dispatches are refused. Organizations can be given their own value in subagentLimitOverrides",
+            description: "Tokens (input, output and cache) all sub-agents of the tree under a person's message may use together; at the cap running sub-agents stop and new dispatches are refused. 0 means no limit; otherwise at least 10,000. Organizations can be given their own value in subagentLimitOverrides",
         })),
     })
         .prefault({}),
@@ -1024,16 +1035,16 @@ export const KernelConfigSchema = z.object({
         image: z
             .string()
             .min(1)
-            .default("capybara-sandbox:latest")
+            .optional()
             .meta(meta({
-            description: "Image for conversation sandboxes, used by the Docker sandbox extension (built from plugins/sandbox-docker/image of capybara-hq/plugins, e.g. by the compose sandbox profile; pre-pull it on every Docker node). The E2B extension ignores it and uses its own template setting",
+            description: "Image for environment instances, passed to the sandbox extension; unset (the default), each extension uses the image published with its own version (ghcr.io/capybara-hq/capybara-sandbox). Set it to a locally built or mirrored image for offline deployments; an extension that builds instances from its own template may ignore it",
         })),
         lockWaitSeconds: z
             .number()
             .positive()
             .default(75)
             .meta(meta({
-            description: "Seconds a sandbox call waits while another command in the same conversation holds the sandbox before failing with sandbox.busy; keep it above the 60-second sandbox lock TTL so a call after a replica crash waits for the dead replica's lock to expire",
+            description: "Seconds a sandbox call waits for the environment's instance (while it is being created, resumed or suspended, or all its concurrent command slots are taken) before failing with sandbox.busy; keep it above the 60-second sandbox lock TTL so a call after a replica crash waits for the dead replica's lock to expire",
         })),
         maxConcurrentCommands: z
             .number()
@@ -1043,7 +1054,7 @@ export const KernelConfigSchema = z.object({
             .default(6)
             .meta(meta({
             hot: true,
-            description: "Sandbox commands and file operations that may run at the same time in one conversation's sandbox (parallel sub-agents share their parent conversation's sandbox); 1 runs them one at a time. Providers that do not declare concurrent exec always get 1",
+            description: "Sandbox commands and file operations that may run at the same time in one environment, shared by all its conversations and their sub-agents; 1 runs them one at a time",
         })),
         deliverMaxBytes: z
             .number()
@@ -1062,7 +1073,7 @@ export const KernelConfigSchema = z.object({
                 .max(100)
                 .default(4)
                 .meta(meta({
-                description: "Most background Bash tasks (run_in_background) that may run at once in one conversation's sandbox, sub-agents included; a launch beyond it is refused",
+                description: "Most background Bash tasks (run_in_background) that may run at once in one conversation, its sub-agents included (counted per root conversation, not per environment); a launch beyond it is refused",
             })),
             maxSeconds: z
                 .number()
@@ -1078,7 +1089,7 @@ export const KernelConfigSchema = z.object({
                 .min(1)
                 .default(10)
                 .meta(meta({
-                description: "How often the worker checks the running background Bash tasks of every sandbox for a finish, in seconds; read when the worker starts",
+                description: "How often the worker checks the running background Bash tasks of every environment for a finish, in seconds; read when the worker starts",
             })),
         })
             .prefault({}),
@@ -1089,7 +1100,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(1)
                 .meta(meta({
-                description: "CPU cores for each sandbox; applies to sandboxes created after the change (E2B: set in the template)",
+                description: "CPU cores for each environment instance; applies to instances created after the change (an extension that sizes instances by its own template, such as E2B, may not apply it)",
             })),
             memoryMb: z
                 .number()
@@ -1097,7 +1108,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(2048)
                 .meta(meta({
-                description: "Memory limit of each sandbox in MiB; applies to sandboxes created after the change (E2B: set in the template)",
+                description: "Memory limit of each environment instance in MiB; applies to instances created after the change (an extension that sizes instances by its own template, such as E2B, may not apply it)",
             })),
             diskMb: z
                 .number()
@@ -1105,7 +1116,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(5120)
                 .meta(meta({
-                description: "Disk limit of each sandbox in MiB; applies to sandboxes created after the change (Docker: only with a volume driver that supports size; E2B: set by the template / plan)",
+                description: "Disk limit of each environment's file system in MiB; applies to file systems created after the change (Docker: only with a volume driver that supports size; an extension whose storage cannot be sized may not apply it)",
             })),
             maxCommandSeconds: z
                 .number()
@@ -1121,7 +1132,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(10)
                 .meta(meta({
-                description: "Minutes without use before a running sandbox is suspended (files are kept)",
+                description: "Minutes without a command from any conversation of the environment before its running instance is suspended (files are kept, processes end)",
             })),
             destroyAfterInactiveDays: z
                 .number()
@@ -1129,7 +1140,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(7)
                 .meta(meta({
-                description: "Days without use before a sandbox is destroyed with its files; the next use starts an empty one",
+                description: "Days without use before an environment's instance is destroyed; its files are kept until the environment is deleted, and the next use starts a new instance on them",
             })),
             maxRunningMinutes: z
                 .number()
@@ -1137,13 +1148,13 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(120)
                 .meta(meta({
-                description: "Minutes a sandbox may run continuously before it is suspended even while in use (skipped while a command is running)",
+                description: "Minutes an environment's instance may run continuously before it is suspended even while in use (skipped while a command is running)",
             })),
             egress: z
                 .enum(["none", "allowlist", "open"])
                 .default("allowlist")
                 .meta(meta({
-                description: "Outbound network from sandboxes: none, allowlist (only allowHosts) or open; applies to sandboxes created after the change, existing ones keep theirs until destroyed",
+                description: "Outbound network from environment instances: none, allowlist (only allowHosts) or open; applies to instances created after the change, existing ones keep theirs until destroyed",
             })),
             allowHosts: z
                 .array(z.string())
@@ -1156,12 +1167,25 @@ export const KernelConfigSchema = z.object({
                 });
             })
                 .meta(meta({
-                description: "Hosts sandboxes may reach when egress is allowlist: lowercase hostnames, optional leading '*.', no IPs, ports or internal-only names; applies to sandboxes created after the change",
+                description: "Hosts environment instances may reach when egress is allowlist: lowercase hostnames, optional leading '*.', no IPs, ports or internal-only names; applies to instances created after the change",
             })),
         })
             .prefault({}),
     })
         .prefault({}),
+    environments: z
+        .object({
+        maxPersonal: z
+            .number()
+            .int()
+            .min(1)
+            .default(10)
+            .meta(meta({
+            hot: true,
+            description: "Most personal environments a member may have in one org, the default one included; creating one more fails with environment.limit_reached",
+        })),
+    })
+        .prefault({}),
     evals: z
         .object({
         orgConcurrency: z
@@ -1228,6 +1252,30 @@ export const KernelConfigSchema = z.object({
         path: ["defaultTokenCap"],
     })
         .prefault({}),
+    models: z
+        .object({
+        listTimeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .max(300_000)
+            .default(10_000)
+            .meta(meta({
+            hot: true,
+            description: "Time limit in milliseconds for one model provider's model list (listModels, which may page through a large platform catalog); a provider that exceeds it is treated as failing to list",
+        })),
+        embedTimeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .max(600_000)
+            .default(60_000)
+            .meta(meta({
+            hot: true,
+            description: "Time limit in milliseconds for one embed call to a model provider (one batch of an extension's ctx.models.embed); the call is aborted and fails with a timeout model error",
+        })),
+    })
+        .prefault({}),
     hooks: z
         .object({
         timeoutMs: z

package/dist/conversations/access.d.ts

@@ -2,10 +2,12 @@ import { type ExpressionBuilder } from "kysely";
 import type { KernelDatabase } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 /**
- * 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.
+ * A sub-agent's conversation is reached through the root of its tree (sub-agents spec §6.1,
+ * review m6, the same rule as its trajectory; agent map spec §4.1: nested sub-agents at any
+ * depth): the root is a chat conversation of the same org and owner whose agent is not deleted
+ * and still visible to the viewer, and every conversation between is a sub-agent conversation of
+ * that org. 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.
  */
 export declare const parentReachable: (viewerAccountId: string) => (eb: ExpressionBuilder<KernelDatabase, "conversations">) => import("kysely").ExpressionWrapper<KernelDatabase, "conversations", import("kysely").SqlBool>;
 /**

package/dist/conversations/access.js

@@ -12,10 +12,32 @@ import { sql } from "kysely";
 import { visibleTo } from "../agents/agent-lookup.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 /**
- * 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.
+ * The root of a sub-agent conversation's tree, as a correlated scalar subquery: walks
+ * `parent_conversation_id` up from the conversation's parent through sub-agent conversations of
+ * the same org (at most 16 levels, far above `subagents.maxDepth`'s bound of 5) to the first
+ * conversation without a parent. Null when the chain leaves the org, passes a conversation of
+ * another kind or does not end.
+ */
+const rootOfParent = () => sql `(
+  WITH RECURSIVE up(id, parent, kind, n) AS (
+    SELECT c.id, c.parent_conversation_id, c.kind, 0 FROM capybara.conversations c
+    WHERE c.id = ${sql.ref("conversations.parent_conversation_id")}
+      AND c.org_id = ${sql.ref("conversations.org_id")}
+    UNION ALL
+    SELECT c.id, c.parent_conversation_id, c.kind, up.n + 1
+    FROM capybara.conversations c JOIN up ON c.id = up.parent
+    WHERE up.kind = 'subagent' AND up.n < 16
+      AND c.org_id = ${sql.ref("conversations.org_id")}
+  )
+  SELECT id FROM up WHERE parent IS NULL LIMIT 1
+)`;
+/**
+ * A sub-agent's conversation is reached through the root of its tree (sub-agents spec §6.1,
+ * review m6, the same rule as its trajectory; agent map spec §4.1: nested sub-agents at any
+ * depth): the root is a chat conversation of the same org and owner whose agent is not deleted
+ * and still visible to the viewer, and every conversation between is a sub-agent conversation of
+ * that org. 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.
  */
 export const parentReachable = (viewerAccountId) => (eb) => eb.or([
     eb("conversations.kind", "<>", "subagent"),
@@ -23,7 +45,7 @@ export const parentReachable = (viewerAccountId) => (eb) => eb.or([
         .selectFrom("conversations as p")
         .innerJoin("agents", "agents.id", "p.agent_id")
         .select(sql `1`.as("one"))
-        .whereRef("p.id", "=", "conversations.parent_conversation_id")
+        .where("p.id", "=", rootOfParent())
         .whereRef("p.org_id", "=", "conversations.org_id")
         .where("p.account_id", "=", viewerAccountId)
         .where("p.kind", "=", "chat")

package/dist/conversations/agent-tree.d.ts

@@ -0,0 +1,46 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * One agent of a conversation tree as the agent map shows it (agent map spec §8, §9.2): the root
+ * conversation or a sub-agent at any depth.
+ */
+export interface AgentTreeNode {
+    /** The conversation's id (a sub-agent's is its child conversation's). */
+    id: string;
+    /** A sub-agent's dispatched description; the root's title ("" before it has one). */
+    description: string;
+    /**
+     * The sub-agent type (`conversations.subagent_type`, set at the first dispatch); null for the
+     * root, and for a sub-agent row that has none (the column is nullable; no sentinel is invented).
+     */
+    agentType: string | null;
+    /**
+     * The latest run's status; `idle` when no run is active and the latest run completed (or the
+     * conversation has no run yet).
+     */
+    status: "queued" | "running" | "waiting" | "completed" | "failed" | "aborted" | "idle";
+    /** The model of the latest run (a queued sub-agent's: the dispatched one); null when unknown. */
+    model: {
+        provider: string;
+        model: string;
+    } | null;
+    /** The first run's start; null until a run started. */
+    startedAt: string | null;
+    /** The latest run's end; null while a run is active or before any run ended. */
+    finishedAt: string | null;
+    /** The wall time of the conversation's own runs, summed (a running run up to now). */
+    durationMs: number;
+    /** The tokens of the conversation's own runs (`usage` events with a run; never descendants'). */
+    tokens: number;
+    /** The tool calls of the conversation's own runs (its `tool_result` events). */
+    toolCalls: number;
+    /** The sub-agents it dispatched, oldest first. */
+    children: AgentTreeNode[];
+}
+/**
+ * The agent tree of the root conversation `rootId` of org `orgId`: null when it is not a root
+ * chat conversation of that org. The tree's ids come from {@link conversationTree} (one recursive
+ * query); one more query reads every node's numbers. A deleted conversation, and a sub-agent
+ * conversation without a dispatch row, is left out with its subtree. Call only after an access
+ * check of the root.
+ */
+export declare function readAgentTree(db: KernelSchemaDb, orgId: string, rootId: string): Promise<AgentTreeNode | null>;

package/dist/conversations/agent-tree.js

@@ -0,0 +1,92 @@
+import { sql } from "kysely";
+import { conversationTree } from "./tree.js";
+const ACTIVE = new Set(["queued", "running", "waiting"]);
+/**
+ * The agent tree of the root conversation `rootId` of org `orgId`: null when it is not a root
+ * chat conversation of that org. The tree's ids come from {@link conversationTree} (one recursive
+ * query); one more query reads every node's numbers. A deleted conversation, and a sub-agent
+ * conversation without a dispatch row, is left out with its subtree. Call only after an access
+ * check of the root.
+ */
+export async function readAgentTree(db, orgId, rootId) {
+    const ids = (await conversationTree(db, rootId)).map((t) => t.id);
+    if (ids.length === 0)
+        return null;
+    const { rows } = await sql `
+    SELECT c.id, c.parent_conversation_id, c.subagent_type, c.title,
+      (SELECT e.payload->>'description' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.parent_conversation_id AND e.type = 'subagent_dispatched'
+          AND e.payload->>'subagentId' = c.id
+        ORDER BY e.seq DESC LIMIT 1) AS description,
+      (SELECT e.payload->'model' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.parent_conversation_id AND e.type = 'subagent_dispatched'
+          AND e.payload->>'subagentId' = c.id
+        ORDER BY e.seq DESC LIMIT 1) AS dispatched_model,
+      (SELECT e.payload->'model' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'run_started'
+        ORDER BY e.seq DESC LIMIT 1) AS run_model,
+      latest.status AS last_status, latest.finished_at AS last_finished_at,
+      runs.started_at, runs.duration_ms,
+      (SELECT count(*) FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'tool_result') AS tool_calls,
+      (SELECT coalesce(sum(
+          coalesce((e.payload->>'inputTokens')::bigint, 0)
+          + coalesce((e.payload->>'outputTokens')::bigint, 0)
+          + coalesce((e.payload->>'cacheReadTokens')::bigint, 0)
+          + coalesce((e.payload->>'cacheWriteTokens')::bigint, 0)
+        ), 0)
+        FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'usage' AND e.run_id IS NOT NULL) AS tokens
+    FROM capybara.conversations c
+    LEFT JOIN LATERAL (
+      SELECT r.status, r.finished_at FROM capybara.runs r
+      WHERE r.conversation_id = c.id
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT 1
+    ) latest ON true
+    CROSS JOIN LATERAL (
+      SELECT min(r.started_at) AS started_at,
+        coalesce(sum(floor(extract(epoch FROM coalesce(r.finished_at, now()) - r.started_at) * 1000))
+          FILTER (WHERE r.started_at IS NOT NULL), 0)::bigint AS duration_ms
+      FROM capybara.runs r WHERE r.conversation_id = c.id
+    ) runs
+    WHERE c.id IN (${sql.join(ids)}) AND c.org_id = ${orgId} AND c.deleted_at IS NULL
+      AND (
+        (c.id = ${rootId} AND c.kind = 'chat' AND c.parent_conversation_id IS NULL)
+        OR (c.id <> ${rootId} AND c.kind = 'subagent' AND EXISTS (
+          SELECT 1 FROM capybara.subagent_dispatches sd WHERE sd.child_conversation_id = c.id
+        ))
+      )
+    ORDER BY c.created_at, c.id
+  `.execute(db);
+    const nodes = new Map();
+    for (const r of rows)
+        nodes.set(r.id, toNode(r, r.id === rootId));
+    for (const r of rows) {
+        if (r.id === rootId || r.parent_conversation_id === null)
+            continue;
+        const node = nodes.get(r.id);
+        const parent = nodes.get(r.parent_conversation_id);
+        if (node && parent)
+            parent.children.push(node);
+    }
+    return nodes.get(rootId) ?? null;
+}
+function toNode(r, isRoot) {
+    const active = r.last_status !== null && ACTIVE.has(r.last_status);
+    const status = r.last_status === null || r.last_status === "completed" ? "idle" : r.last_status;
+    return {
+        id: r.id,
+        description: (isRoot ? r.title : (r.description ?? r.title)) ?? "",
+        agentType: isRoot ? null : r.subagent_type,
+        status,
+        model: modelOf(r.run_model ?? r.dispatched_model),
+        startedAt: r.started_at?.toISOString() ?? null,
+        finishedAt: active ? null : (r.last_finished_at?.toISOString() ?? null),
+        durationMs: Number(r.duration_ms),
+        tokens: Number(r.tokens),
+        toolCalls: Number(r.tool_calls),
+        children: [],
+    };
+}
+const modelOf = (m) => m ? { provider: m.provider, model: m.model } : null;

package/dist/conversations/conversations.controller.d.ts

@@ -1,16 +1,18 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
+import type { EnvironmentView } from "../environments/environments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ConversationToolInfo, type ToolInfo } from "../tools/info.js";
+import type { AgentTreeNode } from "./agent-tree.js";
 import { type ArtifactPreview, ConversationArtifacts } from "./artifacts.js";
 import { type ConversationGroup, ConversationsService, type ConversationView, type SubagentView, type UsageTotals } from "./conversations.service.js";
+import { ConversationEnvironmentStatus } from "./environment-status.js";
 import type { ConversationEvent } from "./events.js";
 import { ConversationFiles, type FileOutput } from "./files.js";
 import { ConversationOutputs, type OutputPage } from "./outputs-read.js";
 import type { QueueItem, QueuePauseReason } from "./queue.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus, type SandboxStatusView } from "./sandbox-status.js";
 declare const ListQuery: z.ZodObject<{
     q: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<{
@@ -42,7 +44,8 @@ declare const SubagentsQuery: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 declare const EventsQuery: z.ZodObject<{
-    after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    after: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    before: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"end">, z.ZodCoercedNumber<unknown>]>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 /** `?keys=a,b`: 1–100 comma-separated tool keys of 1–200 characters each. */
@@ -95,9 +98,12 @@ declare const MessageBody: z.ZodObject<{
  * `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).
  */
 declare const CreateBody: z.ZodObject<{
     agentId: z.ZodString;
+    environmentId: z.ZodOptional<z.ZodString>;
     message: z.ZodOptional<z.ZodObject<{
         text: z.ZodString;
         attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -123,9 +129,7 @@ declare const CreateBody: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$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).
  */
 declare const QueueBody: z.ZodObject<{
     text: z.ZodString;
@@ -173,11 +177,11 @@ export declare class ConversationsController {
     private readonly conversations;
     private readonly outputs;
     private readonly artifacts;
-    private readonly sandboxStatus;
+    private readonly environmentStatus;
     private readonly toolInfo;
     private readonly queue;
     private readonly files;
-    constructor(conversations: ConversationsService, outputs: ConversationOutputs, artifacts: ConversationArtifacts, sandboxStatus: ConversationSandboxStatus, toolInfo: ConversationToolInfo, queue: ConversationQueue, files: ConversationFiles);
+    constructor(conversations: ConversationsService, outputs: ConversationOutputs, artifacts: ConversationArtifacts, environmentStatus: ConversationEnvironmentStatus, toolInfo: ConversationToolInfo, queue: ConversationQueue, files: ConversationFiles);
     /**
      * 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. With a
      * message the answer has `event` (the `user_message`) and `events`: every event the first send
@@ -215,9 +219,14 @@ export declare class ConversationsController {
     get(principal: Principal, org: OrgContext, id: string): Promise<{
         conversation: ConversationView;
     }>;
-    /** `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).
+     */
     events(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof EventsQuery>): Promise<{
         events: ConversationEvent[];
+        turnsBefore?: number;
     }>;
     /**
      * The conversation's sub-agents, newest first (sub-agents spec §14.3): `{ subagents, next }`,
@@ -228,6 +237,14 @@ export declare class ConversationsController {
         subagents: SubagentView[];
         next: string | null;
     }>;
+    /**
+     * 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`.
+     */
+    agentTree(principal: Principal, org: OrgContext, { id }: z.infer<typeof IdParams>): Promise<{
+        root: AgentTreeNode;
+    }>;
     /**
      * The conversation's token usage, its sub-agents' included (sub-agents spec §8.3):
      * `{ usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } }`. Owner only.
@@ -270,11 +287,13 @@ export declare class ConversationsController {
      */
     fileContent(principal: Principal, org: OrgContext, id: string, fileId: string, q: z.infer<typeof FileContentQuery>, reply: FastifyReply): Promise<void>;
     /**
-     * 对话沙箱的状态。响应体**不套外层键**，直接是 `{ 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.
      */
-    sandbox(principal: Principal, org: OrgContext, id: string): Promise<SandboxStatusView>;
+    environment(principal: Principal, org: OrgContext, id: string): Promise<{
+        environment: EnvironmentView | null;
+    }>;
     /**
      * Display metadata (title, kind, key arguments, source) of the tools a conversation's calls name,
      * for the tool rows (UI refresh B). Same visibility as the event stream; never model-visible.
@@ -295,12 +314,12 @@ export declare class ConversationsController {
         pauseReason?: QueuePauseReason;
     }>;
     /**
-     * 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).
      */
-    enqueue(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof QueueBody>, reply: FastifyReply): Promise<{
-        item: QueueItem | null;
-        event?: ConversationEvent;
+    enqueue(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof QueueBody>): Promise<{
+        event: ConversationEvent;
     }>;
     /** "Continue sending" after a pause (202). Declared before `:itemId` routes. */
     resumeQueue(principal: Principal, org: OrgContext, id: string): Promise<Record<string, never>>;
@@ -312,7 +331,13 @@ export declare class ConversationsController {
     sendQueued(principal: Principal, org: OrgContext, id: string, itemId: string): Promise<{
         event: ConversationEvent;
     }>;
-    /** 中止当前运行（会话所有者）：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).
+     */
     abort(principal: Principal, org: OrgContext, id: string): Promise<{
         runId: string;
     }>;