broods 0.54.0 → 0.55.0

package/dist/account.d.ts

@@ -2,230 +2,54 @@ import { SystemModelMessage, LanguageModelCallOptions, RequestOptions, streamTex
 import * as convex_values from 'convex/values';
 import { Infer } from 'convex/values';
 
-/**
- * Account-owned code hook upload validation for Convex config-plane sync.
- * Mirrors core's account hook upload contract without requiring the Node runtime.
- */
 declare const AGENT_HOOK_EVENT_NAMES: readonly ["agent.started", "agent.step.finished", "agent.finished", "agent.failed", "agent.approval.required", "tool.call.started", "tool.call.finished", "tool.result", "subagent.task.started", "subagent.task.finished", "channel.message.received", "channel.message.sending"];
 type AgentHookEventName = (typeof AGENT_HOOK_EVENT_NAMES)[number];
 
-/**
- * Every Vercel AI SDK provider that ships language models, the community
- * providers on the same spec that take an API key (`cloudflare`, `llmgateway`,
- * `ollama`, `openrouter`), `custom` (any OpenAI-compatible endpoint), and
- * `chatgpt` (OpenAI on a Sign in with ChatGPT login instead of an API key).
- * Image-, speech- and transcription-only providers are deliberately absent:
- * they cannot back `config.model`.
- */
-declare const MODEL_PROVIDERS: {
-    readonly alibaba: {
-        readonly label: "Alibaba Qwen";
-        readonly modelPlaceholder: "qwen3-max";
-    };
-    readonly anthropic: {
-        readonly label: "Anthropic";
-        readonly modelPlaceholder: "claude-sonnet-4-5-20250929";
-    };
-    readonly azure: {
-        readonly label: "Azure OpenAI";
-        readonly modelPlaceholder: "gpt-4.1-mini";
-    };
-    readonly baseten: {
-        readonly label: "Baseten";
-        readonly modelPlaceholder: "deepseek-ai/DeepSeek-V3";
-    };
-    readonly bedrock: {
-        readonly label: "Amazon Bedrock";
-        readonly modelPlaceholder: "anthropic.claude-sonnet-4-5-20250929-v1:0";
-    };
-    readonly cerebras: {
-        readonly label: "Cerebras";
-        readonly modelPlaceholder: "llama3.1-8b";
-    };
-    readonly chatgpt: {
-        readonly label: "ChatGPT plan";
-        readonly modelPlaceholder: "gpt-5.5";
-    };
-    readonly cloudflare: {
-        readonly label: "Cloudflare";
-        readonly modelPlaceholder: "@cf/meta/llama-3.3-70b-instruct-fp8-fast";
-    };
-    readonly cohere: {
-        readonly label: "Cohere";
-        readonly modelPlaceholder: "command-a-03-2025";
-    };
-    readonly custom: {
-        readonly label: "Custom OpenAI-compatible";
-        readonly modelPlaceholder: "gpt-oss-120b";
-    };
-    readonly deepinfra: {
-        readonly label: "DeepInfra";
-        readonly modelPlaceholder: "deepseek-ai/DeepSeek-V3";
-    };
-    readonly deepseek: {
-        readonly label: "DeepSeek";
-        readonly modelPlaceholder: "deepseek-chat";
-    };
-    readonly fireworks: {
-        readonly label: "Fireworks";
-        readonly modelPlaceholder: "accounts/fireworks/models/deepseek-v3";
-    };
-    readonly google: {
-        readonly label: "Google";
-        readonly modelPlaceholder: "gemini-2.5-flash";
-    };
-    readonly groq: {
-        readonly label: "Groq";
-        readonly modelPlaceholder: "llama-3.3-70b-versatile";
-    };
-    readonly huggingface: {
-        readonly label: "Hugging Face";
-        readonly modelPlaceholder: "meta-llama/Llama-3.3-70B-Instruct";
-    };
-    readonly llmgateway: {
-        readonly label: "LLM Gateway";
-        readonly modelPlaceholder: "openai/gpt-4.1-mini";
-    };
-    readonly minimax: {
-        readonly label: "MiniMax";
-        readonly modelPlaceholder: "MiniMax-M2.7";
-    };
-    readonly mistral: {
-        readonly label: "Mistral";
-        readonly modelPlaceholder: "mistral-large-latest";
-    };
-    readonly moonshotai: {
-        readonly label: "Moonshot AI Kimi";
-        readonly modelPlaceholder: "kimi-k2.6";
-    };
-    readonly ollama: {
-        readonly label: "Ollama";
-        readonly modelPlaceholder: "gpt-oss:120b";
-    };
-    readonly openai: {
-        readonly label: "OpenAI";
-        readonly modelPlaceholder: "gpt-4.1-mini";
-    };
-    readonly openrouter: {
-        readonly label: "OpenRouter";
-        readonly modelPlaceholder: "anthropic/claude-sonnet-4.5";
-    };
-    readonly perplexity: {
-        readonly label: "Perplexity";
-        readonly modelPlaceholder: "low";
-    };
-    readonly togetherai: {
-        readonly label: "Together.ai";
-        readonly modelPlaceholder: "deepseek-ai/DeepSeek-V3";
-    };
-    readonly v0: {
-        readonly label: "Vercel v0";
-        readonly modelPlaceholder: "v0-1.0-md";
-    };
-    readonly vercel: {
-        readonly label: "Vercel AI Gateway";
-        readonly modelPlaceholder: "openai/gpt-4.1-mini";
-    };
-    readonly vertex: {
-        readonly label: "Google Vertex AI";
-        readonly modelPlaceholder: "gemini-2.5-flash";
-    };
-    readonly xai: {
-        readonly label: "xAI Grok";
-        readonly modelPlaceholder: "grok-4";
-    };
-    readonly zai: {
-        readonly label: "Z.ai GLM";
-        readonly modelPlaceholder: "glm-4.7";
-    };
-};
-type AccountModelProviderName = keyof typeof MODEL_PROVIDERS;
-
-/**
- * Agent config validation, the only copy of it: Convex config HTTP checks a
- * config on write and core re-checks the stored config on every run. Pure
- * module: safe for the default Convex runtime. The public projection lives in
- * ./responses.ts.
- */
+declare const ACCOUNT_MODEL_PROVIDER_NAMES: readonly ["alibaba", "anthropic", "azure", "baseten", "bedrock", "cerebras", "chatgpt", "cloudflare", "cohere", "custom", "deepinfra", "deepseek", "fireworks", "google", "groq", "huggingface", "llmgateway", "minimax", "mistral", "moonshotai", "ollama", "openai", "openrouter", "perplexity", "togetherai", "v0", "vercel", "vertex", "xai", "zai"];
+type AccountModelProviderName = (typeof ACCOUNT_MODEL_PROVIDER_NAMES)[number];
 
 declare const AGENT_HARNESS_TYPES: readonly ["claude-code", "codex", "deepagents", "opencode", "pi"];
 declare const AGENT_HARNESS_DEBUG_LEVELS: readonly ["error", "warn", "info", "debug", "trace"];
 declare const AGENT_HARNESS_PERMISSION_MODES: readonly ["allow-reads", "allow-edits", "allow-all"];
 declare const AGENT_LIFECYCLE_EVENT_NAMES: readonly ["agent.started", "agent.step.finished", "agent.finished", "agent.failed", "agent.approval.required", "tool.call.started", "tool.call.finished", "tool.result", "subagent.task.started", "subagent.task.finished"];
 
-/**
- * Shared validation for MCP server registrations (#331). One normalizer
- * serves every write path (CLI sync, direct API, dashboard). A `url` makes an "http" row
- * core connects to over the stateless 2026-07-28 transport; a `bundle` makes
- * a "hosted" row, hashed here so sha256 always travels with the bundle; the
- * S3 bundle writer (aws/bundles.ts) marks whether Cloudflare Dynamic Workers
- * can run it. Auth header values may carry ${NAME}
- * account env refs; they resolve into the encrypted agent config at sync
- * time, never on this row, and credential-bearing headers must use one
- * instead of an inline secret. `oauth` follows the same rule: clientSecret
- * and refreshToken must be ${NAME} refs, so the row never holds a secret.
- */
-
-/**
- * OAuth 2.0 refresh-token grant for an external row. Core mints access tokens
- * at connect time and sends `Authorization: Bearer <token>`, so a server
- * whose tokens expire (Google's Workspace MCP endpoints) still works where a
- * static header cannot. Secret fields hold ${NAME} refs on the row.
- */
 interface McpOauth {
     clientId: string;
     clientSecret: string;
     refreshToken: string;
-    /** Token endpoint, https only; core defaults to https://oauth2.googleapis.com/token. */
     tokenUrl?: string;
 }
 
-/**
- * Agent configuration: types for the per-agent settings object and the
- * runtime projection of a stored config. The validation rules are the config
- * plane's (`@broods/convex/model/agentRules`), so a config is judged the same
- * on write and on every run. Decrypting the stored blob is
- * `../convex/account-keys.ts`.
- * Account types and auth live in `./accounts.ts` and `../auth.ts`.
- */
-
 interface AgentConfig {
     agent?: AgentBehaviorConfig;
     harness?: AgentHarnessConfig;
     model?: AgentModelConfig;
     provider?: AgentProviderConfig;
+    /** Sandbox record ids. The first is the default for bash, workspaces and a harness. */
     sandboxes?: string[];
     workspaces?: AgentWorkspaceRef[];
     session?: AgentSessionConfig;
     hooks?: AgentHooksConfig;
     channels?: AgentChannelsConfig;
     tools?: AgentToolsConfig;
-    /** Connected MCP servers, keyed by their config-plane row id (#331). */
     mcp?: AgentMcpConfig;
-    /**
-     * Tool names withheld for this run, applied after the tool set is built.
-     * Set by a channel record; a channel can take a tool away, never add one.
-     * Names that are not present are ignored.
-     */
+    /** Withheld after the tool set is built; a channel can take a tool away, never add one. */
     denyTools?: string[];
     skills?: AgentSkillsConfig;
     subagent?: AgentSubagentConfig;
     scheduler?: AgentSchedulerConfig;
-    /**
-     * Registers the `browse` tool, which runs Obscura on the first sandbox. That
-     * sandbox must be lambda with image "obscura" and network allow-all, or a
-     * machine; manifest sync refuses anything else it can see.
-     */
+    /** `browse` runs on the first sandbox: a machine, or lambda "obscura" with allow-all. */
     browser?: {
         enabled?: boolean;
     };
-    /** Policies that gate this agent. Each one carries its own enforcement mode. */
     policies?: string[];
+    /** Opens the runtime-key path; account keys, cron and channel webhooks never need it. */
     publicAccess?: boolean;
     allowRunOverrides?: boolean;
     [key: string]: unknown;
 }
 interface AgentBehaviorConfig {
+    /** Steps per turn. 0 lifts the cap; unset is the harness default. */
     maxTurn?: number;
     system?: string | SystemModelMessage | SystemModelMessage[];
     [key: string]: unknown;
@@ -251,10 +75,6 @@ interface AgentSkillsConfig {
     allowed?: string[];
     [key: string]: unknown;
 }
-/**
- * Opt-in for the `schedule` tool. Off by default: a scheduled task starts
- * billable agent runs long after the turn that asked for it.
- */
 interface AgentSchedulerConfig {
     enabled?: boolean;
     [key: string]: unknown;
@@ -264,33 +84,16 @@ interface AgentSubagentConfig {
     allowed?: string[];
     context?: "new" | "inherited";
     mode?: "ephemeral" | "persistent";
-    /**
-     * Publishes child reasoning, text, and tool stream parts to the existing
-     * WebSocket/JetStream response path. Off by default.
-     */
     stream?: boolean;
-    /**
-     * Controls what the parent agent sees from a finished subagent (AI SDK
-     * "controlling what the model sees"): `full` = the child's whole transcript,
-     * `result` = only its final result (default), `none` = nothing. A
-     * `subagent.task.finished` code hook overrides this for custom shaping.
-     */
+    /** What the parent sees of a finished child; default `result`. A code hook can override it. */
     visibility?: "full" | "result" | "none";
-    /**
-     * Model for virtual subagents (no `agentId`), laid over the parent's
-     * `model` key by key. The child keeps the parent's tools, MCP, sandboxes,
-     * hooks and policies. A registered agent always runs on its own model.
-     */
+    /** Virtual subagents only, merged over the parent's `model`; registered agents use their own. */
     model?: Partial<AgentModelConfig>;
     [key: string]: unknown;
 }
 interface AgentModelConfig extends LanguageModelCallOptions, Partial<Pick<RequestOptions, "maxRetries" | "timeout">> {
     provider?: AccountModelProviderName;
     modelId?: string;
-    /**
-     * Speech-to-text model for inbound audio, on the same provider and key as
-     * `modelId`. Defaults to the widest-container model the provider ships.
-     */
     transcriptionModelId?: string;
     providerOptions?: AgentModelProviderOptions;
     output?: AgentModelOutputConfig;
@@ -317,16 +120,10 @@ type AgentModelOutputMetadata = {
 type AgentProviderConfig = Partial<Record<AccountModelProviderName, AgentProviderSettings>>;
 interface AgentProviderSettings {
     apiKey?: string;
-    /** OpenAI-compatible endpoint (`custom`). Snake form, as documented. */
     base_url?: string;
-    /** OpenAI-compatible endpoint (`custom`). AI-SDK form; the dashboard writes both. */
     baseURL?: string;
-    /** Cloudflare AI Gateway id (`cloudflare`). Set, requests go through the gateway. */
     gatewayId?: string;
-    /** A streamed model request with no response within this many ms is sent again. Unset: no limit. */
-    firstByteTimeoutMs?: number;
     headers?: Record<string, string>;
-    /** Endpoint label; becomes the provider id and the pi harness env prefix. */
     name?: string;
     organization?: string;
     project?: string;
@@ -335,6 +132,7 @@ interface AgentProviderSettings {
 interface AgentWorkspaceRef {
     name: string;
     workspaceId: string;
+    /** Unset inherits the default; `null` is read-only, read from S3 without a mount. */
     sandbox?: string | null;
 }
 interface AgentSessionConfig {
@@ -346,35 +144,19 @@ interface AgentSessionPruningConfig {
     enabled?: boolean;
     [key: string]: unknown;
 }
-/**
- * Compaction after a finished turn, on unless `enabled: false`. It runs once
- * the turn's last model call read `maxContextLength` input tokens or more
- * (default 500000), or after the provider refused a turn for context length.
- * `/compact` works whatever this says.
- */
+/** On by default: runs once a turn's last call read `maxContextLength` (500000) tokens. */
 interface AgentSessionAutoCompactionConfig {
     enabled?: boolean;
     maxContextLength?: number;
     [key: string]: unknown;
 }
 interface AgentHooksConfig {
-    /** Outbound event webhooks. An agent may register several independent endpoints. */
     webhooks?: AgentWebhookHookConfig[];
-    /**
-     * Uploaded code hooks. Each entry references an accountHooks bundle by id; the
-     * bundle runs in the V8 isolate at the matching fire-points and its validated
-     * return is folded into mutable harness state.
-     */
     code?: AgentCodeHookConfig[];
     [key: string]: unknown;
 }
 interface AgentCodeHookConfig {
     hookId: string;
-    /**
-     * Optional narrowing of the events this reference reacts to. Omitted => the
-     * bundle's own declared `events` set. Any listed event outside the bundle's
-     * declared set is ignored at runtime.
-     */
     events?: AgentHookEventName[];
     enabled?: boolean;
     [key: string]: unknown;
@@ -392,22 +174,14 @@ type AgentToolsConfig = Record<string, AgentToolConfig>;
 interface AgentToolConfig {
     enabled?: boolean;
     needsApproval?: boolean;
-    async?: boolean;
     config?: Record<string, unknown>;
     [key: string]: unknown;
 }
 type AgentMcpConfig = Record<string, AgentMcpEntry>;
 interface AgentMcpEntry {
     enabled?: boolean;
-    /** Applies to every tool the server exposes. */
     needsApproval?: boolean;
-    /** Extra request headers; values resolved from account env vars at sync. */
     headers?: Record<string, string>;
-    /**
-     * Overrides for the row's oauth credentials; values resolved from account
-     * env vars at sync, so the row's ${NAME} refs never reach the token
-     * endpoint. tokenUrl stays on the row, where registration checked it.
-     */
     oauth?: Partial<Omit<McpOauth, "tokenUrl">>;
     [key: string]: unknown;
 }
@@ -422,17 +196,11 @@ interface AgentChannelsConfig {
     teams?: AgentTeamsChannelConfig;
     twilio?: AgentTwilioChannelConfig;
     zalo?: AgentZaloChannelConfig;
-    matrix?: AgentMatrixChannelConfig;
     instagram?: AgentInstagramChannelConfig;
     messenger?: AgentMessengerChannelConfig;
     whatsapp?: AgentWhatsAppChannelConfig;
     [key: string]: unknown;
 }
-/**
- * How an attached partitioned workspace splits its folders for runs arriving
- * through this door. `shared` mounts the workspace root; `conversation` mounts
- * a private child folder per thread, issue or chat under `alias`.
- */
 type ChannelPartition = {
     by: "shared";
     alias?: never;
@@ -447,7 +215,6 @@ interface AgentTelegramChannelConfig {
     webhookSecret?: string;
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
-    /** Bot's @username, e.g. `tracy_bot`. Set it to answer only when the agent is mentioned. */
     botUsername?: string;
     reactionEmoji?: string;
     trace?: "enabled" | "disabled";
@@ -462,31 +229,20 @@ interface AgentGitHubChannelConfig {
     privateKey?: string;
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
-    /** Bot username for @-mention detection (e.g. "my-bot" or "my-bot[bot]"). */
     botUserName?: string;
-    /** Bot's numeric GitHub user ID for self-message detection. */
     botUserId?: number;
-    /** When false, the bot does not auto-trigger on new issues (opened/edited/reopened). Defaults to true. The bot still triggers when assigned to an issue. */
     triggerOnIssueOpen?: boolean;
-    /** When false, the bot does not auto-trigger on new PRs (opened/edited/reopened). Defaults to true. The bot still triggers when assigned to a PR. */
     triggerOnPROpen?: boolean;
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A Linear member the agent comments as, through that member's personal API
- * key. The agent answers comments that mention `@userName` on issues, and
- * `webhookSecret` checks every delivery.
- */
 interface AgentLinearChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
     id?: string;
     apiKey?: string;
-    /** Linear GraphQL endpoint. Defaults to `https://api.linear.app/graphql`. */
     apiUrl?: string;
-    /** The member's display name, e.g. `acme-agent`. `@acme-agent` addresses the agent. */
     userName?: string;
     webhookSecret?: string;
     trace?: "enabled" | "disabled";
@@ -512,41 +268,12 @@ interface AgentDiscordChannelConfig {
     publicKey?: string;
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
-    /** Bot's Discord user id. Set it to answer only when the agent is mentioned. */
     botUserId?: string;
-    /** Role ids that count as mentioning the agent, e.g. an on-call role. */
     mentionRoleIds?: string[];
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A Matrix account the agent speaks as. Matrix has no bot concept, so this is
- * usually a person's own account: replies carry a per-message profile named
- * `botName`, and `mentionText` decides what addresses the agent, because a
- * mention of the account would also be a mention of its owner.
- */
-interface AgentMatrixChannelConfig {
-    id?: string;
-    /** Homeserver base URL, e.g. `https://matrix.org`. */
-    apiUrl?: string;
-    /** Access token of the account; `apps/matrix-forwarder` syncs with it. */
-    botToken?: string;
-    /** Room ids. */
-    allowedChannelIds?: string[];
-    /** Matrix user ids, e.g. `@alice:matrix.org`. */
-    allowedUserIds?: string[];
-    /** Name replies are shown under. Unset, replies look like the account's own messages. */
-    botName?: string;
-    /**
-     * Text that addresses the agent, e.g. `@georgi-ai`. Unset, a mention of the
-     * account does. Other messages are stored as context either way.
-     */
-    mentionText?: string;
-    trace?: "enabled" | "disabled";
-    partition?: ChannelPartition;
-    [key: string]: unknown;
-}
 interface AgentPancakeChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
@@ -569,73 +296,46 @@ interface AgentZaloChannelConfig {
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * An Instagram professional account, reached through a Meta app with
- * Instagram Login. `accountId` is the account the webhook entries name.
- */
 interface AgentInstagramChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
     id?: string;
-    /** Instagram user access token with `instagram_business_manage_messages`. */
     accessToken?: string;
-    /** Instagram professional account id. */
     accountId?: string;
-    /** Graph API version, e.g. `v26.0`. Defaults to the SDK's. */
     apiVersion?: string;
-    /** Meta app secret; signs every webhook POST. */
     appSecret?: string;
     userName?: string;
-    /** The verify token typed into the Meta webhook settings. */
     verifyToken?: string;
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/** A Facebook Page the agent answers Messenger DMs for. */
 interface AgentMessengerChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
     id?: string;
-    /** Graph API version, e.g. `v21.0`. Defaults to the SDK's. */
     apiVersion?: string;
-    /** Meta app secret; signs every webhook POST. */
     appSecret?: string;
-    /** Page access token for the Page the app is subscribed to. */
     pageAccessToken?: string;
     userName?: string;
-    /** The verify token typed into the Meta webhook settings. */
     verifyToken?: string;
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A Google Chat app on the HTTP endpoint connection. It posts as the service
- * account in `credentials`, and a webhook is accepted when its Google-signed
- * token names `endpointUrl` or `googleChatProjectNumber` as the audience.
- */
 interface AgentGoogleChatChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
     id?: string;
-    /** The service-account key JSON, as downloaded from Google Cloud. */
     credentials?: string;
-    /** Audience when the app authenticates with "HTTP endpoint URL". */
     endpointUrl?: string;
-    /** Audience when the app authenticates with "Project number". */
     googleChatProjectNumber?: string;
-    /** `service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`, for an app built as a Workspace add-on. */
     workspaceAddOnServiceAccountEmail?: string;
     userName?: string;
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A Microsoft Teams bot registered in Azure Bot Service, authenticated with a
- * client secret. `appTenantId` is required unless `appType` is `MultiTenant`.
- */
 interface AgentTeamsChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
@@ -650,11 +350,6 @@ interface AgentTeamsChannelConfig {
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A Twilio number or Messaging Service for SMS and MMS. `authToken` checks
- * Twilio's signature, which covers the exact public URL Twilio called, so
- * `webhookUrl` is only set when that URL is not the broods webhook URL.
- */
 interface AgentTwilioChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
@@ -662,22 +357,16 @@ interface AgentTwilioChannelConfig {
     accountSid?: string;
     apiUrl?: string;
     authToken?: string;
-    /** `MG...`. Replies go through the service instead of the number texted. */
     messagingServiceSid?: string;
-    /** E.164 number, e.g. `+15551234567`. Messages to another number go to the agent holding it. */
     phoneNumber?: string;
     statusCallbackUrl?: string;
     userName?: string;
-    /** The URL entered in the Twilio console, when it is not `{PUBLIC_BASE_URL}/v1/webhooks/...`. */
+    /** The URL Twilio calls, when not the broods webhook: its signature covers the exact URL. */
     webhookUrl?: string;
     trace?: "enabled" | "disabled";
     partition?: ChannelPartition;
     [key: string]: unknown;
 }
-/**
- * A WhatsApp Business Cloud API number. `appSecret` signs every delivery and
- * `verifyToken` answers Meta's subscription handshake.
- */
 interface AgentWhatsAppChannelConfig {
     allowedChannelIds?: string[];
     allowedUserIds?: string[];
@@ -694,18 +383,8 @@ interface AgentWhatsAppChannelConfig {
     [key: string]: unknown;
 }
 
-/**
- * Cron-job records and patch-merge helpers for the runtime. Input
- * normalization lives in the config plane (packages/convex/model/cronRules.ts,
- * the single home of those rules).
- */
-
 type CronStatus = "active" | "paused";
 type CronLastStatus = "started" | "completed" | "failed";
-/**
- * One-of run payload mirroring the agent direct API's AgentRunInput: provide a
- * single `input` string (wrapped into one user message) or a full `events` list.
- */
 type CronRunInput = {
     input: string;
     events?: never;
@@ -738,20 +417,9 @@ type UpdateCronInput = {
     input?: never;
 });
 
-/**
- * The sandbox provider list: the one list the schema validator, the config
- * rules, core's executor registry and the SDK derive from. A leaf on purpose,
- * so `schema.ts` can read it without pulling the rules' import graph.
- */
 declare const SANDBOX_PROVIDERS: readonly ["sandbox", "lambda", "e2b", "daytona", "vercel", "cloudflare", "worker", "machine", "custom"];
 type SandboxProvider = (typeof SANDBOX_PROVIDERS)[number];
 
-/**
- * Sandbox-config validation for the Convex config plane. Ports core's former
- * storage/sandbox-config.ts normalizer so the public /v1/sandboxes contract
- * is unchanged. The public projection lives in ./responses.ts.
- */
-
 declare const SANDBOX_IMAGES: readonly ["browser", "obscura"];
 declare const SANDBOX_RUNTIMES: readonly ["bash", "python", "node"];
 declare const SANDBOX_PERMISSION_MODES: readonly ["edit", "ask", "bypass"];
@@ -762,9 +430,6 @@ type PermissionMode = (typeof SANDBOX_PERMISSION_MODES)[number];
 type NetworkMode = (typeof SANDBOX_NETWORK_MODES)[number];
 type SandboxSize = (typeof SANDBOX_SIZE_NAMES)[number];
 type SandboxImage = (typeof SANDBOX_IMAGES)[number];
-/**
- * Idle and maximum lifetime controls for a persistent sandbox.
- */
 interface SandboxLifecycleConfig {
     idleTimeoutSeconds?: number;
     maxLifetimeSeconds?: number;
@@ -774,9 +439,6 @@ interface SandboxNetworkConfig {
     allowDomains?: string[];
     allowCidrs?: string[];
 }
-/**
- * Account-scoped reusable sandbox configuration referenced by agents.
- */
 interface SandboxConfig {
     provider: SandboxProvider;
     fallbackProvider?: SandboxProvider;
@@ -796,47 +458,20 @@ interface SandboxConfig {
     options?: Record<string, unknown>;
 }
 
-/**
- * Workspace isolation levels, the one list the config plane, core, the
- * dashboard and the CLI read. No imports on purpose: the CLI bundles this file
- * without the Convex runtime behind workspaceRules (like modelProviders.ts).
- */
 declare const WORKSPACE_ISOLATION_LEVELS: readonly ["conversation", "agent"];
-/**
- * How a workspace splits its files. "conversation" mounts a folder per channel
- * partition, "agent" gives every attached agent its own folder. Unset shares
- * one root between every agent and conversation.
- */
+/** A folder per channel partition or per agent; unset shares one root. */
 type WorkspaceIsolation = (typeof WORKSPACE_ISOLATION_LEVELS)[number];
 
-/**
- * Workspace-config validation for the Convex config plane. Ports core's
- * former storage/workspace-config.ts normalizer so the public /v1/workspaces
- * contract is unchanged. Workspace config holds no secrets (a roleArn is not
- * a secret, and R2 keys are `${NAME}` env refs), so it is stored and returned
- * in plaintext. Pure module, safe
- * for the default Convex runtime. The public projection lives in
- * ./responses.ts. Core runs the storage access rule too, so it reads the env
- * names of both sides.
- */
-
 declare const WORKSPACE_STORAGE_PROVIDERS: readonly ["s3"];
 type WorkspaceStorageProvider = (typeof WORKSPACE_STORAGE_PROVIDERS)[number];
 type WorkspaceStorageAuth = {
     type: "managed";
-}
-/**
- * The role's trust policy requires the account's Broods-assigned
- * sts:ExternalId (`storageTrust.ts`); a customer never sets one here.
- */
- | {
+} | {
     type: "assumeRole";
     roleArn: string;
 } | {
     type: "r2";
-    /** `${NAME}` ref to the parent R2 token's access key id. */
     accessKeyId: string;
-    /** `${NAME}` ref to the parent R2 token's secret access key. */
     secretAccessKey: string;
 };
 interface WorkspaceStorageConfig {
@@ -860,11 +495,6 @@ interface WorkspaceConfig {
     };
 }
 
-/**
- * Versioned policy document accepted by account-management CRUD, as the
- * `agentPolicies` and `accountRoles` tables store it. `mode` says how hard
- * the policy bites where it is attached; omitted reads as `audit`.
- */
 declare const policyDocumentValidator: convex_values.VObject<{
     mode?: "enforce" | "audit" | undefined;
     version: 1;
@@ -944,7 +574,6 @@ declare const policyDocumentValidator: convex_values.VObject<{
             resourceIds?: string[] | undefined;
         } | undefined, {
             toolNames: convex_values.VArray<string[] | undefined, convex_values.VString<string, "required">, "optional">;
-            /** MCP registration ids, for scoping tool.call rules per server (#331). */
             mcpIds: convex_values.VArray<string[] | undefined, convex_values.VString<string, "required">, "optional">;
             workspaceIds: convex_values.VArray<string[] | undefined, convex_values.VString<string, "required">, "optional">;
             workspaceNames: convex_values.VArray<string[] | undefined, convex_values.VString<string, "required">, "optional">;
@@ -970,35 +599,15 @@ declare const policyDocumentValidator: convex_values.VObject<{
 }, "required", "version" | "mode" | "rules">;
 type PolicyDocument = Infer<typeof policyDocumentValidator>;
 
-/**
- * Channel record validation for the config plane, the single home of the
- * normalizers core's `shared/domain/channel-record.ts` re-exports. Kept free
- * of Convex imports so the rules stay unit-testable; the public projection
- * lives in ./responses.ts.
- */
-/** Where a reply lands: its own thread, or wherever the message came from. */
 declare const CHANNEL_REPLY_TARGETS: readonly ["thread", "source"];
 type ChannelReplyIn = (typeof CHANNEL_REPLY_TARGETS)[number];
 
-/**
- * The core HTTP contract every handler speaks, plus generic request/response
- * helpers. Handlers take a CoreRequest + RequestContext and return a Web
- * Response; the transport edge (`src/server.ts`) builds the CoreRequest from
- * a real request. Keep route-specific logic out of here.
- */
 declare global {
     interface BunFetchRequestInit {
         timeout?: number | boolean;
     }
 }
 
-/**
- * Wire types for the public account-manage and harness APIs. These mirror
- * the deployed API contract (docs/api-reference/openapi.yaml is the source
- * of truth); they are intentionally independent of the runtime internals so
- * the SDK keeps working when the runtime is ported.
- */
-
 interface Cron {
     accountId: string;
     cronId: string;
@@ -1038,32 +647,19 @@ interface Skill {
     }>;
 }
 
-/**
- * Connections: external accounts an agent acts through, one of each type per
- * Broods account. `broods connect <type>` opens the provider's sign-in; the
- * deployment trades the code, checks the ID token and keeps the tokens, and
- * core refreshes them from then on. `chatgpt` backs the `chatgpt` model
- * provider. Plain data, so the CLI, the config plane, core and the dashboard
- * read one copy.
- */
 declare const CONNECTION_TYPE_NAMES: readonly ["chatgpt"];
 type ConnectionType = (typeof CONNECTION_TYPE_NAMES)[number];
-/** Starts a sign-in: `POST /v1/account/connections/{type}/start`. */
 interface ConnectionStart {
-    /** The loopback address the provider redirects back to. */
     redirectUri: string;
     codeChallenge: string;
     state: string;
     nonce: string;
 }
-/** The provider's consent screen, plus the client and host id the PUT echoes back. */
 interface ConnectionStartResult {
     authorizeUrl: string;
-    /** The client the consent runs on; a redirect that signs in again may omit it. */
     clientId: string;
     hostId: string;
 }
-/** Finishes a sign-in: `PUT /v1/account/connections/{type}` with the redirect's code. */
 interface ConnectionCode {
     code: string;
     codeVerifier: string;
@@ -1073,71 +669,37 @@ interface ConnectionCode {
     clientId: string;
     hostId: string;
 }
-/** A connection as the API answers it: never its tokens. */
 interface Connection {
     type: ConnectionType;
     clientId: string;
-    /** The deployment's `ext_agent_host_id`, kept across sign-ins. */
     hostId: string;
     email?: string;
     scopes: string[];
-    /** ISO 8601 access-token expiry; Broods refreshes it before then. */
     expiresAt: string;
     updatedAt: string;
-    /** Answered by a sign-in only: the models the plan may call. */
     models?: string[];
 }
 
-/**
- * Account config-plane client for the broods public account REST API.
- *
- * This is the DYNAMIC counterpart to the config-first `broods dev` / `broods
- * deploy` flow: `broods dev` syncs the predefined resources declared in your
- * `broods/` folder, while `BroodsAccountClient` creates and mutates the full
- * account config plane at runtime: agents, sandboxes (config + lifecycle),
- * workspaces (config + files), tools, policies, skills, crons, and the account
- * itself. One caller is a multi-tenant app provisioning one agent per customer
- * from its own backend.
- *
- * Kept intentionally standalone (import from `broods/account`): pure fetch,
- * no Node built-ins, no `.env` file loading, so it runs in edge/worker
- * runtimes such as Convex actions, Cloudflare Workers, and the browser-less
- * server runtimes, as well as Node and Bun.
- *
- * Auth: every call sends `Authorization: Bearer {accountSecret}` to
- * `{baseUrl}/v1/...`, or a short-lived `bsts_` role session token from
- * `assumeRole()`, limited to what the role's policy allows. Secrets inside
- * agent configs are encrypted at rest by the platform and come back redacted
- * (`********`) on reads.
- */
-
-/** A config PATCH body: objects merge key by key, `null` deletes a key, arrays and scalars replace. */
+/** Objects merge key by key, `null` deletes a key, arrays and scalars replace. */
 type ConfigPatch<T> = T extends readonly unknown[] ? T : T extends object ? {
     [K in keyof T]?: ConfigPatch<T[K]> | null;
 } : T;
 interface BroodsAccountClientOptions {
-    /** Base URL of the broods gateway. Falls back to `BROODS_BASE_URL`, then `https://gateway.broods.app`. */
     baseUrl?: string;
-    /** Account key used as the Bearer token. Falls back to `BROODS_ACCOUNT_SECRET`. */
     accountSecret?: string;
-    /**
-     * Short-lived `bsts_` role session token (from {@link BroodsAccountClient.assumeRole})
-     * used as the Bearer instead of the account key. The session can only do
-     * what its role's policy allows. Falls back to `BROODS_SESSION_TOKEN`.
-     */
+    /** From {@link BroodsAccountClient.assumeRole}; wins over `accountSecret`. */
     sessionToken?: string;
     fetch?: typeof fetch;
 }
-/** Public account record returned by `GET /v1/account`. */
 interface BroodsAccount {
     accountId: string;
     username: string;
     status: string;
-    /** Days an audit row is kept; absent means the 90 day default. */
+    /** Absent means the 90 day default. */
     auditRetentionDays?: number;
     [key: string]: unknown;
 }
-/** Public agent record; `config` comes back with secret values redacted. */
+/** `config` secrets come back redacted as `********`. */
 interface AccountAgent {
     accountId: string;
     agentId: string;
@@ -1154,20 +716,16 @@ interface CreateAgentResult {
     name: string;
     description?: string;
 }
-/** Write-only account environment variable metadata. */
 interface AccountEnvVar {
     name: string;
-    /** ISO 8601, like every other timestamp in the API. */
     updatedAt: string;
 }
 
-/** Fields accepted by `PATCH /v1/agents/{id}`. `config` is deep-merged; `null` values delete keys. */
 interface UpdateAgentInput {
     name?: string;
     description?: string | null;
     config?: ConfigPatch<AgentConfig>;
 }
-/** Public workspace record returned by the workspaces routes. */
 interface AccountWorkspace {
     accountId: string;
     workspaceId: string;
@@ -1177,7 +735,6 @@ interface AccountWorkspace {
     createdAt: string;
     updatedAt: string;
 }
-/** One entry of a workspace file listing (`GET /v1/workspaces/{id}/files`). */
 interface WorkspaceFileEntry {
     path: string;
     name: string;
@@ -1185,7 +742,7 @@ interface WorkspaceFileEntry {
     sizeBytes?: number;
     updatedAt?: string;
 }
-/** Public sandbox config record; `config` comes back with secret values (e.g. `envVars`) redacted. */
+/** `config` secrets such as `envVars` come back redacted. */
 interface AccountSandbox {
     accountId: string;
     sandboxId: string;
@@ -1196,7 +753,6 @@ interface AccountSandbox {
     updatedAt: string;
     [key: string]: unknown;
 }
-/** Public agent-policy record returned by the policies routes. */
 interface AccountPolicy {
     accountId: string;
     policyId: string;
@@ -1207,11 +763,7 @@ interface AccountPolicy {
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Public account-role record returned by the roles routes. The policy uses the
- * API action namespace (`"agents:read"`, `"crons:write"`, ...); `projectId` and
- * `stageId` bound which runtime keys may assume the role.
- */
+/** `policy` uses API actions (`agents:read`); `projectId` + `stageId` bound who may assume it. */
 interface AccountRole {
     accountId: string;
     roleId: string;
@@ -1223,7 +775,6 @@ interface AccountRole {
     createdAt: string;
     updatedAt: string;
 }
-/** One link of an agent actor's delegation chain: who asked, or an agent that delegated. */
 type AuditPrincipalLink = {
     kind: "user";
     id: string;
@@ -1237,10 +788,8 @@ type AuditPrincipalLink = {
     agentId: string;
 };
 /**
- * One row of the account's hash-chained audit ledger, as `GET /v1/audit`
- * serves it. `hash` is sha256 over the canonical JSON of every field but
- * `hash` itself (an absent optional field is left out, not null), with
- * `prevHash` linking it to the row before.
+ * `hash` is sha256 of the canonical JSON of every other field (an absent optional is left
+ * out, not null); `prevHash` is the previous row's `hash`.
  */
 interface AuditEvent {
     accountId: string;
@@ -1270,44 +819,31 @@ interface AuditEvent {
     stageId?: string;
     traceId?: string;
 }
-/** A page of ledger rows plus the chain head to compare the last row against. */
 interface AuditPage {
     events: AuditEvent[];
-    /** Pass as `since` to read the rows after this page. */
     nextSince: number;
     head: {
         seq: number;
         hash: string;
     } | null;
 }
-/** Result of `GET /v1/audit/verify`: the chain recomputed over the checked range. */
 interface AuditVerification {
     ok: boolean;
     brokenAtSeq?: number;
     checkedFrom?: number;
     checkedTo?: number;
 }
-/** The account's audit export target. The signing secret never comes back. */
 interface AuditSink {
     kind: "webhook";
     url: string;
-    /** Highest seq the receiver acknowledged. */
     exportedSeq: number;
     lastError?: string;
     updatedAt: string;
 }
-/** Short-lived role session minted by `POST /v1/account/assume-role`. */
 interface AssumeRoleResult {
-    /** `bsts_` bearer token; pass it as `sessionToken` to a new client. */
     token: string;
-    /** ISO timestamp when the session stops working. */
     expiresAt: string;
 }
-/**
- * One real place a team talks, bound to an agent: a Slack channel, a Discord
- * channel, a repo. The runtime reads it on the inbound webhook to decide who
- * answers there and with what instructions, workspaces and policies.
- */
 interface AccountChannel {
     accountId: string;
     channelId: string;
@@ -1333,39 +869,26 @@ interface ChannelRecordConfig {
         name: string;
         workspaceId: string;
     }>;
-    /** Added to whatever the agent already carries. Each policy holds its own mode. */
     policies?: string[];
-    /**
-     * Tool names withheld in this channel, applied after the tool set is built,
-     * so it also covers sandbox tools (`bash`, `read`, …) that `config.tools`
-     * cannot name. Narrowing only; unknown names are ignored.
-     */
+    /** Also covers sandbox tools (`bash`, `read`, …); unknown names are ignored. */
     denyTools?: string[];
-    /**
-     * Where the reply lands. `source` answers wherever the message came from, and
-     * threads only when the message already did. Slack only. No other provider
-     * gives the runtime a second place to reply.
-     */
+    /** Slack only. `source` replies where the message came from, threading only if it was. */
     replyIn?: ChannelReplyIn;
     partition?: ChannelPartition;
-    /** Images the agent may stand a sandbox up from for a thread here. */
     sandboxImages?: string[];
-    /** Named groups of people, readable from policy conditions as `userRoles`. */
+    /** Readable from policy conditions as `userRoles`. */
     tagRoles?: Array<{
         roleId: string;
         userIds: string[];
     }>;
 }
-/** The stage a resource belongs to. Same name in two stages = two resources. */
 interface StageScope {
     project: string;
     stage: string;
 }
 /**
- * OAuth 2.0 refresh-token grant on an external MCP row. The runtime mints and
- * refreshes access tokens and sends `Authorization: Bearer <token>` itself.
- * `clientSecret` and `refreshToken` must be `${NAME}` account env refs;
- * `tokenUrl` defaults to https://oauth2.googleapis.com/token.
+ * Refresh-token grant; the runtime mints the Bearer itself. `clientSecret` and `refreshToken`
+ * must be `${NAME}` env refs; `tokenUrl` defaults to https://oauth2.googleapis.com/token.
  */
 interface McpOauthInput {
     clientId: string;
@@ -1373,9 +896,8 @@ interface McpOauthInput {
     refreshToken: string;
     tokenUrl?: string;
 }
-/** Where a hosted MCP server may run. */
+/** `auto` (the default) runs a hosted bundle on Cloudflare Workers when it can, else Lambda. */
 type McpRuntime = "auto" | "lambda";
-/** Public MCP server registration returned by the `/v1/mcp` routes (#331). */
 interface AccountMcp {
     accountId: string;
     serverId: string;
@@ -1383,16 +905,12 @@ interface AccountMcp {
     stageId: string;
     name: string;
     description?: string;
+    /** `http` sets `url`, `hosted` sets `sha256`/`runtime`, `machine` sets `sandbox`/`command`. */
     transport: "http" | "hosted" | "machine";
-    /** External servers only; a hosted row has no endpoint of its own. */
     url?: string;
-    /** Machine servers only: the sandbox (by name) that serves it. */
     sandbox?: string;
-    /** Machine servers only: argv of the stdio server a lambda sandbox runs. */
     command?: string[];
-    /** Hosted servers only: content hash of the uploaded bundle. */
     sha256?: string;
-    /** Hosted servers only: "auto" or "lambda". */
     runtime?: McpRuntime;
     headers?: Record<string, string>;
     oauth?: McpOauthInput;
@@ -1403,11 +921,7 @@ interface AccountMcp {
     updatedAt: string;
     deletedAt?: string;
 }
-/**
- * Fields accepted by `POST /v1/mcp`: `url` connects, `bundle` uploads inline
- * (≤10 MB); a larger bundle goes through `uploadMcpBundle` first; `sandbox`
- * runs it on that sandbox: a machine's daemon, or `command` on a lambda VM.
- */
+/** `bundle` inline is ≤10 MB, a larger one goes through `uploadMcpBundle` first. */
 interface CreateMcpInput {
     name: string;
     description?: string;
@@ -1420,14 +934,8 @@ interface CreateMcpInput {
     headers?: Record<string, string>;
     oauth?: McpOauthInput;
     allowedTools?: string[];
-    /**
-     * Hosted servers only. "auto" (the default) runs it on Cloudflare Workers
-     * when its bundle can run there, on Lambda otherwise; "lambda" always runs
-     * it on Lambda.
-     */
     runtime?: McpRuntime;
 }
-/** Fields accepted by `PATCH /v1/mcp/{serverId}`; every field is optional. */
 interface UpdateMcpInput {
     name?: string;
     description?: string;
@@ -1440,19 +948,10 @@ interface UpdateMcpInput {
     headers?: Record<string, string>;
     oauth?: McpOauthInput;
     allowedTools?: string[];
-    /**
-     * Hosted servers only. "auto" (the default) runs it on Cloudflare Workers
-     * when its bundle can run there, on Lambda otherwise; "lambda" always runs
-     * it on Lambda.
-     */
     runtime?: McpRuntime;
     disabled?: boolean;
 }
-/**
- * Body of a skill upload (`POST /v1/skills`, `PUT /v1/skills/{skillName}`).
- * `json` needs `name`/`description`/`content`; `files` needs base64 `files`
- * including a root `SKILL.md`; `github` needs a tree `url`.
- */
+/** `json` needs name, description, content; `files` a root `SKILL.md`; `github` a tree `url`. */
 interface SkillUploadInput {
     source: "json" | "files" | "github";
     name?: string;
@@ -1465,101 +964,72 @@ interface SkillUploadInput {
     }>;
     url?: string;
 }
-/** Result of `POST /v1/account/rotate-secret`. The returned `secret` is the new account key, shown once; the old key stops working immediately. */
 interface RotateSecretResult {
     account: BroodsAccount;
     secret: string;
 }
 /**
- * Result of `GET /v1/account/storage-trust`: what a workspace's own AWS role
- * must trust. Broods assigns `externalId` per account and sends it on every
- * AssumeRole of an `assumeRole` workspace's role; it is never set in config.
+ * `externalId` is per account and sent on every AssumeRole; it is never set in config.
+ * `principalArn` and `trustPolicy` are absent on a deployment with no AWS.
  */
 interface StorageTrust {
     externalId: string;
-    /** The Broods AWS principal to trust; absent on a deployment with no AWS. */
     principalArn?: string;
-    /** A ready-to-paste trust policy JSON; absent on a deployment with no AWS. */
     trustPolicy?: string;
 }
-/** Result of `DELETE /v1/account`: the account and all account-scoped data are removed; `cleanup` reports per-resource deletion counts. */
 interface DeleteAccountResult {
     deleted: boolean;
     cleanup?: Record<string, number>;
 }
-/** Result of a suspend/resume/terminate sandbox lifecycle action. */
 interface SandboxLifecycleResult {
     status: string;
 }
-/** Result of `POST /v1/sandboxes/{id}/snapshot`. */
 interface SandboxSnapshotResult {
     status: string;
     snapshotId?: string;
     externalImageId?: string;
 }
-/** Sealed ticket from `POST /v1/sandboxes/{id}/terminal`; hand `token` to the gateway terminal WebSocket at `websocketPath`. */
 interface SandboxTerminalTicket {
     token: string;
     expiresAt: number;
     websocketPath: string;
 }
-/** Non-2xx response from the account API (404s on id routes return null instead). */
 declare class BroodsAccountApiError extends Error {
     readonly status: number;
     readonly body: string;
     constructor(method: string, path: string, status: number, body: string);
 }
-/** Build a validated account env-var reference for use in an agent config. */
 declare function envPlaceholder(name: string): string;
-/**
- * The credential the environment supplies, with a role session winning over
- * the account key. The constructor throws through this same resolution, so
- * callers that can run without an account credential (`broods mcp` with only a
- * stored login) probe here instead of catching the constructor.
- */
+/** The constructor's env fallback, for callers that must not throw without one. */
 declare function resolveEnvCredential(): string | undefined;
 /**
- * Typed client for the broods account config API. All `get`/`update`/`delete`
- * methods return `null`/`false` when the resource does not exist (HTTP 404) so
- * callers can implement upsert flows without try/catch; every other non-2xx
- * status throws {@link BroodsAccountApiError}.
+ * Lookups, updates and deletes return `null`/`false` on a 404, so upserts need no try/catch.
+ * Any other failure throws {@link BroodsAccountApiError}.
  */
 declare class BroodsAccountClient {
     private readonly baseUrl;
     private readonly bearerToken;
     private readonly fetchImpl;
     constructor(options?: BroodsAccountClientOptions);
-    /** The account this secret belongs to. Its `accountId` is the first segment of channel webhook URLs. */
     getAccount(): Promise<BroodsAccount>;
-    /** The external id and Broods principal this account's own storage roles must trust. */
     getStorageTrust(): Promise<StorageTrust>;
-    /** Update account metadata (username/description). Returns null when the account is gone. Runtime config is managed through the agent endpoints. */
     updateAccount(patch: {
         username?: string;
         description?: string | null;
-        /** 1 to 3650 days, or null to return to the 90 day default. */
+        /** 1 to 3650 days, or null for the 90 day default. */
         auditRetentionDays?: number | null;
     }): Promise<BroodsAccount | null>;
     /**
-     * Exchange a role for a short-lived `bsts_` session token. Callable with
-     * the account key, a CLI login token, or a runtime key (the latter
-     * only into roles scoped to the key's own project/stage). Construct a new
-     * client with `{ sessionToken: result.token }` to act as the role.
+     * A runtime key may assume only roles scoped to its own project and stage.
+     * Act as the role with `new BroodsAccountClient({ sessionToken: result.token })`.
      */
     assumeRole(roleId: string, options?: {
         ttlSeconds?: number;
     }): Promise<AssumeRoleResult>;
-    /** Rotate the account key. The returned `secret` is the new key, shown once, and the current key stops working immediately, so persist it before the process exits. */
+    /** The old key dies at once and `secret` is shown only once: persist it before exiting. */
     rotateSecret(): Promise<RotateSecretResult>;
-    /** Delete this account and cascade-clean every account-scoped resource. `cleanup` reports per-resource deletion counts. */
     deleteAccount(): Promise<DeleteAccountResult>;
-    /**
-     * Provider webhook URL for one of the account's channels. Paste this into the
-     * provider's webhook settings (Slack Event Subscriptions, Zalo OA webhook,
-     * Pancake page webhook). Routing is per account + channel: the credentials
-     * that verify the request pick the receiving agent, and a channel record
-     * binds each place to the agent that should answer there.
-     */
+    /** One URL per account and channel type; the credentials that verify a request pick the agent. */
     webhookUrl(accountId: string, channelType: string): string;
     listAgents(): Promise<AccountAgent[]>;
     createAgent(input: {
@@ -1568,31 +1038,22 @@ declare class BroodsAccountClient {
         config: AgentConfig;
     }): Promise<CreateAgentResult>;
     getAgent(agentId: string): Promise<AccountAgent | null>;
-    /** PATCH an agent. `config` deep-merges into the stored config; `null` leaves delete keys. Returns null when the agent is gone. */
     updateAgent(agentId: string, patch: UpdateAgentInput): Promise<AccountAgent | null>;
     deleteAgent(agentId: string): Promise<boolean>;
-    /** List account environment variable names and update timestamps; values are never returned. */
     listEnvVars(): Promise<AccountEnvVar[]>;
-    /** Create or replace one write-only account environment variable. */
     setEnvVar(name: string, value: string): Promise<void>;
-    /** Delete one account environment variable. Returns false when it is already absent. */
     deleteEnvVar(name: string): Promise<boolean>;
-    /** The account's connections (`broods connect`), never their tokens. */
     listConnections(): Promise<Connection[]>;
-    /** The account's connection of one type, or null when there is none. */
     getConnection(type: ConnectionType): Promise<Connection | null>;
-    /** Starts a sign-in: the provider's consent screen for `broods connect` to open. */
     startConnection(type: ConnectionType, start: ConnectionStart): Promise<ConnectionStartResult>;
-    /** Finishes a sign-in with the code the browser brought back; the deployment keeps the tokens. */
     connect(type: ConnectionType, code: ConnectionCode): Promise<Connection>;
-    /** Forget a connection and revoke it at the provider. False when there was none. */
     disconnect(type: ConnectionType): Promise<boolean>;
     listCrons(): Promise<Cron[]>;
     createCron(input: CreateCronInput): Promise<Cron>;
     getCron(cronId: string): Promise<Cron | null>;
     updateCron(cronId: string, patch: UpdateCronInput): Promise<Cron | null>;
     deleteCron(cronId: string): Promise<boolean>;
-    /** Run history for a cron, newest first. Returns [] when the cron is gone. */
+    /** Newest first. */
     listCronRuns(cronId: string, options?: {
         limit?: number;
     }): Promise<CronRun[]>;
@@ -1609,19 +1070,14 @@ declare class BroodsAccountClient {
         config?: ConfigPatch<WorkspaceConfig>;
     }): Promise<AccountWorkspace | null>;
     deleteWorkspace(workspaceId: string): Promise<boolean>;
-    /** Flat listing of every file in the workspace's S3-backed filesystem. Returns [] when the workspace is gone. */
     listWorkspaceFiles(workspaceId: string): Promise<WorkspaceFileEntry[]>;
-    /** Short-lived download URL for one workspace file. Returns null when the workspace or file is gone. */
     getWorkspaceFileUrl(workspaceId: string, path: string): Promise<string | null>;
-    /** Upload or replace one workspace file from base64 content. Throws when the workspace is gone (404). */
     uploadWorkspaceFile(workspaceId: string, input: {
         path: string;
         contentBase64: string;
         contentType?: string;
     }): Promise<WorkspaceFileEntry>;
-    /** Rename a workspace file or folder. Returns how many objects moved; throws when the workspace or source path is gone. */
     renameWorkspaceFile(workspaceId: string, path: string, newPath: string): Promise<number>;
-    /** Delete a workspace file or folder. Returns how many objects were deleted, 0 when the workspace or path is gone. */
     deleteWorkspaceFile(workspaceId: string, path: string): Promise<number>;
     listSandboxes(): Promise<AccountSandbox[]>;
     createSandbox(input: {
@@ -1630,30 +1086,24 @@ declare class BroodsAccountClient {
         config?: SandboxConfig;
     }): Promise<AccountSandbox>;
     getSandbox(sandboxId: string): Promise<AccountSandbox | null>;
-    /** PATCH a sandbox config. `config` deep-merges into the stored config; `null` leaves delete keys. Returns null when the sandbox is gone. */
     updateSandbox(sandboxId: string, patch: {
         name?: string;
         description?: string | null;
         config?: ConfigPatch<SandboxConfig>;
     }): Promise<AccountSandbox | null>;
     deleteSandbox(sandboxId: string): Promise<boolean>;
-    /** Suspend a persistent sandbox reservation. Throws on 404/403/409 (missing sandbox, foreign reservation, or unsupported provider). */
     suspendSandbox(sandboxId: string, reservationKey: string): Promise<SandboxLifecycleResult>;
-    /** Resume a persistent sandbox reservation. Throws on 404/403/409. */
     resumeSandbox(sandboxId: string, reservationKey: string): Promise<SandboxLifecycleResult>;
-    /** Terminate a persistent sandbox reservation and drop its live-instance row. Throws on 404/403/409. */
     terminateSandbox(sandboxId: string, reservationKey: string): Promise<SandboxLifecycleResult>;
-    /** Snapshot a persistent sandbox reservation into an image any sandbox of that provider on the same stage can pin with `snapshot` (`sandbox`, `daytona`, `e2b`, `vercel`, or `lambda`, which answers `building` until its image build lands). The snapshot is locked to the stage of the sandbox it was taken from: pinning it on another stage throws a 400. Throws on 404/403/409. */
+    /**
+     * Providers `sandbox`, `daytona`, `e2b`, `vercel` and `lambda` (`building` until its image
+     * lands). Only the source stage may pin the snapshot; any other stage gets a 400.
+     */
     snapshotSandbox(sandboxId: string, reservationKey: string, name: string): Promise<SandboxSnapshotResult>;
-    /** Mint a short-lived sealed ticket for an interactive PTY session on a persistent sandbox (`sandbox`/`lambda`/`cloudflare` providers). Throws on 404/403/409. */
+    /** Providers `sandbox`, `lambda` and `cloudflare` only. */
     openSandboxTerminal(sandboxId: string, reservationKey: string): Promise<SandboxTerminalTicket>;
-    /** MCP servers live in one stage, so the collection routes need a scope. */
     listMcp(scope: StageScope): Promise<AccountMcp[]>;
     createMcp(scope: StageScope, input: CreateMcpInput): Promise<AccountMcp>;
-    /**
-     * Upload a hosted MCP bundle too large for the JSON body; returns the
-     * `bundleStorageId` + `sha256` pair `createMcp`/`updateMcp` accept.
-     */
     uploadMcpBundle(bundle: string): Promise<{
         bundleStorageId: string;
         sha256: string;
@@ -1668,7 +1118,6 @@ declare class BroodsAccountClient {
         document: PolicyDocument;
     }): Promise<AccountPolicy>;
     getPolicy(policyId: string): Promise<AccountPolicy | null>;
-    /** PATCH a policy. `description: null` clears it. Returns null when the policy is gone. */
     updatePolicy(policyId: string, patch: {
         name?: string;
         description?: string | null;
@@ -1676,9 +1125,8 @@ declare class BroodsAccountClient {
         status?: string;
     }): Promise<AccountPolicy | null>;
     deletePolicy(policyId: string): Promise<boolean>;
-    /** Roles are account-secret only: a session cannot list, mint, or edit roles. */
+    /** Roles need the account key: a session cannot list, mint, or edit them. */
     listRoles(): Promise<AccountRole[]>;
-    /** Create a role whose policy uses the API action namespace. `projectId`/`stageId` must be provided together. */
     createRole(input: {
         name: string;
         policy: PolicyDocument;
@@ -1686,41 +1134,36 @@ declare class BroodsAccountClient {
         stageId?: string;
     }): Promise<AccountRole>;
     getRole(roleId: string): Promise<AccountRole | null>;
-    /** PATCH a role. `status: "disabled"` kills every live session of the role. Returns null when the role is gone. */
+    /** `status: "disabled"` kills every live session of the role. */
     updateRole(roleId: string, patch: {
         name?: string;
         policy?: PolicyDocument;
         status?: "active" | "disabled";
     }): Promise<AccountRole | null>;
     deleteRole(roleId: string): Promise<boolean>;
-    /** The audit ledger: rows since a seq, chain verification, and the webhook sink. */
     readonly audit: {
-        /** Rows with `seq > since`, oldest first, at most `limit` (default 100, max 500). */
+        /** Rows with `seq > since`, oldest first; `limit` defaults to 100, max 500. */
         list: (options?: {
             since?: number;
             limit?: number;
         }) => Promise<AuditPage>;
         /**
-         * Recompute the chain over `[fromSeq, toSeq]`, from the oldest kept row by
-         * default, at most 1000 rows per call. `ok` covers only `checkedFrom` to
-         * `checkedTo`; on a longer ledger call again with `fromSeq: checkedTo + 1`.
+         * At most 1000 rows per call: `ok` covers only `checkedFrom` to `checkedTo`, so on a longer
+         * ledger call again with `fromSeq: checkedTo + 1`.
          */
         verify: (options?: {
             fromSeq?: number;
             toSeq?: number;
         }) => Promise<AuditVerification>;
-        /** The account's sink, or null when none is set. */
         getSink: () => Promise<AuditSink | null>;
-        /** Set the one webhook sink. `url` must be public https; `secret` signs each batch. */
+        /** `url` must be public https; `secret` signs each batch. */
         setSink: (input: {
             url: string;
             secret: string;
         }) => Promise<AuditSink>;
-        /** Remove the sink; exports stop and rows age out on retention alone. Returns whether one existed. */
         deleteSink: () => Promise<boolean>;
     };
     listChannels(): Promise<AccountChannel[]>;
-    /** Bind one real chat channel to an agent. One active record per place. */
     createChannel(input: {
         platform: string;
         externalId: string;
@@ -1730,7 +1173,6 @@ declare class BroodsAccountClient {
         config: ChannelRecordConfig;
     }): Promise<AccountChannel>;
     getChannel(channelId: string): Promise<AccountChannel | null>;
-    /** PATCH a channel. `description: null` clears it. Returns null when it is gone. */
     updateChannel(channelId: string, patch: {
         name?: string;
         description?: string | null;
@@ -1739,15 +1181,11 @@ declare class BroodsAccountClient {
         status?: "active" | "deleted";
     }): Promise<AccountChannel | null>;
     deleteChannel(channelId: string): Promise<boolean>;
-    /** All skills for the account, each with its `<accountId>/<name>` path. */
     listSkills(): Promise<Skill[]>;
-    /** Upload a new skill from JSON content, a base64 file bundle, or a GitHub tree URL. Every bundle must include a root `SKILL.md`. */
     createSkill(input: SkillUploadInput): Promise<Skill>;
     getSkill(skillName: string): Promise<Skill | null>;
-    /** Replace a skill's bundle in place (`PUT`). Throws when the skill is gone (404). */
     uploadSkill(skillName: string, input: SkillUploadInput): Promise<Skill>;
     deleteSkill(skillName: string): Promise<boolean>;
-    /** POST a sandbox lifecycle action, throwing on any non-2xx (including 404, since these are not upsert flows). */
     private sandboxAction;
     private request;
 }