broods 0.3.0 → 0.4.0

package/dist/index.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 ?? [];
@@ -337,6 +355,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;
@@ -364,6 +385,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
 var envFileCache = new Map;
@@ -448,6 +483,15 @@ function readStoredAuthSync() {
 // 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;
@@ -506,6 +550,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)) {
@@ -563,7 +610,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);
@@ -710,6 +757,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 } : {}
   };
@@ -725,11 +774,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) {
@@ -862,6 +916,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 } : {}
       }));
@@ -872,16 +928,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;
       }
     };
@@ -897,6 +954,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
     };
   }
@@ -989,6 +1097,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);
@@ -1009,25 +1124,27 @@ function formatWireError(error) {
 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) {
@@ -1065,25 +1182,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]);
@@ -1103,6 +1227,7 @@ export {
   isObservabilityClientMessage,
   isChannelDefinition,
   isBroodsConfig,
+  envPlaceholder,
   env,
   defineZaloChannel,
   defineWorkspace,
@@ -1121,6 +1246,7 @@ export {
   BroodsWebSocketClient as WebsocketClient,
   BroodsWebSocketClient as WebSocketClient,
   MAX_OBSERVABILITY_BACKFILL,
+  IngressAcceptedError,
   DEFAULT_CORE_BASE_URL,
   BroodsWebSocketClient,
   BroodsClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "broods",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI + TypeScript SDK for the broods agent platform.",
   "type": "module",
   "license": "MIT",
@@ -50,16 +50,16 @@
     "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"
   }
 }