broods 0.2.0 → 0.3.0

package/dist/account.d.ts

@@ -0,0 +1,799 @@
+import { SystemModelMessage, LanguageModelCallOptions, RequestOptions, streamText, JSONSchema7, ModelMessage } 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';
+
+/**
+ * Agent policy contracts and validation.
+ * Runtime decisions are made by OPA using the same document/input shape.
+ */
+declare const AGENT_POLICY_ACTIONS: readonly ["tool.call", "workspace.read", "workspace.write", "workspace.exec", "subagent.run", "skill.load"];
+type AgentPolicyAction = (typeof AGENT_POLICY_ACTIONS)[number];
+type AgentPolicyEffect = "allow" | "deny";
+type AgentPolicyMode = "enforce" | "audit";
+type AgentPolicyConditionOperator = "equals" | "notEquals" | "in" | "notIn" | "prefix" | "contains";
+interface AgentPolicyCondition {
+    attribute: string;
+    operator: AgentPolicyConditionOperator;
+    value: string | number | boolean | string[] | number[] | boolean[];
+}
+interface AgentPolicyResourceSelector {
+    toolNames?: string[];
+    toolIds?: string[];
+    workspaceIds?: string[];
+    workspaceNames?: string[];
+    filePaths?: string[];
+    subagentIds?: string[];
+    skillPaths?: string[];
+}
+interface AgentPolicyRule {
+    id: string;
+    effect: AgentPolicyEffect;
+    actions: AgentPolicyAction[];
+    resources?: AgentPolicyResourceSelector;
+    conditions?: AgentPolicyCondition[];
+}
+interface AgentPolicyDocument {
+    version: 1;
+    rules: AgentPolicyRule[];
+}
+interface AgentPolicyConfig {
+    policyIds?: string[];
+    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.
+ * Account types and auth live in `./accounts.ts` and `../auth.ts`.
+ */
+
+interface AgentConfig {
+    agent?: AgentBehaviorConfig;
+    model?: AgentModelConfig;
+    provider?: AgentProviderConfig;
+    sandbox?: string;
+    workspaces?: AgentWorkspaceRef[];
+    session?: AgentSessionConfig;
+    hooks?: AgentHooksConfig;
+    channels?: AgentChannelsConfig;
+    tools?: AgentToolsConfig;
+    skills?: AgentSkillsConfig;
+    subagent?: AgentSubagentConfig;
+    policy?: AgentPolicyConfig;
+    publicAccess?: boolean;
+    [key: string]: unknown;
+}
+interface AgentBehaviorConfig {
+    maxTurn?: number;
+    system?: string | SystemModelMessage | SystemModelMessage[];
+    [key: string]: unknown;
+}
+type StreamTextOptions = Parameters<typeof streamText>[0];
+type AgentModelProviderOptions = StreamTextOptions["providerOptions"];
+interface AgentSkillsConfig {
+    enabled?: boolean;
+    allowed?: string[];
+    [key: string]: unknown;
+}
+interface AgentSubagentConfig {
+    enabled?: boolean;
+    allowed?: string[];
+    context?: "new" | "inherited";
+    mode?: "ephemeral" | "persistent";
+    /**
+     * 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.
+     */
+    visibility?: "full" | "result" | "none";
+    [key: string]: unknown;
+}
+interface AgentModelConfig extends LanguageModelCallOptions, Pick<RequestOptions, "maxRetries" | "timeout"> {
+    provider?: AccountModelProviderName;
+    modelId?: string;
+    providerOptions?: AgentModelProviderOptions;
+    output?: AgentModelOutputConfig;
+}
+type AgentModelOutputConfig = ({
+    type: "text";
+} & AgentModelOutputMetadata) | ({
+    type: "object";
+    schema: JSONSchema7;
+} & AgentModelOutputMetadata) | ({
+    type: "array";
+    element: JSONSchema7;
+} & AgentModelOutputMetadata) | ({
+    type: "choice";
+    options: string[];
+} & AgentModelOutputMetadata) | ({
+    type: "json";
+} & AgentModelOutputMetadata);
+type AgentModelOutputMetadata = {
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+};
+type AgentProviderConfig = Partial<Record<AccountModelProviderName, AgentProviderSettings>>;
+/**
+ * Constructor settings for a model provider. The keys are an explicit allow-list
+ * (no open index signature) so a misspelled option — most commonly the camel
+ * `baseUrl` instead of the canonical `base_url`/`baseURL` — is a compile-time
+ * error in the SDK and is caught by `normalizeProviderSettings` at runtime.
+ * Keep this list in sync with `normalizeProviderSettings` and the SDK's
+ * `KNOWN_PROVIDER_SETTING_KEYS`.
+ */
+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;
+    headers?: Record<string, string>;
+    organization?: string;
+    project?: string;
+    name?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+}
+interface AgentWorkspaceRef {
+    name: string;
+    workspaceId: string;
+    sandbox?: string | null;
+}
+interface AgentSessionConfig {
+    pruning?: AgentSessionPruningConfig;
+    compaction?: AgentSessionCompactionConfig;
+    [key: string]: unknown;
+}
+interface AgentSessionPruningConfig {
+    enabled?: boolean;
+    [key: string]: unknown;
+}
+interface AgentSessionCompactionConfig {
+    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;
+}
+interface AgentWebhookHookConfig {
+    enabled?: boolean;
+    url?: string;
+    secret?: string;
+    events?: AgentLifecycleEventName[];
+    [key: string]: unknown;
+}
+type AgentLifecycleEventName = "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";
+type AgentChannelHookEventName = "channel.message.received" | "channel.message.sending";
+type AgentHookEventName = AgentLifecycleEventName | AgentChannelHookEventName;
+type AgentToolsConfig = Record<string, AgentToolConfig>;
+interface AgentToolConfig {
+    enabled?: boolean;
+    needsApproval?: boolean;
+    async?: boolean;
+    config?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface AgentChannelsConfig {
+    telegram?: AgentTelegramChannelConfig;
+    github?: AgentGitHubChannelConfig;
+    slack?: AgentSlackChannelConfig;
+    discord?: AgentDiscordChannelConfig;
+    pancake?: AgentPancakeChannelConfig;
+    zalo?: AgentZaloChannelConfig;
+    [key: string]: unknown;
+}
+type AgentChannelWorkspaceScope = {
+    level: "channel";
+    alias?: never;
+} | {
+    level: "conversation";
+    alias: string;
+};
+interface AgentTelegramChannelConfig {
+    id?: string;
+    apiUrl?: TelegramAdapterConfig["apiUrl"];
+    botToken?: TelegramAdapterConfig["botToken"];
+    webhookSecret?: TelegramAdapterConfig["secretToken"];
+    allowedChatIds?: number[];
+    reactionEmoji?: string;
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+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"];
+    allowedRepos?: string[];
+    /** Bot username for @-mention detection (e.g. "my-bot" or "my-bot[bot]"). */
+    userName?: 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;
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+interface AgentSlackChannelConfig {
+    id?: string;
+    apiUrl?: SlackAdapterConfig["apiUrl"];
+    botToken?: string;
+    signingSecret?: SlackAdapterConfig["signingSecret"];
+    allowedChannelIds?: string[];
+    reactionEmoji?: string;
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+interface AgentDiscordChannelConfig {
+    id?: string;
+    apiUrl?: DiscordAdapterConfig["apiUrl"];
+    botToken?: DiscordAdapterConfig["botToken"];
+    publicKey?: DiscordAdapterConfig["publicKey"];
+    allowedGuildIds?: string[];
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+interface AgentPancakeChannelConfig {
+    id?: string;
+    pageId?: string;
+    pageAccessToken?: string;
+    webhookSecret?: string;
+    senderId?: string;
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+interface AgentZaloChannelConfig {
+    id?: string;
+    botToken?: string;
+    webhookSecret?: string;
+    allowedUserIds?: string[];
+    workspaceScope?: AgentChannelWorkspaceScope;
+    [key: string]: unknown;
+}
+
+/**
+ * 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.
+ */
+
+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;
+} | {
+    events: ModelMessage[];
+    input?: never;
+};
+type CreateCronInput = {
+    name: string;
+    description?: string;
+    agentId: string;
+    conversationKey?: string;
+    scheduleExpression: string;
+    timezone?: string;
+    status?: CronStatus;
+} & CronRunInput;
+type UpdateCronInput = {
+    name?: string;
+    description?: string | null;
+    agentId?: string;
+    conversationKey?: string | null;
+    scheduleExpression?: string;
+    timezone?: string | null;
+    status?: CronStatus;
+} & ({
+    input?: string;
+    events?: never;
+} | {
+    events?: ModelMessage[];
+    input?: never;
+});
+
+/**
+ * Predefined sandbox sizes — the canonical (vcpu, memoryMb, storageGb) catalog
+ * shared by sandbox config validation, the workdir resource mapping, and the
+ * Convex `sandboxInstances` mirror. Sizes are the user-facing knob (`config.size`)
+ * that reconciles issue #78's tiers with each backend's real limits.
+ *
+ * The specs are canonical/advisory: workdir applies them as create-time resources
+ * (clamping vcpu to its allowed set); MicroVM bakes size into the image so the
+ * specs are display-only there; daytona/e2b/vercel size natively. The control-plane
+ * mirror type lives here too so the Convex writer and the executors share one shape
+ * without importing across the _shared/harness boundary.
+ */
+
+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.
+ * Stored encrypted at rest because `envVars`/`options` may hold secrets.
+ */
+
+type SandboxProvider = "sandbox" | "lambda" | "e2b" | "daytona" | "vercel";
+type SandboxRuntimeName = "bash" | "python" | "node";
+type SandboxPermissionMode = "edit" | "ask" | "bypass";
+type SandboxNetworkMode = "allow-all" | "deny-all" | "restricted";
+interface SandboxLifecycleConfig {
+    idleTimeoutSeconds?: number;
+    maxLifetimeSeconds?: number;
+}
+interface SandboxNetworkConfig {
+    mode: SandboxNetworkMode;
+    allowDomains?: string[];
+    allowCidrs?: string[];
+}
+interface SandboxConfig {
+    provider: SandboxProvider;
+    size?: SandboxSize;
+    snapshot?: string;
+    runtimes?: SandboxRuntimeName[];
+    network?: SandboxNetworkConfig;
+    permissionMode?: SandboxPermissionMode;
+    persistent?: boolean;
+    lifecycle?: SandboxLifecycleConfig;
+    onCreate?: string[];
+    onResume?: string[];
+    timeout?: number;
+    memoryLimit?: number;
+    outputLimitBytes?: number;
+    envVars?: Record<string, undefined | string>;
+    options?: Record<string, unknown>;
+}
+
+/**
+ * Workspace config: account-scoped, reusable workspace definitions referenced by
+ * 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.
+ */
+declare const WORKSPACE_STORAGE_PROVIDERS: readonly ["s3"];
+type WorkspaceStorageProvider = (typeof WORKSPACE_STORAGE_PROVIDERS)[number];
+type WorkspaceStorageAuth = {
+    type: "managed";
+} | {
+    type: "assumeRole";
+    roleArn: string;
+    externalId?: string;
+};
+interface WorkspaceStorageConfig {
+    provider: WorkspaceStorageProvider;
+    bucket?: string;
+    region?: string;
+    endpoint?: string;
+    prefix?: string;
+    auth?: WorkspaceStorageAuth;
+}
+interface WorkspaceConfig {
+    storage: WorkspaceStorageConfig;
+    isolation?: boolean;
+    harness?: {
+        enabled?: 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;
+    name: string;
+    description?: string;
+    agentId: string;
+    events: ModelMessage[];
+    conversationKey?: string;
+    scheduleExpression: string;
+    timezone?: string;
+    status: CronStatus;
+    createdAt: string;
+    updatedAt: string;
+    lastInvokedAt?: string;
+    lastStatus?: CronLastStatus;
+    lastError?: string;
+}
+interface CronRun {
+    accountId: string;
+    cronId: string;
+    runId: string;
+    eventId: string;
+    conversationKey: string;
+    status: CronLastStatus;
+    result?: unknown;
+    error?: string;
+    startedAt: string;
+    completedAt?: string;
+}
+interface Skill {
+    path: string;
+    name: string;
+    description: string;
+    files?: Array<{
+        path: string;
+        size?: number;
+    }>;
+}
+
+/**
+ * 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;
+}
+/** 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>;
+    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;
+}
+
+export { BroodsAccountApiError, BroodsAccountClient };
+export type { AccountAgent, AccountPolicy, AccountSandbox, AccountTool, AccountWorkspace, BroodsAccount, BroodsAccountClientOptions, CreateAgentResult, CreateToolInput, DeleteAccountResult, RotateSecretResult, SandboxLifecycleResult, SandboxSnapshotResult, SandboxTerminalTicket, SkillUploadInput, UpdateAgentInput, UpdateToolInput, WorkspaceFileEntry };