broods 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,24 +1,47 @@
-import { SystemModelMessage, CallSettings, streamText, JSONSchema7, ModelMessage, TextStreamPart, ToolSet } from 'ai';
+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';
 
 /**
- * Shared channel streaming driver.
- * Turns the agent's streamed output into incremental channel updates so a chat
- * reply appears live instead of only after the whole turn. Three modes:
- *  - "edit": post one placeholder message, then edit it in place on a throttled
- *    cadence (needs the channel's beginMessage/editMessage primitives); when the
- *    reply outgrows the channel's message-length cap the current message is frozen
- *    and streaming continues in a fresh one (rotation).
- *  - "progress": one live preview for the whole turn (openclaw's progress draft).
- *    While the model works it shows a compact status (💭 reasoning + 🛠 tool lines);
- *    when the answer starts streaming the text takes over the same message; finish()
- *    finalizes that one message in place. One message per turn — never per-block.
- *  - "chunk": send a new message as each paragraph completes (uses sendText, so it
- *    works for every channel).
- * Accumulation + throttling live here so each channel adapter stays thin; a channel
- * that cannot edit a posted message falls back to "chunk" for edit/progress modes.
+ * Agent policy contracts and validation.
+ * Runtime decisions are made by OPA using the same document/input shape.
  */
-
-type ChannelStreamMode = "edit" | "chunk" | "progress";
+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.
@@ -31,6 +54,7 @@ declare const ACCOUNT_MODEL_PROVIDERS: {
     readonly bedrock: true;
     readonly gateway: true;
     readonly minimax: true;
+    readonly custom: true;
 };
 type AccountModelProviderName = keyof typeof ACCOUNT_MODEL_PROVIDERS;
 
@@ -52,6 +76,7 @@ interface AgentConfig {
     tools?: AgentToolsConfig;
     skills?: AgentSkillsConfig;
     subagent?: AgentSubagentConfig;
+    policy?: AgentPolicyConfig;
     publicAccess?: boolean;
     [key: string]: unknown;
 }
@@ -72,9 +97,16 @@ interface AgentSubagentConfig {
     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 Omit<CallSettings, "abortSignal" | "headers"> {
+interface AgentModelConfig extends LanguageModelCallOptions, Pick<RequestOptions, "maxRetries" | "timeout"> {
     provider?: AccountModelProviderName;
     modelId?: string;
     providerOptions?: AgentModelProviderOptions;
@@ -125,6 +157,23 @@ interface AgentSessionCompactionConfig {
 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 {
@@ -135,6 +184,8 @@ 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;
@@ -152,54 +203,83 @@ interface AgentChannelsConfig {
     zalo?: AgentZaloChannelConfig;
     [key: string]: unknown;
 }
-type AgentChannelStreamingMode = ChannelStreamMode | "off";
-interface AgentChannelStreamingConfig {
-    mode?: AgentChannelStreamingMode;
-    [key: string]: unknown;
-}
+type AgentChannelWorkspaceScope = {
+    level: "channel";
+    alias?: never;
+} | {
+    level: "conversation";
+    alias: string;
+};
 interface AgentTelegramChannelConfig {
-    botToken?: string;
-    webhookSecret?: string;
+    id?: string;
+    apiUrl?: TelegramAdapterConfig["apiUrl"];
+    botToken?: TelegramAdapterConfig["botToken"];
+    webhookSecret?: TelegramAdapterConfig["secretToken"];
     allowedChatIds?: number[];
     reactionEmoji?: string;
-    streaming?: AgentChannelStreamingConfig;
+    workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
 }
 interface AgentGitHubChannelConfig {
-    webhookSecret?: string;
-    appId?: string;
-    privateKey?: string;
+    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?: string;
+    signingSecret?: SlackAdapterConfig["signingSecret"];
     allowedChannelIds?: string[];
-    streaming?: AgentChannelStreamingConfig;
+    reactionEmoji?: string;
+    workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
 }
 interface AgentDiscordChannelConfig {
-    botToken?: string;
-    publicKey?: string;
+    id?: string;
+    apiUrl?: DiscordAdapterConfig["apiUrl"];
+    botToken?: DiscordAdapterConfig["botToken"];
+    publicKey?: DiscordAdapterConfig["publicKey"];
     allowedGuildIds?: string[];
-    streaming?: AgentChannelStreamingConfig;
+    workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
 }
 interface AgentPancakeChannelConfig {
+    id?: string;
     pageId?: string;
     pageAccessToken?: string;
     webhookSecret?: string;
     senderId?: string;
-    options?: Record<string, unknown>;
-    streaming?: AgentChannelStreamingConfig;
+    workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
 }
 interface AgentZaloChannelConfig {
+    id?: string;
     botToken?: string;
     webhookSecret?: string;
     allowedUserIds?: string[];
-    streaming?: AgentChannelStreamingConfig;
+    workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
 }
 
@@ -248,6 +328,21 @@ type UpdateCronInput = {
     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
@@ -256,7 +351,8 @@ type UpdateCronInput = {
  * DynamoDB / Convex stores call these at their create/update entry points.
  * Stored encrypted at rest because `envVars`/`options` may hold secrets.
  */
-type SandboxProvider = "lambda" | "e2b" | "daytona" | "kubernetes" | "vercel";
+
+type SandboxProvider = "sandbox" | "lambda" | "e2b" | "daytona" | "vercel";
 type SandboxRuntimeName = "bash" | "python" | "node";
 type SandboxPermissionMode = "edit" | "ask" | "bypass";
 type SandboxNetworkMode = "allow-all" | "deny-all" | "restricted";
@@ -271,11 +367,12 @@ interface SandboxNetworkConfig {
 }
 interface SandboxConfig {
     provider: SandboxProvider;
+    size?: SandboxSize;
+    snapshot?: string;
     runtimes?: SandboxRuntimeName[];
     network?: SandboxNetworkConfig;
     permissionMode?: SandboxPermissionMode;
     persistent?: boolean;
-    ephemeralHome?: boolean;
     lifecycle?: SandboxLifecycleConfig;
     onCreate?: string[];
     onResume?: string[];
@@ -296,15 +393,127 @@ interface SandboxConfig {
  */
 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: {
-        provider: WorkspaceStorageProvider;
-    };
+    storage: WorkspaceStorageConfig;
+    isolation?: boolean;
     harness?: {
         enabled?: boolean;
     };
 }
 
+/**
+ * Telegram channel adapter implementated as a ChannelAdapter.
+ * Implements Telegram auth, message normalization, and reply actions through the Chat SDK Telegram adapter.
+ */
+
+interface TelegramSource {
+    chatId: number;
+    messageId: string;
+    threadId: string;
+    fromUserId?: number;
+    fromUsername?: string;
+}
+
+/**
+ * GitHub channel adapter.
+ * Keep Broods-specific event filtering/source mapping here; delegate GitHub auth and API calls to Chat SDK.
+ */
+
+interface GitHubSource {
+    owner: string;
+    repo: string;
+    installationId: number;
+    threadId: string;
+    messageId?: string;
+    issueNumber?: number;
+    pullNumber?: number;
+    commentId?: number;
+    target: "issue" | "issue_comment" | "pull_request" | "pull_request_review_comment";
+}
+
+/**
+ * Slack channel adapter.
+ * Handle request verification, inbound normalization, and Slack Web API reply actions here.
+ */
+
+interface SlackSource {
+    teamId: string;
+    channelId: string;
+    threadTs?: string;
+    messageTs?: string;
+    responseUrl?: string;
+    commandToken?: string;
+    userId?: string;
+}
+
+/**
+ * Discord channel adapter.
+ * Verify interaction signatures, normalize slash commands, and send replies through Chat SDK's Discord adapter.
+ */
+
+interface DiscordSource {
+    applicationId: string;
+    interactionToken?: string;
+    interactionId?: string;
+    guildId?: string;
+    channelId?: string;
+    threadId?: string;
+    messageId?: string;
+    commandToken?: string;
+    userId?: string;
+}
+
+/**
+ * Pancake channel adapter.
+ * Keep Pancake webhook normalization and outbound message API calls here.
+ *
+ * Per-conversation policy (e.g. skipping human-owned conversations by tag) is
+ * not baked in: the parsed source carries `tagIds` so a user `onMessageReceived`
+ * hook can decide to drop the message.
+ */
+
+interface PancakeSource {
+    pageId: string;
+    conversationId: string;
+    messageId: string;
+    messageType: "INBOX" | "COMMENT";
+    postId?: string;
+    fromId?: string;
+    fromName?: string;
+    pageCustomerId?: string;
+    tagIds?: string[];
+}
+
+/**
+ * Zalo channel adapter.
+ * Keep official Zalo Bot API webhook normalization and outbound API calls here.
+ */
+
+interface ZaloSource {
+    chatId: string;
+    chatType: "PRIVATE";
+    messageId: string;
+    senderId: string;
+    senderName?: string;
+    eventName: string;
+    date?: number;
+}
+
 /**
  * Canonical CLI manifest wire types — the single source of truth shared by the
  * backend (cliSync.ts, cliHttp.ts) and the SDK/CLI (packages/broods).
@@ -313,7 +522,7 @@ interface WorkspaceConfig {
  * import it without pulling the Convex server module graph into its typecheck.
  */
 type CliManifestResource = {
-    kind: "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool";
+    kind: "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "hook" | "policy";
     name: string;
     description?: string;
     config: unknown;
@@ -325,6 +534,8 @@ type GeneratedIds = {
     crons: Record<string, string>;
     skills: Record<string, string>;
     tools: Record<string, string>;
+    hooks: Record<string, string>;
+    policies: Record<string, string>;
 };
 type CliManifest = {
     version: 1;
@@ -351,12 +562,12 @@ type AgentConfigDoc = Doc<"agentConfigs">;
 type WorkspaceConfigDoc = Doc<"workspaceConfigs">;
 type SandboxConfigDoc = Doc<"sandboxConfigs">;
 type CronDoc = Doc<"crons">;
-type CliResourceKind = "agent" | "workspace" | "sandbox" | "cron";
+type CliResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "policy";
 
 /**
  * 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 Lambda internals so
+ * of truth); they are intentionally independent of the runtime internals so
  * the SDK keeps working when the runtime is ported.
  */
 
@@ -443,10 +654,11 @@ interface CustomTool {
     name: string;
     description: string;
     sha256: string;
+    runtime?: "isolate" | "sandbox";
 }
 
 type StreamTextOptions = Parameters<typeof streamText>[0];
-type JsonCallSettings = Partial<Omit<CallSettings, "abortSignal" | "headers">>;
+type JsonCallSettings = Partial<LanguageModelCallOptions & Pick<RequestOptions, "maxRetries" | "timeout">>;
 type AgentRunModelOverrides = JsonCallSettings & Pick<StreamTextOptions, "providerOptions">;
 type AgentRunOverrides = {
     system?: SystemModelMessage | SystemModelMessage[];
@@ -542,6 +754,7 @@ type ObservabilitySubscribeMessage = {
     type: "subscribe";
     stream: "logs" | "traces";
     backfill?: number;
+    liveOnly?: boolean;
     minLevel?: LogLevel;
 };
 type ObservabilityUnsubscribeMessage = {
@@ -636,6 +849,7 @@ interface ResourceApi {
     readonly crons?: Record<string, unknown>;
     readonly skills?: Record<string, unknown>;
     readonly tools?: Record<string, unknown>;
+    readonly policies?: Record<string, unknown>;
 }
 interface BroodsClientOptions {
     /**
@@ -816,12 +1030,14 @@ interface BroodsProjectConfig {
         [name: string]: string | undefined;
     };
     dashboardUrl?: string;
+    /** Convex control-plane base URL for sync/env calls; defaults to the URL discovered at login. */
+    baseUrl?: string;
 }
 interface BroodsConfigDefinition {
     readonly [CONFIG_MARKER]: true;
     readonly config: BroodsProjectConfig;
 }
-type ResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool";
+type ResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool" | "policy";
 interface ResourceDefinition<Kind extends ResourceKind, Name extends string, Config> {
     readonly [RESOURCE_MARKER]: true;
     readonly kind: Kind;
@@ -858,65 +1074,45 @@ interface ToolDefinitionConfig {
     path: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    runtime?: "isolate" | "sandbox";
     defaultConfig?: Record<string, unknown>;
 }
+type PolicyDefinitionConfig = Omit<AgentPolicyDocument, "version"> & {
+    version?: AgentPolicyDocument["version"];
+};
 type ChannelType = "telegram" | "github" | "slack" | "discord" | "pancake" | "zalo";
 interface ChannelDefinition<Type extends ChannelType, Config> {
     readonly [CHANNEL_MARKER]: true;
     readonly kind: "channel";
     readonly type: Type;
+    readonly workspaceScope?: AgentChannelWorkspaceScope;
     readonly config: Config;
 }
+type RequiredChannelKeys<Config, Keys extends keyof Config> = Required<Pick<Config, Keys>> & Omit<Config, Keys>;
 type ChannelSecret = string | EnvRef | undefined;
-interface TelegramChannelInput {
-    botToken: ChannelSecret;
-    webhookSecret: ChannelSecret;
-    allowedChatIds: readonly number[];
-    reactionEmoji?: string | EnvRef;
-    streaming?: EnvRefString<NonNullable<AgentTelegramChannelConfig["streaming"]>>;
-}
-interface GitHubChannelInput {
-    webhookSecret: ChannelSecret;
-    appId: ChannelSecret;
-    privateKey: ChannelSecret;
-    allowedRepos?: readonly (string | EnvRef)[];
-}
-interface SlackChannelInput {
-    botToken: ChannelSecret;
-    signingSecret: ChannelSecret;
-    allowedChannelIds?: readonly (string | EnvRef)[];
-    streaming?: EnvRefString<NonNullable<AgentSlackChannelConfig["streaming"]>>;
-}
-interface DiscordChannelInput {
-    botToken: ChannelSecret;
-    publicKey: ChannelSecret;
-    allowedGuildIds?: readonly (string | EnvRef)[];
-    streaming?: EnvRefString<NonNullable<AgentDiscordChannelConfig["streaming"]>>;
-}
-interface PancakeChannelInput {
+type ChannelIdentityInput = {
+    workspaceScope?: AgentChannelWorkspaceScope;
+};
+type TelegramChannelInput = EnvRefString<RequiredChannelKeys<Pick<AgentTelegramChannelConfig, "apiUrl" | "botToken" | "webhookSecret" | "allowedChatIds" | "reactionEmoji">, "botToken" | "webhookSecret" | "allowedChatIds">> & ChannelIdentityInput;
+type GitHubChannelInput = EnvRefString<RequiredChannelKeys<Pick<AgentGitHubChannelConfig, "apiUrl" | "webhookSecret" | "appId" | "privateKey" | "allowedRepos" | "userName" | "botUserId" | "triggerOnIssueOpen" | "triggerOnPROpen">, "webhookSecret" | "appId" | "privateKey">> & ChannelIdentityInput;
+type SlackChannelInput = EnvRefString<RequiredChannelKeys<Pick<AgentSlackChannelConfig, "apiUrl" | "botToken" | "signingSecret" | "allowedChannelIds" | "reactionEmoji">, "botToken" | "signingSecret">> & ChannelIdentityInput;
+type DiscordChannelInput = EnvRefString<RequiredChannelKeys<Pick<AgentDiscordChannelConfig, "apiUrl" | "botToken" | "publicKey" | "allowedGuildIds">, "botToken" | "publicKey">> & ChannelIdentityInput;
+interface PancakeChannelInput extends ChannelIdentityInput {
     pageId: ChannelSecret;
     pageAccessToken: ChannelSecret;
     webhookSecret: ChannelSecret;
     senderId?: string | EnvRef;
-    ignoreTagIds?: readonly (string | EnvRef)[];
-    streaming?: EnvRefString<NonNullable<AgentPancakeChannelConfig["streaming"]>>;
 }
-type PancakeChannelDefinitionConfig = Omit<PancakeChannelInput, "ignoreTagIds"> & {
-    options?: {
-        ignoreTagIds?: readonly (string | EnvRef)[];
-    };
-};
-interface ZaloChannelInput {
+interface ZaloChannelInput extends ChannelIdentityInput {
     botToken: ChannelSecret;
     webhookSecret: ChannelSecret;
     allowedUserIds: readonly (string | EnvRef)[];
-    streaming?: EnvRefString<NonNullable<AgentZaloChannelConfig["streaming"]>>;
 }
 type TelegramChannelDefinition = ChannelDefinition<"telegram", TelegramChannelInput>;
 type GitHubChannelDefinition = ChannelDefinition<"github", GitHubChannelInput>;
 type SlackChannelDefinition = ChannelDefinition<"slack", SlackChannelInput>;
 type DiscordChannelDefinition = ChannelDefinition<"discord", DiscordChannelInput>;
-type PancakeChannelDefinition = ChannelDefinition<"pancake", PancakeChannelDefinitionConfig>;
+type PancakeChannelDefinition = ChannelDefinition<"pancake", PancakeChannelInput>;
 type ZaloChannelDefinition = ChannelDefinition<"zalo", ZaloChannelInput>;
 type AnyChannelDefinition = TelegramChannelDefinition | GitHubChannelDefinition | SlackChannelDefinition | DiscordChannelDefinition | PancakeChannelDefinition | ZaloChannelDefinition;
 /**
@@ -941,6 +1137,133 @@ type AgentSubagentDefinitionConfig = Omit<NonNullable<AgentConfig["subagent"]>,
 type AgentSkillsDefinitionConfig = Omit<NonNullable<AgentConfig["skills"]>, "allowed"> & {
     allowed?: readonly (SkillResource | string)[];
 };
+interface HookContext {
+    fetch: typeof fetch;
+    config: Record<string, unknown>;
+    /**
+     * Mutable per-request scratchpad shared across this agent request's hooks.
+     * Seed it in an early hook (e.g. `onStart`) and read or modify it later —
+     * every loop hook, `onSubagentFinish`, and the reply's `onMessageSending`
+     * see the same state. Keep it JSON-serializable. `onMessageReceived`,
+     * delayed background replies, and each subagent's own run get fresh state.
+     */
+    state: Record<string, unknown>;
+}
+type Handler<Event, Result> = (ctx: HookContext, event: Event) => Result | void | Promise<Result | void>;
+/**
+ * Channel-specific routing data attached to an inbound message. Inherited from
+ * the core channel adapters (via contracts.ts) so an `onMessageReceived` hook
+ * that narrows on `event.channel` always sees exactly what core emits (e.g.
+ * Pancake `tagIds`).
+ */
+type TelegramMessageSource = TelegramSource;
+type GitHubMessageSource = GitHubSource;
+type SlackMessageSource = SlackSource;
+type DiscordMessageSource = DiscordSource;
+type PancakeMessageSource = PancakeSource;
+type ZaloMessageSource = ZaloSource;
+/**
+ * Inbound channel message passed to `onMessageReceived`, discriminated on
+ * `channel` so each variant exposes its channel's strongly-typed `source`.
+ */
+type ChannelMessageReceived = {
+    channel: "telegram";
+    text: string;
+    source: TelegramMessageSource;
+} | {
+    channel: "github";
+    text: string;
+    source: GitHubMessageSource;
+} | {
+    channel: "slack";
+    text: string;
+    source: SlackMessageSource;
+} | {
+    channel: "discord";
+    text: string;
+    source: DiscordMessageSource;
+} | {
+    channel: "pancake";
+    text: string;
+    source: PancakeMessageSource;
+} | {
+    channel: "zalo";
+    text: string;
+    source: ZaloMessageSource;
+};
+/**
+ * Inline agent hook callbacks. Handlers are serialized with `.toString()`,
+ * bundled into one account hook, and run in a fresh V8 isolate. Keep them
+ * self-contained: use only `ctx`, `event`, and JavaScript globals. Do not rely
+ * on imports or closure variables. Arrow functions and function expressions are
+ * preferred so the serialized source is valid as an object-literal value.
+ *
+ * Subagent runs fire hooks too: a registered subagent runs its own hooks, a
+ * prompt-only (virtual) subagent inherits this bundle — always with fresh
+ * `ctx.state`. `onSubagentFinish` fires on the parent with the parent's state.
+ */
+interface AgentHooks {
+    onStart?: Handler<{
+        system: string;
+        messages: unknown[];
+    }, {
+        system?: string;
+        messages?: unknown[];
+    }>;
+    onStepFinish?: Handler<{
+        stepNumber: number;
+        finishReason: string;
+        toolCallCount: number;
+    }, void>;
+    onToolCall?: Handler<{
+        toolName: string;
+        input: unknown;
+    }, {
+        decision?: "allow" | "deny";
+        args?: Record<string, unknown>;
+        denyReason?: string;
+    }>;
+    onToolResult?: Handler<{
+        toolName: string;
+        output: unknown;
+    }, {
+        output?: unknown;
+    }>;
+    onFinish?: Handler<{
+        finishReason: string;
+        response: unknown;
+    }, {
+        output?: unknown;
+    }>;
+    onApproval?: Handler<{
+        approvals: unknown;
+    }, {
+        approve?: boolean;
+    }>;
+    onError?: Handler<{
+        error: string;
+    }, void>;
+    onSubagentFinish?: Handler<{
+        taskId: string;
+        result: unknown;
+    }, {
+        visibleResult?: unknown;
+    }>;
+    onMessageReceived?: Handler<ChannelMessageReceived, {
+        drop?: boolean;
+        text?: string;
+    }>;
+    onMessageSending?: Handler<{
+        channel: ChannelType;
+        text: string;
+    }, {
+        drop?: boolean;
+        text?: string;
+    }>;
+}
+type AgentPolicyDefinitionConfig = Omit<AgentPolicyConfig, "policyIds"> & {
+    policies?: readonly (PolicyResource | string)[];
+};
 /**
  * Code-first agent config surface. Built from an explicit `Pick` of `AgentConfig`
  * (not `Omit`) so the SDK input type does NOT inherit `AgentConfig`'s
@@ -949,12 +1272,16 @@ type AgentSkillsDefinitionConfig = Omit<NonNullable<AgentConfig["skills"]>, "all
  * `workspace:` instead of `workspaces:`. Add a key here when core's `AgentConfig`
  * gains a new top-level field that should be code-definable.
  */
-type AgentDefinitionConfig = EnvRefString<Pick<AgentConfig, "agent" | "model" | "provider" | "session" | "hooks" | "tools">> & {
+type AgentDefinitionConfig = EnvRefString<Pick<AgentConfig, "agent" | "model" | "provider" | "session" | "tools">> & {
+    hooks?: AgentHooks & {
+        webhooks?: readonly EnvRefString<AgentWebhookHookConfig>[];
+    };
     channels?: readonly AnyChannelDefinition[];
     sandbox?: SandboxResource | string;
     workspaces?: readonly AgentWorkspaceInput[];
     subagent?: AgentSubagentDefinitionConfig;
     skills?: AgentSkillsDefinitionConfig;
+    policy?: AgentPolicyDefinitionConfig;
     /**
      * Opt the agent into the public runtime endpoint (SSE/WebSocket via the
      * environment runtime key). Off by default — secured: when unset the public
@@ -971,8 +1298,9 @@ 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 PolicyResource<Name extends string = string> = ResourceDefinition<"policy", Name, PolicyDefinitionConfig>;
 type CronResource<Name extends string = string> = ResourceDefinition<"cron", Name, CronDefinitionConfig>;
-type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronResource | SkillResource | ToolResource;
+type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronResource | SkillResource | ToolResource | PolicyResource;
 /**
  * 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
@@ -999,10 +1327,11 @@ declare function defineWorkspace<const Name extends string>(input: ResourceDefin
 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 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, defineSandbox, defineSkill, defineSlackChannel, defineTelegramChannel, defineTool, defineWorkspace, defineZaloChannel, env, isBroodsConfig, isChannelDefinition, isObservabilityClientMessage, isResource, normalizeHttpServiceUrl, readSseStream, resolveRunEvents, toWebSocketBaseUrl };
-export type { Account, Agent, AgentChannelsConfig, AgentConfig, AgentConfigDoc, AgentDefinitionConfig, AgentDiscordChannelConfig, AgentGitHubChannelConfig, AgentHandle, AgentPancakeChannelConfig, AgentReference, AgentResource, AgentRunEventInput, AgentRunInput, AgentRunModelOverrides, AgentRunOverrides, AgentRunResult, AgentSkillsDefinitionConfig, AgentSlackChannelConfig, AgentStreamPart, AgentSubagentDefinitionConfig, AgentTelegramChannelConfig, AgentWorkspaceInput, AgentWorkspaceRef, AgentWorkspaceRefInput, AgentZaloChannelConfig, AnyChannelDefinition, AnyResource, AsyncAgentRun, AsyncPollOptions, AsyncRequestAccepted, AsyncStatus, BroodsClientOptions, BroodsConfigDefinition, BroodsProjectConfig, BroodsWebSocketClientOptions, ChannelDefinition, ChannelReference, ChannelType, CliManifest, CliManifestResource, CliResourceKind, CreateClientCronInput, CreateCronInput, Cron, CronDefinitionConfig, CronDoc, CronLastStatus, CronResource, CronRun, CronStatus, CustomTool, DiscordChannelDefinition, DiscordChannelInput, Doc, EnvAccessor, EnvRef, EnvRefString, EnvironmentDoc, GeneratedIds, GitHubChannelDefinition, GitHubChannelInput, Id, LogLevel, ObservabilityBackfillMessage, ObservabilityClientMessage, ObservabilityErrorMessage, ObservabilityLogEntry, ObservabilityLogMessage, ObservabilityReadyMessage, ObservabilityServerMessage, ObservabilitySpanMessage, ObservabilitySpanRow, ObservabilitySubscribeMessage, ObservabilityUnsubscribeMessage, PancakeChannelDefinition, PancakeChannelInput, ProjectDoc, ResourceApi, ResourceDefinition, ResourceDefinitionInput, ResourceKind, Sandbox, SandboxConfig, SandboxConfigDoc, SandboxDefinitionConfig, SandboxResource, Skill, SkillDefinitionConfig, SkillResource, SlackChannelDefinition, SlackChannelInput, TelegramChannelDefinition, TelegramChannelInput, ToolApprovalSummary, ToolDefinitionConfig, ToolResource, UpdateCronInput, WebSocketClientCancelMessage, WebSocketClientExecuteMessage, WebSocketClientMessage, WebSocketConstructorLike, WebSocketHandlers, WebSocketLike, WebSocketRunInput, WebSocketServerMessage, WebSocketStreamMessage, WebSocketSubscription, Workspace, WorkspaceConfig, WorkspaceConfigDoc, WorkspaceResource, ZaloChannelDefinition, ZaloChannelInput };
+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, 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, 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 };