broods 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,8 +1,19 @@
 import { SystemModelMessage, LanguageModelCallOptions, RequestOptions, streamText, JSONSchema7, ModelMessage, TextStreamPart, ToolSet } from 'ai';
-import { DiscordAdapterConfig } from '@chat-adapter/discord';
-import { GitHubAdapterConfig } from '@chat-adapter/github';
-import { SlackAdapterConfig } from '@chat-adapter/slack';
-import { TelegramAdapterConfig } from '@chat-adapter/telegram';
+
+/**
+ * Supported account model provider names.
+ * Keep provider identifiers here so config validation and model resolution share one source.
+ */
+declare const ACCOUNT_MODEL_PROVIDERS: {
+    readonly google: true;
+    readonly openai: true;
+    readonly anthropic: true;
+    readonly bedrock: true;
+    readonly gateway: true;
+    readonly minimax: true;
+    readonly custom: true;
+};
+type AccountModelProviderName = keyof typeof ACCOUNT_MODEL_PROVIDERS;
 
 /**
  * Agent policy contracts and validation.
@@ -43,21 +54,6 @@ interface AgentPolicyConfig {
     mode?: AgentPolicyMode;
 }
 
-/**
- * Supported account model provider names.
- * Keep provider identifiers here so config validation and model resolution share one source.
- */
-declare const ACCOUNT_MODEL_PROVIDERS: {
-    readonly google: true;
-    readonly openai: true;
-    readonly anthropic: true;
-    readonly bedrock: true;
-    readonly gateway: true;
-    readonly minimax: true;
-    readonly custom: true;
-};
-type AccountModelProviderName = keyof typeof ACCOUNT_MODEL_PROVIDERS;
-
 /**
  * Agent configuration: types for the per-agent settings object, input
  * normalization, encryption helpers, patch-merge, and redaction.
@@ -232,9 +228,9 @@ type AgentChannelWorkspaceScope = {
 };
 interface AgentTelegramChannelConfig {
     id?: string;
-    apiUrl?: TelegramAdapterConfig["apiUrl"];
-    botToken?: TelegramAdapterConfig["botToken"];
-    webhookSecret?: TelegramAdapterConfig["secretToken"];
+    apiUrl?: string;
+    botToken?: string;
+    webhookSecret?: string;
     allowedChatIds?: number[];
     reactionEmoji?: string;
     workspaceScope?: AgentChannelWorkspaceScope;
@@ -242,18 +238,10 @@ interface AgentTelegramChannelConfig {
 }
 interface AgentGitHubChannelConfig {
     id?: string;
-    apiUrl?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["apiUrl"];
-    webhookSecret?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["webhookSecret"];
-    appId?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["appId"];
-    privateKey?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["privateKey"];
+    apiUrl?: string;
+    webhookSecret?: string;
+    appId?: string;
+    privateKey?: string;
     allowedRepos?: string[];
     /** Bot username for @-mention detection (e.g. "my-bot" or "my-bot[bot]"). */
     userName?: string;
@@ -268,9 +256,9 @@ interface AgentGitHubChannelConfig {
 }
 interface AgentSlackChannelConfig {
     id?: string;
-    apiUrl?: SlackAdapterConfig["apiUrl"];
+    apiUrl?: string;
     botToken?: string;
-    signingSecret?: SlackAdapterConfig["signingSecret"];
+    signingSecret?: string;
     allowedChannelIds?: string[];
     reactionEmoji?: string;
     workspaceScope?: AgentChannelWorkspaceScope;
@@ -278,9 +266,9 @@ interface AgentSlackChannelConfig {
 }
 interface AgentDiscordChannelConfig {
     id?: string;
-    apiUrl?: DiscordAdapterConfig["apiUrl"];
-    botToken?: DiscordAdapterConfig["botToken"];
-    publicKey?: DiscordAdapterConfig["publicKey"];
+    apiUrl?: string;
+    botToken?: string;
+    publicKey?: string;
     allowedGuildIds?: string[];
     workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
@@ -304,10 +292,7 @@ interface AgentZaloChannelConfig {
 }
 
 /**
- * Cron-job types, input normalization, and patch-merge helpers.
- * Provider-agnostic — both the DynamoDB and Convex stores import the
- * normalizer at their create/update entry points so behaviour is
- * symmetric across modes.
+ * Cron-job records, input normalization, and patch-merge helpers.
  */
 
 type CronStatus = "active" | "paused";
@@ -366,9 +351,8 @@ type SandboxSize = "tiny" | "xsmall" | "small" | "medium" | "large";
 /**
  * Sandbox config: account-scoped, reusable sandbox definitions referenced by
  * agents via `config.sandbox`. A sandbox is a collection of Claude-Code-style
- * tools (bash/read/write/edit/glob/grep) backed by a provider. Validation +
- * the public projection live here; the
- * DynamoDB / Convex stores call these at their create/update entry points.
+ * tools (bash/read/write/edit/glob/grep) backed by a provider. Validation and
+ * the public projection live here.
  * Stored encrypted at rest because `envVars`/`options` may hold secrets.
  */
 
@@ -408,8 +392,8 @@ interface SandboxConfig {
  * agents via `config.workspaces[].workspaceId`. A workspace is the persistent
  * S3-backed filesystem mounted into a sandbox; agents referencing the same
  * workspaceId share the same files. Holds no secrets, so it is stored in
- * plaintext (unlike sandbox config). Validation + the public projection live
- * here; the DynamoDB / Convex stores call these at create/update.
+ * plaintext (unlike sandbox config). Validation and the public projection live
+ * here.
  */
 declare const WORKSPACE_STORAGE_PROVIDERS: readonly ["s3"];
 type WorkspaceStorageProvider = (typeof WORKSPACE_STORAGE_PROVIDERS)[number];
@@ -428,12 +412,18 @@ interface WorkspaceStorageConfig {
     prefix?: string;
     auth?: WorkspaceStorageAuth;
 }
+interface WorkspaceHarnessConfig {
+    workspace?: {
+        enabled?: boolean;
+    };
+    memory?: {
+        enabled?: boolean;
+    };
+}
 interface WorkspaceConfig {
     storage: WorkspaceStorageConfig;
     isolation?: boolean;
-    harness?: {
-        enabled?: boolean;
-    };
+    harness?: WorkspaceHarnessConfig;
 }
 
 /**
@@ -565,7 +555,7 @@ type CliManifest = {
 };
 
 /**
- * Type contracts inherited from Convex and core storage/runtime modules.
+ * Type contracts inherited from Convex and core domain/runtime modules.
  * Keep this file type-only so the public SDK does not bundle backend code.
  */
 
@@ -619,9 +609,15 @@ interface ToolApprovalSummary {
     input: unknown;
 }
 interface AsyncStatus {
-    status: "processing" | "awaiting_approval" | "completed" | "failed" | "not_found";
+    status: "accepted" | "queued" | "applied" | "processing" | "awaiting_approval" | "completed" | "failed" | "expired" | "not_found";
+    requestedMode?: "reject" | "followup" | "collect" | "steer";
+    appliedMode?: "reject" | "followup" | "collect" | "steer";
+    appliedToEventId?: string;
+    result?: unknown;
     response?: unknown;
     error?: string;
+    /** True when `failed` was a deliberate /stop, not a fault. */
+    stoppedByUser?: boolean;
     approvals?: ToolApprovalSummary[];
 }
 interface AsyncRequestAccepted {
@@ -629,6 +625,8 @@ interface AsyncRequestAccepted {
     statusId: string;
     eventId: string;
     agentId: string;
+    status?: "accepted" | "queued" | "applied" | "processing";
+    requestedMode?: "reject" | "followup" | "collect" | "steer";
 }
 interface Cron {
     accountId: string;
@@ -714,6 +712,8 @@ declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator
  * Shared WebSocket wire message contracts used by the SDK client and gateway.
  */
 
+type IngressMode = "reject" | "followup" | "collect" | "steer";
+type IngressStatus = "accepted" | "queued" | "applied" | "processing" | "awaiting_approval" | "completed" | "failed" | "expired";
 type WebSocketStreamMessage = AgentStreamPart | {
     type: string;
     [key: string]: unknown;
@@ -722,17 +722,78 @@ type WebSocketServerMessage = {
     type: "meta";
     sessionId: string;
     taskId: string;
-} | WebSocketStreamMessage;
+} | {
+    type: "ack";
+    requestId: string;
+    eventId: string;
+    status: IngressStatus;
+    statusUrl?: string;
+} | {
+    type: "status";
+    requestId: string;
+    eventId: string;
+    status: IngressStatus | "not_found";
+    requestedMode?: IngressMode;
+    appliedMode?: IngressMode;
+    appliedToEventId?: string;
+    statusUrl?: string;
+    error?: string;
+} | {
+    type: "attached";
+    requestId: string;
+    eventId: string;
+    status: IngressStatus;
+    replayFromCursor?: string;
+    replayThroughCursor?: string;
+    statusUrl?: string;
+} | {
+    type: "replay_unavailable";
+    requestId: string;
+    eventId: string;
+    status: IngressStatus | "not_found";
+    statusUrl?: string;
+} | WebSocketOutputMessage | WebSocketStreamMessage;
+/**
+ * Durable-stream envelope around one stream part. The SDK unwraps `data` for
+ * handlers and surfaces the envelope itself through `onOutput` so clients can
+ * persist `cursor` for attach-based resume.
+ */
+type WebSocketOutputMessage = {
+    type: "output";
+    eventId: string;
+    cursor: string;
+    replay: boolean;
+    data: WebSocketStreamMessage;
+};
 type WebSocketClientExecuteMessage = {
     type: "execute";
     agentId: string;
     sessionId?: string;
     eventId?: string;
+    /** Defaults to "steer": join the live run at its next step boundary. */
+    mode?: IngressMode;
+    idempotencyKey?: string;
 } & AgentRunEventInput & AgentRunOverrides;
+type WebSocketClientControlMessage = {
+    type: "control";
+    requestId: string;
+    eventId: string;
+    idempotencyKey?: string;
+    /** Defaults to "steer": join the live run at its next step boundary. */
+    mode?: IngressMode;
+} & AgentRunEventInput;
+type WebSocketClientAttachMessage = {
+    type: "attach";
+    requestId: string;
+    agentId: string;
+    conversationKey: string;
+    eventId: string;
+    afterCursor?: string;
+};
 type WebSocketClientCancelMessage = {
     type: "cancel";
 };
-type WebSocketClientMessage = WebSocketClientExecuteMessage | WebSocketClientCancelMessage;
+type WebSocketClientMessage = WebSocketClientExecuteMessage | WebSocketClientControlMessage | WebSocketClientAttachMessage | WebSocketClientCancelMessage;
 
 /**
  * Shared WebSocket wire-protocol types for the observability gateway, used by
@@ -821,12 +882,20 @@ declare const DEFAULT_CORE_BASE_URL = "https://gateway.broods.app";
 type AgentRunInputBase = {
     conversationKey?: string;
     eventId?: string;
+    /** Busy-conversation behavior. Defaults to `steer`: join the live run at its next step boundary (falls back to a FIFO follow-up). */
+    mode?: "reject" | "followup" | "collect" | "steer";
+    /** Stable retry identity within the conversation; defaults to eventId. */
+    idempotencyKey?: string;
 } & AgentRunOverrides;
 type AgentRunInput = AgentRunInputBase & AgentRunEventInput;
 interface AgentRunResult {
     text: string;
     events: TextStreamPart<ToolSet>[];
 }
+declare class IngressAcceptedError extends Error {
+    readonly accepted: AsyncRequestAccepted;
+    constructor(accepted: AsyncRequestAccepted);
+}
 interface AsyncPollOptions {
     intervalMs?: number;
     timeoutMs?: number;
@@ -950,6 +1019,332 @@ declare class BroodsClient {
 }
 declare function normalizeHttpServiceUrl(value: string): 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 — e.g. 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/...`. Secrets inside agent configs are encrypted at rest by
+ * the platform and come back redacted (`********`) on reads.
+ */
+
+interface BroodsAccountClientOptions {
+    /** Base URL of the broods gateway. Falls back to `BROODS_BASE_URL`, then `https://gateway.broods.app`. */
+    baseUrl?: string;
+    /** Account secret used as the Bearer token. Falls back to `BROODS_ACCOUNT_SECRET`. */
+    accountSecret?: string;
+    fetch?: typeof fetch;
+}
+/** Public account record returned by `GET /v1/account`. */
+interface BroodsAccount {
+    accountId: string;
+    username: string;
+    status: string;
+    [key: string]: unknown;
+}
+/** Public agent record; `config` comes back with secret values redacted. */
+interface AccountAgent {
+    accountId: string;
+    agentId: string;
+    name: string;
+    description?: string;
+    status: string;
+    config: AgentConfig;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateAgentResult {
+    accountId: string;
+    agentId: string;
+    name: string;
+    description?: string;
+}
+/** Write-only account environment variable metadata. */
+interface AccountEnvVar {
+    name: string;
+    updatedAt: number;
+}
+/** Build a validated account env-var reference for use in an agent config. */
+declare function envPlaceholder(name: string): string;
+/** Fields accepted by `PATCH /v1/agents/{id}`. `config` is deep-merged; `null` values delete keys. */
+interface UpdateAgentInput {
+    name?: string;
+    description?: string | null;
+    config?: unknown;
+}
+/** Public workspace record returned by the workspaces routes. */
+interface AccountWorkspace {
+    accountId: string;
+    workspaceId: string;
+    name: string;
+    description?: string;
+    config: WorkspaceConfig;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One entry of a workspace file listing (`GET /v1/workspaces/{id}/files`). */
+interface WorkspaceFileEntry {
+    path: string;
+    name: string;
+    isFolder: boolean;
+    sizeBytes?: number;
+    updatedAt?: string;
+}
+/** Public sandbox config record; `config` comes back with secret values (e.g. `envVars`) redacted. */
+interface AccountSandbox {
+    accountId: string;
+    sandboxId: string;
+    name: string;
+    description?: string;
+    config: SandboxConfig;
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+/** Public agent-policy record returned by the policies routes. */
+interface AccountPolicy {
+    accountId: string;
+    policyId: string;
+    name: string;
+    description?: string;
+    document: AgentPolicyDocument;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Public uploaded-tool record returned by the tools routes. */
+interface AccountTool {
+    accountId: string;
+    toolId: string;
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    sha256: string;
+    runtime: "isolate" | "sandbox";
+    defaultConfig?: unknown;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string;
+}
+/** Fields accepted by `POST /v1/tools`. `bundle` is already-bundled JavaScript module source. */
+interface CreateToolInput {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    bundle: string;
+    runtime?: "isolate" | "sandbox";
+    defaultConfig?: unknown;
+}
+/** Fields accepted by `PATCH /v1/tools/{toolId}`; every field is optional. Omitting `bundle` keeps the stored one. */
+interface UpdateToolInput {
+    name?: string;
+    description?: string;
+    inputSchema?: unknown;
+    bundle?: string;
+    runtime?: "isolate" | "sandbox";
+    defaultConfig?: unknown;
+}
+/**
+ * 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`.
+ */
+interface SkillUploadInput {
+    source: "json" | "files" | "github";
+    name?: string;
+    description?: string;
+    content?: string;
+    files?: Array<{
+        path: string;
+        contentBase64: string;
+        contentType?: string;
+    }>;
+    url?: string;
+}
+/** Result of `POST /v1/account/rotate-secret`. The returned `secret` is shown once; the old secret stops working immediately. */
+interface RotateSecretResult {
+    account: BroodsAccount;
+    secret: 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);
+}
+/**
+ * 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}.
+ */
+declare class BroodsAccountClient {
+    private readonly baseUrl;
+    private readonly accountSecret;
+    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>;
+    /** 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;
+    }): Promise<BroodsAccount | null>;
+    /** Rotate the account secret. The returned `secret` is shown once and the current secret stops working immediately, so persist it before the process exits. */
+    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 an agent's channels. Paste this into the
+     * provider's webhook settings (Slack Event Subscriptions, Zalo OA webhook,
+     * Pancake page webhook). Routing is per account + agent, so each agent's
+     * channels are isolated from every other agent's.
+     */
+    webhookUrl(accountId: string, agentId: string, channelType: string): string;
+    listAgents(): Promise<AccountAgent[]>;
+    createAgent(input: {
+        name: string;
+        description?: string;
+        config: unknown;
+    }): 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>;
+    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. */
+    listCronRuns(cronId: string, options?: {
+        limit?: number;
+    }): Promise<CronRun[]>;
+    listWorkspaces(): Promise<AccountWorkspace[]>;
+    createWorkspace(input: {
+        name: string;
+        description?: string;
+        config?: unknown;
+    }): Promise<AccountWorkspace>;
+    getWorkspace(workspaceId: string): Promise<AccountWorkspace | null>;
+    updateWorkspace(workspaceId: string, patch: {
+        name?: string;
+        description?: string | null;
+        config?: unknown;
+    }): 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 false when the workspace or source path is gone. */
+    renameWorkspaceFile(workspaceId: string, path: string, newPath: string): Promise<boolean>;
+    /** Delete a workspace file or folder. Returns false when the workspace or path is gone. */
+    deleteWorkspaceFile(workspaceId: string, path: string): Promise<boolean>;
+    listSandboxes(): Promise<AccountSandbox[]>;
+    createSandbox(input: {
+        name: string;
+        description?: string;
+        config?: unknown;
+    }): Promise<AccountSandbox>;
+    getSandbox(sandboxId: string): Promise<AccountSandbox | null>;
+    /** PATCH a sandbox config. `config` fully replaces the stored config. Returns null when the sandbox is gone. */
+    updateSandbox(sandboxId: string, patch: {
+        name?: string;
+        description?: string | null;
+        config?: unknown;
+    }): 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 a reusable image (self-hosted `sandbox` provider). Throws on 404/403/409. */
+    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` providers). Throws on 404/403/409. */
+    openSandboxTerminal(sandboxId: string, reservationKey: string): Promise<SandboxTerminalTicket>;
+    listTools(): Promise<AccountTool[]>;
+    createTool(input: CreateToolInput): Promise<AccountTool>;
+    getTool(toolId: string): Promise<AccountTool | null>;
+    /** PATCH an uploaded tool. Omitting `bundle` keeps the stored bundle and runtime. Returns null when the tool is gone. */
+    updateTool(toolId: string, patch: UpdateToolInput): Promise<AccountTool | null>;
+    deleteTool(toolId: string): Promise<boolean>;
+    listPolicies(): Promise<AccountPolicy[]>;
+    createPolicy(input: {
+        name: string;
+        description?: string;
+        document: AgentPolicyDocument;
+    }): 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;
+        document?: AgentPolicyDocument;
+        status?: string;
+    }): Promise<AccountPolicy | null>;
+    deletePolicy(policyId: 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;
+}
+
 /**
  * WebSocket client for deployed-agent endpoints.
  * Uses the gateway URL when configured, or derives one from the core service URL.
@@ -964,9 +1359,26 @@ type WebSocketRunInput = {
     projectSlug?: string;
     environmentSlug?: string;
     signal?: AbortSignal;
+    /** Defaults to "steer": join the live run at its next step boundary. */
+    mode?: "reject" | "followup" | "collect" | "steer";
+    idempotencyKey?: string;
 } & AgentRunEventInput & AgentRunOverrides;
+type WebSocketAttachInput = Omit<WebSocketClientAttachMessage, "type"> & {
+    endpointId?: string;
+    agent?: AgentReference;
+    projectSlug?: string;
+    environmentSlug?: string;
+    signal?: AbortSignal;
+};
 interface WebSocketHandlers {
+    /**
+     * Receives every server message with durable output envelopes unwrapped:
+     * stream parts arrive as themselves (`message.type === "text-delta"`), never
+     * nested under `data`. Use `onOutput` when the envelope cursor is needed.
+     */
     onMessage?(message: WebSocketServerMessage): void;
+    /** Receives the raw durable output envelope (cursor, replay flag, part). */
+    onOutput?(output: WebSocketOutputMessage): void;
     onMeta?(meta: Extract<WebSocketServerMessage, {
         type: "meta";
     }>): void;
@@ -975,6 +1387,7 @@ interface WebSocketHandlers {
 }
 interface WebSocketSubscription {
     readonly url: string;
+    sendControl(message: Omit<WebSocketClientControlMessage, "type">): void;
     close(code?: number, reason?: string): void;
 }
 interface BroodsWebSocketClientOptions {
@@ -1011,6 +1424,8 @@ declare class BroodsWebSocketClient {
     private readonly connectTimeoutMs;
     constructor(options?: BroodsWebSocketClientOptions);
     subscribe(input: WebSocketRunInput, handlers?: WebSocketHandlers): WebSocketSubscription;
+    /** Attach to a previously started event and replay from an exclusive cursor. */
+    attach(input: WebSocketAttachInput, handlers?: WebSocketHandlers): WebSocketSubscription;
     stream(input: WebSocketRunInput): AsyncGenerator<WebSocketServerMessage>;
     buildUrl(input: Pick<WebSocketRunInput, "agent" | "endpointId" | "projectSlug" | "environmentSlug">): string;
     private resolveWebSocket;
@@ -1034,10 +1449,9 @@ interface EnvRef<Name extends string = string> {
     readonly __beeblastEnv: true;
     readonly name: Name;
 }
-/** Callable + property-access accessor for {@link env}. */
+/** Callable accessor for {@link env}. */
 interface EnvAccessor {
     <const Name extends string>(name: Name): EnvRef<Name>;
-    readonly [name: string]: EnvRef;
 }
 type EnvRefString<T> = T extends string ? T | EnvRef : T extends readonly (infer Item)[] ? readonly EnvRefString<Item>[] : T extends (infer Item)[] ? EnvRefString<Item>[] : T extends object ? {
     [Key in keyof T]: EnvRefString<T[Key]>;
@@ -1065,14 +1479,17 @@ interface ResourceDefinition<Kind extends ResourceKind, Name extends string, Con
     readonly description?: string;
     readonly config: Config;
 }
-interface ResourceDefinitionInput<Name extends string, Config> {
+/**
+ * Authoring shape for every resource helper: the resource's own `name` (plus an
+ * optional human `description`) sits inline with that resource's config keys.
+ */
+type ResourceInput<Name extends string, Config> = {
     name: Name;
     description?: string;
-    config: Config;
-}
+} & Config;
 /**
  * Code-first sandbox config surface. Mirrors core's `SandboxConfig` but lets
- * `envVars` values be `env.NAME` references (compiled to `${NAME}` placeholders
+ * `envVars` values be `env("NAME")` references (compiled to `${NAME}` placeholders
  * at sync time, exactly like provider `apiKey`). Add overrides here if more
  * sandbox fields should accept env refs.
  */
@@ -1086,15 +1503,46 @@ interface SkillDefinitionConfig {
      */
     path: string;
 }
-interface ToolDefinitionConfig {
+/** Broods-side context on `ToolExecuteOptions`, alongside the AI SDK's own fields. */
+interface ToolExecuteContext {
+    /** Resolved tool config, `env("NAME")` already substituted. Where secrets arrive. */
+    config: Record<string, unknown>;
+    /** SSRF-guarded fetch. Also installed as the global `fetch`. */
+    fetch: typeof fetch;
+    /** Per-run scratchpad. Read back after hooks; empty and unused for tools. */
+    state: Record<string, unknown>;
+}
+/** Call options an inline `execute` receives, mirroring the AI SDK's tool(). */
+interface ToolExecuteOptions {
+    toolCallId?: string;
+    context: ToolExecuteContext;
+    abortSignal?: AbortSignal;
+    /** Conversation so far. Truncated from the front to the newest 512 KB. */
+    messages: ModelMessage[];
+    experimental_context?: unknown;
+}
+interface ToolDefinitionConfig<Input = Record<string, unknown>> {
     /**
-     * JavaScript module file exporting the custom tool bundle. Relative paths are
-     * resolved from the `broods/` project directory.
+     * Optional module file exporting the tool implementation, resolved from the
+     * `broods/` project directory. Omit it and declare `execute` inline instead —
+     * the CLI then bundles the module this tool is exported from.
      */
-    path: string;
+    path?: string;
+    /**
+     * Runs in the isolate or the sandbox runner, not locally. Shaped like the AI
+     * SDK's `tool({ execute })`: the input first, call options second. Annotate
+     * the parameter to type it — `inputSchema` is JSON Schema, so it cannot be
+     * inferred.
+     */
+    execute?: (input: Input, options: ToolExecuteOptions) => unknown;
     description: string;
     inputSchema: Record<string, unknown>;
     runtime?: "isolate" | "sandbox";
+    /**
+     * Account-wide, non-secret defaults. Environment references are rejected
+     * here; put `env("NAME")` under the enabling agent's `tools.<tool>.config` so
+     * the value is resolved per environment and stored with encrypted agent config.
+     */
     defaultConfig?: Record<string, unknown>;
 }
 type PolicyDefinitionConfig = Omit<AgentPolicyDocument, "version"> & {
@@ -1126,7 +1574,7 @@ interface PancakeChannelInput extends ChannelIdentityInput {
 interface ZaloChannelInput extends ChannelIdentityInput {
     botToken: ChannelSecret;
     webhookSecret: ChannelSecret;
-    allowedUserIds: readonly (string | EnvRef)[];
+    allowedUserIds?: readonly (string | EnvRef)[];
 }
 type TelegramChannelDefinition = ChannelDefinition<"telegram", TelegramChannelInput>;
 type GitHubChannelDefinition = ChannelDefinition<"github", GitHubChannelInput>;
@@ -1272,6 +1720,7 @@ interface AgentHooks {
     onMessageReceived?: Handler<ChannelMessageReceived, {
         drop?: boolean;
         text?: string;
+        metadata?: unknown;
     }>;
     onMessageSending?: Handler<{
         channel: ChannelType;
@@ -1299,7 +1748,7 @@ type AgentPolicyDefinitionConfig = Omit<AgentPolicyConfig, "policyIds"> & {
  * typo like the camel `baseUrl` (instead of `base_url`/`baseURL`) slip past
  * `tsc`. Keep the keys in lockstep with core's `AgentProviderSettings`; the
  * `_ProviderKeyParity` assertion below fails `broods check` if they drift.
- * Every string field also accepts an `env(...)` reference.
+ * Every string field also accepts an `env("NAME")` reference.
  */
 interface ProviderSettingsInput {
     apiKey?: string | EnvRef;
@@ -1351,12 +1800,11 @@ type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronRes
  * References an account/environment variable resolved on the SERVER at runtime —
  * set it with `broods env set <NAME>` or in the dashboard (the Convex-style
  * `convex env set` model). It is a deferred reference, never read from your local
- * environment and never baked into the deployed config. Use either form:
+ * environment and never baked into the deployed config:
  *
- *   apiKey: env.OPENAI_API_KEY     // property access (reads like process.env)
- *   apiKey: env("OPENAI_API_KEY")  // call form (equivalent)
+ *   apiKey: env("OPENAI_API_KEY")
  *
- * Both compile to a `${NAME}` placeholder the harness fills in at run time. This is
+ * It compiles to a `${NAME}` placeholder the harness fills in at run time. This is
  * NOT `process.env`: agent configs are compiled locally, so `process.env.NAME` would
  * bake the literal local value into the deployed config instead of deferring it.
  */
@@ -1368,16 +1816,18 @@ declare function defineDiscordChannel(config: DiscordChannelInput): DiscordChann
 declare function definePancakeChannel(config: PancakeChannelInput): PancakeChannelDefinition;
 declare function defineZaloChannel(config: ZaloChannelInput): ZaloChannelDefinition;
 declare function defineBroods(config: BroodsProjectConfig): BroodsConfigDefinition;
-declare function defineAgent<const Name extends string>(input: ResourceDefinitionInput<Name, AgentDefinitionConfig>): AgentResource<Name>;
-declare function defineWorkspace<const Name extends string>(input: ResourceDefinitionInput<Name, WorkspaceConfig>): WorkspaceResource<Name>;
-declare function defineSandbox<const Name extends string>(input: ResourceDefinitionInput<Name, SandboxDefinitionConfig>): SandboxResource<Name>;
-declare function defineSkill<const Name extends string>(input: ResourceDefinitionInput<Name, SkillDefinitionConfig>): SkillResource<Name>;
-declare function defineTool<const Name extends string>(input: ResourceDefinitionInput<Name, ToolDefinitionConfig>): ToolResource<Name>;
-declare function definePolicy<const Name extends string>(input: ResourceDefinitionInput<Name, PolicyDefinitionConfig>): PolicyResource<Name>;
-declare function defineCron<const Name extends string>(input: ResourceDefinitionInput<Name, CronDefinitionConfig>): CronResource<Name>;
+declare function defineAgent<const Name extends string>(input: ResourceInput<Name, AgentDefinitionConfig>): AgentResource<Name>;
+declare function defineWorkspace<const Name extends string>(input: ResourceInput<Name, WorkspaceConfig>): WorkspaceResource<Name>;
+declare function defineSandbox<const Name extends string>(input: ResourceInput<Name, SandboxDefinitionConfig>): SandboxResource<Name>;
+declare function defineSkill<const Name extends string>(input: ResourceInput<Name, SkillDefinitionConfig>): SkillResource<Name>;
+declare function defineTool<const Name extends string, Input = Record<string, unknown>>(input: {
+    name: Name;
+} & ToolDefinitionConfig<Input>): ToolResource<Name>;
+declare function definePolicy<const Name extends string>(input: ResourceInput<Name, PolicyDefinitionConfig>): PolicyResource<Name>;
+declare function defineCron<const Name extends string>(input: ResourceInput<Name, CronDefinitionConfig>): CronResource<Name>;
 declare function isResource(value: unknown): value is AnyResource;
 declare function isChannelDefinition(value: unknown): value is AnyChannelDefinition;
 declare function isBroodsConfig(value: unknown): value is BroodsConfigDefinition;
 
-export { BroodsClient, BroodsWebSocketClient, DEFAULT_CORE_BASE_URL, MAX_OBSERVABILITY_BACKFILL, BroodsWebSocketClient as WebSocketClient, BroodsWebSocketClient as WebsocketClient, defineAgent, defineBroods, defineCron, defineDiscordChannel, defineGitHubChannel, definePancakeChannel, definePolicy, defineSandbox, defineSkill, defineSlackChannel, defineTelegramChannel, defineTool, defineWorkspace, defineZaloChannel, env, isBroodsConfig, isChannelDefinition, isObservabilityClientMessage, isResource, normalizeHttpServiceUrl, readSseStream, resolveRunEvents, toWebSocketBaseUrl };
-export type { Account, Agent, AgentChannelWorkspaceScope, AgentChannelsConfig, AgentCodeHookConfig, AgentConfig, AgentConfigDoc, AgentDefinitionConfig, AgentDiscordChannelConfig, AgentGitHubChannelConfig, AgentHandle, AgentHookEventName, AgentHooks, AgentHooksConfig, AgentPancakeChannelConfig, AgentPolicyConfig, AgentPolicyDefinitionConfig, AgentPolicyDocument, AgentProviderSettings, AgentReference, AgentResource, AgentRunEventInput, AgentRunInput, AgentRunModelOverrides, AgentRunOverrides, AgentRunResult, AgentSkillsDefinitionConfig, AgentSlackChannelConfig, AgentStreamPart, AgentSubagentDefinitionConfig, AgentTelegramChannelConfig, AgentWebhookHookConfig, AgentWorkspaceInput, AgentWorkspaceRef, AgentWorkspaceRefInput, AgentZaloChannelConfig, AnyChannelDefinition, AnyResource, AsyncAgentRun, AsyncPollOptions, AsyncRequestAccepted, AsyncStatus, BroodsClientOptions, BroodsConfigDefinition, BroodsProjectConfig, BroodsWebSocketClientOptions, ChannelDefinition, ChannelMessageReceived, ChannelReference, ChannelType, CliManifest, CliManifestResource, CliResourceKind, CreateClientCronInput, CreateCronInput, Cron, CronDefinitionConfig, CronDoc, CronLastStatus, CronResource, CronRun, CronStatus, CustomTool, DiscordChannelDefinition, DiscordChannelInput, DiscordMessageSource, DiscordSource, Doc, EnvAccessor, EnvRef, EnvRefString, EnvironmentDoc, GeneratedIds, GitHubChannelDefinition, GitHubChannelInput, GitHubMessageSource, GitHubSource, HookContext, Id, LogLevel, ObservabilityBackfillMessage, ObservabilityClientMessage, ObservabilityErrorMessage, ObservabilityLogEntry, ObservabilityLogMessage, ObservabilityReadyMessage, ObservabilityServerMessage, ObservabilitySpanMessage, ObservabilitySpanRow, ObservabilitySubscribeMessage, ObservabilityUnsubscribeMessage, PancakeChannelDefinition, PancakeChannelInput, PancakeMessageSource, PancakeSource, PolicyDefinitionConfig, PolicyResource, ProjectDoc, ProviderConfigInput, ProviderSettingsInput, ResourceApi, ResourceDefinition, ResourceDefinitionInput, ResourceKind, Sandbox, SandboxConfig, SandboxConfigDoc, SandboxDefinitionConfig, SandboxResource, Skill, SkillDefinitionConfig, SkillResource, SlackChannelDefinition, SlackChannelInput, SlackMessageSource, SlackSource, TelegramChannelDefinition, TelegramChannelInput, TelegramMessageSource, TelegramSource, ToolApprovalSummary, ToolDefinitionConfig, ToolResource, UpdateCronInput, WebSocketClientCancelMessage, WebSocketClientExecuteMessage, WebSocketClientMessage, WebSocketConstructorLike, WebSocketHandlers, WebSocketLike, WebSocketRunInput, WebSocketServerMessage, WebSocketStreamMessage, WebSocketSubscription, Workspace, WorkspaceConfig, WorkspaceConfigDoc, WorkspaceResource, ZaloChannelDefinition, ZaloChannelInput, ZaloMessageSource, ZaloSource };
+export { BroodsAccountApiError, BroodsAccountClient, BroodsClient, BroodsWebSocketClient, DEFAULT_CORE_BASE_URL, IngressAcceptedError, MAX_OBSERVABILITY_BACKFILL, BroodsWebSocketClient as WebSocketClient, BroodsWebSocketClient as WebsocketClient, defineAgent, defineBroods, defineCron, defineDiscordChannel, defineGitHubChannel, definePancakeChannel, definePolicy, defineSandbox, defineSkill, defineSlackChannel, defineTelegramChannel, defineTool, defineWorkspace, defineZaloChannel, env, envPlaceholder, isBroodsConfig, isChannelDefinition, isObservabilityClientMessage, isResource, normalizeHttpServiceUrl, readSseStream, resolveRunEvents, toWebSocketBaseUrl };
+export type { Account, AccountAgent, AccountEnvVar, AccountPolicy, AccountSandbox, AccountTool, AccountWorkspace, Agent, AgentChannelWorkspaceScope, AgentChannelsConfig, AgentCodeHookConfig, AgentConfig, AgentConfigDoc, AgentDefinitionConfig, AgentDiscordChannelConfig, AgentGitHubChannelConfig, AgentHandle, AgentHookEventName, AgentHooks, AgentHooksConfig, AgentPancakeChannelConfig, AgentPolicyConfig, AgentPolicyDefinitionConfig, AgentPolicyDocument, AgentProviderSettings, AgentReference, AgentResource, AgentRunEventInput, AgentRunInput, AgentRunModelOverrides, AgentRunOverrides, AgentRunResult, AgentSkillsDefinitionConfig, AgentSlackChannelConfig, AgentStreamPart, AgentSubagentDefinitionConfig, AgentTelegramChannelConfig, AgentWebhookHookConfig, AgentWorkspaceInput, AgentWorkspaceRef, AgentWorkspaceRefInput, AgentZaloChannelConfig, AnyChannelDefinition, AnyResource, AsyncAgentRun, AsyncPollOptions, AsyncRequestAccepted, AsyncStatus, BroodsAccount, BroodsAccountClientOptions, BroodsClientOptions, BroodsConfigDefinition, BroodsProjectConfig, BroodsWebSocketClientOptions, ChannelDefinition, ChannelMessageReceived, ChannelReference, ChannelType, CliManifest, CliManifestResource, CliResourceKind, CreateAgentResult, CreateClientCronInput, CreateCronInput, CreateToolInput, Cron, CronDefinitionConfig, CronDoc, CronLastStatus, CronResource, CronRun, CronStatus, CustomTool, DeleteAccountResult, DiscordChannelDefinition, DiscordChannelInput, DiscordMessageSource, DiscordSource, Doc, EnvAccessor, EnvRef, EnvRefString, EnvironmentDoc, GeneratedIds, GitHubChannelDefinition, GitHubChannelInput, GitHubMessageSource, GitHubSource, HookContext, Id, IngressMode, IngressStatus, LogLevel, ObservabilityBackfillMessage, ObservabilityClientMessage, ObservabilityErrorMessage, ObservabilityLogEntry, ObservabilityLogMessage, ObservabilityReadyMessage, ObservabilityServerMessage, ObservabilitySpanMessage, ObservabilitySpanRow, ObservabilitySubscribeMessage, ObservabilityUnsubscribeMessage, PancakeChannelDefinition, PancakeChannelInput, PancakeMessageSource, PancakeSource, PolicyDefinitionConfig, PolicyResource, ProjectDoc, ProviderConfigInput, ProviderSettingsInput, ResourceApi, ResourceDefinition, ResourceInput, ResourceKind, RotateSecretResult, Sandbox, SandboxConfig, SandboxConfigDoc, SandboxDefinitionConfig, SandboxLifecycleResult, SandboxResource, SandboxSnapshotResult, SandboxTerminalTicket, Skill, SkillDefinitionConfig, SkillResource, SkillUploadInput, SlackChannelDefinition, SlackChannelInput, SlackMessageSource, SlackSource, TelegramChannelDefinition, TelegramChannelInput, TelegramMessageSource, TelegramSource, ToolApprovalSummary, ToolDefinitionConfig, ToolExecuteContext, ToolExecuteOptions, ToolResource, UpdateAgentInput, UpdateCronInput, UpdateToolInput, WebSocketAttachInput, WebSocketClientAttachMessage, WebSocketClientCancelMessage, WebSocketClientControlMessage, WebSocketClientExecuteMessage, WebSocketClientMessage, WebSocketConstructorLike, WebSocketHandlers, WebSocketLike, WebSocketOutputMessage, WebSocketRunInput, WebSocketServerMessage, WebSocketStreamMessage, WebSocketSubscription, Workspace, WorkspaceConfig, WorkspaceConfigDoc, WorkspaceFileEntry, WorkspaceResource, ZaloChannelDefinition, ZaloChannelInput, ZaloMessageSource, ZaloSource };