broods 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1008 @@
+import { SystemModelMessage, CallSettings, streamText, JSONSchema7, ModelMessage, TextStreamPart, ToolSet } from 'ai';
+
+/**
+ * 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.
+ */
+
+type ChannelStreamMode = "edit" | "chunk" | "progress";
+
+/**
+ * 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;
+};
+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;
+    publicAccess?: boolean;
+    [key: string]: unknown;
+}
+interface AgentBehaviorConfig {
+    maxTurn?: number;
+    system?: string | SystemModelMessage | SystemModelMessage[];
+    [key: string]: unknown;
+}
+type StreamTextOptions$1 = Parameters<typeof streamText>[0];
+type AgentModelProviderOptions = StreamTextOptions$1["providerOptions"];
+interface AgentSkillsConfig {
+    enabled?: boolean;
+    allowed?: string[];
+    [key: string]: unknown;
+}
+interface AgentSubagentConfig {
+    enabled?: boolean;
+    allowed?: string[];
+    context?: "new" | "inherited";
+    mode?: "ephemeral" | "persistent";
+    [key: string]: unknown;
+}
+interface AgentModelConfig extends Omit<CallSettings, "abortSignal" | "headers"> {
+    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>>;
+interface AgentProviderSettings {
+    [key: string]: unknown;
+}
+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[];
+    [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 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 AgentChannelStreamingMode = ChannelStreamMode | "off";
+interface AgentChannelStreamingConfig {
+    mode?: AgentChannelStreamingMode;
+    [key: string]: unknown;
+}
+interface AgentTelegramChannelConfig {
+    botToken?: string;
+    webhookSecret?: string;
+    allowedChatIds?: number[];
+    reactionEmoji?: string;
+    streaming?: AgentChannelStreamingConfig;
+    [key: string]: unknown;
+}
+interface AgentGitHubChannelConfig {
+    webhookSecret?: string;
+    appId?: string;
+    privateKey?: string;
+    allowedRepos?: string[];
+    [key: string]: unknown;
+}
+interface AgentSlackChannelConfig {
+    botToken?: string;
+    signingSecret?: string;
+    allowedChannelIds?: string[];
+    streaming?: AgentChannelStreamingConfig;
+    [key: string]: unknown;
+}
+interface AgentDiscordChannelConfig {
+    botToken?: string;
+    publicKey?: string;
+    allowedGuildIds?: string[];
+    streaming?: AgentChannelStreamingConfig;
+    [key: string]: unknown;
+}
+interface AgentPancakeChannelConfig {
+    pageId?: string;
+    pageAccessToken?: string;
+    webhookSecret?: string;
+    senderId?: string;
+    options?: Record<string, unknown>;
+    streaming?: AgentChannelStreamingConfig;
+    [key: string]: unknown;
+}
+interface AgentZaloChannelConfig {
+    botToken?: string;
+    webhookSecret?: string;
+    allowedUserIds?: string[];
+    streaming?: AgentChannelStreamingConfig;
+    [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;
+});
+
+/**
+ * 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 = "lambda" | "e2b" | "daytona" | "kubernetes" | "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;
+    runtimes?: SandboxRuntimeName[];
+    network?: SandboxNetworkConfig;
+    permissionMode?: SandboxPermissionMode;
+    persistent?: boolean;
+    ephemeralHome?: 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];
+interface WorkspaceConfig {
+    storage: {
+        provider: WorkspaceStorageProvider;
+    };
+    harness?: {
+        enabled?: boolean;
+    };
+}
+
+/**
+ * Canonical CLI manifest wire types — the single source of truth shared by the
+ * backend (cliSync.ts, cliHttp.ts) and the SDK/CLI (packages/broods).
+ *
+ * This file is intentionally type-only with no runtime imports so the SDK can
+ * import it without pulling the Convex server module graph into its typecheck.
+ */
+type CliManifestResource = {
+    kind: "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool";
+    name: string;
+    description?: string;
+    config: unknown;
+};
+type GeneratedIds = {
+    agents: Record<string, string>;
+    workspaces: Record<string, string>;
+    sandboxes: Record<string, string>;
+    crons: Record<string, string>;
+    skills: Record<string, string>;
+    tools: Record<string, string>;
+};
+type CliManifest = {
+    version: 1;
+    project: string;
+    environment: string;
+    resources: CliManifestResource[];
+};
+
+/**
+ * Type contracts inherited from Convex and core storage/runtime modules.
+ * Keep this file type-only so the public SDK does not bundle backend code.
+ */
+
+type Id<TableName extends string = string> = string & {
+    readonly __tableName?: TableName;
+};
+type Doc<TableName extends string = string> = Record<string, unknown> & {
+    readonly _id: Id<TableName>;
+};
+
+type ProjectDoc = Doc<"projects">;
+type EnvironmentDoc = Doc<"environments">;
+type AgentConfigDoc = Doc<"agentConfigs">;
+type WorkspaceConfigDoc = Doc<"workspaceConfigs">;
+type SandboxConfigDoc = Doc<"sandboxConfigs">;
+type CronDoc = Doc<"crons">;
+type CliResourceKind = "agent" | "workspace" | "sandbox" | "cron";
+
+/**
+ * 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
+ * the SDK keeps working when the runtime is ported.
+ */
+
+interface Account {
+    account: {
+        accountId: string;
+        username: string;
+    };
+    secret: string;
+}
+interface Agent {
+    accountId: string;
+    agentId: string;
+    name: string;
+}
+interface Sandbox {
+    sandboxId: string;
+    name: string;
+}
+interface Workspace {
+    workspaceId: string;
+    name: string;
+}
+/** A tool call held for user approval by an `ask`-mode sandbox. */
+interface ToolApprovalSummary {
+    approvalId: string;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+interface AsyncStatus {
+    status: "processing" | "awaiting_approval" | "completed" | "failed" | "not_found";
+    response?: unknown;
+    error?: string;
+    approvals?: ToolApprovalSummary[];
+}
+interface AsyncRequestAccepted {
+    statusUrl: string;
+    statusId: string;
+    eventId: string;
+    agentId: string;
+}
+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;
+    }>;
+}
+interface CustomTool {
+    accountId: string;
+    toolId: string;
+    name: string;
+    description: string;
+    sha256: string;
+}
+
+type StreamTextOptions = Parameters<typeof streamText>[0];
+type JsonCallSettings = Partial<Omit<CallSettings, "abortSignal" | "headers">>;
+type AgentRunModelOverrides = JsonCallSettings & Pick<StreamTextOptions, "providerOptions">;
+type AgentRunOverrides = {
+    system?: SystemModelMessage | SystemModelMessage[];
+    model?: AgentRunModelOverrides;
+};
+type AgentRunEventInput = {
+    /** Shorthand for a single user text message. */
+    input: string;
+    events?: never;
+} | {
+    /** Full-fidelity event list for multimodal content or tool responses. */
+    events: [ModelMessage, ...ModelMessage[]];
+    input?: never;
+};
+/**
+ * Resolves a run's events from either the explicit `events` list or the `input`
+ * string shorthand, matching the core direct API's event contract.
+ */
+declare function resolveRunEvents(input: AgentRunEventInput): ModelMessage[];
+
+/**
+ * Shared direct-run stream contracts and SSE parsing helpers.
+ */
+
+type AgentStreamPart = TextStreamPart<ToolSet> | {
+    type: "structured-output";
+    output: unknown;
+};
+/** Yield the payload of each `data:` line from an SSE response body. */
+declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+
+/**
+ * Shared WebSocket wire message contracts used by the SDK client and gateway.
+ */
+
+type WebSocketStreamMessage = AgentStreamPart | {
+    type: string;
+    [key: string]: unknown;
+};
+type WebSocketServerMessage = {
+    type: "meta";
+    sessionId: string;
+    taskId: string;
+} | WebSocketStreamMessage;
+type WebSocketClientExecuteMessage = {
+    type: "execute";
+    agentId: string;
+    sessionId?: string;
+    eventId?: string;
+} & AgentRunEventInput & AgentRunOverrides;
+type WebSocketClientCancelMessage = {
+    type: "cancel";
+};
+type WebSocketClientMessage = WebSocketClientExecuteMessage | WebSocketClientCancelMessage;
+
+/**
+ * Shared WebSocket wire-protocol types for the observability gateway, used by
+ * the gateway, the SDK/CLI, and the dashboard. Pure types + tiny pure helpers,
+ * zero runtime deps. Kept separate from the agent-test websocket-contracts.
+ */
+type LogLevel = "INFO" | "WARN" | "ERROR";
+declare const MAX_OBSERVABILITY_BACKFILL = 500;
+type ObservabilityLogEntry = {
+    ts: number;
+    level: LogLevel | "DEBUG";
+    eventType: string;
+    message: string;
+    traceId?: string;
+    accountId?: string;
+    endpointId?: string;
+    service?: string;
+    agentId?: string;
+    conversationKey?: string;
+    data?: unknown;
+};
+type ObservabilitySpanRow = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: "task" | "subtask" | "model.step" | "tool.call" | "phase";
+    startTimeMs: number;
+    endTimeMs: number;
+    durationMs: number;
+    status: "running" | "ok" | "error";
+    endpointId?: string;
+    agentId?: string;
+    conversationKey?: string;
+    attributes?: Record<string, unknown>;
+    error?: string;
+};
+type ObservabilitySubscribeMessage = {
+    type: "subscribe";
+    stream: "logs" | "traces";
+    backfill?: number;
+    minLevel?: LogLevel;
+};
+type ObservabilityUnsubscribeMessage = {
+    type: "unsubscribe";
+    stream: "logs" | "traces";
+};
+type ObservabilityClientMessage = ObservabilitySubscribeMessage | ObservabilityUnsubscribeMessage;
+type ObservabilityReadyMessage = {
+    type: "ready";
+};
+type ObservabilityBackfillMessage = {
+    type: "backfill";
+    stream: "logs" | "traces";
+    entries: ObservabilityLogEntry[] | ObservabilitySpanRow[];
+};
+type ObservabilityLogMessage = {
+    type: "log";
+    entry: ObservabilityLogEntry;
+};
+type ObservabilitySpanMessage = {
+    type: "span";
+    entry: ObservabilitySpanRow;
+};
+type ObservabilityErrorMessage = {
+    type: "error";
+    error: string;
+};
+type ObservabilityServerMessage = ObservabilityReadyMessage | ObservabilityBackfillMessage | ObservabilityLogMessage | ObservabilitySpanMessage | ObservabilityErrorMessage;
+declare function isObservabilityClientMessage(v: unknown): v is ObservabilityClientMessage;
+
+/**
+ * Configurable client for running deployed agents over direct core SSE.
+ * Stream chunks are the Vercel AI SDK's `TextStreamPart` parts that core emits.
+ */
+
+declare const DEFAULT_CORE_BASE_URL = "https://gateway.broods.app";
+/**
+ * Input for a single agent run. The core direct API is event-based (a list of
+ * Vercel AI SDK model messages), so `events` is the full-fidelity form — use it
+ * for multimodal content (images/files), ephemeral system messages, or
+ * tool-approval responses. `input` is a shorthand for a single user text message
+ * and is wrapped into one user event. Provide exactly one of the two.
+ */
+type AgentRunInputBase = {
+    conversationKey?: string;
+    eventId?: string;
+} & AgentRunOverrides;
+type AgentRunInput = AgentRunInputBase & AgentRunEventInput;
+interface AgentRunResult {
+    text: string;
+    events: TextStreamPart<ToolSet>[];
+}
+interface AsyncPollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+interface AsyncAgentRun extends AsyncRequestAccepted {
+    conversationKey: string;
+    poll(): Promise<AsyncStatus>;
+    wait(options?: AsyncPollOptions): Promise<AsyncStatus>;
+}
+interface AgentReference<Name extends string = string> {
+    readonly kind: "agent";
+    readonly name: Name;
+    readonly id: string;
+    readonly project: string;
+    readonly environment: string;
+    /**
+     * Authoritative scope of the environment's runtime key, embedded by codegen
+     * from the deploy response. When present the client posts to the scoped URL
+     * `/v1/{projectSlug}/agents/{environmentSlug}/{endpointId}` (matching the
+     * dashboard); when absent it falls back to the base URL.
+     */
+    readonly endpointId?: string;
+    readonly projectSlug?: string;
+    readonly environmentSlug?: string;
+}
+interface ChannelReference {
+    readonly kind: "channel";
+    readonly type: "telegram" | "github" | "slack" | "discord" | "pancake" | "zalo";
+    readonly agentName: string;
+    readonly agentId: string;
+    readonly accountId: string;
+    readonly webhookPath: string;
+}
+interface ResourceApi {
+    readonly agents: Record<string, AgentReference>;
+    readonly channels?: Record<string, ChannelReference>;
+    readonly workspaces?: Record<string, unknown>;
+    readonly sandboxes?: Record<string, unknown>;
+    readonly crons?: Record<string, unknown>;
+    readonly skills?: Record<string, unknown>;
+    readonly tools?: Record<string, unknown>;
+}
+interface BroodsClientOptions {
+    /**
+     * Base URL of the core service to call directly. Use `https://gateway.broods.app`
+     * for the hosted service. If you only have a domain, use `host` instead.
+     */
+    baseUrl?: string;
+    /** Hostname or URL of the core service. `gateway.broods.app` becomes `https://gateway.broods.app`. */
+    host?: string;
+    /** API key used as the Bearer token for direct runtime calls. */
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+type AgentHandle = {
+    id: string;
+    run: (input: AgentRunInput) => Promise<AgentRunResult>;
+    runAsync: (input: AgentRunInput) => Promise<AsyncAgentRun>;
+    stream: (input: AgentRunInput) => AsyncGenerator<TextStreamPart<ToolSet>>;
+};
+type CreateClientCronInput = CreateCronInput | (Omit<CreateCronInput, "agentId"> & {
+    agent: AgentReference | string;
+});
+declare class BroodsClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    constructor(options?: BroodsClientOptions);
+    /** Return the public provider webhook URL for a generated channel reference. */
+    channelWebhookUrl(ref: ChannelReference): string;
+    agent<const Name extends string>(ref: AgentReference<Name>): AgentHandle;
+    agent(name: string, agentId: string): AgentHandle;
+    /** Run an agent and accumulate the streamed text and raw parts. */
+    run(ref: AgentReference, input: AgentRunInput): Promise<AgentRunResult>;
+    run(input: AgentRunInput & {
+        agentId: string;
+        agentName?: string;
+    }): Promise<AgentRunResult>;
+    /** Stream an agent run, yielding each AI SDK `TextStreamPart` as it arrives. */
+    stream(ref: AgentReference, input: AgentRunInput): AsyncGenerator<TextStreamPart<ToolSet>>;
+    stream(input: AgentRunInput & {
+        agentId: string;
+        agentName?: string;
+    }): AsyncGenerator<TextStreamPart<ToolSet>>;
+    /** Start an async agent run and return the status id/URL used for polling. */
+    runAsync(ref: AgentReference, input: AgentRunInput): Promise<AsyncAgentRun>;
+    runAsync(input: AgentRunInput & {
+        agentId: string;
+        agentName?: string;
+    }): Promise<AsyncAgentRun>;
+    /** Fetch one async status snapshot by status URL or status id + agent id. */
+    getAsyncStatus(status: AsyncRequestAccepted | string, options?: {
+        agentId?: string;
+    }): Promise<AsyncStatus>;
+    /** Poll async status until it reaches completed, failed, awaiting_approval, or timeout. */
+    waitForAsyncStatus(status: AsyncRequestAccepted | string, options?: AsyncPollOptions & {
+        agentId?: string;
+    }): Promise<AsyncStatus>;
+    createCron(input: CreateClientCronInput): Promise<Cron>;
+    listCrons(): Promise<Cron[]>;
+    getCron(cronId: string): Promise<Cron | null>;
+    listCronRuns(cronId: string, options?: {
+        limit?: number;
+    }): Promise<CronRun[]>;
+    updateCron(cronId: string, patch: UpdateCronInput): Promise<Cron>;
+    deleteCron(cronId: string): Promise<boolean>;
+    /**
+     * Scoped invoke URL for a deployed agent. When codegen embedded the runtime
+     * key's scope, this is `/v1/{projectSlug}/agents/{environmentSlug}/{endpointId}`
+     * (the same URL the dashboard shows, so core can validate the key against the
+     * path); otherwise it falls back to the base URL.
+     */
+    private scopedUrl;
+    private openStream;
+    private fetchCore;
+    private apiKeyHeaders;
+    private fetchJson;
+    private resolveStatusUrl;
+}
+declare function normalizeHttpServiceUrl(value: string): string;
+
+/**
+ * WebSocket client for deployed-agent endpoints.
+ * Uses the gateway URL when configured, or derives one from the core service URL.
+ */
+
+type WebSocketRunInput = {
+    agent?: AgentReference;
+    agentId?: string;
+    endpointId?: string;
+    sessionId?: string;
+    eventId?: string;
+    projectSlug?: string;
+    environmentSlug?: string;
+    signal?: AbortSignal;
+} & AgentRunEventInput & AgentRunOverrides;
+interface WebSocketHandlers {
+    onMessage?(message: WebSocketServerMessage): void;
+    onMeta?(meta: Extract<WebSocketServerMessage, {
+        type: "meta";
+    }>): void;
+    onDone?(): void;
+    onError?(error: Error): void;
+}
+interface WebSocketSubscription {
+    readonly url: string;
+    close(code?: number, reason?: string): void;
+}
+interface BroodsWebSocketClientOptions {
+    /** Base URL of the core service. Use `https://...`; the client converts it to `wss://...`. */
+    baseUrl?: string;
+    /** Hostname or URL of the core service. `gateway.broods.app` becomes `https://gateway.broods.app`. */
+    host?: string;
+    /** API key used as the WebSocket token. Defaults to BROODS_API_KEY from the environment or local .env files. */
+    apiKey?: string;
+    WebSocket?: WebSocketConstructorLike;
+    connectTimeoutMs?: number;
+}
+interface WebSocketConstructorLike {
+    new (url: string): WebSocketLike;
+}
+interface WebSocketLike {
+    readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+declare class BroodsWebSocketClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly WebSocketImpl?;
+    private readonly connectTimeoutMs;
+    constructor(options?: BroodsWebSocketClientOptions);
+    subscribe(input: WebSocketRunInput, handlers?: WebSocketHandlers): WebSocketSubscription;
+    stream(input: WebSocketRunInput): AsyncGenerator<WebSocketServerMessage>;
+    buildUrl(input: Pick<WebSocketRunInput, "agent" | "endpointId" | "projectSlug" | "environmentSlug">): string;
+    private resolveWebSocket;
+}
+
+declare function toWebSocketBaseUrl(url: string): string;
+
+/**
+ * Resource definition helpers for the code-first `broods/` project folder.
+ *
+ * Layout: markers, then types (env refs, project config, resource primitives,
+ * per-kind config surfaces, per-kind resource aliases), then the env runtime
+ * value, the resource constructors, and the type guards. Every runtime function
+ * here is synchronous.
+ */
+
+declare const RESOURCE_MARKER: unique symbol;
+declare const CONFIG_MARKER: unique symbol;
+declare const CHANNEL_MARKER: unique symbol;
+interface EnvRef<Name extends string = string> {
+    readonly __beeblastEnv: true;
+    readonly name: Name;
+}
+/** Callable + property-access accessor for {@link env}. */
+interface EnvAccessor {
+    <const Name extends string>(name: Name): EnvRef<Name>;
+    readonly [name: string]: EnvRef;
+}
+type EnvRefString<T> = T extends string ? T | EnvRef : T extends readonly (infer Item)[] ? readonly EnvRefString<Item>[] : T extends (infer Item)[] ? EnvRefString<Item>[] : T extends object ? {
+    [Key in keyof T]: EnvRefString<T[Key]>;
+} : T;
+interface BroodsProjectConfig {
+    project?: string;
+    environments?: {
+        dev?: string;
+        deploy?: string;
+        [name: string]: string | undefined;
+    };
+    dashboardUrl?: string;
+}
+interface BroodsConfigDefinition {
+    readonly [CONFIG_MARKER]: true;
+    readonly config: BroodsProjectConfig;
+}
+type ResourceKind = "agent" | "workspace" | "sandbox" | "cron" | "skill" | "tool";
+interface ResourceDefinition<Kind extends ResourceKind, Name extends string, Config> {
+    readonly [RESOURCE_MARKER]: true;
+    readonly kind: Kind;
+    readonly name: Name;
+    readonly description?: string;
+    readonly config: Config;
+}
+interface ResourceDefinitionInput<Name extends string, Config> {
+    name: Name;
+    description?: string;
+    config: Config;
+}
+/**
+ * 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"> & {
+    envVars?: Record<string, string | EnvRef | undefined>;
+};
+interface SkillDefinitionConfig {
+    /**
+     * Folder containing SKILL.md plus optional scripts/assets. Relative paths are
+     * resolved from the `broods/` project directory.
+     */
+    path: string;
+}
+interface ToolDefinitionConfig {
+    /**
+     * JavaScript module file exporting the custom tool bundle. Relative paths are
+     * resolved from the `broods/` project directory.
+     */
+    path: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    defaultConfig?: Record<string, unknown>;
+}
+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 config: Config;
+}
+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 {
+    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 {
+    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 ZaloChannelDefinition = ChannelDefinition<"zalo", ZaloChannelInput>;
+type AnyChannelDefinition = TelegramChannelDefinition | GitHubChannelDefinition | SlackChannelDefinition | DiscordChannelDefinition | PancakeChannelDefinition | ZaloChannelDefinition;
+/**
+ * Per-agent workspace mount with an optional sandbox override. A bare
+ * `defineWorkspace(...)` inherits the agent-level sandbox; the object form lets
+ * a single workspace pin its own sandbox, or set `sandbox: null` to force the
+ * workspace read-only (no compute attached).
+ */
+interface AgentWorkspaceRefInput {
+    workspace: WorkspaceResource | string;
+    sandbox?: SandboxResource | string | null;
+}
+type AgentWorkspaceInput = WorkspaceResource | AgentWorkspaceRefInput;
+/**
+ * `subagent` block where `allowed` may reference other `defineAgent(...)`
+ * resources directly; the compiler rewrites them to agent names and the backend
+ * resolves those to deploy-time agent ids.
+ */
+type AgentSubagentDefinitionConfig = Omit<NonNullable<AgentConfig["subagent"]>, "allowed"> & {
+    allowed?: readonly (AgentResource | string)[];
+};
+type AgentSkillsDefinitionConfig = Omit<NonNullable<AgentConfig["skills"]>, "allowed"> & {
+    allowed?: readonly (SkillResource | 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
+ * `[key: string]: unknown` index signature — which would otherwise disable
+ * TypeScript's excess-property checks and silently accept typos like
+ * `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">> & {
+    channels?: readonly AnyChannelDefinition[];
+    sandbox?: SandboxResource | string;
+    workspaces?: readonly AgentWorkspaceInput[];
+    subagent?: AgentSubagentDefinitionConfig;
+    skills?: AgentSkillsDefinitionConfig;
+    /**
+     * Opt the agent into the public runtime endpoint (SSE/WebSocket via the
+     * environment runtime key). Off by default — secured: when unset the public
+     * endpoint refuses requests for this agent. Reach a private agent through an
+     * internal endpoint or a channel webhook. See issue #65.
+     */
+    publicAccess?: boolean;
+};
+type CronDefinitionConfig = Omit<CreateCronInput, "agentId" | "name"> & {
+    agent: AgentResource | string;
+};
+type AgentResource<Name extends string = string> = ResourceDefinition<"agent", Name, AgentDefinitionConfig>;
+type WorkspaceResource<Name extends string = string> = ResourceDefinition<"workspace", Name, WorkspaceConfig>;
+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 CronResource<Name extends string = string> = ResourceDefinition<"cron", Name, CronDefinitionConfig>;
+type AnyResource = AgentResource | WorkspaceResource | SandboxResource | CronResource | SkillResource | ToolResource;
+/**
+ * References an account/environment variable resolved on the SERVER at runtime —
+ * set it with `broods env set <NAME>` or in the dashboard (the Convex-style
+ * `convex env set` model). It is a deferred reference, never read from your local
+ * environment and never baked into the deployed config. Use either form:
+ *
+ *   apiKey: env.OPENAI_API_KEY     // property access (reads like process.env)
+ *   apiKey: env("OPENAI_API_KEY")  // call form (equivalent)
+ *
+ * Both compile to a `${NAME}` placeholder the harness fills in at run time. This is
+ * NOT `process.env`: agent configs are compiled locally, so `process.env.NAME` would
+ * bake the literal local value into the deployed config instead of deferring it.
+ */
+declare const env: EnvAccessor;
+declare function defineTelegramChannel(config: TelegramChannelInput): TelegramChannelDefinition;
+declare function defineGitHubChannel(config: GitHubChannelInput): GitHubChannelDefinition;
+declare function defineSlackChannel(config: SlackChannelInput): SlackChannelDefinition;
+declare function defineDiscordChannel(config: DiscordChannelInput): DiscordChannelDefinition;
+declare function definePancakeChannel(config: PancakeChannelInput): PancakeChannelDefinition;
+declare function defineZaloChannel(config: ZaloChannelInput): ZaloChannelDefinition;
+declare function defineBroods(config: BroodsProjectConfig): BroodsConfigDefinition;
+declare function defineAgent<const Name extends string>(input: ResourceDefinitionInput<Name, AgentDefinitionConfig>): AgentResource<Name>;
+declare function defineWorkspace<const Name extends string>(input: ResourceDefinitionInput<Name, WorkspaceConfig>): WorkspaceResource<Name>;
+declare function defineSandbox<const Name extends string>(input: ResourceDefinitionInput<Name, SandboxDefinitionConfig>): SandboxResource<Name>;
+declare function defineSkill<const Name extends string>(input: ResourceDefinitionInput<Name, SkillDefinitionConfig>): SkillResource<Name>;
+declare function defineTool<const Name extends string>(input: ResourceDefinitionInput<Name, ToolDefinitionConfig>): ToolResource<Name>;
+declare function 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 };