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

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
@@ -207,9 +215,9 @@ export const KernelConfigSchema = z.object({
         dir: z
             .string()
             .min(1)
-            .default("/var/lib/capybara/plugins")
+            .default(".capybara/plugins")
             .meta(meta({
-            description: "Local directory where each replica unpacks installed extension packages (<dir>/<name>/<first 16 hex of sha256>/); safe to wipe, replicas re-download from the package store",
+            description: "Local directory where each replica unpacks installed extension packages (<dir>/<name>/<first 16 hex of sha256>/), relative to the working directory unless absolute (the image sets /var/lib/capybara/plugins); safe to wipe, replicas re-download from the package store",
         })),
         drainSeconds: z
             .number()
@@ -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"],
@@ -336,7 +344,7 @@ export const KernelConfigSchema = z.object({
             .min(1)
             .default(360)
             .meta(meta({
-            description: "Minutes between periodic refreshes of every enabled marketplace (one maintenance job for all replicas)",
+            description: "Minutes between periodic refreshes of every enabled marketplace (one run per period across all replicas)",
         })),
         maxIndexBytes: z
             .number()
@@ -472,6 +480,12 @@ export const KernelConfigSchema = z.object({
             .meta(meta({
             description: "Optional replica identifier; when set, every HTTP response carries an x-capybara-replica header with this value (used by the dual-replica test harness and for debugging load balancers)",
         })),
+        swagger: z
+            .boolean()
+            .default(false)
+            .meta(meta({
+            description: "Serve the OpenAPI document and swagger UI at /docs (JSON at /docs-json). The routes are not authenticated, so enable it in development and trials only",
+        })),
         publicUrl: z
             .url()
             .optional()
@@ -479,7 +493,7 @@ export const KernelConfigSchema = z.object({
             description: "Externally reachable origin of the web app (apps/web, which proxies /api to the kernel), not the kernel's own address; required for OAuth connectors: the redirect URI is <publicUrl>/api/v1/oauth/callback (served through the web /api proxy, which also carries the OAuth binding cookie) and the callback redirects to web pages under it, e.g. https://capybara.example.com",
         })),
     })
-        .default({ port: 8080, trustProxy: false }),
+        .default({ port: 8080, trustProxy: false, swagger: false }),
     roles: z
         .preprocess(
     // Also accept a comma-separated string (CAPYBARA_ROLES=api,worker; env values that are not
@@ -562,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()
@@ -650,6 +670,7 @@ export const KernelConfigSchema = z.object({
     })
         .default({
         maxSteps: 50,
+        wakeOnBackgroundTask: true,
         maxRunSeconds: DEFAULT_MAX_RUN_SECONDS,
         streamIdleMs: 60000,
         maxOutputTokens: 16000,
@@ -745,7 +766,7 @@ export const KernelConfigSchema = z.object({
             .int()
             .positive()
             .default(20000)
-            .meta(meta({ description: "Maximum characters returned by one read_tool_output call" })),
+            .meta(meta({ description: "Maximum characters returned by one ReadToolOutput call" })),
         oauthAllowInsecureLoopback: z
             .boolean()
             .default(false)
@@ -909,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)
@@ -917,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()
@@ -964,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()
@@ -972,8 +1062,37 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(104_857_600)
             .meta(meta({
-            description: "Largest file in bytes an agent may deliver from its sandbox to the user as an artifact (sandbox_deliver)",
+            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
@@ -981,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()
@@ -989,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()
@@ -997,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()
@@ -1013,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()
@@ -1021,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()
@@ -1029,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())
@@ -1048,7 +1167,65 @@ 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",
+        })),
+        device: z
+            .object({
+            reconnectGraceSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(120)
+                .meta(meta({
+                hot: true,
+                description: "Seconds a connected machine may stay disconnected before its environment is reported offline; also sent to the device program at sign-in",
+            })),
+            leaseTtlMs: z
+                .number()
+                .int()
+                .min(6000)
+                .default(30000)
+                .meta(meta({
+                description: "Milliseconds the replica holding a machine's connection keeps its lease without renewing it; at least 6000",
+            })),
+            authCodeTtlSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(600)
+                .meta(meta({
+                description: "Seconds a device sign-in code stays valid before the program must start over (device.expired)",
+            })),
+            pollIntervalSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(5)
+                .meta(meta({
+                description: "Seconds the device program waits between token polls during sign-in; polling faster gets device.slow_down",
+            })),
+            maxFrameBytes: z
+                .number()
+                .int()
+                .positive()
+                .default(16 * 1024 * 1024)
+                .meta(meta({
+                description: "Largest WebSocket frame in bytes accepted from or sent to a connected machine",
             })),
         })
             .prefault({}),
@@ -1120,6 +1297,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

@@ -0,0 +1,31 @@
+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 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>;
+/**
+ * Whether a person may still see a conversation (one query, no agent view): what the event stream,
+ * attachment downloads, file and output reads and the extension UI check. `ConversationsService`
+ * delegates to it; it depends on the database only, so the attachments (which the skills and tools
+ * use) can check access without the conversations module.
+ */
+export declare class ConversationAccess {
+    private readonly db;
+    constructor(db: KernelDb);
+    /**
+     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
+     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
+     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
+     */
+    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+}
+/** The one {@link ConversationAccess} (database only). */
+export declare class ConversationAccessModule {
+}

package/dist/conversations/access.js

@@ -0,0 +1,110 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { sql } from "kysely";
+import { visibleTo } from "../agents/agent-lookup.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * 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"),
+    eb.exists(eb
+        .selectFrom("conversations as p")
+        .innerJoin("agents", "agents.id", "p.agent_id")
+        .select(sql `1`.as("one"))
+        .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))),
+]);
+/**
+ * Whether a person may still see a conversation (one query, no agent view): what the event stream,
+ * attachment downloads, file and output reads and the extension UI check. `ConversationsService`
+ * delegates to it; it depends on the database only, so the attachments (which the skills and tools
+ * use) can check access without the conversations module.
+ */
+let ConversationAccess = class ConversationAccess {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
+     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
+     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
+     */
+    async isAccessible(orgId, conversationId, viewerAccountId) {
+        const row = await this.db
+            .selectFrom("conversations")
+            .select("conversations.id")
+            .where("conversations.id", "=", conversationId)
+            .where("conversations.org_id", "=", orgId)
+            .where("conversations.account_id", "=", viewerAccountId)
+            .where("conversations.deleted_at", "is", null)
+            .where("conversations.kind", "in", ["chat", "subagent"])
+            .where(parentReachable(viewerAccountId))
+            .where((eb) => eb.and([
+            eb.exists(eb
+                .selectFrom("accounts")
+                .select(sql `1`.as("one"))
+                .where("accounts.id", "=", viewerAccountId)
+                .where("accounts.status", "=", "active")),
+            eb.exists(eb
+                .selectFrom("agents")
+                .select(sql `1`.as("one"))
+                .whereRef("agents.id", "=", "conversations.agent_id")
+                .where("agents.deleted_at", "is", null)
+                .where(visibleTo(viewerAccountId))),
+        ]))
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+};
+ConversationAccess = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], ConversationAccess);
+export { ConversationAccess };
+/** The one {@link ConversationAccess} (database only). */
+let ConversationAccessModule = class ConversationAccessModule {
+};
+ConversationAccessModule = __decorate([
+    Module({ providers: [ConversationAccess], exports: [ConversationAccess] })
+], ConversationAccessModule);
+export { ConversationAccessModule };

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>;