broods 0.3.0 → 0.4.0

package/README.md

@@ -41,8 +41,8 @@ writes `BROODS_API_KEY` to `.env.local`; the SDK also accepts `apiKey`,
 ## Two ways to configure agents
 
 **Config-first (`broods dev` / `broods deploy`).** Resources declared in your
-`broods/` folder with `defineAgent`, `defineWorkspace`, etc. are *predefined
-configs*: the CLI syncs them to your project on deploy and codegen gives you
+`broods/` folder with `defineAgent`, `defineWorkspace`, etc. are _predefined
+configs_: the CLI syncs them to your project on deploy and codegen gives you
 typed references. Use this when the set of agents is fixed and versioned with
 your code.
 
@@ -59,7 +59,7 @@ such as Convex actions and Cloudflare Workers where the main SDK entry (which
 reads `.env` files from disk) cannot load:
 
 ```ts
-import { BroodsAccountClient } from "broods/account";
+import { BroodsAccountClient, envPlaceholder } from "broods/account";
 
 // baseUrl defaults to https://gateway.broods.app (override with BROODS_BASE_URL);
 // the secret falls back to BROODS_ACCOUNT_SECRET from the runtime's environment.
@@ -76,6 +76,13 @@ const created = await account.createAgent({
     publicAccess: true,
   },
 });
+
+// Store an account secret once, then reference it from any dynamic agent.
+// Reads list only names/timestamps; secret values are never returned.
+await account.setEnvVar("OVH_API_KEY", process.env.OVH_API_KEY!);
+await account.updateAgent(created.agentId, {
+  config: { provider: { custom: { apiKey: envPlaceholder("OVH_API_KEY") } } },
+});
 await account.updateAgent(created.agentId, {
   config: { channels: { slack: { id: "conn-1", botToken: "xoxb-…" } } },
 });
@@ -96,8 +103,16 @@ const sandbox = await account.createSandbox({
   name: "reserved",
   config: { provider: "lambda", persistent: true, permissionMode: "ask" },
 });
-await account.uploadWorkspaceFile("ws_1", { path: "memory/seed.md", contentBase64: "IyBTZWVk" });
-await account.createSkill({ source: "json", name: "triage", description: "Triage flow", content: "# Triage" });
+await account.uploadWorkspaceFile("ws_1", {
+  path: "memory/seed.md",
+  contentBase64: "IyBTZWVk",
+});
+await account.createSkill({
+  source: "json",
+  name: "triage",
+  description: "Triage flow",
+  content: "# Triage",
+});
 const runs = await account.listCronRuns("cron_1", { limit: 20 });
 
 // Persistent sandbox lifecycle is driven by reservationKey.

package/dist/account.d.ts

@@ -1,8 +1,19 @@
 import { SystemModelMessage, LanguageModelCallOptions, RequestOptions, streamText, JSONSchema7, ModelMessage } from 'ai';
-import { DiscordAdapterConfig } from '@chat-adapter/discord';
-import { GitHubAdapterConfig } from '@chat-adapter/github';
-import { SlackAdapterConfig } from '@chat-adapter/slack';
-import { TelegramAdapterConfig } from '@chat-adapter/telegram';
+
+/**
+ * Supported account model provider names.
+ * Keep provider identifiers here so config validation and model resolution share one source.
+ */
+declare const ACCOUNT_MODEL_PROVIDERS: {
+    readonly google: true;
+    readonly openai: true;
+    readonly anthropic: true;
+    readonly bedrock: true;
+    readonly gateway: true;
+    readonly minimax: true;
+    readonly custom: true;
+};
+type AccountModelProviderName = keyof typeof ACCOUNT_MODEL_PROVIDERS;
 
 /**
  * Agent policy contracts and validation.
@@ -43,21 +54,6 @@ interface AgentPolicyConfig {
     mode?: AgentPolicyMode;
 }
 
-/**
- * Supported account model provider names.
- * Keep provider identifiers here so config validation and model resolution share one source.
- */
-declare const ACCOUNT_MODEL_PROVIDERS: {
-    readonly google: true;
-    readonly openai: true;
-    readonly anthropic: true;
-    readonly bedrock: true;
-    readonly gateway: true;
-    readonly minimax: true;
-    readonly custom: true;
-};
-type AccountModelProviderName = keyof typeof ACCOUNT_MODEL_PROVIDERS;
-
 /**
  * Agent configuration: types for the per-agent settings object, input
  * normalization, encryption helpers, patch-merge, and redaction.
@@ -232,9 +228,9 @@ type AgentChannelWorkspaceScope = {
 };
 interface AgentTelegramChannelConfig {
     id?: string;
-    apiUrl?: TelegramAdapterConfig["apiUrl"];
-    botToken?: TelegramAdapterConfig["botToken"];
-    webhookSecret?: TelegramAdapterConfig["secretToken"];
+    apiUrl?: string;
+    botToken?: string;
+    webhookSecret?: string;
     allowedChatIds?: number[];
     reactionEmoji?: string;
     workspaceScope?: AgentChannelWorkspaceScope;
@@ -242,18 +238,10 @@ interface AgentTelegramChannelConfig {
 }
 interface AgentGitHubChannelConfig {
     id?: string;
-    apiUrl?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["apiUrl"];
-    webhookSecret?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["webhookSecret"];
-    appId?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["appId"];
-    privateKey?: Extract<GitHubAdapterConfig, {
-        appId: string;
-    }>["privateKey"];
+    apiUrl?: string;
+    webhookSecret?: string;
+    appId?: string;
+    privateKey?: string;
     allowedRepos?: string[];
     /** Bot username for @-mention detection (e.g. "my-bot" or "my-bot[bot]"). */
     userName?: string;
@@ -268,9 +256,9 @@ interface AgentGitHubChannelConfig {
 }
 interface AgentSlackChannelConfig {
     id?: string;
-    apiUrl?: SlackAdapterConfig["apiUrl"];
+    apiUrl?: string;
     botToken?: string;
-    signingSecret?: SlackAdapterConfig["signingSecret"];
+    signingSecret?: string;
     allowedChannelIds?: string[];
     reactionEmoji?: string;
     workspaceScope?: AgentChannelWorkspaceScope;
@@ -278,9 +266,9 @@ interface AgentSlackChannelConfig {
 }
 interface AgentDiscordChannelConfig {
     id?: string;
-    apiUrl?: DiscordAdapterConfig["apiUrl"];
-    botToken?: DiscordAdapterConfig["botToken"];
-    publicKey?: DiscordAdapterConfig["publicKey"];
+    apiUrl?: string;
+    botToken?: string;
+    publicKey?: string;
     allowedGuildIds?: string[];
     workspaceScope?: AgentChannelWorkspaceScope;
     [key: string]: unknown;
@@ -304,10 +292,7 @@ interface AgentZaloChannelConfig {
 }
 
 /**
- * Cron-job types, input normalization, and patch-merge helpers.
- * Provider-agnostic — both the DynamoDB and Convex stores import the
- * normalizer at their create/update entry points so behaviour is
- * symmetric across modes.
+ * Cron-job records, input normalization, and patch-merge helpers.
  */
 
 type CronStatus = "active" | "paused";
@@ -366,9 +351,8 @@ type SandboxSize = "tiny" | "xsmall" | "small" | "medium" | "large";
 /**
  * Sandbox config: account-scoped, reusable sandbox definitions referenced by
  * agents via `config.sandbox`. A sandbox is a collection of Claude-Code-style
- * tools (bash/read/write/edit/glob/grep) backed by a provider. Validation +
- * the public projection live here; the
- * DynamoDB / Convex stores call these at their create/update entry points.
+ * tools (bash/read/write/edit/glob/grep) backed by a provider. Validation and
+ * the public projection live here.
  * Stored encrypted at rest because `envVars`/`options` may hold secrets.
  */
 
@@ -408,8 +392,8 @@ interface SandboxConfig {
  * agents via `config.workspaces[].workspaceId`. A workspace is the persistent
  * S3-backed filesystem mounted into a sandbox; agents referencing the same
  * workspaceId share the same files. Holds no secrets, so it is stored in
- * plaintext (unlike sandbox config). Validation + the public projection live
- * here; the DynamoDB / Convex stores call these at create/update.
+ * plaintext (unlike sandbox config). Validation and the public projection live
+ * here.
  */
 declare const WORKSPACE_STORAGE_PROVIDERS: readonly ["s3"];
 type WorkspaceStorageProvider = (typeof WORKSPACE_STORAGE_PROVIDERS)[number];
@@ -428,12 +412,18 @@ interface WorkspaceStorageConfig {
     prefix?: string;
     auth?: WorkspaceStorageAuth;
 }
+interface WorkspaceHarnessConfig {
+    workspace?: {
+        enabled?: boolean;
+    };
+    memory?: {
+        enabled?: boolean;
+    };
+}
 interface WorkspaceConfig {
     storage: WorkspaceStorageConfig;
     isolation?: boolean;
-    harness?: {
-        enabled?: boolean;
-    };
+    harness?: WorkspaceHarnessConfig;
 }
 
 /**
@@ -534,6 +524,13 @@ interface CreateAgentResult {
     name: string;
     description?: string;
 }
+/** Write-only account environment variable metadata. */
+interface AccountEnvVar {
+    name: string;
+    updatedAt: number;
+}
+/** Build a validated account env-var reference for use in an agent config. */
+declare function envPlaceholder(name: string): string;
 /** Fields accepted by `PATCH /v1/agents/{id}`. `config` is deep-merged; `null` values delete keys. */
 interface UpdateAgentInput {
     name?: string;
@@ -701,6 +698,12 @@ declare class BroodsAccountClient {
     /** PATCH an agent. `config` deep-merges into the stored config; `null` leaves delete keys. Returns null when the agent is gone. */
     updateAgent(agentId: string, patch: UpdateAgentInput): Promise<AccountAgent | null>;
     deleteAgent(agentId: string): Promise<boolean>;
+    /** List account environment variable names and update timestamps; values are never returned. */
+    listEnvVars(): Promise<AccountEnvVar[]>;
+    /** Create or replace one write-only account environment variable. */
+    setEnvVar(name: string, value: string): Promise<void>;
+    /** Delete one account environment variable. Returns false when it is already absent. */
+    deleteEnvVar(name: string): Promise<boolean>;
     listCrons(): Promise<Cron[]>;
     createCron(input: CreateCronInput): Promise<Cron>;
     getCron(cronId: string): Promise<Cron | null>;
@@ -795,5 +798,5 @@ declare class BroodsAccountClient {
     private request;
 }
 
-export { BroodsAccountApiError, BroodsAccountClient };
-export type { AccountAgent, AccountPolicy, AccountSandbox, AccountTool, AccountWorkspace, BroodsAccount, BroodsAccountClientOptions, CreateAgentResult, CreateToolInput, DeleteAccountResult, RotateSecretResult, SandboxLifecycleResult, SandboxSnapshotResult, SandboxTerminalTicket, SkillUploadInput, UpdateAgentInput, UpdateToolInput, WorkspaceFileEntry };
+export { BroodsAccountApiError, BroodsAccountClient, envPlaceholder };
+export type { AccountAgent, AccountEnvVar, AccountPolicy, AccountSandbox, AccountTool, AccountWorkspace, BroodsAccount, BroodsAccountClientOptions, CreateAgentResult, CreateToolInput, DeleteAccountResult, RotateSecretResult, SandboxLifecycleResult, SandboxSnapshotResult, SandboxTerminalTicket, SkillUploadInput, UpdateAgentInput, UpdateToolInput, WorkspaceFileEntry };

package/dist/account.js

@@ -1,6 +1,13 @@
 // @bun
 // src/account.ts
 var DEFAULT_ACCOUNT_BASE_URL = "https://gateway.broods.app";
+var ACCOUNT_ENV_VAR_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+function envPlaceholder(name) {
+  if (!ACCOUNT_ENV_VAR_NAME_PATTERN.test(name) || name.length > 64) {
+    throw new Error("envPlaceholder name must match /^[A-Z][A-Z0-9_]*$/ and be at most 64 characters.");
+  }
+  return `\${${name}}`;
+}
 
 class BroodsAccountApiError extends Error {
   status;
@@ -73,6 +80,17 @@ class BroodsAccountClient {
     const result = await this.request("DELETE", `/v1/agents/${encodeURIComponent(agentId)}`);
     return result?.deleted ?? false;
   }
+  async listEnvVars() {
+    const result = await this.request("GET", "/v1/env");
+    return result?.env ?? [];
+  }
+  async setEnvVar(name, value) {
+    await this.request("PUT", `/v1/env/${encodeURIComponent(name)}`, { value });
+  }
+  async deleteEnvVar(name) {
+    const result = await this.request("DELETE", `/v1/env/${encodeURIComponent(name)}`);
+    return result?.deleted ?? false;
+  }
   async listCrons() {
     const result = await this.request("GET", "/v1/crons");
     return result?.crons ?? [];
@@ -266,6 +284,7 @@ class BroodsAccountClient {
   }
 }
 export {
+  envPlaceholder,
   BroodsAccountClient,
   BroodsAccountApiError
 };