broods 0.1.0

package/dist/index.js

@@ -0,0 +1,845 @@
+// @bun
+// src/run-input.ts
+function resolveRunEvents(input) {
+  if (input.events && input.input !== undefined) {
+    throw new Error("Run input accepts either `input` or `events`, not both");
+  }
+  if (input.events && input.events.length > 0)
+    return input.events;
+  if (typeof input.input === "string") {
+    return [{ role: "user", content: [{ type: "text", text: input.input }] }];
+  }
+  throw new Error("Run input requires `input` (string) or a non-empty `events` array");
+}
+// src/stream.ts
+async function* readSseStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split(`
+`);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith("data: "))
+          yield line.slice(6);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+// src/observability-contracts.ts
+var MAX_OBSERVABILITY_BACKFILL = 500;
+function isObservabilityClientMessage(v) {
+  if (typeof v !== "object" || v === null)
+    return false;
+  const msg = v;
+  if (msg["type"] === "subscribe") {
+    const stream = msg["stream"];
+    if (stream !== "logs" && stream !== "traces")
+      return false;
+    const backfill = msg["backfill"];
+    if (backfill !== undefined && (typeof backfill !== "number" || !Number.isSafeInteger(backfill) || backfill < 0 || backfill > MAX_OBSERVABILITY_BACKFILL))
+      return false;
+    const minLevel = msg["minLevel"];
+    if (minLevel !== undefined && minLevel !== "INFO" && minLevel !== "WARN" && minLevel !== "ERROR")
+      return false;
+    return true;
+  }
+  if (msg["type"] === "unsubscribe") {
+    const stream = msg["stream"];
+    return stream === "logs" || stream === "traces";
+  }
+  return false;
+}
+// src/runtime-config.ts
+import { existsSync, readFileSync } from "fs";
+import { join as join2, resolve } from "path";
+
+// src/config.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var PROJECT_DIR = "broods";
+var GENERATED_DIR = "_generated";
+var USER_CONFIG_PATH = join(homedir(), ".broods", "config.json");
+async function readStoredAuth() {
+  const envToken = process.env.BROODS_TOKEN;
+  const envUrl = process.env.BROODS_DASHBOARD_URL;
+  if (envToken && envUrl) {
+    return {
+      dashboardUrl: envUrl,
+      token: envToken,
+      createdAt: new Date().toISOString()
+    };
+  }
+  try {
+    return JSON.parse(await readFile(USER_CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeStoredAuth(config) {
+  await mkdir(dirname(USER_CONFIG_PATH), { recursive: true });
+  await writeFile(USER_CONFIG_PATH, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+function stripTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+
+// src/runtime-config.ts
+var loadedEnvForCwd = null;
+function loadBroodsRuntimeConfig(cwd = process.cwd()) {
+  loadEnvFiles(cwd);
+  const stored = readStoredAuthSync();
+  return {
+    dashboardUrl: process.env.BROODS_DASHBOARD_URL ?? stored?.dashboardUrl,
+    token: process.env.BROODS_TOKEN ?? stored?.token,
+    project: process.env.BROODS_PROJECT,
+    environment: process.env.BROODS_ENVIRONMENT
+  };
+}
+function loadEnvFiles(cwd) {
+  const root = resolve(cwd);
+  if (loadedEnvForCwd === root)
+    return;
+  loadedEnvForCwd = root;
+  const originallySet = new Set(Object.keys(process.env));
+  for (const file of [".env", ".env.local"]) {
+    const path = join2(root, file);
+    if (!existsSync(path))
+      continue;
+    for (const [key, value] of Object.entries(parseEnv(readFileSync(path, "utf8")))) {
+      if (!originallySet.has(key))
+        process.env[key] = value;
+    }
+  }
+}
+function parseEnv(source) {
+  const values = {};
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const assignment = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const eq = assignment.indexOf("=");
+    if (eq <= 0)
+      continue;
+    const key = assignment.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    values[key] = unquoteEnvValue(assignment.slice(eq + 1).trim());
+  }
+  return values;
+}
+function unquoteEnvValue(value) {
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\n/g, `
+`).replace(/\\"/g, '"');
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  const commentIndex = value.indexOf(" #");
+  return commentIndex >= 0 ? value.slice(0, commentIndex).trimEnd() : value;
+}
+function readStoredAuthSync() {
+  try {
+    const value = JSON.parse(readFileSync(USER_CONFIG_PATH, "utf8"));
+    if (typeof value.dashboardUrl !== "string" || typeof value.token !== "string")
+      return null;
+    return {
+      dashboardUrl: stripTrailingSlash(value.dashboardUrl),
+      token: value.token
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/client.ts
+var DEFAULT_CORE_BASE_URL = "https://gateway.broods.app";
+
+class BroodsClient {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  constructor(options = {}) {
+    loadBroodsRuntimeConfig();
+    this.baseUrl = normalizeHttpServiceUrl(options.baseUrl || options.host || process.env.BROODS_BASE_URL || process.env.BROODS_HOST || DEFAULT_CORE_BASE_URL);
+    this.apiKey = options.apiKey || process.env.BROODS_API_KEY || undefined;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  channelWebhookUrl(ref) {
+    return `${this.baseUrl}${ref.webhookPath.startsWith("/") ? "" : "/"}${ref.webhookPath}`;
+  }
+  agent(refOrName, agentId) {
+    if (typeof refOrName === "string") {
+      const name = refOrName;
+      const id = agentId ?? "";
+      if (!id)
+        throw new Error(`Agent ${name} is missing a generated id. Run broods deploy first.`);
+      return {
+        id,
+        run: (input) => this.run({ ...input, agentName: name, agentId: id }),
+        runAsync: (input) => this.runAsync({ ...input, agentName: name, agentId: id }),
+        stream: (input) => this.stream({ ...input, agentName: name, agentId: id })
+      };
+    }
+    const ref = refOrName;
+    if (!ref.id)
+      throw new Error(`Agent ${ref.name} is missing a generated id. Run broods deploy first.`);
+    return {
+      id: ref.id,
+      run: (input) => this.run(ref, input),
+      runAsync: (input) => this.runAsync(ref, input),
+      stream: (input) => this.stream(ref, input)
+    };
+  }
+  async run(refOrInput, maybeInput) {
+    const events = [];
+    let text = "";
+    const stream = maybeInput ? this.stream(refOrInput, maybeInput) : this.stream(refOrInput);
+    for await (const part of stream) {
+      events.push(part);
+      if (part.type === "text-delta")
+        text += part.text;
+    }
+    return { text, events };
+  }
+  async* stream(refOrInput, maybeInput) {
+    const input = maybeInput ? {
+      ...maybeInput,
+      agentId: refOrInput.id,
+      agentName: refOrInput.name
+    } : refOrInput;
+    const body = directRunBody(input, "cli");
+    const targetUrl = maybeInput ? this.scopedUrl(refOrInput) : this.baseUrl;
+    const response = await this.openStream(body, targetUrl);
+    if (!response.ok)
+      throw new Error(`Run failed: ${response.status} ${await response.text()}`);
+    if (!response.body)
+      throw new Error("Run response has no body");
+    for await (const data of readSseStream(response.body)) {
+      let part;
+      try {
+        part = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (part.type === "error")
+        throw new Error(`Agent run failed: ${formatStreamError(part.error)}`);
+      yield part;
+    }
+  }
+  async runAsync(refOrInput, maybeInput) {
+    const input = maybeInput ? {
+      ...maybeInput,
+      agentId: refOrInput.id,
+      agentName: refOrInput.name
+    } : refOrInput;
+    const body = directRunBody(input, "async");
+    const response = await this.fetchJson(`${this.baseUrl}/async`, {
+      method: "POST",
+      headers: this.apiKeyHeaders(),
+      body: JSON.stringify(body)
+    });
+    if (response.status !== 202) {
+      throw new Error(`Async run failed: ${response.status} ${await responseErrorDetails(response, "202 JSON")}`);
+    }
+    const accepted = normalizeAsyncAccepted(await response.json(), body);
+    return {
+      ...accepted,
+      conversationKey: body.conversationKey,
+      poll: () => this.getAsyncStatus(accepted),
+      wait: (options) => this.waitForAsyncStatus(accepted, options)
+    };
+  }
+  async getAsyncStatus(status, options = {}) {
+    const statusUrl = this.resolveStatusUrl(status, options);
+    const response = await this.fetchJson(statusUrl, {
+      method: "GET",
+      headers: this.apiKeyHeaders()
+    });
+    if (response.status === 404)
+      return { status: "not_found" };
+    if (!response.ok)
+      throw new Error(`Status check failed: ${response.status} ${await response.text()}`);
+    return await response.json();
+  }
+  async waitForAsyncStatus(status, options = {}) {
+    const deadline = Date.now() + (options.timeoutMs ?? 180000);
+    const intervalMs = options.intervalMs ?? 2000;
+    while (Date.now() < deadline) {
+      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") {
+        return payload;
+      }
+      await sleep(intervalMs, options.signal);
+    }
+    throw new Error("Polling timeout");
+  }
+  async createCron(input) {
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons`, {
+      method: "POST",
+      headers: this.apiKeyHeaders(),
+      body: JSON.stringify(resolveCronInput(input))
+    });
+    if (response.status !== 201)
+      throw new Error(`Create cron job failed: ${response.status} ${await cronErrorDetails(response)}`);
+    return await response.json();
+  }
+  async listCrons() {
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons`, {
+      method: "GET",
+      headers: this.apiKeyHeaders()
+    });
+    if (!response.ok)
+      throw new Error(`List cron jobs failed: ${response.status} ${await cronErrorDetails(response)}`);
+    const payload = await response.json();
+    return payload.crons;
+  }
+  async getCron(cronId) {
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons/${encodeURIComponent(cronId)}`, {
+      method: "GET",
+      headers: this.apiKeyHeaders()
+    });
+    if (response.status === 404)
+      return null;
+    if (!response.ok)
+      throw new Error(`Get cron job failed: ${response.status} ${await cronErrorDetails(response)}`);
+    return await response.json();
+  }
+  async listCronRuns(cronId, options = {}) {
+    const params = new URLSearchParams;
+    if (options.limit !== undefined)
+      params.set("limit", String(options.limit));
+    const suffix = params.size > 0 ? `?${params}` : "";
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons/${encodeURIComponent(cronId)}/runs${suffix}`, {
+      method: "GET",
+      headers: this.apiKeyHeaders()
+    });
+    if (!response.ok)
+      throw new Error(`List cron job runs failed: ${response.status} ${await cronErrorDetails(response)}`);
+    const payload = await response.json();
+    return payload.runs;
+  }
+  async updateCron(cronId, patch) {
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons/${encodeURIComponent(cronId)}`, {
+      method: "PATCH",
+      headers: this.apiKeyHeaders(),
+      body: JSON.stringify(patch)
+    });
+    if (!response.ok)
+      throw new Error(`Update cron job failed: ${response.status} ${await cronErrorDetails(response)}`);
+    return await response.json();
+  }
+  async deleteCron(cronId) {
+    const response = await this.fetchJson(`${this.baseUrl}/accounts/me/crons/${encodeURIComponent(cronId)}`, {
+      method: "DELETE",
+      headers: this.apiKeyHeaders()
+    });
+    if (response.status === 404)
+      return false;
+    if (!response.ok)
+      throw new Error(`Delete cron job failed: ${response.status} ${await cronErrorDetails(response)}`);
+    const payload = await response.json();
+    return payload.deleted;
+  }
+  scopedUrl(ref) {
+    if (ref.projectSlug && ref.environmentSlug && ref.endpointId) {
+      return `${this.baseUrl}/v1/${encodeURIComponent(ref.projectSlug)}` + `/agents/${encodeURIComponent(ref.environmentSlug)}/${encodeURIComponent(ref.endpointId)}`;
+    }
+    return this.baseUrl;
+  }
+  async openStream(body, targetUrl) {
+    if (this.apiKey) {
+      return await this.fetchCore(body, targetUrl, {
+        Authorization: `Bearer ${this.apiKey}`
+      });
+    }
+    throw new Error(`BroodsClient streams directly from the core service at ${this.baseUrl}. ` + "Provide apiKey. " + "For a self-hosted core service, set host/baseUrl or BROODS_HOST/BROODS_BASE_URL.");
+  }
+  async fetchCore(body, targetUrl, authHeaders) {
+    try {
+      return await this.fetchImpl(targetUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+          ...authHeaders
+        },
+        body: JSON.stringify(body)
+      });
+    } catch (error) {
+      throw new Error(`Cannot access the broods core service at ${targetUrl}. ` + `The SDK uses ${DEFAULT_CORE_BASE_URL} by default; set host/baseUrl or BROODS_HOST/BROODS_BASE_URL ` + `to your own core service URL if your account uses a custom deployment. ` + `Cause: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  apiKeyHeaders() {
+    if (!this.apiKey) {
+      throw new Error("BroodsClient requires apiKey or BROODS_API_KEY.");
+    }
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+  }
+  async fetchJson(targetUrl, init) {
+    try {
+      return await this.fetchImpl(targetUrl, {
+        ...init,
+        headers: {
+          "Content-Type": "application/json",
+          ...init.headers ?? {}
+        }
+      });
+    } catch (error) {
+      throw new Error(`Cannot access the broods core service at ${targetUrl}. ` + `Cause: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  resolveStatusUrl(status, options) {
+    if (typeof status !== "string")
+      return status.statusUrl;
+    if (/^https?:\/\//.test(status))
+      return status;
+    if (!options.agentId)
+      throw new Error("Polling by status id requires agentId.");
+    return statusUrlFor(this.baseUrl, status, options.agentId);
+  }
+}
+function normalizeHttpServiceUrl(value) {
+  const trimmed = value.trim();
+  const withProtocol = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(trimmed) ? trimmed : `https://${trimmed}`;
+  return stripTrailingSlash(withProtocol);
+}
+function directRunBody(input, prefix) {
+  const eventId = input.eventId ?? `${prefix}-${Date.now()}`;
+  return {
+    agentId: input.agentId,
+    eventId,
+    conversationKey: input.conversationKey ?? eventId,
+    events: resolveRunEvents(input),
+    ...input.system !== undefined ? { system: input.system } : {},
+    ...input.model !== undefined ? { model: input.model } : {}
+  };
+}
+function normalizeAsyncAccepted(payload, requestBody) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Async response must be an object");
+  }
+  const statusUrl = payload.statusUrl;
+  if (typeof statusUrl !== "string" || statusUrl.length === 0) {
+    throw new Error("Async response missing statusUrl");
+  }
+  const status = parseStatusUrl(statusUrl);
+  if (!status.statusId)
+    throw new Error("Async response statusUrl missing status id");
+  return {
+    statusUrl,
+    statusId: status.statusId,
+    eventId: status.statusId,
+    agentId: status.agentId ?? requestBody.agentId
+  };
+}
+function parseStatusUrl(statusUrl) {
+  const url = new URL(statusUrl);
+  const match = url.pathname.match(/\/status\/([^/]+)$/);
+  return {
+    statusId: match?.[1] ? decodeURIComponent(match[1]) : undefined,
+    agentId: url.searchParams.get("agentId") ?? undefined
+  };
+}
+function statusUrlFor(baseUrl, statusId, agentId) {
+  return `${normalizeHttpServiceUrl(baseUrl)}/status/${encodeURIComponent(statusId)}?agentId=${encodeURIComponent(agentId)}`;
+}
+async function responseErrorDetails(response, expected) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.toLowerCase().includes("text/event-stream")) {
+    await response.body?.cancel().catch(() => {});
+    return `expected ${expected}, but the server returned an SSE stream. This usually means the core deployment routed /async to the direct streaming runner instead of the async handler.`;
+  }
+  const text = await response.text();
+  if (text.length <= 2000)
+    return text;
+  return `${text.slice(0, 2000)}... [truncated ${text.length - 2000} chars]`;
+}
+async function cronErrorDetails(response) {
+  const text = await response.text();
+  if (text.includes("Request body must include eventId and conversationKey")) {
+    return `${text}. Cron job APIs must be served by the configured baseUrl. ` + "Prefer defining stable cron jobs with defineCron(...) in broods/ and syncing with `broods dev` or `broods deploy`.";
+  }
+  return text;
+}
+function resolveCronInput(input) {
+  if ("agentId" in input)
+    return input;
+  const agent = input.agent;
+  const agentId = typeof agent === "string" ? agent : agent.id;
+  const { agent: _agent, ...rest } = input;
+  return { ...rest, agentId };
+}
+function sleep(ms, signal) {
+  return new Promise((resolvePromise, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Async status polling aborted."));
+      return;
+    }
+    const timer = setTimeout(resolvePromise, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new Error("Async status polling aborted."));
+    }, { once: true });
+  });
+}
+function formatStreamError(error) {
+  if (typeof error === "string")
+    return error;
+  if (!error || typeof error !== "object")
+    return String(error);
+  const err = error;
+  const detail = err.data?.error?.message ?? err.message ?? err.responseBody ?? JSON.stringify(error);
+  const prefix = err.name ? `${err.name}: ` : "";
+  const status = err.statusCode ? ` (HTTP ${err.statusCode})` : "";
+  return `${prefix}${detail}${status}`;
+}
+// src/websocket.ts
+var DEFAULT_CONNECT_TIMEOUT_MS = 2000;
+var WS_CONNECTING = 0;
+var WS_OPEN = 1;
+var LAMBDA_FUNCTION_URL_HOST_RE = /\.lambda-url\.[a-z0-9-]+\.on\.aws$/i;
+
+class BroodsWebSocketClient {
+  baseUrl;
+  apiKey;
+  WebSocketImpl;
+  connectTimeoutMs;
+  constructor(options = {}) {
+    loadBroodsRuntimeConfig();
+    this.baseUrl = normalizeWebSocketServiceUrl(options.baseUrl || process.env.BROODS_WEBSOCKET_URL || options.host || process.env.BROODS_BASE_URL || process.env.BROODS_HOST || DEFAULT_CORE_BASE_URL);
+    this.apiKey = options.apiKey || process.env.BROODS_API_KEY || "";
+    if (!this.apiKey)
+      throw new Error("BroodsWebSocketClient requires apiKey or BROODS_API_KEY.");
+    this.WebSocketImpl = options.WebSocket;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+  }
+  subscribe(input, handlers = {}) {
+    const WebSocketImpl = this.resolveWebSocket();
+    const url = this.buildUrl(input);
+    const agentId = resolveAgentId(input);
+    const accessError = webSocketAccessError(this.baseUrl);
+    const socket = new WebSocketImpl(url);
+    let opened = false;
+    let closed = false;
+    const timeout = setTimeout(() => {
+      if (!opened)
+        fail(accessError);
+    }, this.connectTimeoutMs);
+    const close = (code = 1000, reason = "client closed") => {
+      if (closed)
+        return;
+      closed = true;
+      clearTimeout(timeout);
+      input.signal?.removeEventListener("abort", onAbort);
+      if (socket.readyState === WS_OPEN || socket.readyState === WS_CONNECTING) {
+        socket.close(code, reason);
+      }
+    };
+    const fail = (error) => {
+      handlers.onError?.(error);
+      close(1011, "websocket error");
+    };
+    const finish = () => {
+      handlers.onDone?.();
+      close(1000, "done");
+    };
+    const onAbort = () => {
+      if (socket.readyState === WS_OPEN) {
+        socket.send(JSON.stringify({ type: "cancel" }));
+      }
+      fail(new Error("WebSocket run aborted."));
+    };
+    input.signal?.addEventListener("abort", onAbort, { once: true });
+    socket.onopen = () => {
+      opened = true;
+      clearTimeout(timeout);
+      if (input.signal?.aborted) {
+        onAbort();
+        return;
+      }
+      socket.send(JSON.stringify({
+        type: "execute",
+        agentId,
+        events: resolveRunEvents(input),
+        sessionId: input.sessionId,
+        ...input.eventId !== undefined ? { eventId: input.eventId } : {},
+        ...input.system !== undefined ? { system: input.system } : {},
+        ...input.model !== undefined ? { model: input.model } : {}
+      }));
+    };
+    socket.onmessage = (event) => {
+      if (typeof event.data !== "string")
+        return;
+      const payload = parseServerMessage(event.data);
+      if (!payload)
+        return;
+      handlers.onMessage?.(payload);
+      switch (payload.type) {
+        case "meta":
+          handlers.onMeta?.(payload);
+          break;
+        case "done":
+          finish();
+          break;
+        case "error":
+          fail(new Error(formatWireError(payload.error)));
+          break;
+      }
+    };
+    socket.onerror = () => {
+      fail(accessError);
+    };
+    socket.onclose = (event) => {
+      clearTimeout(timeout);
+      input.signal?.removeEventListener("abort", onAbort);
+      if (closed || event.code === 1000)
+        return;
+      fail(new Error(event.reason || "WebSocket connection closed."));
+    };
+    return {
+      url,
+      close
+    };
+  }
+  async* stream(input) {
+    const queue = [];
+    let done = false;
+    let error = null;
+    let wake = null;
+    const wakeReader = () => {
+      wake?.();
+      wake = null;
+    };
+    const subscription = this.subscribe(input, {
+      onMessage(message) {
+        queue.push(message);
+        wakeReader();
+      },
+      onDone() {
+        done = true;
+        wakeReader();
+      },
+      onError(nextError) {
+        error = nextError;
+        wakeReader();
+      }
+    });
+    try {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift();
+          continue;
+        }
+        if (error)
+          throw error;
+        if (done)
+          return;
+        await new Promise((resolve2) => {
+          wake = resolve2;
+        });
+      }
+    } finally {
+      subscription.close();
+    }
+  }
+  buildUrl(input) {
+    const endpointId = resolveEndpointId(input);
+    const projectSlug = input.projectSlug ?? input.agent?.projectSlug;
+    const environmentSlug = input.environmentSlug ?? input.agent?.environmentSlug;
+    const projectPrefix = projectSlug ? `/${projectSlug}` : "";
+    const environmentPrefix = environmentSlug ? `/${environmentSlug}` : "";
+    const wsBaseUrl = toWebSocketBaseUrl(this.baseUrl);
+    return `${wsBaseUrl}/v1${projectPrefix}/agents${environmentPrefix}/${encodeURIComponent(endpointId)}/ws` + `?token=${encodeURIComponent(this.apiKey)}`;
+  }
+  resolveWebSocket() {
+    const WebSocketImpl = this.WebSocketImpl ?? globalThis.WebSocket;
+    if (!WebSocketImpl) {
+      throw new Error("WebSocket is not available. Pass a WebSocket implementation in BroodsWebSocketClient options.");
+    }
+    return WebSocketImpl;
+  }
+}
+function resolveAgentId(input) {
+  const agentId = input.agentId ?? input.agent?.id ?? input.endpointId;
+  if (!agentId) {
+    throw new Error("WebSocket run requires agent, agentId, or endpointId.");
+  }
+  return agentId;
+}
+function resolveEndpointId(input) {
+  const endpointId = input.endpointId ?? input.agent?.endpointId ?? input.agent?.id;
+  if (!endpointId) {
+    throw new Error("WebSocket run requires agent or endpointId.");
+  }
+  return endpointId;
+}
+function toWebSocketBaseUrl(url) {
+  const parsed = new URL(normalizeWebSocketServiceUrl(url));
+  if (parsed.protocol === "https:")
+    parsed.protocol = "wss:";
+  if (parsed.protocol === "http:")
+    parsed.protocol = "ws:";
+  return stripTrailingSlash(parsed.toString());
+}
+function normalizeWebSocketServiceUrl(value) {
+  const trimmed = value.trim();
+  if (/^wss?:\/\//.test(trimmed))
+    return stripTrailingSlash(trimmed);
+  return normalizeHttpServiceUrl(trimmed);
+}
+function webSocketAccessError(baseUrl) {
+  const host = new URL(baseUrl).hostname;
+  if (LAMBDA_FUNCTION_URL_HOST_RE.test(host)) {
+    return new Error(`Cannot access the WebSocket service at ${baseUrl}. AWS Lambda Function URLs do not support WebSocket upgrades; ` + "set BROODS_WEBSOCKET_URL or BROODS_HOST to the deployed WebSocket gateway URL instead.");
+  }
+  return new Error(`Cannot access the WebSocket service at ${baseUrl}.`);
+}
+function parseServerMessage(data) {
+  try {
+    const value = JSON.parse(data);
+    return typeof value === "object" && value !== null && typeof value.type === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+function formatWireError(error) {
+  if (typeof error === "string")
+    return error;
+  if (error && typeof error === "object" && typeof error.message === "string") {
+    return error.message;
+  }
+  return error === undefined ? "WebSocket stream error." : JSON.stringify(error);
+}
+// src/resources.ts
+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) {
+  return { __beeblastEnv: true, name };
+}, {
+  get(target, property, receiver) {
+    if (typeof property === "string")
+      return { __beeblastEnv: true, name: property };
+    return Reflect.get(target, property, receiver);
+  }
+});
+function defineResource(kind, input) {
+  if (input.config === undefined) {
+    throw new Error(`Resource "${input.name}" must include config`);
+  }
+  return {
+    [RESOURCE_MARKER]: true,
+    kind,
+    name: input.name,
+    ...input.description ? { description: input.description } : {},
+    config: input.config
+  };
+}
+function defineChannel(type, config) {
+  return {
+    [CHANNEL_MARKER]: true,
+    kind: "channel",
+    type,
+    config
+  };
+}
+function defineTelegramChannel(config) {
+  return defineChannel("telegram", config);
+}
+function defineGitHubChannel(config) {
+  return defineChannel("github", config);
+}
+function defineSlackChannel(config) {
+  return defineChannel("slack", config);
+}
+function defineDiscordChannel(config) {
+  return defineChannel("discord", config);
+}
+function definePancakeChannel(config) {
+  const { ignoreTagIds, ...channelConfig } = config;
+  return defineChannel("pancake", {
+    ...channelConfig,
+    ...ignoreTagIds === undefined ? {} : { options: { ignoreTagIds } }
+  });
+}
+function defineZaloChannel(config) {
+  return defineChannel("zalo", config);
+}
+function defineBroods(config) {
+  return { [CONFIG_MARKER]: true, config };
+}
+function defineAgent(input) {
+  return defineResource("agent", input);
+}
+function defineWorkspace(input) {
+  return defineResource("workspace", input);
+}
+function defineSandbox(input) {
+  return defineResource("sandbox", input);
+}
+function defineSkill(input) {
+  return defineResource("skill", input);
+}
+function defineTool(input) {
+  return defineResource("tool", input);
+}
+function defineCron(input) {
+  return defineResource("cron", input);
+}
+function isResource(value) {
+  return Boolean(value && typeof value === "object" && value[RESOURCE_MARKER]);
+}
+function isChannelDefinition(value) {
+  return Boolean(value && typeof value === "object" && value[CHANNEL_MARKER]);
+}
+function isBroodsConfig(value) {
+  return Boolean(value && typeof value === "object" && value[CONFIG_MARKER]);
+}
+export {
+  toWebSocketBaseUrl,
+  resolveRunEvents,
+  readSseStream,
+  normalizeHttpServiceUrl,
+  isResource,
+  isObservabilityClientMessage,
+  isChannelDefinition,
+  isBroodsConfig,
+  env,
+  defineZaloChannel,
+  defineWorkspace,
+  defineTool,
+  defineTelegramChannel,
+  defineSlackChannel,
+  defineSkill,
+  defineSandbox,
+  definePancakeChannel,
+  defineGitHubChannel,
+  defineDiscordChannel,
+  defineCron,
+  defineBroods,
+  defineAgent,
+  BroodsWebSocketClient as WebsocketClient,
+  BroodsWebSocketClient as WebSocketClient,
+  MAX_OBSERVABILITY_BACKFILL,
+  DEFAULT_CORE_BASE_URL,
+  BroodsWebSocketClient,
+  BroodsClient
+};