broods 0.3.0 → 0.4.0

package/dist/cli/index.js

@@ -2,18 +2,19 @@
 // @bun
 
 // src/cli/index.ts
-import { mkdir as mkdir3, readFile as readFile3, readdir as readdir2, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile3, readdir as readdir2, writeFile as writeFile4 } from "fs/promises";
 import { createHash as createHash2 } from "crypto";
 import { basename as basename2, dirname as dirname2, join as join4, relative as relative2, resolve as resolve4 } from "path";
 import { watch } from "fs";
 import { spawn as spawn2 } from "child_process";
-import { tmpdir } from "os";
+import { tmpdir as tmpdir2 } from "os";
 import { performance } from "perf_hooks";
 
 // src/manifest.ts
 import { pathToFileURL } from "url";
 import { createHash } from "crypto";
-import { readdir, readFile as readFile2 } from "fs/promises";
+import { mkdtemp, readdir, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
 import { basename, isAbsolute, join as join3, relative, resolve as resolve2 } from "path";
 
 // src/config.ts
@@ -23,6 +24,9 @@ import { dirname, join } from "path";
 var PROJECT_DIR = "broods";
 var GENERATED_DIR = "_generated";
 var USER_CONFIG_PATH = join(homedir(), ".broods", "config.json");
+var BROODS_APEX_DOMAIN = "broods.app";
+var DASHBOARD_HOST_PREFIX = "dashboard";
+var GATEWAY_HOST_PREFIX = "gateway";
 async function readStoredAuth() {
   const envToken = process.env.BROODS_TOKEN;
   const envConvexUrl = process.env.BROODS_BASE_URL;
@@ -50,6 +54,20 @@ async function writeStoredAuth(config) {
 function stripTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
+function gatewayUrlForDashboard(dashboardUrl) {
+  try {
+    const url = new URL(dashboardUrl);
+    if (!url.hostname.startsWith(`${DASHBOARD_HOST_PREFIX}.`))
+      return;
+    const rest = url.hostname.slice(DASHBOARD_HOST_PREFIX.length + 1);
+    if (rest !== BROODS_APEX_DOMAIN && !rest.endsWith(`.${BROODS_APEX_DOMAIN}`))
+      return;
+    url.hostname = `${GATEWAY_HOST_PREFIX}.${rest}`;
+    return stripTrailingSlash(url.origin);
+  } catch {
+    return;
+  }
+}
 
 // src/runtime-config.ts
 import { existsSync, readFileSync, statSync } from "fs";
@@ -137,25 +155,27 @@ function readStoredAuthSync() {
 var RESOURCE_MARKER = Symbol.for("broods.resource");
 var CONFIG_MARKER = Symbol.for("broods.config");
 var CHANNEL_MARKER = Symbol.for("broods.channel");
-var env = new Proxy(function env2(name) {
+var ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+var env = new Proxy((name) => {
+  if (!ENV_NAME_PATTERN.test(name)) {
+    throw new Error("env name must match /^[A-Z][A-Z0-9_]*$/ and be at most 64 characters.");
+  }
   return { __beeblastEnv: true, name };
 }, {
   get(target, property, receiver) {
-    if (typeof property === "string")
-      return { __beeblastEnv: true, name: property };
+    if (typeof property === "string" && ENV_NAME_PATTERN.test(property)) {
+      throw new Error(`env.${property} is not supported; use env("${property}")`);
+    }
     return Reflect.get(target, property, receiver);
   }
 });
-function defineResource(kind, input) {
-  if (input.config === undefined) {
-    throw new Error(`Resource "${input.name}" must include config`);
-  }
+function defineResource(kind, name, description, config) {
   return {
     [RESOURCE_MARKER]: true,
     kind,
-    name: input.name,
-    ...input.description ? { description: input.description } : {},
-    config: input.config
+    name,
+    ...description ? { description } : {},
+    config
   };
 }
 function defineChannel(type, config) {
@@ -193,25 +213,32 @@ function defineBroods(config) {
   return { [CONFIG_MARKER]: true, config };
 }
 function defineAgent(input) {
-  return defineResource("agent", input);
+  const { name, description, ...config } = input;
+  return defineResource("agent", name, description, config);
 }
 function defineWorkspace(input) {
-  return defineResource("workspace", input);
+  const { name, description, ...config } = input;
+  return defineResource("workspace", name, description, config);
 }
 function defineSandbox(input) {
-  return defineResource("sandbox", input);
+  const { name, description, ...config } = input;
+  return defineResource("sandbox", name, description, config);
 }
 function defineSkill(input) {
-  return defineResource("skill", input);
+  const { name, description, ...config } = input;
+  return defineResource("skill", name, description, config);
 }
 function defineTool(input) {
-  return defineResource("tool", input);
+  const { name, ...config } = input;
+  return defineResource("tool", name, undefined, config);
 }
 function definePolicy(input) {
-  return defineResource("policy", input);
+  const { name, description, ...config } = input;
+  return defineResource("policy", name, description, config);
 }
 function defineCron(input) {
-  return defineResource("cron", input);
+  const { name, description, ...config } = input;
+  return defineResource("cron", name, description, config);
 }
 function isResource(value) {
   return Boolean(value && typeof value === "object" && value[RESOURCE_MARKER]);
@@ -224,8 +251,20 @@ function isBroodsConfig(value) {
 }
 
 // src/manifest.ts
-var MAX_BUNDLE_FILE_BYTES = 1e6;
-var MAX_BUNDLE_TOTAL_BYTES = 5000000;
+var SDK_STUB_SOURCE = `const passthrough = (input) => input;
+export const defineTool = passthrough;
+export const defineAgent = passthrough;
+export const defineWorkspace = passthrough;
+export const defineSandbox = passthrough;
+export const defineSkill = passthrough;
+export const definePolicy = passthrough;
+export const defineCron = passthrough;
+export const defineBroods = passthrough;
+export const env = (name) => ({ __beeblastEnv: true, name });
+export default {};
+`;
+var MAX_BUNDLE_FILE_BYTES = 1e7;
+var MAX_BUNDLE_TOTAL_BYTES = 20000000;
 var MAX_BUNDLE_FILES = 200;
 var SKIPPED_BUNDLE_DIRECTORIES = new Set(["node_modules", ".git"]);
 var UNSAFE_BUNDLE_FILE_NAMES = [
@@ -252,7 +291,11 @@ async function compileProject(options = {}) {
   const files = await listTypeScriptFiles(root);
   const exports = await loadExports(files);
   const config = await findConfig(exports, cwd, options.project);
-  const resourceExports = exports.filter((entry) => isResource(entry.value)).map((entry) => ({ exportName: entry.exportName, resource: entry.value }));
+  const resourceExports = exports.filter((entry) => isResource(entry.value)).map((entry) => ({
+    exportName: entry.exportName,
+    file: entry.file,
+    resource: entry.value
+  }));
   const resources = resourceExports.map((entry) => entry.resource);
   assertUniqueResources(resources);
   const channels = compileChannels(resourceExports, exports);
@@ -266,7 +309,7 @@ async function compileProject(options = {}) {
   assertSupportedWorkspaceSandboxMounts(resources);
   const resourceAliases = aliasesForResources(resourceExports);
   const environment = resolveEnvironment(config, options.environment ?? (options.useRuntimeEnvironment === false ? undefined : process.env.BROODS_ENVIRONMENT), options.command ?? "dev");
-  const manifestResources = (await Promise.all(resources.map((resource) => toManifestResources(resource, root)))).flat().sort((a, b) => `${a.kind}:${a.name}`.localeCompare(`${b.kind}:${b.name}`));
+  const manifestResources = (await Promise.all(resourceExports.map((entry) => toManifestResources(entry, root)))).flat().sort((a, b) => `${a.kind}:${a.name}`.localeCompare(`${b.kind}:${b.name}`));
   return {
     config,
     resources,
@@ -282,25 +325,25 @@ async function compileProject(options = {}) {
 }
 function collectEnvRefNames(manifest) {
   const names = new Set;
-  function walk(value) {
-    if (Array.isArray(value)) {
-      for (const entry of value)
-        walk(entry);
+  for (const resource of manifest.resources)
+    collectEnvRefNamesFromValue(resource.config, names);
+  return [...names].sort();
+}
+function collectEnvRefNamesFromValue(value, names) {
+  if (Array.isArray(value)) {
+    for (const entry of value)
+      collectEnvRefNamesFromValue(entry, names);
+    return;
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    if (record.__beeblastEnv === true && typeof record.name === "string") {
+      names.add(record.name);
       return;
     }
-    if (value && typeof value === "object") {
-      const record = value;
-      if (record.__beeblastEnv === true && typeof record.name === "string") {
-        names.add(record.name);
-        return;
-      }
-      for (const entry of Object.values(record))
-        walk(entry);
-    }
+    for (const entry of Object.values(record))
+      collectEnvRefNamesFromValue(entry, names);
   }
-  for (const resource of manifest.resources)
-    walk(resource.config);
-  return [...names].sort();
 }
 function resolveEnvironment(config, explicit, command) {
   if (explicit)
@@ -333,7 +376,11 @@ async function loadExports(files) {
   for (const file of files) {
     const href = `${pathToFileURL(file).href}?t=${Date.now()}`;
     const mod = await import(href);
-    values.push(...Object.entries(mod).map(([exportName, value]) => ({ exportName, value })));
+    values.push(...Object.entries(mod).map(([exportName, value]) => ({
+      exportName,
+      file,
+      value
+    })));
   }
   return values;
 }
@@ -550,7 +597,7 @@ function supportsS3WorkspaceMount(sandbox) {
   return Boolean(options && typeof options === "object" && !Array.isArray(options) && options.mountAwsS3Buckets === true);
 }
 function sandboxProvider(sandbox) {
-  return typeof sandbox.config.provider === "string" ? sandbox.config.provider : "lambda";
+  return typeof sandbox.config.provider === "string" ? sandbox.config.provider : "sandbox";
 }
 function assertUniqueResources(resources) {
   const seen = new Set;
@@ -640,7 +687,8 @@ function capitalize(value) {
 function isValidIdentifier(value) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value);
 }
-async function toManifestResources(resource, projectRoot) {
+async function toManifestResources(entry, projectRoot) {
+  const resource = entry.resource;
   if (resource.kind === "agent") {
     const normalized = normalizeAgentConfig(resource, projectRoot);
     return [
@@ -653,19 +701,22 @@ async function toManifestResources(resource, projectRoot) {
       }
     ];
   }
-  return [{
-    kind: resource.kind,
-    name: resource.name,
-    ...resource.description ? { description: resource.description } : {},
-    config: await normalizeConfig(resource, projectRoot)
-  }];
+  return [
+    {
+      kind: resource.kind,
+      name: resource.name,
+      ...resource.description ? { description: resource.description } : {},
+      config: await normalizeConfig(entry, projectRoot)
+    }
+  ];
 }
-async function normalizeConfig(resource, projectRoot) {
+async function normalizeConfig(entry, projectRoot) {
+  const resource = entry.resource;
   if (resource.kind === "skill") {
     return await normalizeSkillConfig(resource.config, projectRoot);
   }
   if (resource.kind === "tool") {
-    return await normalizeToolConfig(resource.config, projectRoot);
+    return await normalizeToolConfig(entry, resource.config, projectRoot);
   }
   if (resource.kind === "policy") {
     const config = { ...resource.config };
@@ -679,14 +730,24 @@ async function normalizeConfig(resource, projectRoot) {
     config.name = config.name ?? resource.name;
     delete config.agent;
     if (typeof config.input === "string") {
-      config.events = [{ role: "user", content: [{ type: "text", text: config.input }] }];
+      config.events = [
+        { role: "user", content: [{ type: "text", text: config.input }] }
+      ];
       delete config.input;
     }
     return rewriteValues(config);
   }
   return rewriteValues(resource.config);
 }
-var KNOWN_PROVIDER_NAMES = ["google", "openai", "anthropic", "bedrock", "gateway", "minimax", "custom"];
+var KNOWN_PROVIDER_NAMES = [
+  "google",
+  "openai",
+  "anthropic",
+  "bedrock",
+  "gateway",
+  "minimax",
+  "custom"
+];
 var KNOWN_PROVIDER_SETTING_KEYS = new Set([
   "apiKey",
   "base_url",
@@ -786,11 +847,13 @@ function normalizeInlineAgentHooks(agentName, hooks) {
     if (typeof handler !== "function") {
       throw new Error(`Agent "${agentName}" config.hooks.${name} must be a function`);
     }
-    return [{
-      name,
-      event: INLINE_AGENT_HOOK_EVENTS[name],
-      source: toHookFunctionExpression(handler.toString())
-    }];
+    return [
+      {
+        name,
+        event: INLINE_AGENT_HOOK_EVENTS[name],
+        source: toHookFunctionExpression(handler.toString())
+      }
+    ];
   });
   if (entries.length === 0)
     return;
@@ -904,26 +967,43 @@ async function normalizeSkillConfig(config, projectRoot) {
     files
   };
 }
-async function normalizeToolConfig(config, projectRoot) {
-  const bundlePath = resolveContainedResourcePath(projectRoot, config.path, "Tool");
+async function normalizeToolConfig(entry, config, projectRoot) {
+  const defaultConfigEnvRefs = new Set;
+  collectEnvRefNamesFromValue(config.defaultConfig, defaultConfigEnvRefs);
+  if (defaultConfigEnvRefs.size > 0) {
+    throw new Error(`Tool "${entry.resource.name}" defaultConfig cannot contain env("NAME") references; put environment values in the agent's tools.<tool>.config so they stay encrypted and environment-scoped`);
+  }
+  const bundlePath = config.path ? resolveContainedResourcePath(projectRoot, config.path, "Tool") : entry.file;
   const manifestPath = relative(projectRoot, bundlePath).split("\\").join("/");
   assertSafeBundlePath(manifestPath, "Tool");
   const sourceSize = Buffer.byteLength(await readFile2(bundlePath));
   if (sourceSize > MAX_BUNDLE_FILE_BYTES) {
     throw new Error(`Tool source ${manifestPath} is too large (${sourceSize} bytes, max ${MAX_BUNDLE_FILE_BYTES})`);
   }
-  const build = await Bun.build({
-    entrypoints: [bundlePath],
-    root: projectRoot,
-    target: "node",
-    format: "esm",
-    minify: false
-  });
-  if (!build.success || build.outputs.length !== 1) {
-    const details = build.logs.map((entry) => entry.message).filter(Boolean).join("; ");
-    throw new Error(`Tool bundle ${manifestPath} failed to build${details ? `: ${details}` : ""}`);
+  const shimDir = await mkdtemp(join3(tmpdir(), "broods-tool-"));
+  const shimPath = join3(shimDir, "tool-adapter.mjs");
+  await writeFile2(shimPath, toolShimSource(bundlePath, config.path, entry), "utf8");
+  if (!config.path) {
+    await writeFile2(join3(shimDir, "broods-stub.mjs"), SDK_STUB_SOURCE, "utf8");
   }
-  const bundle = await build.outputs[0].text();
+  let bundle;
+  try {
+    const build = await Bun.build({
+      entrypoints: [shimPath],
+      target: "node",
+      format: "esm",
+      minify: false,
+      plugins: config.path ? [] : [sdkStubPlugin(shimDir)]
+    });
+    if (!build.success || build.outputs.length !== 1) {
+      const details = build.logs.map((entry2) => entry2.message).filter(Boolean).join("; ");
+      throw new Error(`Tool bundle ${manifestPath} failed to build${details ? `: ${details}` : ""}`);
+    }
+    bundle = await build.outputs[0].text();
+  } finally {
+    await rm(shimDir, { recursive: true, force: true });
+  }
+  bundle = normalizeBundleComments(bundle, bundlePath, manifestPath);
   const bundleSize = Buffer.byteLength(bundle);
   if (bundleSize > MAX_BUNDLE_FILE_BYTES) {
     throw new Error(`Tool bundle ${manifestPath} is too large (${bundleSize} bytes, max ${MAX_BUNDLE_FILE_BYTES})`);
@@ -948,7 +1028,10 @@ function normalizeWorkspaceRef(entry, agentName) {
     if (typeof name !== "string") {
       throw new Error(`Agent ${agentName} workspace ref must be a defineWorkspace(...) resource or its name`);
     }
-    const normalized = { name, workspaceId: name };
+    const normalized = {
+      name,
+      workspaceId: name
+    };
     if ("sandbox" in entry) {
       const sandbox = entry.sandbox;
       normalized.sandbox = sandbox === null ? null : isResource(sandbox) ? sandbox.name : sandbox;
@@ -1048,21 +1131,49 @@ function contentTypeForPath(path) {
     return "text/plain; charset=utf-8";
   return "application/octet-stream";
 }
+function sdkStubPlugin(shimDir) {
+  const stub = join3(shimDir, "broods-stub.mjs");
+  return {
+    name: "broods-sdk-stub",
+    setup(build) {
+      build.onResolve({ filter: /^broods(\/.*)?$/ }, () => ({ path: stub }));
+    }
+  };
+}
+function toolShimSource(bundlePath, explicitPath, entry) {
+  const from = JSON.stringify(bundlePath);
+  if (explicitPath) {
+    return `import __toolModule from ${from};
+const __impl = typeof __toolModule === "function" ? __toolModule() : __toolModule;
+export default { name: __impl.name, execute: (input, options) => __impl.execute(options.context, input) };
+`;
+  }
+  return `import { ${entry.exportName} as __tool } from ${from};
+export default { name: ${JSON.stringify(entry.resource.name)}, execute: (input, options) => __tool.execute(input, options) };
+`;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeBundleComments(bundle, bundlePath, manifestPath) {
+  const sourceComment = new RegExp(`^// .*${escapeRegExp(basename(bundlePath))}$`, "gm");
+  return bundle.replace(/^\/\/ .*tool-adapter\.mjs$/gm, () => "// tool-adapter.mjs").replace(/^\/\/ .*broods-stub\.mjs$/gm, () => "// broods-stub.mjs").replace(sourceComment, () => `// ${manifestPath}`);
+}
 function normalizeProjectName(name) {
   return name.replace(/^@/, "").replace(/\//g, "-").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
 
 // src/codegen.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir2, writeFile as writeFile3 } from "fs/promises";
 import { resolve as resolve3 } from "path";
 async function writeGeneratedFiles(manifest, ids, cwd = process.cwd(), aliases = {}, endpoint = null, channels = []) {
   const dir = resolve3(cwd, PROJECT_DIR, GENERATED_DIR);
   const scopedIds = idsForManifest(ids, manifest);
   await mkdir2(dir, { recursive: true });
-  await writeFile2(resolve3(dir, "ids.ts"), idsFile(scopedIds), "utf8");
-  await writeFile2(resolve3(dir, "api.ts"), apiFile(manifest, scopedIds, aliases, endpoint, channels), "utf8");
-  await writeFile2(resolve3(dir, "resources.ts"), resourcesFile(manifest), "utf8");
-  await writeFile2(resolve3(dir, "dataModel.ts"), dataModelFile(), "utf8");
+  await writeFile3(resolve3(dir, "ids.ts"), idsFile(scopedIds), "utf8");
+  await writeFile3(resolve3(dir, "api.ts"), apiFile(manifest, scopedIds, aliases, endpoint, channels), "utf8");
+  await writeFile3(resolve3(dir, "resources.ts"), resourcesFile(manifest), "utf8");
+  await writeFile3(resolve3(dir, "dataModel.ts"), dataModelFile(), "utf8");
 }
 function idsForManifest(ids, manifest) {
   const namesByKind = {
@@ -1169,7 +1280,9 @@ class BroodsSyncClient {
     this.fetchImpl = options.fetch ?? fetch;
   }
   async getManifest(project, environment) {
-    const response = await this.request(project, environment, "/manifest", { method: "GET" });
+    const response = await this.request(project, environment, "/manifest", {
+      method: "GET"
+    });
     if (response.status === 404)
       return null;
     await assertOk(response, "Fetch manifest failed");
@@ -1185,7 +1298,9 @@ class BroodsSyncClient {
     return await response.json();
   }
   async getRuntimeKey(project, environment) {
-    const response = await this.request(project, environment, "/runtime-key", { method: "GET" });
+    const response = await this.request(project, environment, "/runtime-key", {
+      method: "GET"
+    });
     if (response.status === 404)
       return null;
     await assertOk(response, "Fetch runtime key failed");
@@ -1209,7 +1324,9 @@ class BroodsSyncClient {
     await assertOk(response, "Set environment variable failed");
   }
   async listEnv(project, environment) {
-    const response = await this.request(project, environment, "/env", { method: "GET" });
+    const response = await this.request(project, environment, "/env", {
+      method: "GET"
+    });
     await assertOk(response, "List environment variables failed");
     const payload = await response.json();
     return payload.variables ?? [];
@@ -1274,7 +1391,10 @@ class BroodsSyncClient {
   }
 }
 function diffManifests(local, remote) {
-  const remoteResources = new Map((remote?.resources ?? []).map((entry) => [`${entry.kind}:${entry.name}`, entry]));
+  const remoteResources = new Map((remote?.resources ?? []).map((entry) => [
+    `${entry.kind}:${entry.name}`,
+    entry
+  ]));
   const localResources = new Map(local.resources.map((entry) => [`${entry.kind}:${entry.name}`, entry]));
   const entries = [];
   const unmatchedLocal = [];
@@ -1284,7 +1404,11 @@ function diffManifests(local, remote) {
     if (!remoteResource) {
       unmatchedLocal.push({ key, resource });
     } else if (stableJson(snapshotResource(remoteResource)) !== stableJson(snapshotResource(resource))) {
-      entries.push({ operation: "update", kind: resource.kind, name: resource.name });
+      entries.push({
+        operation: "update",
+        kind: resource.kind,
+        name: resource.name
+      });
     }
   }
   for (const [key, resource] of remoteResources) {
@@ -1309,12 +1433,20 @@ function diffManifests(local, remote) {
   }
   for (const { key, resource } of unmatchedLocal) {
     if (!renamedLocalKeys.has(key)) {
-      entries.push({ operation: "create", kind: resource.kind, name: resource.name });
+      entries.push({
+        operation: "create",
+        kind: resource.kind,
+        name: resource.name
+      });
     }
   }
   for (const { key, resource } of unmatchedRemote) {
     if (!renamedRemoteKeys.has(key)) {
-      entries.push({ operation: "delete", kind: resource.kind, name: resource.name });
+      entries.push({
+        operation: "delete",
+        kind: resource.kind,
+        name: resource.name
+      });
     }
   }
   return entries.sort((a, b) => diffSortKey(a).localeCompare(diffSortKey(b)));
@@ -1353,7 +1485,10 @@ function normalizeEnvRefs(value) {
     if (record.__beeblastEnv === true && typeof record.name === "string") {
       return `\${${record.name}}`;
     }
-    return Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, normalizeEnvRefs(entry)]));
+    return Object.fromEntries(Object.entries(record).map(([key, entry]) => [
+      key,
+      normalizeEnvRefs(entry)
+    ]));
   }
   return value;
 }
@@ -1426,6 +1561,15 @@ async function* readSseStream(body) {
 // src/client.ts
 var DEFAULT_CORE_BASE_URL = "https://gateway.broods.app";
 
+class IngressAcceptedError extends Error {
+  accepted;
+  constructor(accepted) {
+    super(`Ingress ${accepted.eventId} was accepted asynchronously with status ${accepted.status ?? "queued"}`);
+    this.accepted = accepted;
+    this.name = "IngressAcceptedError";
+  }
+}
+
 class BroodsClient {
   baseUrl;
   apiKey;
@@ -1484,6 +1628,9 @@ class BroodsClient {
     const response = await this.openStream(body, targetUrl);
     if (!response.ok)
       throw new Error(`Run failed: ${response.status} ${await response.text()}`);
+    if (response.status === 202) {
+      throw new IngressAcceptedError(normalizeAsyncAccepted(await response.json(), body));
+    }
     if (!response.body)
       throw new Error("Run response has no body");
     for await (const data of readSseStream(response.body)) {
@@ -1541,7 +1688,7 @@ class BroodsClient {
       if (options.signal?.aborted)
         throw new Error("Async status polling aborted.");
       const payload = await this.getAsyncStatus(status, options);
-      if (payload.status === "awaiting_approval" || payload.status === "completed" || payload.status === "failed" || payload.status === "not_found") {
+      if (payload.status === "awaiting_approval" || payload.status === "completed" || payload.status === "failed" || payload.status === "expired" || payload.status === "not_found") {
         return payload;
       }
       await sleep(intervalMs, options.signal);
@@ -1688,6 +1835,8 @@ function directRunBody(input, prefix) {
     eventId,
     conversationKey: input.conversationKey ?? eventId,
     events: resolveRunEvents(input),
+    ...input.mode !== undefined ? { mode: input.mode } : {},
+    ...input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {},
     ...input.system !== undefined ? { system: input.system } : {},
     ...input.model !== undefined ? { model: input.model } : {}
   };
@@ -1703,11 +1852,16 @@ function normalizeAsyncAccepted(payload, requestBody) {
   const status = parseStatusUrl(statusUrl);
   if (!status.statusId)
     throw new Error("Async response statusUrl missing status id");
+  const eventId = typeof payload.eventId === "string" ? payload.eventId : status.statusId;
+  const acceptedStatus = payload.status;
+  const requestedMode = payload.requestedMode;
   return {
     statusUrl,
     statusId: status.statusId,
-    eventId: status.statusId,
-    agentId: status.agentId ?? requestBody.agentId
+    eventId,
+    agentId: status.agentId ?? requestBody.agentId,
+    ...acceptedStatus === "accepted" || acceptedStatus === "queued" || acceptedStatus === "applied" || acceptedStatus === "processing" ? { status: acceptedStatus } : {},
+    ...requestedMode === "reject" || requestedMode === "followup" || requestedMode === "collect" || requestedMode === "steer" ? { requestedMode } : {}
   };
 }
 function parseStatusUrl(statusUrl) {
@@ -1841,6 +1995,8 @@ class BroodsWebSocketClient {
         events: resolveRunEvents(input),
         sessionId: input.sessionId,
         ...input.eventId !== undefined ? { eventId: input.eventId } : {},
+        ...input.mode !== undefined ? { mode: input.mode } : {},
+        ...input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {},
         ...input.system !== undefined ? { system: input.system } : {},
         ...input.model !== undefined ? { model: input.model } : {}
       }));
@@ -1851,16 +2007,17 @@ class BroodsWebSocketClient {
       const payload = parseServerMessage(event.data);
       if (!payload)
         return;
-      handlers.onMessage?.(payload);
-      switch (payload.type) {
+      const effective = unwrapServerMessage(payload, handlers);
+      handlers.onMessage?.(effective);
+      switch (effective.type) {
         case "meta":
-          handlers.onMeta?.(payload);
+          handlers.onMeta?.(effective);
           break;
         case "done":
           finish();
           break;
         case "error":
-          fail(new Error(formatWireError(payload.error)));
+          fail(new Error(formatWireError(effective.error)));
           break;
       }
     };
@@ -1876,6 +2033,57 @@ class BroodsWebSocketClient {
     };
     return {
       url,
+      sendControl(message) {
+        if (socket.readyState !== WS_OPEN)
+          throw new Error("WebSocket is not open");
+        socket.send(JSON.stringify({ type: "control", ...message }));
+      },
+      close
+    };
+  }
+  attach(input, handlers = {}) {
+    const WebSocketImpl = this.resolveWebSocket();
+    const url = this.buildUrl(input);
+    const socket = new WebSocketImpl(url);
+    let closed = false;
+    const close = (code = 1000, reason = "client closed") => {
+      if (closed)
+        return;
+      closed = true;
+      if (socket.readyState === WS_OPEN || socket.readyState === WS_CONNECTING)
+        socket.close(code, reason);
+    };
+    socket.onopen = () => socket.send(JSON.stringify({
+      type: "attach",
+      ...input,
+      signal: undefined,
+      agent: undefined
+    }));
+    socket.onmessage = (event) => {
+      if (typeof event.data !== "string")
+        return;
+      const payload = parseServerMessage(event.data);
+      if (!payload)
+        return;
+      const effective = unwrapServerMessage(payload, handlers);
+      handlers.onMessage?.(effective);
+      if (effective.type === "done")
+        handlers.onDone?.();
+      if (effective.type === "error")
+        handlers.onError?.(new Error(formatWireError(effective.error)));
+    };
+    socket.onerror = () => handlers.onError?.(webSocketAccessError(this.baseUrl));
+    socket.onclose = (event) => {
+      if (!closed && event.code !== 1000)
+        handlers.onError?.(new Error(event.reason || "WebSocket connection closed."));
+    };
+    return {
+      url,
+      sendControl(message) {
+        if (socket.readyState !== WS_OPEN)
+          throw new Error("WebSocket is not open");
+        socket.send(JSON.stringify({ type: "control", ...message }));
+      },
       close
     };
   }
@@ -1968,6 +2176,13 @@ function normalizeWebSocketServiceUrl(value) {
 function webSocketAccessError(baseUrl) {
   return new Error(`Cannot access the WebSocket service at ${baseUrl}.`);
 }
+function unwrapServerMessage(payload, handlers) {
+  if (payload.type !== "output")
+    return payload;
+  const output = payload;
+  handlers.onOutput?.(output);
+  return output.data;
+}
 function parseServerMessage(data) {
   try {
     const value = JSON.parse(data);
@@ -2595,7 +2810,7 @@ function renderStreamPart(part, state) {
 // package.json
 var package_default = {
   name: "broods",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "CLI + TypeScript SDK for the broods agent platform.",
   type: "module",
   license: "MIT",
@@ -2645,17 +2860,17 @@ var package_default = {
     node: ">=22"
   },
   dependencies: {
-    "@chat-adapter/discord": "^4.31.0",
-    "@chat-adapter/github": "^4.31.0",
-    "@chat-adapter/slack": "^4.31.0",
-    "@chat-adapter/telegram": "^4.31.0",
-    ai: "^7.0.11"
+    "@chat-adapter/discord": "^4.35.0",
+    "@chat-adapter/github": "^4.35.0",
+    "@chat-adapter/slack": "^4.35.0",
+    "@chat-adapter/telegram": "^4.35.0",
+    ai: "^7.0.37"
   },
   devDependencies: {
     "@types/bun": "^1.3.14",
-    rollup: "^4.53.3",
+    rollup: "^4.62.2",
     typescript: "^6.0.3",
-    "rollup-plugin-dts": "^6.3.0"
+    "rollup-plugin-dts": "^6.4.1"
   }
 };
 
@@ -2676,7 +2891,7 @@ Commands:
   init                 Create a broods/ project shell
   login                Authenticate with WorkOS through the dashboard
   dev                  Watch + sync Development AND live-tail agent logs (like \`convex dev\`);
-                       confirms before deleting; auto-pushes env.NAME values from .env.local
+                       confirms before deleting; auto-pushes env("NAME") values from .env.local
   dev --once           Sync Development a single time and exit (no watch, no log stream)
   diff                 Show local desired state vs remote state
   deploy               Sync Production once; writes BROODS_API_KEY to .env.local
@@ -2686,7 +2901,7 @@ Commands:
   env list             List environment variable names (values stay hidden)
   env rm <name>        Remove an environment variable
   stream               Stream live logs for the whole project/environment (Ctrl+C to stop)
-  logs                 Backfill recent logs then live-tail; default 100 lines
+  logs                 Backfill recent logs then live-tail; all levels, default 100 lines
                        (--errors / --level warn filter to WARN+; -n/--limit <n> changes backfill size)
   agent list           List the agents in the current project/environment scope
   agent get <name>     Show an agent's resources (model, sandbox, workspaces, tools, channels)
@@ -2761,8 +2976,10 @@ async function init(args) {
   await writeStarter(resolve4(root, ".gitignore"), `_generated
 .cache
 `, force);
+  const dashboardUrl = optionValue(args, "--dashboard-url") ?? DEFAULT_DASHBOARD_URL;
   await writeLocalEnvDefaults({
-    dashboardUrl: optionValue(args, "--dashboard-url") ?? DEFAULT_DASHBOARD_URL,
+    dashboardUrl,
+    baseUrl: gatewayUrlForDashboard(dashboardUrl),
     project: optionValue(args, "--project") ?? inferProjectName(process.cwd()),
     environment: optionValue(args, "--env") ?? "development",
     region: optionValue(args, "--region") ?? DEFAULT_SERVICE_REGION,
@@ -2782,6 +2999,7 @@ async function login(args) {
   const environment = optionValue(args, "--env") ?? process.env.BROODS_ENVIRONMENT ?? "development";
   await writeLocalEnvDefaults({
     dashboardUrl: auth.dashboardUrl ?? dashboardUrl,
+    baseUrl: auth.baseUrl,
     project,
     environment,
     region: optionValue(args, "--region") ?? process.env.BROODS_REGION ?? DEFAULT_SERVICE_REGION,
@@ -2816,7 +3034,10 @@ async function diff(args) {
     command: "dev"
   });
   const auth = await requireAuth(optionValue(args, "--base-url") ?? config.baseUrl);
-  const client = new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token });
+  const client = new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  });
   const remote = await client.getManifest(manifest.project, manifest.environment);
   printDiffEntries(diffManifests(manifest, remote?.manifest ?? null));
 }
@@ -2828,7 +3049,10 @@ async function deploy(args) {
     useRuntimeEnvironment: false
   });
   const auth = await requireAuth(optionValue(args, "--base-url") ?? config.baseUrl);
-  const client = new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token });
+  const client = new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  });
   const result = await client.putManifest(manifest, hasFlag(args, "--prune"), hasFlag(args, "--rotate-key"));
   await writeGeneratedFiles(manifest, result.ids, process.cwd(), resourceAliases, result.deployment, channels);
   await ensureGitIgnore();
@@ -2869,7 +3093,7 @@ async function dev(args) {
     printReadyLine(performance.now() - start);
     return;
   }
-  const declinedFile = join4(tmpdir(), `broods-declined-${process.pid}.txt`);
+  const declinedFile = join4(tmpdir2(), `broods-declined-${process.pid}.txt`);
   const childEnv = {
     ...process.env,
     BROODS_DECLINED_FILE: declinedFile,
@@ -2932,7 +3156,12 @@ async function streamDevLogs(args, signal) {
   }
   const minLevel = resolveMinLevel(args);
   try {
-    for await (const entry of subscribeObservabilityLogs({ baseUrl: creds.baseUrl, apiKey: creds.apiKey, project, environment }, { backfill: 0, minLevel, signal })) {
+    for await (const entry of subscribeObservabilityLogs({
+      baseUrl: creds.baseUrl,
+      apiKey: creds.apiKey,
+      project,
+      environment
+    }, { backfill: 0, minLevel, signal })) {
       console.log(formatObservabilityEntry(entry));
     }
   } catch (error) {
@@ -2964,6 +3193,7 @@ async function ensureLocalDevDefaults(args) {
   const values = parseEnv2(current);
   const missing = [
     "BROODS_DASHBOARD_URL",
+    "BROODS_BASE_URL",
     "BROODS_PROJECT",
     "BROODS_ENVIRONMENT",
     "BROODS_REGION"
@@ -2980,7 +3210,10 @@ async function ensureLocalDevDefaults(args) {
   let region = optionValue(args, "--region") ?? process.env.BROODS_REGION ?? DEFAULT_SERVICE_REGION;
   if (process.stdin.isTTY && needsProject) {
     const auth = await requireAuthOrLogin(dashboardUrl);
-    const client = new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token });
+    const client = new BroodsSyncClient({
+      baseUrl: auth.baseUrl,
+      token: auth.token
+    });
     const context = await getOnboardingContextOrFallback(client, auth);
     const selectedContext = await selectOnboardingOrg(client, context);
     project = await selectOnboardingProject(selectedContext, project);
@@ -2997,6 +3230,7 @@ async function ensureLocalDevDefaults(args) {
   }
   await writeLocalEnvDefaults({
     dashboardUrl,
+    baseUrl: runtime.baseUrl ?? gatewayUrlForDashboard(dashboardUrl),
     project,
     environment,
     region,
@@ -3022,13 +3256,15 @@ async function getOnboardingContextOrFallback(client, auth) {
     printWarning("CLI onboarding endpoint is not available yet; using the org from the current login.");
     return {
       currentOrgId: auth.org.id,
-      orgs: [{
-        id: auth.org.id,
-        name: auth.org.name,
-        slug: auth.org.slug,
-        role: "admin",
-        accountStatus: "active"
-      }],
+      orgs: [
+        {
+          id: auth.org.id,
+          name: auth.org.name,
+          slug: auth.org.slug,
+          role: "admin",
+          accountStatus: "active"
+        }
+      ],
       projects: []
     };
   }
@@ -3057,7 +3293,11 @@ async function selectOnboardingProject(context, inferred) {
   if (context.projects.length === 0) {
     return promptText("Project name", inferred);
   }
-  const createNew = { kind: "create", name: defaultProjectName(context, inferred), slug: "" };
+  const createNew = {
+    kind: "create",
+    name: defaultProjectName(context, inferred),
+    slug: ""
+  };
   const choices = [
     ...context.projects,
     createNew
@@ -3068,12 +3308,12 @@ async function selectOnboardingProject(context, inferred) {
   }
   return selected.name;
 }
-function runSyncChild(args, env3) {
+function runSyncChild(args, env2) {
   return new Promise((resolvePromise, reject) => {
     const entryPoint = process.argv[1] ?? "";
     const child = spawn2(process.execPath, [entryPoint, "dev", "--once", ...args], {
       stdio: "inherit",
-      env: env3
+      env: env2
     });
     child.on("error", reject);
     child.on("exit", (code, signal) => {
@@ -3092,7 +3332,10 @@ async function syncDev(args) {
     command: "dev"
   });
   const auth = await requireAuth(optionValue(args, "--base-url") ?? config.baseUrl);
-  const client = new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token });
+  const client = new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  });
   const remote = await client.getManifest(manifest.project, manifest.environment);
   const diff2 = diffManifests(manifest, remote?.manifest ?? null);
   printDiffEntries(diff2.filter((entry) => entry.operation !== "delete"));
@@ -3192,7 +3435,7 @@ async function loadEnvSyncCache() {
 async function saveEnvSyncCache(cache) {
   const path = envSyncCachePath();
   await mkdir3(resolve4(path, ".."), { recursive: true });
-  await writeFile3(path, `${JSON.stringify(cache, null, 2)}
+  await writeFile4(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
 async function rememberEnvSyncValue(scopeKey, project, environment, name, value) {
@@ -3233,7 +3476,7 @@ async function rememberDeclinedDeletes(keys) {
   const path = process.env.BROODS_DECLINED_FILE;
   if (!path || keys.length === 0)
     return;
-  await writeFile3(path, `${keys.join(`
+  await writeFile4(path, `${keys.join(`
 `)}
 `, { flag: "a" });
 }
@@ -3241,7 +3484,7 @@ async function clearDeclinedDeletes() {
   const path = process.env.BROODS_DECLINED_FILE;
   if (!path)
     return;
-  await writeFile3(path, "", "utf8");
+  await writeFile4(path, "", "utf8");
 }
 async function envCommand(args) {
   const subcommand = args[0];
@@ -3259,7 +3502,10 @@ async function envCommand(args) {
     command: "dev"
   });
   const auth = await requireAuth(optionValue(args, "--base-url") ?? config.baseUrl);
-  const client = new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token });
+  const client = new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  });
   const scopeKey = envSyncScopeKey(auth.baseUrl, auth.token);
   const target = `${manifest.project}/${manifest.environment}`;
   if (isList) {
@@ -3308,7 +3554,7 @@ function resolveMinLevel(args) {
     return "WARN";
   const raw = optionValue(args, "--level");
   if (!raw)
-    return "WARN";
+    return;
   const upper = raw.toUpperCase();
   if (upper === "WARN" || upper === "WARNING")
     return "WARN";
@@ -3402,7 +3648,10 @@ async function loadAgentsWithIds(args) {
     command: "dev"
   });
   const auth = await requireAuth(optionValue(args, "--base-url") ?? config.baseUrl);
-  const remote = await new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token }).getManifest(manifest.project, manifest.environment);
+  const remote = await new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  }).getManifest(manifest.project, manifest.environment);
   const agents = manifest.resources.filter((resource) => resource.kind === "agent").map((resource) => ({
     name: resource.name,
     config: resource.config ?? {},
@@ -3479,18 +3728,27 @@ async function run(args) {
   const agent = manifest.resources.find((resource) => resource.kind === "agent" && resource.name === agentName);
   if (!agent)
     throw new Error(`Unknown local agent: ${agentName}`);
-  const remote = await new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token }).getManifest(manifest.project, manifest.environment);
+  const remote = await new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  }).getManifest(manifest.project, manifest.environment);
   const agentId = remote?.ids.agents[agentName];
   if (!agentId)
     throw new Error(`Agent ${agentName} is not synced yet. Run broods dev --once or broods deploy first.`);
-  const runtimeKey = await new BroodsSyncClient({ baseUrl: auth.baseUrl, token: auth.token }).getRuntimeKey(manifest.project, manifest.environment).catch(() => null);
+  const runtimeKey = await new BroodsSyncClient({
+    baseUrl: auth.baseUrl,
+    token: auth.token
+  }).getRuntimeKey(manifest.project, manifest.environment).catch(() => null);
   if (runtimeKey?.apiKey) {
     await writeEnvValue("BROODS_API_KEY", runtimeKey.apiKey);
   }
   if (agent.config.publicAccess !== true) {
     printWarning(`\u26A0 Agent "${agentName}" does not set publicAccess: true. The public endpoint is secured by default; ` + "if the deployed agent has not enabled it, this run will be refused.");
   }
-  const client = new BroodsClient(runtimeKey?.apiKey ? { apiKey: runtimeKey.apiKey } : {});
+  const client = new BroodsClient({
+    baseUrl: optionValue(args, "--base-url") ?? process.env.BROODS_BASE_URL ?? process.env.BROODS_HOST ?? auth.baseUrl,
+    ...runtimeKey?.apiKey ? { apiKey: runtimeKey.apiKey } : {}
+  });
   const state = createRenderState();
   try {
     for await (const part of client.stream({
@@ -3517,7 +3775,7 @@ async function run(args) {
 }
 async function writeStarter(path, contents, force) {
   try {
-    await writeFile3(path, contents, { flag: force ? "w" : "wx" });
+    await writeFile4(path, contents, { flag: force ? "w" : "wx" });
   } catch (error) {
     if (error.code === "EEXIST")
       return;
@@ -3537,7 +3795,7 @@ async function ensureGitIgnore() {
 ` : missing.join(`
 `) + `
 `;
-  await writeFile3(path, body, "utf8");
+  await writeFile4(path, body, "utf8");
 }
 async function writeLocalEnvDefaults(options) {
   const path = resolve4(process.cwd(), ".env.local");
@@ -3545,14 +3803,13 @@ async function writeLocalEnvDefaults(options) {
   const values = parseEnv2(current);
   const nextValues = {
     BROODS_DASHBOARD_URL: options.dashboardUrl,
+    ...options.baseUrl ? { BROODS_BASE_URL: options.baseUrl } : {},
     BROODS_PROJECT: options.project,
     BROODS_ENVIRONMENT: options.environment,
     BROODS_REGION: options.region
   };
   const lines = current ? current.replace(/\n?$/, `
-`).split(/\n/) : [
-    "# Local broods CLI settings. Tokens are stored outside the repo."
-  ];
+`).split(/\n/) : ["# Local broods CLI settings. Tokens are stored outside the repo."];
   let changed = false;
   for (const [key, value] of Object.entries(nextValues)) {
     if (values[key] !== undefined && !options.force)
@@ -3571,7 +3828,7 @@ async function writeLocalEnvDefaults(options) {
   const body = `${lines.filter((line, index, all) => !(line === "" && index === all.length - 1)).join(`
 `)}
 `;
-  await writeFile3(path, body, "utf8");
+  await writeFile4(path, body, "utf8");
 }
 async function writeEnvValue(key, value) {
   const path = resolve4(process.cwd(), ".env.local");
@@ -3587,7 +3844,7 @@ async function writeEnvValue(key, value) {
   const body = `${lines.filter((line, i, all) => !(line === "" && i === all.length - 1)).join(`
 `)}
 `;
-  await writeFile3(path, body, "utf8");
+  await writeFile4(path, body, "utf8");
 }
 async function readTextIfExists(path) {
   try {
@@ -3653,33 +3910,29 @@ function starterAgent() {
 ` + `// A Lambda sandbox: a fresh, ephemeral bash environment created per run.
 ` + `export const lambdaSandbox = defineSandbox({
 ` + `  name: "lambda-sandbox",
-` + `  config: {
-` + `    provider: "lambda",
-` + `    network: { mode: "deny-all" },
-` + `    permissionMode: "bypass",
-` + `    timeout: 60,
-` + `  },
+` + `  provider: "lambda",
+` + `  network: { mode: "deny-all" },
+` + `  permissionMode: "bypass",
+` + `  timeout: 60,
 ` + `});
 
 ` + `export const myAgent = defineAgent({
 ` + `  name: "my-agent",
-` + `  config: {
-` + `    provider: {
-` + `      openai: { apiKey: env.OPENAI_API_KEY },
-` + `    },
-` + `    model: {
-` + `      provider: "openai",
-` + `      modelId: "gpt-5.5",
-` + `    },
-` + `    agent: {
-` + `      system: "You are a helpful assistant.",
-` + `    },
-` + `    sandbox: lambdaSandbox,
-` + `    // Expose the public runtime endpoint (SSE/WebSocket) so the API key and
-` + `    // \`broods run\` can reach this agent. Off by default \u2014 secured: a
-` + `    // private agent is only reachable via internal endpoints or channel webhooks.
-` + `    publicAccess: true,
+` + `  provider: {
+` + `    openai: { apiKey: env("OPENAI_API_KEY") },
+` + `  },
+` + `  model: {
+` + `    provider: "openai",
+` + `    modelId: "gpt-5.5",
+` + `  },
+` + `  agent: {
+` + `    system: "You are a helpful assistant.",
 ` + `  },
+` + `  sandbox: lambdaSandbox,
+` + `  // Expose the public runtime endpoint (SSE/WebSocket) so the API key and
+` + `  // \`broods run\` can reach this agent. Off by default \u2014 secured: a
+` + `  // private agent is only reachable via internal endpoints or channel webhooks.
+` + `  publicAccess: true,
 ` + `});
 `;
 }