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

package/dist/config/schema.d.ts

@@ -51,6 +51,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
         url: z.ZodString;
         poolMax: z.ZodDefault<z.ZodNumber>;
         connectTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     redis: z.ZodPrefault<z.ZodObject<{
         url: z.ZodString;
@@ -119,6 +120,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     runtime: z.ZodDefault<z.ZodObject<{
         maxSteps: z.ZodDefault<z.ZodNumber>;
+        wakeOnBackgroundTask: z.ZodDefault<z.ZodBoolean>;
         maxRunSeconds: z.ZodDefault<z.ZodNumber>;
         streamIdleMs: z.ZodDefault<z.ZodNumber>;
         maxOutputTokens: z.ZodDefault<z.ZodNumber>;
@@ -175,15 +177,32 @@ export declare const KernelConfigSchema: z.ZodObject<{
         requestMediaBytes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     subagents: z.ZodPrefault<z.ZodObject<{
-        maxConcurrentPerRun: z.ZodDefault<z.ZodNumber>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentPerConversation: z.ZodDefault<z.ZodNumber>;
         maxDispatchesPerRun: z.ZodDefault<z.ZodNumber>;
         maxTokensPerRun: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    web: z.ZodPrefault<z.ZodObject<{
+        search: z.ZodPrefault<z.ZodObject<{
+            maxResults: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        fetch: z.ZodPrefault<z.ZodObject<{
+            maxPageChars: z.ZodDefault<z.ZodNumber>;
+            maxAnswerTokens: z.ZodDefault<z.ZodNumber>;
+            cacheSeconds: z.ZodDefault<z.ZodNumber>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     sandbox: z.ZodPrefault<z.ZodObject<{
-        image: z.ZodDefault<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
         lockWaitSeconds: z.ZodDefault<z.ZodNumber>;
         maxConcurrentCommands: z.ZodDefault<z.ZodNumber>;
         deliverMaxBytes: z.ZodDefault<z.ZodNumber>;
+        background: z.ZodPrefault<z.ZodObject<{
+            maxTasks: z.ZodDefault<z.ZodNumber>;
+            maxSeconds: z.ZodDefault<z.ZodNumber>;
+            pollSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         limits: z.ZodPrefault<z.ZodObject<{
             cpu: z.ZodDefault<z.ZodNumber>;
             memoryMb: z.ZodDefault<z.ZodNumber>;
@@ -200,6 +219,9 @@ export declare const KernelConfigSchema: z.ZodObject<{
             allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    environments: z.ZodPrefault<z.ZodObject<{
+        maxPersonal: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     evals: z.ZodPrefault<z.ZodObject<{
         orgConcurrency: z.ZodDefault<z.ZodNumber>;
         workerConcurrency: z.ZodDefault<z.ZodNumber>;

package/dist/config/schema.js

@@ -179,6 +179,14 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(5000)
             .meta(meta({ description: "PostgreSQL connect timeout in milliseconds" })),
+        idleTimeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(60_000)
+            .meta(meta({
+            description: "How long an idle PostgreSQL connection stays in the pool, in milliseconds",
+        })),
     })
         .prefault({}),
     redis: z
@@ -324,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"],
@@ -568,6 +576,12 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(50)
             .meta(meta({ description: "Maximum model steps per agent run before the final wrap-up" })),
+        wakeOnBackgroundTask: z
+            .boolean()
+            .default(true)
+            .meta(meta({
+            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()
             .int()
@@ -656,6 +670,7 @@ export const KernelConfigSchema = z.object({
     })
         .default({
         maxSteps: 50,
+        wakeOnBackgroundTask: true,
         maxRunSeconds: DEFAULT_MAX_RUN_SECONDS,
         streamIdleMs: 60000,
         maxOutputTokens: 16000,
@@ -915,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)
@@ -923,44 +948,103 @@ 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({}),
+    web: z
+        .object({
+        search: z
+            .object({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(10)
+                .meta(meta({
+                hot: true,
+                description: "Maximum number of results one WebSearch call returns to the model, however many the search provider returns",
+            })),
+        })
+            .prefault({}),
+        fetch: z
+            .object({
+            maxPageChars: z
+                .number()
+                .int()
+                .positive()
+                .default(400_000)
+                .meta(meta({
+                hot: true,
+                description: "Maximum characters of a fetched page kept for answering a WebFetch prompt; longer pages are truncated",
+            })),
+            maxAnswerTokens: z
+                .number()
+                .int()
+                .positive()
+                .default(4000)
+                .meta(meta({
+                hot: true,
+                description: "Maximum output tokens of the model call that answers a WebFetch prompt from the page",
+            })),
+            cacheSeconds: z
+                .number()
+                .int()
+                .min(0)
+                .default(900)
+                .meta(meta({
+                hot: true,
+                description: "Seconds a fetched page is cached per organization and URL; 0 turns the cache off",
+            })),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .default(180_000)
+                .meta(meta({
+                hot: true,
+                description: "Time limit of one WebFetch call in milliseconds, the provider's fetch and the answering model call together; replaces tools.timeoutMs for WebFetch",
+            })),
+        })
+            .prefault({}),
+    })
+        .prefault({}),
     sandbox: 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()
@@ -970,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()
@@ -980,6 +1064,35 @@ export const KernelConfigSchema = z.object({
             .meta(meta({
             description: "Largest file in bytes an agent may deliver from its sandbox to the user as an artifact (Deliver)",
         })),
+        background: z
+            .object({
+            maxTasks: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(4)
+                .meta(meta({
+                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()
+                .int()
+                .positive()
+                .default(7200)
+                .meta(meta({
+                description: "Longest a background Bash task may run, in seconds; the task is killed at its deadline and ends as timed_out. Clamped to sandbox.limits.maxCommandSeconds; not limited by runtime.maxRunSeconds",
+            })),
+            pollSeconds: z
+                .number()
+                .int()
+                .min(1)
+                .default(10)
+                .meta(meta({
+                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({}),
         limits: z
             .object({
             cpu: z
@@ -987,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()
@@ -995,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()
@@ -1003,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()
@@ -1019,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()
@@ -1027,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()
@@ -1035,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())
@@ -1054,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

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,10 +45,11 @@ 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")
+        .where("p.deleted_at", "is", null)
         .where("agents.deleted_at", "is", null)
         .where(visibleTo(viewerAccountId))),
 ]);
@@ -53,6 +76,7 @@ let ConversationAccess = class ConversationAccess {
             .where("conversations.id", "=", conversationId)
             .where("conversations.org_id", "=", orgId)
             .where("conversations.account_id", "=", viewerAccountId)
+            .where("conversations.deleted_at", "is", null)
             .where("conversations.kind", "in", ["chat", "subagent"])
             .where(parentReachable(viewerAccountId))
             .where((eb) => eb.and([

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/attachments.service.d.ts

@@ -28,6 +28,16 @@ export declare const MAX_PENDING_SKILL_PACKAGES = 5;
  * `POST /skills` 开始处理时再顺延这么久，处理期间不会被清理。
  */
 export declare const SKILL_PACKAGE_TTL_HOURS = 1;
+/** The image types an agent avatar upload may have (cropped square in the browser). */
+export declare const AGENT_AVATAR_CONTENT_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+/** The size limit of an agent avatar upload (bytes). */
+export declare const AGENT_AVATAR_MAX_BYTES: number;
+/** Unfinished avatar uploads one account may have in an org (counted apart from other uploads). */
+export declare const MAX_PENDING_AGENT_AVATARS = 10;
+/** An avatar upload not saved into a profile expires (and is cleaned up) after this many hours. */
+export declare const AGENT_AVATAR_TTL_HOURS = 24;
+/** Download redirect lifetime of an avatar (seconds); also its `Cache-Control` max-age. */
+export declare const AGENT_AVATAR_DOWNLOAD_TTL_SECONDS = 300;
 /**
  * 技能包解出的文件在 `kernel/<orgId>/` 下的前缀：按上传 id，同一上传重试写到同一批键（幂等），
  * 并发处理同一上传也不会互相覆盖出不同内容。版本行记下这个前缀（`skill_versions.object_prefix`）。
@@ -169,6 +179,26 @@ export declare class AttachmentsService {
      * 不是该账号的 ready 技能包（如已被并发的请求用掉）→ `attachment.not_found`。
      */
     consumeSkillPackage(orgId: string, accountId: string, id: string): Promise<void>;
+    /**
+     * Makes an agent avatar upload ready to be saved into a profile (outside any transaction: it may
+     * read the object store): only the uploader, only the `agent-avatar` purpose, an image type, not
+     * expired and not yet used by another agent, else `attachment.not_found`. An upload still
+     * `pending` is finalized first (size, type and the image signature are checked). The expiry is
+     * extended so the cleanup job cannot delete it before {@link consumeAgentAvatar} runs.
+     */
+    prepareAgentAvatar(orgId: string, accountId: string, id: string, agentId: string): Promise<void>;
+    /**
+     * In the caller's transaction, binds a ready avatar upload to `agentId` (row lock; the expiry is
+     * cleared, so the cleanup job keeps it while the profile uses it). An upload another agent
+     * already uses, or one that is not the account's ready avatar → `attachment.not_found`; saving
+     * the same upload to the same agent again is fine.
+     */
+    consumeAgentAvatar(orgId: string, accountId: string, id: string, agentId: string): Promise<void>;
+    /**
+     * A short-lived presigned GET (inline, with the checked image type) of the avatar upload bound
+     * to `agentId`; `null` when there is none or its object is gone or no longer the finalized one.
+     */
+    agentAvatarUrl(orgId: string, agentId: string, id: string): Promise<string | null>;
     /**
      * 删除过期（`expires_at < now()`）且从未绑定到会话的附件：先把行认领为 `deleting`（`FOR UPDATE SKIP LOCKED`，
      * 多副本并发时互不重复），再删对象、删行。删对象失败的行保持 `deleting`，下次运行重试。