broods 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 import { SystemModelMessage, LanguageModelCallOptions, RequestOptions, streamText, JSONSchema7, ModelMessage, TextStreamPart, ToolSet } from 'ai';
 
+/**
+ * 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, plus `custom`
  * (any OpenAI-compatible endpoint) and `minimax`. Image-, speech- and
@@ -114,6 +121,8 @@ interface AgentConfig {
     hooks?: AgentHooksConfig;
     channels?: AgentChannelsConfig;
     tools?: AgentToolsConfig;
+    /** Connected MCP servers, keyed by their config-plane row id (#331). */
+    mcpServers?: AgentMcpServersConfig;
     /**
      * 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.
@@ -269,8 +278,7 @@ interface AgentWebhookHookConfig {
     [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;
@@ -279,6 +287,15 @@ interface AgentToolConfig {
     config?: Record<string, unknown>;
     [key: string]: unknown;
 }
+type AgentMcpServersConfig = Record<string, AgentMcpServerConfig>;
+interface AgentMcpServerConfig {
+    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>;
+    [key: string]: unknown;
+}
 interface AgentChannelsConfig {
     telegram?: AgentTelegramChannelConfig;
     github?: AgentGitHubChannelConfig;
@@ -385,7 +402,9 @@ interface AgentZaloChannelConfig {
 }
 
 /**
- * Cron-job records, input normalization, and patch-merge helpers.
+ * 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";
@@ -427,48 +446,45 @@ type UpdateCronInput = {
 });
 
 /**
- * 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.
+ * 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.
  */
-
-type SandboxSize = "tiny" | "xsmall" | "small" | "medium" | "large";
-
+declare const SANDBOX_PROVIDERS: readonly ["sandbox", "lambda", "e2b", "daytona", "vercel"];
+declare const SANDBOX_RUNTIMES: readonly ["bash", "python", "node"];
+declare const SANDBOX_PERMISSION_MODES: readonly ["edit", "ask", "bypass"];
+declare const SANDBOX_NETWORK_MODES: readonly ["allow-all", "deny-all", "restricted"];
+declare const SANDBOX_SIZE_NAMES: readonly ["tiny", "xsmall", "small", "medium", "large"];
+type SandboxProvider = (typeof SANDBOX_PROVIDERS)[number];
+type RuntimeName = (typeof SANDBOX_RUNTIMES)[number];
+type PermissionMode = (typeof SANDBOX_PERMISSION_MODES)[number];
+type NetworkMode = (typeof SANDBOX_NETWORK_MODES)[number];
+type SandboxSize = (typeof SANDBOX_SIZE_NAMES)[number];
 /**
- * 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 and
- * the public projection live here.
- * Stored encrypted at rest because `envVars`/`options` may hold secrets.
+ * Idle and maximum lifetime controls for a persistent sandbox.
  */
-
-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;
 }
+/**
+ * Provider-normalized sandbox network policy.
+ */
 interface SandboxNetworkConfig {
-    mode: SandboxNetworkMode;
+    mode: NetworkMode;
     allowDomains?: string[];
     allowCidrs?: string[];
 }
+/**
+ * Account-scoped reusable sandbox configuration referenced by agents.
+ */
 interface SandboxConfig {
     provider: SandboxProvider;
     size?: SandboxSize;
     snapshot?: string;
-    runtimes?: SandboxRuntimeName[];
+    runtimes?: RuntimeName[];
     network?: SandboxNetworkConfig;
-    permissionMode?: SandboxPermissionMode;
+    permissionMode?: PermissionMode;
     persistent?: boolean;
     lifecycle?: SandboxLifecycleConfig;
     onCreate?: string[];
@@ -481,12 +497,12 @@ interface SandboxConfig {
 }
 
 /**
- * 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 and the public projection live
- * here.
+ * 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), so it is stored and returned in plaintext. Pure module — safe
+ * for the default Convex runtime. The public projection lives in
+ * ./responses.ts.
  */
 declare const WORKSPACE_STORAGE_PROVIDERS: readonly ["s3"];
 type WorkspaceStorageProvider = (typeof WORKSPACE_STORAGE_PROVIDERS)[number];
@@ -505,43 +521,72 @@ interface WorkspaceStorageConfig {
     prefix?: string;
     auth?: WorkspaceStorageAuth;
 }
-interface WorkspaceHarnessConfig {
-    workspace?: {
-        enabled?: boolean;
-    };
-    memory?: {
-        enabled?: boolean;
-    };
-}
 interface WorkspaceConfig {
     storage: WorkspaceStorageConfig;
     isolation?: boolean;
-    harness?: WorkspaceHarnessConfig;
+    harness?: {
+        workspace?: {
+            enabled?: boolean;
+        };
+        memory?: {
+            enabled?: boolean;
+        };
+    };
 }
 
 /**
- * Agent policy contracts and validation.
- * Runtime decisions are made by OPA using the same document/input shape.
+ * Agent-policy validation for the Convex config plane. Ports core's public
+ * CRUD normalizer so policy documents keep the account-management API
+ * contract. The public projection lives in ./responses.ts.
+ */
+declare const AGENT_POLICY_ACTIONS: readonly ["agent.invoke", "tool.call", "workspace.read", "workspace.write", "workspace.exec", "subagent.run", "skill.load"];
+/**
+ * API action namespace for account roles: one read/write pair per config-plane
+ * resource route. Roles carry the same PolicyDocument shape as agent policies;
+ * each caller passes its action set to `normalizePolicyDocument`.
+ */
+declare const API_POLICY_ACTIONS: readonly ["account:read", "account:write", "agents:read", "agents:write", "channels:read", "channels:write", "crons:read", "crons:write", "env:read", "env:write", "hooks:read", "hooks:write", "mcp:read", "mcp:write", "policies:read", "policies:write", "sandboxes:read", "sandboxes:write", "skills:read", "skills:write", "tools:read", "tools:write", "workspaces:read", "workspaces:write"];
+type AgentPolicyAction = (typeof AGENT_POLICY_ACTIONS)[number];
+type ApiPolicyAction = (typeof API_POLICY_ACTIONS)[number];
+type PolicyAction = AgentPolicyAction | ApiPolicyAction;
+/**
+ * One optional predicate on a policy rule.
  */
-declare const POLICY_ACTIONS: readonly ["agent.invoke", "tool.call", "workspace.read", "workspace.write", "workspace.exec", "subagent.run", "skill.load"];
-type PolicyAction = (typeof POLICY_ACTIONS)[number];
-type PolicyEffect = "allow" | "deny";
-type PolicyMode = "enforce" | "audit";
-type PolicyConditionOperator = "equals" | "notEquals" | "in" | "notIn" | "prefix" | "contains";
 interface PolicyCondition {
     attribute: string;
     operator: PolicyConditionOperator;
     value: string | number | boolean | string[] | number[] | boolean[];
 }
+type PolicyConditionOperator = "equals" | "notEquals" | "in" | "notIn" | "prefix" | "contains";
+/**
+ * Versioned policy document accepted by account-management CRUD.
+ */
+interface PolicyDocument {
+    version: 1;
+    /** How hard this policy bites where it is attached. Omitted reads as `audit`. */
+    mode?: "enforce" | "audit";
+    rules: PolicyRule[];
+}
+type PolicyEffect = "allow" | "deny";
+/**
+ * Resource selector fields supported by policy rules.
+ */
 interface PolicyResourceSelector {
     toolNames?: string[];
     toolIds?: string[];
+    /** MCP registration ids, for scoping tool.call rules per server (#331). */
+    mcpIds?: string[];
     workspaceIds?: string[];
     workspaceNames?: string[];
     filePaths?: string[];
     subagentIds?: string[];
     skillPaths?: string[];
+    /** Config-plane resource ids for API-action rules; "*" matches every id. */
+    resourceIds?: string[];
 }
+/**
+ * One allow/deny rule inside a policy document.
+ */
 interface PolicyRule {
     id: string;
     effect: PolicyEffect;
@@ -549,26 +594,13 @@ interface PolicyRule {
     resources?: PolicyResourceSelector;
     conditions?: PolicyCondition[];
 }
-interface PolicyDocument {
-    version: 1;
-    /**
-     * How hard this policy bites. `audit` records what it would have done and
-     * blocks nothing; `enforce` lets its deny rules refuse, and switches the
-     * places it is attached to over to default-deny. Omitted reads as `audit`,
-     * so a freshly written policy can never break a running agent.
-     */
-    mode?: PolicyMode;
-    rules: PolicyRule[];
-}
 
 /**
- * Channel records: an account-scoped row per real place a team talks — one Slack
- * channel, one Discord channel, one repository. It binds that place to an agent
- * and adds instructions, workspaces, policies and roles scoped to it.
- * Distinct from `config.channels`, which holds one adapter's credentials.
- * A record narrows and adds; it never grants capability the agent lacks.
+ * 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];
@@ -685,7 +717,7 @@ interface ZaloSource {
  * import it without pulling the Convex server module graph into its typecheck.
  */
 type CliManifestResource = {
-    kind: "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "hook" | "policy" | "channelRecord";
+    kind: "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "hook" | "mcp" | "policy" | "channelRecord";
     name: string;
     description?: string;
     config: unknown;
@@ -698,6 +730,7 @@ type GeneratedIds = {
     skills: Record<string, string>;
     tools: Record<string, string>;
     hooks: Record<string, string>;
+    mcpServers: Record<string, string>;
     policies: Record<string, string>;
     channelRecords: Record<string, string>;
 };
@@ -726,7 +759,7 @@ type AgentConfigDoc = Doc<"agentConfigs">;
 type WorkspaceConfigDoc = Doc<"workspaceConfigs">;
 type SandboxConfigDoc = Doc<"sandboxConfigs">;
 type CronDoc = Doc<"crons">;
-type CliResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "policy" | "channelRecord";
+type CliResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "mcp" | "policy" | "channelRecord";
 
 /**
  * Wire types for the public account-manage and harness APIs. These mirror
@@ -1205,8 +1238,10 @@ declare function normalizeHttpServiceUrl(value: string): string;
  * 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.
+ * `{baseUrl}/v1/...` — or a short-lived `fp_sts_` 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.
  */
 
 interface BroodsAccountClientOptions {
@@ -1214,6 +1249,12 @@ interface BroodsAccountClientOptions {
     baseUrl?: string;
     /** Account secret used as the Bearer token. Falls back to `BROODS_ACCOUNT_SECRET`. */
     accountSecret?: string;
+    /**
+     * Short-lived `fp_sts_` role session token (from {@link BroodsAccountClient.assumeRole})
+     * used as the Bearer instead of the account secret. The session can only do
+     * what its role's policy allows. Falls back to `BROODS_SESSION_TOKEN`.
+     */
+    sessionToken?: string;
     fetch?: typeof fetch;
 }
 /** Public account record returned by `GET /v1/account`. */
@@ -1293,6 +1334,29 @@ 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 stage runtime keys may assume the role.
+ */
+interface AccountRole {
+    accountId: string;
+    roleId: string;
+    name: string;
+    projectId?: string;
+    stageId?: string;
+    status: "active" | "disabled";
+    policy: PolicyDocument;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Short-lived role session minted by `POST /v1/account/assume-role`. */
+interface AssumeRoleResult {
+    /** `fp_sts_` 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 — a Slack channel, a Discord channel, a repo —
  * bound to an agent. The runtime reads it on the inbound webhook to decide who
@@ -1386,6 +1450,46 @@ interface UpdateToolInput {
     runtime?: "isolate" | "sandbox";
     defaultConfig?: unknown;
 }
+/** Public MCP server registration returned by the `/v1/mcp` routes (#331). */
+interface AccountMcpServer {
+    accountId: string;
+    serverId: string;
+    projectId: string;
+    stageId: string;
+    name: string;
+    description?: string;
+    transport: "http" | "hosted";
+    /** External servers only; a hosted row has no endpoint of its own. */
+    url?: string;
+    /** Hosted servers only: content hash of the uploaded bundle. */
+    sha256?: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[];
+    disabled: boolean;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string;
+}
+/** Fields accepted by `POST /v1/mcp`: `url` connects, `bundle` uploads. */
+interface CreateMcpServerInput {
+    name: string;
+    description?: string;
+    url?: string;
+    bundle?: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[];
+}
+/** Fields accepted by `PATCH /v1/mcp/{serverId}`; every field is optional. */
+interface UpdateMcpServerInput {
+    name?: string;
+    description?: string;
+    url?: string;
+    bundle?: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[];
+    disabled?: boolean;
+}
 /**
  * Body of a skill upload (`POST /v1/skills`, `PUT /v1/skills/{skillName}`).
  * `json` needs `name`/`description`/`content`; `files` needs base64 `files`
@@ -1443,7 +1547,7 @@ declare class BroodsAccountApiError extends Error {
  */
 declare class BroodsAccountClient {
     private readonly baseUrl;
-    private readonly accountSecret;
+    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. */
@@ -1453,6 +1557,15 @@ declare class BroodsAccountClient {
         username?: string;
         description?: string | null;
     }): Promise<BroodsAccount | null>;
+    /**
+     * Exchange a role for a short-lived `fp_sts_` session token. Callable with
+     * the account secret, a CLI login token, or a stage 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.
+     */
+    assumeRole(roleId: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<AssumeRoleResult>;
     /** 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. */
@@ -1548,6 +1661,12 @@ declare class BroodsAccountClient {
     /** 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>;
+    /** MCP servers are stage-scoped like tools; both scope fields are required. */
+    listMcpServers(scope: ToolScope): Promise<AccountMcpServer[]>;
+    createMcpServer(scope: ToolScope, input: CreateMcpServerInput): Promise<AccountMcpServer>;
+    getMcpServer(serverId: string): Promise<AccountMcpServer | null>;
+    updateMcpServer(serverId: string, patch: UpdateMcpServerInput): Promise<AccountMcpServer | null>;
+    deleteMcpServer(serverId: string): Promise<boolean>;
     listPolicies(): Promise<AccountPolicy[]>;
     createPolicy(input: {
         name: string;
@@ -1563,6 +1682,23 @@ 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. */
+    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;
+        projectId?: string;
+        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. */
+    updateRole(roleId: string, patch: {
+        name?: string;
+        policy?: PolicyDocument;
+        status?: "active" | "disabled";
+    }): Promise<AccountRole | null>;
+    deleteRole(roleId: string): Promise<boolean>;
     listChannels(): Promise<AccountChannel[]>;
     /** Bind one real chat channel to an agent. One active record per place. */
     createChannel(input: {
@@ -1722,7 +1858,7 @@ interface BroodsConfigDefinition {
     readonly [CONFIG_MARKER]: true;
     readonly config: BroodsProjectConfig;
 }
-type ResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "policy" | "channelRecord";
+type ResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "mcp" | "policy" | "channelRecord";
 interface ResourceDefinition<Kind extends ResourceKind, Name extends string, Config> {
     readonly [RESOURCE_MARKER]: true;
     readonly kind: Kind;
@@ -1738,14 +1874,24 @@ type ResourceInput<Name extends string, Config> = {
     name: Name;
     description?: string;
 } & Config;
+/**
+ * Provider-specific sandbox knobs. `reservationKey` names the reserved machine a
+ * `persistent` sandbox reconnects to when no workspace is mounted; unset, each
+ * agent gets its own, and pinning one string on two sandboxes shares a machine.
+ * Keys are scoped to the account, so they cannot reach another account's machine.
+ */
+type SandboxDefinitionOptions = Record<string, unknown> & {
+    reservationKey?: string;
+};
 /**
  * Code-first sandbox config surface. Mirrors core's `SandboxConfig` but lets
  * `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.
  */
-type SandboxDefinitionConfig = Omit<SandboxConfig, "envVars"> & {
+type SandboxDefinitionConfig = Omit<SandboxConfig, "envVars" | "options"> & {
     envVars?: Record<string, string | EnvRef | undefined>;
+    options?: SandboxDefinitionOptions;
 };
 type HarnessType = NonNullable<AgentConfig["harness"]>["type"];
 type HarnessDefinition = Omit<NonNullable<AgentConfig["harness"]>, "type"> & {
@@ -1805,6 +1951,33 @@ interface ToolDefinitionConfig<Input = Record<string, unknown>> {
 type PolicyDefinitionConfig = Omit<PolicyDocument, "version"> & {
     version?: PolicyDocument["version"];
 };
+/**
+ * MCP server registration (#331) — external (`url`) or hosted (`path`).
+ * Either way the server's tools are offered as `<name>__<tool>`; an external
+ * row is dialed over the stateless HTTP transport (spec 2026-07-28) at agent
+ * registration time. The name namespaces those tools, so it must be 1-32
+ * lowercase letters, digits, or hyphens, starting with a letter.
+ */
+interface McpServerDefinitionConfig {
+    /** External server's MCP endpoint; http(s), no embedded credentials. */
+    url?: string;
+    /**
+     * Hosted alternative to `url`: a module (resolved from the `broods/`
+     * directory) whose default export is a fetch-style MCP handler —
+     * `export default createMcpHandler(...)` from @modelcontextprotocol/server.
+     * The CLI bundles it and the tool-runner Lambda hosts it, one invoke per
+     * request.
+     */
+    path?: string;
+    /**
+     * Extra request headers. Credential-bearing headers (Authorization,
+     * X-Api-Key, ...) must reference an account env var — e.g.
+     * `Bearer ${env("TOKEN")}` — never carry an inline secret.
+     */
+    headers?: Record<string, string>;
+    /** Tool names agents may use from this server; omit to allow all. */
+    allowedTools?: string[];
+}
 type ChannelType = "telegram" | "github" | "slack" | "discord" | "pancake" | "zalo";
 /**
  * A connection is one app install: the credentials an agent needs before a
@@ -2106,7 +2279,7 @@ interface ProviderSettingsInput {
 }
 /** Per-provider settings; provider names stay synced with core's `AgentConfig`. */
 type ProviderConfigInput = Partial<Record<keyof NonNullable<AgentConfig["provider"]>, ProviderSettingsInput>>;
-type AgentDefinitionConfig = EnvRefString<Pick<AgentConfig, "agent" | "model" | "scheduler" | "session" | "tools">> & {
+type AgentDefinitionConfig = EnvRefString<Pick<AgentConfig, "agent" | "model" | "scheduler" | "session" | "tools" | "mcpServers">> & {
     provider?: ProviderConfigInput;
 } & {
     harness?: HarnessDefinition;
@@ -2145,10 +2318,11 @@ type WorkspaceResource<Name extends string = string> = ResourceDefinition<"works
 type SandboxResource<Name extends string = string> = ResourceDefinition<"sandbox", Name, SandboxDefinitionConfig>;
 type SkillResource<Name extends string = string> = ResourceDefinition<"skill", Name, SkillDefinitionConfig>;
 type ToolResource<Name extends string = string> = ResourceDefinition<"tool", Name, ToolDefinitionConfig>;
+type McpServerResource<Name extends string = string> = ResourceDefinition<"mcp", Name, McpServerDefinitionConfig>;
 type PolicyResource<Name extends string = string> = ResourceDefinition<"policy", Name, PolicyDefinitionConfig>;
 type CronResource<Name extends string = string> = ResourceDefinition<"cron", Name, CronDefinitionConfig>;
 type ChannelResource<Name extends string = string> = ResourceDefinition<"channelRecord", Name, ChannelDefinitionConfig>;
-type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronResource | SkillResource | ToolResource | PolicyResource | ChannelResource;
+type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronResource | SkillResource | ToolResource | McpServerResource | PolicyResource | ChannelResource;
 /**
  * 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
@@ -2188,11 +2362,12 @@ declare function defineSkill<const Name extends string>(input: ResourceInput<Nam
 declare function defineTool<const Name extends string, Input = Record<string, unknown>>(input: {
     name: Name;
 } & ToolDefinitionConfig<Input>): ToolResource<Name>;
+declare function defineMcp<const Name extends string>(input: ResourceInput<Name, McpServerDefinitionConfig>): McpServerResource<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 isConnectionDefinition(value: unknown): value is AnyConnectionDefinition;
 declare function isBroodsConfig(value: unknown): value is BroodsConfigDefinition;
 
-export { BroodsAccountApiError, BroodsAccountClient, BroodsClient, BroodsWebSocketClient, DEFAULT_CORE_BASE_URL, IngressAcceptedError, MAX_OBSERVABILITY_BACKFILL, BroodsWebSocketClient as WebSocketClient, BroodsWebSocketClient as WebsocketClient, defineAgent, defineBroods, defineCron, defineDiscordChannel, defineDiscordConnection, defineGitHubChannel, defineGitHubConnection, defineHarness, definePancakeChannel, definePancakeConnection, definePolicy, defineSandbox, defineSkill, defineSlackChannel, defineSlackConnection, defineTelegramChannel, defineTelegramConnection, defineTool, defineWorkspace, defineZaloChannel, defineZaloConnection, env, envPlaceholder, isBroodsConfig, isConnectionDefinition, isLogLevel, isObservabilityClientMessage, isResource, isRootSpanKind, normalizeHttpServiceUrl, readSseStream, resolveRunEvents, toWebSocketBaseUrl };
-export type { Account, AccountAgent, AccountChannel, AccountEnvVar, AccountPolicy, AccountSandbox, AccountTool, AccountWorkspace, Agent, AgentChannelsConfig, AgentCodeHookConfig, AgentConfig, AgentConfigDoc, AgentDefinitionConfig, AgentDiscordChannelConfig, AgentGitHubChannelConfig, AgentHandle, AgentHookEventName, AgentHooks, AgentHooksConfig, AgentPancakeChannelConfig, AgentProviderSettings, AgentReference, AgentResource, AgentRunEventInput, AgentRunInput, AgentRunModelOverrides, AgentRunOverrides, AgentRunResult, AgentSkillsDefinitionConfig, AgentSlackChannelConfig, AgentStreamPart, AgentSubagentDefinitionConfig, AgentTelegramChannelConfig, AgentWebhookHookConfig, AgentWorkspaceInput, AgentWorkspaceRef, AgentWorkspaceRefInput, AgentZaloChannelConfig, AnyConnectionDefinition, AnyResource, AsyncAgentRun, AsyncPollOptions, AsyncRequestAccepted, AsyncStatus, BroodsAccount, BroodsAccountClientOptions, BroodsClientOptions, BroodsConfigDefinition, BroodsProjectConfig, BroodsWebSocketClientOptions, ChannelAgentInput, ChannelDefinitionConfig, ChannelMessageReceived, ChannelPartition, ChannelRecordConfig, ChannelReference, ChannelReplyIn, ChannelResource, ChannelType, CliManifest, CliManifestResource, CliResourceKind, ConnectionDefinition, CreateAgentResult, CreateClientCronInput, CreateCronInput, CreateToolInput, Cron, CronDefinitionConfig, CronDoc, CronLastStatus, CronResource, CronRun, CronStatus, CustomTool, DeleteAccountResult, DiscordChannelInput, DiscordConnectionDefinition, DiscordConnectionInput, DiscordMessageSource, DiscordSource, Doc, EnvAccessor, EnvRef, EnvRefString, GeneratedIds, GitHubChannelInput, GitHubConnectionDefinition, GitHubConnectionInput, GitHubMessageSource, GitHubSource, HarnessDefinition, HarnessType, HookContext, Id, IngressMode, IngressStatus, LogLevel, ObservabilityBackfillMessage, ObservabilityClientMessage, ObservabilityErrorMessage, ObservabilityLogEntry, ObservabilityLogMessage, ObservabilityReadyMessage, ObservabilityServerMessage, ObservabilitySpanMessage, ObservabilitySpanRow, ObservabilitySubscribeMessage, ObservabilityUnsubscribeMessage, PancakeChannelInput, PancakeConnectionDefinition, PancakeConnectionInput, PancakeMessageSource, PancakeSource, PolicyDefinitionConfig, PolicyDocument, PolicyResource, ProjectDoc, ProviderConfigInput, ProviderSettingsInput, ResourceApi, ResourceDefinition, ResourceInput, ResourceKind, RotateSecretResult, Sandbox, SandboxConfig, SandboxConfigDoc, SandboxDefinitionConfig, SandboxLifecycleResult, SandboxResource, SandboxSnapshotResult, SandboxTerminalTicket, Skill, SkillDefinitionConfig, SkillResource, SkillUploadInput, SlackChannelInput, SlackConnectionDefinition, SlackConnectionInput, SlackMessageSource, SlackSource, StageDoc, TelegramChannelInput, TelegramConnectionDefinition, TelegramConnectionInput, TelegramMessageSource, TelegramSource, ToolApprovalSummary, ToolDefinitionConfig, ToolExecuteContext, ToolExecuteOptions, ToolResource, ToolScope, UpdateAgentInput, UpdateCronInput, UpdateToolInput, WebSocketAttachInput, WebSocketClientAttachMessage, WebSocketClientCancelMessage, WebSocketClientControlMessage, WebSocketClientExecuteMessage, WebSocketClientMessage, WebSocketConstructorLike, WebSocketHandlers, WebSocketLike, WebSocketOutputMessage, WebSocketRunInput, WebSocketServerMessage, WebSocketStreamMessage, WebSocketSubscription, Workspace, WorkspaceConfig, WorkspaceConfigDoc, WorkspaceDefinitionConfig, WorkspaceFileEntry, WorkspaceResource, ZaloChannelInput, ZaloConnectionDefinition, ZaloConnectionInput, 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, defineDiscordConnection, defineGitHubChannel, defineGitHubConnection, defineHarness, defineMcp, definePancakeChannel, definePancakeConnection, definePolicy, defineSandbox, defineSkill, defineSlackChannel, defineSlackConnection, defineTelegramChannel, defineTelegramConnection, defineTool, defineWorkspace, defineZaloChannel, defineZaloConnection, env, envPlaceholder, isBroodsConfig, isConnectionDefinition, isLogLevel, isObservabilityClientMessage, isResource, isRootSpanKind, normalizeHttpServiceUrl, readSseStream, resolveRunEvents, toWebSocketBaseUrl };
+export type { Account, AccountAgent, AccountChannel, AccountEnvVar, AccountMcpServer, AccountPolicy, AccountRole, AccountSandbox, AccountTool, AccountWorkspace, Agent, AgentChannelsConfig, AgentCodeHookConfig, AgentConfig, AgentConfigDoc, AgentDefinitionConfig, AgentDiscordChannelConfig, AgentGitHubChannelConfig, AgentHandle, AgentHookEventName, AgentHooks, AgentHooksConfig, AgentPancakeChannelConfig, AgentProviderSettings, AgentReference, AgentResource, AgentRunEventInput, AgentRunInput, AgentRunModelOverrides, AgentRunOverrides, AgentRunResult, AgentSkillsDefinitionConfig, AgentSlackChannelConfig, AgentStreamPart, AgentSubagentDefinitionConfig, AgentTelegramChannelConfig, AgentWebhookHookConfig, AgentWorkspaceInput, AgentWorkspaceRef, AgentWorkspaceRefInput, AgentZaloChannelConfig, AnyConnectionDefinition, AnyResource, AssumeRoleResult, AsyncAgentRun, AsyncPollOptions, AsyncRequestAccepted, AsyncStatus, BroodsAccount, BroodsAccountClientOptions, BroodsClientOptions, BroodsConfigDefinition, BroodsProjectConfig, BroodsWebSocketClientOptions, ChannelAgentInput, ChannelDefinitionConfig, ChannelMessageReceived, ChannelPartition, ChannelRecordConfig, ChannelReference, ChannelReplyIn, ChannelResource, ChannelType, CliManifest, CliManifestResource, CliResourceKind, ConnectionDefinition, CreateAgentResult, CreateClientCronInput, CreateCronInput, CreateMcpServerInput, CreateToolInput, Cron, CronDefinitionConfig, CronDoc, CronLastStatus, CronResource, CronRun, CronStatus, CustomTool, DeleteAccountResult, DiscordChannelInput, DiscordConnectionDefinition, DiscordConnectionInput, DiscordMessageSource, DiscordSource, Doc, EnvAccessor, EnvRef, EnvRefString, GeneratedIds, GitHubChannelInput, GitHubConnectionDefinition, GitHubConnectionInput, GitHubMessageSource, GitHubSource, HarnessDefinition, HarnessType, HookContext, Id, IngressMode, IngressStatus, LogLevel, McpServerDefinitionConfig, McpServerResource, ObservabilityBackfillMessage, ObservabilityClientMessage, ObservabilityErrorMessage, ObservabilityLogEntry, ObservabilityLogMessage, ObservabilityReadyMessage, ObservabilityServerMessage, ObservabilitySpanMessage, ObservabilitySpanRow, ObservabilitySubscribeMessage, ObservabilityUnsubscribeMessage, PancakeChannelInput, PancakeConnectionDefinition, PancakeConnectionInput, PancakeMessageSource, PancakeSource, PolicyDefinitionConfig, PolicyDocument, PolicyResource, ProjectDoc, ProviderConfigInput, ProviderSettingsInput, ResourceApi, ResourceDefinition, ResourceInput, ResourceKind, RotateSecretResult, Sandbox, SandboxConfig, SandboxConfigDoc, SandboxDefinitionConfig, SandboxDefinitionOptions, SandboxLifecycleResult, SandboxResource, SandboxSnapshotResult, SandboxTerminalTicket, Skill, SkillDefinitionConfig, SkillResource, SkillUploadInput, SlackChannelInput, SlackConnectionDefinition, SlackConnectionInput, SlackMessageSource, SlackSource, StageDoc, TelegramChannelInput, TelegramConnectionDefinition, TelegramConnectionInput, TelegramMessageSource, TelegramSource, ToolApprovalSummary, ToolDefinitionConfig, ToolExecuteContext, ToolExecuteOptions, ToolResource, ToolScope, UpdateAgentInput, UpdateCronInput, UpdateMcpServerInput, UpdateToolInput, WebSocketAttachInput, WebSocketClientAttachMessage, WebSocketClientCancelMessage, WebSocketClientControlMessage, WebSocketClientExecuteMessage, WebSocketClientMessage, WebSocketConstructorLike, WebSocketHandlers, WebSocketLike, WebSocketOutputMessage, WebSocketRunInput, WebSocketServerMessage, WebSocketStreamMessage, WebSocketSubscription, Workspace, WorkspaceConfig, WorkspaceConfigDoc, WorkspaceDefinitionConfig, WorkspaceFileEntry, WorkspaceResource, ZaloChannelInput, ZaloConnectionDefinition, ZaloConnectionInput, ZaloMessageSource, ZaloSource };

package/dist/index.js

@@ -1 +1 @@
-import{S,r,y}from"./chunk-vyvy543y.js";import{p,b,c,x,d,m,_,g,T,k,E,C,R,A,M,P,O,N,D,j,z,U,L,Z,F,B,W,q,K,V,t,i,v}from"./chunk-t6xktzr3.js";var u=500;function f(e){if(typeof e!=="object"||e===null)return!1;let n=e;if(n.type==="subscribe"){let s=n.stream;if(s!=="logs"&&s!=="traces")return!1;let o=n.backfill;if(o!==void 0&&(typeof o!=="number"||!Number.isSafeInteger(o)||o<0||o>500))return!1;if(n.liveOnly!==void 0&&typeof n.liveOnly!=="boolean")return!1;let a=n.minLevel;if(a!==void 0&&!l(a))return!1;return!0}if(n.type==="unsubscribe"){let s=n.stream;return s==="logs"||s==="traces"}return!1}function l(e){return e==="DEBUG"||e==="INFO"||e==="WARN"||e==="ERROR"}function I(e){return e==="task"||e==="cron"||e==="subtask"}export{r as BroodsAccountApiError,y as BroodsAccountClient,d as BroodsClient,_ as BroodsWebSocketClient,c as DEFAULT_CORE_BASE_URL,x as IngressAcceptedError,u as MAX_OBSERVABILITY_BACKFILL,_ as WebSocketClient,_ as WebsocketClient,L as defineAgent,U as defineBroods,V as defineCron,P as defineDiscordChannel,k as defineDiscordConnection,O as defineGitHubChannel,E as defineGitHubConnection,Z as defineHarness,N as definePancakeChannel,C as definePancakeConnection,K as definePolicy,B as defineSandbox,W as defineSkill,D as defineSlackChannel,R as defineSlackConnection,j as defineTelegramChannel,A as defineTelegramConnection,q as defineTool,F as defineWorkspace,z as defineZaloChannel,M as defineZaloConnection,T as env,S as envPlaceholder,v as isBroodsConfig,i as isConnectionDefinition,l as isLogLevel,f as isObservabilityClientMessage,t as isResource,I as isRootSpanKind,m as normalizeHttpServiceUrl,b as readSseStream,p as resolveRunEvents,g as toWebSocketBaseUrl};
+import{a as O,b as R,c as L}from"./chunk-36yhe6qb.js";import{A as _,B as P,C as U,D as B,E as H,F as K,G as j,H as G,I as F,J as z,K as Z,L as V,M as X,N as Y,O as J,P as Q,Q as ee,R as te,S as re,T as ne,U as se,d as v,e as k,p as S,q as A,r as M,s as h,t as w,u as W,v as E,w as D,x as T,y as q,z as N}from"./chunk-rwpj4428.js";import"./chunk-4sdsq7gb.js";var a=500;function i(e){if(typeof e!=="object"||e===null)return!1;let t=e;if(t.type==="subscribe"){let r=t.stream;if(r!=="logs"&&r!=="traces")return!1;let n=t.backfill;if(n!==void 0&&(typeof n!=="number"||!Number.isSafeInteger(n)||n<0||n>500))return!1;if(t.liveOnly!==void 0&&typeof t.liveOnly!=="boolean")return!1;let s=t.minLevel;if(s!==void 0&&!o(s))return!1;return!0}if(t.type==="unsubscribe"){let r=t.stream;return r==="logs"||r==="traces"}return!1}function o(e){return e==="DEBUG"||e==="INFO"||e==="WARN"||e==="ERROR"}function p(e){return e==="task"||e==="cron"||e==="subtask"}export{R as BroodsAccountApiError,L as BroodsAccountClient,M as BroodsClient,w as BroodsWebSocketClient,S as DEFAULT_CORE_BASE_URL,A as IngressAcceptedError,a as MAX_OBSERVABILITY_BACKFILL,w as WebSocketClient,w as WebsocketClient,z as defineAgent,F as defineBroods,te as defineCron,U as defineDiscordChannel,D as defineDiscordConnection,B as defineGitHubChannel,T as defineGitHubConnection,Z as defineHarness,Q as defineMcp,H as definePancakeChannel,q as definePancakeConnection,ee as definePolicy,X as defineSandbox,Y as defineSkill,K as defineSlackChannel,N as defineSlackConnection,j as defineTelegramChannel,_ as defineTelegramConnection,J as defineTool,V as defineWorkspace,G as defineZaloChannel,P as defineZaloConnection,E as env,O as envPlaceholder,se as isBroodsConfig,ne as isConnectionDefinition,o as isLogLevel,i as isObservabilityClientMessage,re as isResource,p as isRootSpanKind,h as normalizeHttpServiceUrl,k as readSseStream,v as resolveRunEvents,W as toWebSocketBaseUrl};