@band-ai/sdk 0.1.6 → 0.2.0

package/dist/chunk-US226AS4.js

@@ -0,0 +1,130 @@
+// src/platform/streaming/disconnectReason.ts
+import { z } from "zod";
+var UPGRADE_CODES = [
+  "invalid_on_conflict",
+  "connection_conflict",
+  "too_many_requests",
+  "tracking_failed"
+];
+var UPGRADE_REASONS = {
+  invalid_on_conflict: {
+    status: 400,
+    message: "Invalid websocket conflict policy.",
+    retryable: false
+  },
+  connection_conflict: {
+    status: 409,
+    message: "Websocket connection conflict.",
+    retryable: false
+  },
+  too_many_requests: {
+    status: 429,
+    message: "Too many websocket connection attempts.",
+    retryable: true
+  },
+  tracking_failed: {
+    status: 503,
+    message: "Websocket connection tracking failed.",
+    retryable: true
+  }
+};
+var upgradeErrorSchema = z.object({
+  status: z.number(),
+  body: z.preprocess(
+    (body) => {
+      if (typeof body !== "string") {
+        return body;
+      }
+      try {
+        return JSON.parse(body);
+      } catch {
+        return null;
+      }
+    },
+    z.object({
+      error: z.object({
+        code: z.enum(UPGRADE_CODES),
+        message: z.string().optional(),
+        retry_after: z.number().nullable().optional(),
+        request_id: z.string().nullable().optional()
+      })
+    })
+  ),
+  headers: z.record(z.unknown()).optional()
+});
+var WebSocketDisconnectError = class extends Error {
+  reason;
+  constructor(reason) {
+    super(reason.message);
+    this.name = "WebSocketDisconnectError";
+    this.reason = reason;
+  }
+};
+function parseSupersedeDisconnectReason(payload) {
+  if (typeof payload.reason !== "string" || typeof payload.message !== "string") {
+    return null;
+  }
+  return {
+    source: "agent_control",
+    code: payload.reason,
+    message: payload.message,
+    retryable: false,
+    retryAfter: typeof payload.retry_after === "number" ? payload.retry_after : null,
+    targetSocketId: typeof payload.target_socket_id === "string" ? payload.target_socket_id : null,
+    correlationId: typeof payload.correlation_id === "string" ? payload.correlation_id : null
+  };
+}
+function parseUpgradeDisconnectReason(event) {
+  const parsed = upgradeErrorSchema.safeParse(event);
+  if (!parsed.success) {
+    return null;
+  }
+  const { status, body, headers } = parsed.data;
+  const {
+    code,
+    message,
+    retry_after: retryAfter,
+    request_id: requestId
+  } = body.error;
+  const reason = UPGRADE_REASONS[code];
+  if (status !== reason.status) {
+    return null;
+  }
+  return {
+    source: "upgrade",
+    status: reason.status,
+    code,
+    message: message ?? reason.message,
+    retryable: reason.retryable,
+    retryAfter: retryAfter ?? retryAfterFromHeaders(headers),
+    requestId: requestId ?? null
+  };
+}
+function genericCloseReason(event) {
+  return {
+    source: "websocket_close",
+    code: "websocket.closed",
+    message: "Phoenix socket closed without a platform disconnect reason.",
+    retryable: true,
+    closeCode: typeof event?.code === "number" ? event.code : null,
+    closeReason: typeof event?.reason === "string" && event.reason.length > 0 ? event.reason : null
+  };
+}
+function retryAfterFromHeaders(headers) {
+  const value = headers?.["retry-after"] ?? headers?.["Retry-After"];
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const seconds = Number(value);
+    return Number.isFinite(seconds) ? seconds : null;
+  }
+  return null;
+}
+
+export {
+  WebSocketDisconnectError,
+  parseSupersedeDisconnectReason,
+  parseUpgradeDisconnectReason,
+  genericCloseReason
+};

package/dist/{chunk-IZPV6QS6.js → chunk-WL2HNJZ6.js}

@@ -1,12 +1,26 @@
 import {
   ValidationError
-} from "./chunk-YR3BOQNW.js";
+} from "./chunk-JY75VSQK.js";
 
 // src/config/loader.ts
 import { readFileSync } from "fs";
 import yaml from "js-yaml";
 var DEFAULT_CONFIG_PATH = "./agent_config.yaml";
-var DEFAULT_ENV_PREFIX = "THENVOI_";
+var DEFAULT_ENV_PREFIX = "BAND_";
+var LEGACY_ENV_PREFIX = "THENVOI_";
+var _warnedLegacyEnvVars = /* @__PURE__ */ new Set();
+function readBandFirstEnv(env, field) {
+  const bandVar = `${DEFAULT_ENV_PREFIX}${field}`;
+  const bandValue = env[bandVar];
+  if (bandValue !== void 0) return bandValue;
+  const legacyVar = `${LEGACY_ENV_PREFIX}${field}`;
+  const legacyValue = env[legacyVar];
+  if (legacyValue !== void 0 && !_warnedLegacyEnvVars.has(legacyVar)) {
+    _warnedLegacyEnvVars.add(legacyVar);
+    console.warn(`[band] ${legacyVar} is deprecated; use ${bandVar} instead`);
+  }
+  return legacyValue;
+}
 var REQUIRED_FIELDS = ["agent_id", "api_key"];
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype", "toString", "valueOf"]);
 function toSnakeCase(key) {
@@ -90,19 +104,32 @@ function loadAgentConfig(agentKey, configPath) {
 }
 function loadAgentConfigFromEnv(options) {
   const env = options?.env ?? process.env;
-  const prefix = options?.prefix === void 0 ? DEFAULT_ENV_PREFIX : options.prefix === "" || options.prefix.endsWith("_") ? options.prefix : `${options.prefix}_`;
-  const section = normalizeKeys({
-    agent_id: env[`${prefix}AGENT_ID`],
-    api_key: env[`${prefix}API_KEY`],
-    ws_url: env[`${prefix}WS_URL`],
-    rest_url: env[`${prefix}REST_URL`]
-  });
+  let section;
+  let requiredHint;
+  if (options?.prefix === void 0) {
+    section = normalizeKeys({
+      agent_id: readBandFirstEnv(env, "AGENT_ID"),
+      api_key: readBandFirstEnv(env, "API_KEY"),
+      ws_url: readBandFirstEnv(env, "WS_URL"),
+      rest_url: readBandFirstEnv(env, "REST_URL")
+    });
+    requiredHint = `${DEFAULT_ENV_PREFIX}AGENT_ID and ${DEFAULT_ENV_PREFIX}API_KEY (legacy ${LEGACY_ENV_PREFIX}* still accepted)`;
+  } else {
+    const prefix = options.prefix === "" || options.prefix.endsWith("_") ? options.prefix : `${options.prefix}_`;
+    section = normalizeKeys({
+      agent_id: env[`${prefix}AGENT_ID`],
+      api_key: env[`${prefix}API_KEY`],
+      ws_url: env[`${prefix}WS_URL`],
+      rest_url: env[`${prefix}REST_URL`]
+    });
+    requiredHint = `${prefix}AGENT_ID and ${prefix}API_KEY`;
+  }
   try {
-    return toAgentConfigResult(section, `environment variables (${prefix}AGENT_ID, ${prefix}API_KEY)`);
+    return toAgentConfigResult(section, `environment variables (${requiredHint})`);
   } catch (error) {
     if (error instanceof ValidationError) {
       throw new ValidationError(
-        `${error.message}. Set ${prefix}AGENT_ID and ${prefix}API_KEY, or use loadAgentConfig() for agent_config.yaml.`
+        `${error.message}. Set ${requiredHint}, or use loadAgentConfig() for agent_config.yaml.`
       );
     }
     throw error;

package/dist/chunk-WLCM2OXG.js

@@ -0,0 +1,181 @@
+import {
+  MEMORY_SEGMENT,
+  MEMORY_STORE_SCOPE,
+  MEMORY_SYSTEM,
+  MEMORY_SYSTEM_TYPES,
+  MEMORY_TYPE,
+  TOOL_MODELS
+} from "./chunk-RV76SKFT.js";
+
+// src/runtime/prompts/base.ts
+var ENVIRONMENT_SECTION = `
+## Environment
+
+Multi-participant chat. Messages show sender: [Name]: content.
+Messages prefixed with [System]: are platform updates (participant changes, contact updates, etc.) \u2014 not messages from users.
+Use \`band_send_message(content, mentions)\` to respond. Plain text output is not delivered.
+Mentions use handles: @<username> for users, @<username>/<agent-name> for agents.`;
+var MULTI_AGENT_RULES_SECTION = `## CRITICAL: Delegate When You Cannot Help Directly
+
+You have NO internet access and NO real-time data. When asked about weather, news, stock prices,
+or any current information you cannot answer directly:
+
+1. Call \`band_lookup_peers()\` to find available specialized agents
+2. If a relevant agent exists, call \`band_add_participant(name)\` to add them
+3. Ask that agent using \`band_send_message(question, mentions=[agent_handle])\`
+4. Wait for their response and relay it back to the user
+
+NEVER say "I can't do that" without first checking if another agent can help via \`band_lookup_peers()\`.
+
+## CRITICAL: Do NOT Remove Agents Automatically
+
+After adding an agent to help with a task:
+1. Ask your question and wait for their response
+2. Relay their response back to the original requester
+3. **Do NOT remove the agent** - they stay silent unless mentioned and may be useful for follow-ups
+
+Only remove agents if the user explicitly requests it.
+
+## CRITICAL: Always Relay Information Back to the Requester
+
+When someone asks you to get information from another agent:
+1. Ask the other agent for the information
+2. When you receive the response, IMMEDIATELY relay it back to the ORIGINAL REQUESTER
+3. Do NOT just thank the helper agent - the requester is waiting for their answer!`;
+var THINKING_SECTION = `## IMPORTANT: Always Share Your Thinking
+
+You MUST call \`band_send_event(content, message_type="thought")\` BEFORE every action.
+This is required so users can see your reasoning process.`;
+var EXAMPLES_SECTION = `## Examples
+
+### Simple question - answer directly
+[John Doe]: What's 2+2?
+-> band_send_event("Simple arithmetic, answering directly.", message_type="thought")
+-> band_send_message("4", mentions=["@john"])
+
+### User asks about weather (you cannot answer directly)
+[John Doe]: What's the weather in Tokyo?
+-> band_send_event("I can't check weather directly. Looking for a Weather Agent.", message_type="thought")
+-> band_lookup_peers()
+-> band_send_event("Found Weather Agent. Adding to room.", message_type="thought")
+-> band_add_participant("Weather Agent")
+-> band_send_message("What's the weather in Tokyo?", mentions=["@john/weather-agent"])
+
+[Weather Agent]: Tokyo is 15\xB0C and cloudy.
+-> band_send_event("Got weather response. Relaying back to John Doe.", message_type="thought")
+-> band_send_message("The weather in Tokyo is 15\xB0C and cloudy.", mentions=["@john"])
+
+### No suitable agent available
+[John Doe]: What's the stock price of AAPL?
+-> band_send_event("I can't check stock prices. Looking for a Stock Agent.", message_type="thought")
+-> band_lookup_peers()
+-> band_send_event("No stock agent available. Must inform user.", message_type="thought")
+-> band_send_message("I don't have access to stock prices, and there's no specialized agent available to help with that.", mentions=["@john"])
+
+### Follow-up question in same conversation
+[John Doe]: What about London?
+-> band_send_event("Follow-up weather question. Asking Weather Agent.", message_type="thought")
+-> band_send_message("What's the weather in London?", mentions=["@john/weather-agent"])
+
+[Weather Agent]: London is 8\xB0C and rainy.
+-> band_send_event("Got London weather. Relaying to John Doe.", message_type="thought")
+-> band_send_message("London is 8\xB0C and rainy.", mentions=["@john"])`;
+var BASE_INSTRUCTIONS = [
+  ENVIRONMENT_SECTION,
+  MULTI_AGENT_RULES_SECTION,
+  THINKING_SECTION,
+  EXAMPLES_SECTION
+].join("\n\n") + "\n";
+
+// src/runtime/prompts/memory.ts
+var MEMORY_INTRO = `## Memory Tools
+
+You have access to memory tools for storing and retrieving information
+across conversations. Use \`band_store_memory\` to persist important
+information and \`band_list_memories\` / \`band_get_memory\` to recall it.
+Use \`band_supersede_memory\` to mark outdated memories and
+\`band_archive_memory\` to hide memories that should be preserved.`;
+function longTermPattern(label, type, segment, scope) {
+  return {
+    label,
+    system: MEMORY_SYSTEM.long_term,
+    type,
+    segment,
+    scope
+  };
+}
+var COMMON_MEMORY_PATTERNS = [
+  longTermPattern("Facts learned about a specific agent/entity", MEMORY_TYPE.semantic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("Events involving a specific person/agent", MEMORY_TYPE.episodic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("A user's preferences or profile info", MEMORY_TYPE.semantic, MEMORY_SEGMENT.user, MEMORY_STORE_SCOPE.subject),
+  longTermPattern("Org-wide knowledge or how to perform a task", MEMORY_TYPE.procedural, MEMORY_SEGMENT.tool, MEMORY_STORE_SCOPE.organization)
+];
+function renderMemoryPattern(pattern) {
+  return `- ${pattern.label}: \`system="${pattern.system}"\`, \`type="${pattern.type}"\`, \`segment="${pattern.segment}"\`, \`scope="${pattern.scope}"\``;
+}
+var MEMORY_COMMON_PATTERNS = [
+  "Common patterns:",
+  ...COMMON_MEMORY_PATTERNS.map(renderMemoryPattern)
+].join("\n");
+var MEMORY_SCOPE_GUIDANCE = `Prefer \`scope="${MEMORY_STORE_SCOPE.subject}"\` whenever the memory is about a specific person or agent, so it
+stays attached to that subject rather than leaking org-wide. Storing with \`scope="${MEMORY_STORE_SCOPE.subject}"\` requires a
+real \`subject_id\` UUID, so resolve it first via \`band_lookup_peers\` or the participant list.
+Reserve \`scope="${MEMORY_STORE_SCOPE.organization}"\` for knowledge that is genuinely shared across the whole organization and
+is not about any one subject.`;
+function quoteChoices(values) {
+  return values.map((value) => `\`"${value}"\``).join(" | ");
+}
+function memoryTypeLines() {
+  return Object.entries(MEMORY_SYSTEM_TYPES).map(([system, types]) => `  - ${system}: ${quoteChoices(types)}`).join("\n");
+}
+function buildMemorySection() {
+  const storeMemoryProps = TOOL_MODELS.band_store_memory.properties;
+  const systems = storeMemoryProps.system.enum;
+  const segments = storeMemoryProps.segment.enum;
+  const scopes = storeMemoryProps.scope.enum;
+  const fieldRules = `When calling \`band_store_memory\`, the \`system\`, \`type\`, \`segment\`, and \`scope\` fields
+must use these exact values (case-sensitive):
+
+- **system**: ${quoteChoices(systems)}
+- **type** (must match the chosen system):
+${memoryTypeLines()}
+- **segment**: ${quoteChoices(segments)}
+- **scope**: ${quoteChoices(scopes)}`;
+  return [MEMORY_INTRO, fieldRules, MEMORY_COMMON_PATTERNS, MEMORY_SCOPE_GUIDANCE].join("\n\n");
+}
+var MEMORY_SECTION = buildMemorySection();
+
+// src/runtime/prompts/templates.ts
+var TEMPLATES = {
+  default: `You are {agent_name}, {agent_description}.
+
+{custom_section}
+` + BASE_INSTRUCTIONS
+};
+function renderSystemPrompt(options) {
+  const agentName = options?.agentName ?? "Agent";
+  const agentDescription = options?.agentDescription ?? "An AI assistant";
+  const customSection = options?.customSection ?? "";
+  const includeBaseInstructions = options?.includeBaseInstructions ?? true;
+  if (!includeBaseInstructions) {
+    return `You are ${agentName}, ${agentDescription}.
+
+${customSection}`.trim();
+  }
+  const template = options?.template ?? "default";
+  const templateString = TEMPLATES[template] ?? TEMPLATES.default;
+  const parts = [
+    templateString.replaceAll("{agent_name}", agentName).replaceAll("{agent_description}", agentDescription).replaceAll("{custom_section}", customSection)
+  ];
+  if (options?.capabilities?.memory) {
+    parts.push(MEMORY_SECTION);
+  }
+  return parts.join("\n\n");
+}
+
+export {
+  BASE_INSTRUCTIONS,
+  MEMORY_SECTION,
+  TEMPLATES,
+  renderSystemPrompt
+};

package/dist/config.cjs

@@ -40,13 +40,13 @@ var import_node_fs = require("fs");
 var import_js_yaml = __toESM(require("js-yaml"), 1);
 
 // src/core/errors.ts
-var ThenvoiSdkError = class extends Error {
+var BandSdkError = class extends Error {
   constructor(message, cause) {
     super(message, cause !== void 0 ? { cause } : void 0);
-    this.name = "ThenvoiSdkError";
+    this.name = "BandSdkError";
   }
 };
-var ValidationError = class extends ThenvoiSdkError {
+var ValidationError = class extends BandSdkError {
   constructor(message, cause) {
     super(message, cause);
     this.name = "ValidationError";
@@ -55,7 +55,21 @@ var ValidationError = class extends ThenvoiSdkError {
 
 // src/config/loader.ts
 var DEFAULT_CONFIG_PATH = "./agent_config.yaml";
-var DEFAULT_ENV_PREFIX = "THENVOI_";
+var DEFAULT_ENV_PREFIX = "BAND_";
+var LEGACY_ENV_PREFIX = "THENVOI_";
+var _warnedLegacyEnvVars = /* @__PURE__ */ new Set();
+function readBandFirstEnv(env, field) {
+  const bandVar = `${DEFAULT_ENV_PREFIX}${field}`;
+  const bandValue = env[bandVar];
+  if (bandValue !== void 0) return bandValue;
+  const legacyVar = `${LEGACY_ENV_PREFIX}${field}`;
+  const legacyValue = env[legacyVar];
+  if (legacyValue !== void 0 && !_warnedLegacyEnvVars.has(legacyVar)) {
+    _warnedLegacyEnvVars.add(legacyVar);
+    console.warn(`[band] ${legacyVar} is deprecated; use ${bandVar} instead`);
+  }
+  return legacyValue;
+}
 var REQUIRED_FIELDS = ["agent_id", "api_key"];
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype", "toString", "valueOf"]);
 function toSnakeCase(key) {
@@ -139,19 +153,32 @@ function loadAgentConfig(agentKey, configPath) {
 }
 function loadAgentConfigFromEnv(options) {
   const env = options?.env ?? process.env;
-  const prefix = options?.prefix === void 0 ? DEFAULT_ENV_PREFIX : options.prefix === "" || options.prefix.endsWith("_") ? options.prefix : `${options.prefix}_`;
-  const section = normalizeKeys({
-    agent_id: env[`${prefix}AGENT_ID`],
-    api_key: env[`${prefix}API_KEY`],
-    ws_url: env[`${prefix}WS_URL`],
-    rest_url: env[`${prefix}REST_URL`]
-  });
+  let section;
+  let requiredHint;
+  if (options?.prefix === void 0) {
+    section = normalizeKeys({
+      agent_id: readBandFirstEnv(env, "AGENT_ID"),
+      api_key: readBandFirstEnv(env, "API_KEY"),
+      ws_url: readBandFirstEnv(env, "WS_URL"),
+      rest_url: readBandFirstEnv(env, "REST_URL")
+    });
+    requiredHint = `${DEFAULT_ENV_PREFIX}AGENT_ID and ${DEFAULT_ENV_PREFIX}API_KEY (legacy ${LEGACY_ENV_PREFIX}* still accepted)`;
+  } else {
+    const prefix = options.prefix === "" || options.prefix.endsWith("_") ? options.prefix : `${options.prefix}_`;
+    section = normalizeKeys({
+      agent_id: env[`${prefix}AGENT_ID`],
+      api_key: env[`${prefix}API_KEY`],
+      ws_url: env[`${prefix}WS_URL`],
+      rest_url: env[`${prefix}REST_URL`]
+    });
+    requiredHint = `${prefix}AGENT_ID and ${prefix}API_KEY`;
+  }
   try {
-    return toAgentConfigResult(section, `environment variables (${prefix}AGENT_ID, ${prefix}API_KEY)`);
+    return toAgentConfigResult(section, `environment variables (${requiredHint})`);
   } catch (error) {
     if (error instanceof ValidationError) {
       throw new ValidationError(
-        `${error.message}. Set ${prefix}AGENT_ID and ${prefix}API_KEY, or use loadAgentConfig() for agent_config.yaml.`
+        `${error.message}. Set ${requiredHint}, or use loadAgentConfig() for agent_config.yaml.`
       );
     }
     throw error;

package/dist/config.d.cts

@@ -13,7 +13,13 @@ interface LoadAgentConfigFromEnvOptions {
 }
 /** Load agent credentials from a YAML config file (defaults to `./agent_config.yaml`). */
 declare function loadAgentConfig(agentKey?: string, configPath?: string): AgentConfigResult;
-/** Load agent credentials from environment variables (prefix defaults to `THENVOI_`). */
+/**
+ * Load agent credentials from environment variables. With no explicit prefix the
+ * default is `BAND_` with a per-field fallback to the legacy `THENVOI_` variable
+ * (Band wins independently for each of AGENT_ID/API_KEY/WS_URL/REST_URL, and each
+ * legacy variable used warns once per process). An explicit prefix — including an
+ * empty string — is used exactly, with no fallback or warning.
+ */
 declare function loadAgentConfigFromEnv(options?: LoadAgentConfigFromEnvOptions): AgentCredentials;
 
 export { type AgentConfigResult, type AgentCredentials, type LoadAgentConfigFromEnvOptions, loadAgentConfig, loadAgentConfigFromEnv };

package/dist/config.d.ts

@@ -13,7 +13,13 @@ interface LoadAgentConfigFromEnvOptions {
 }
 /** Load agent credentials from a YAML config file (defaults to `./agent_config.yaml`). */
 declare function loadAgentConfig(agentKey?: string, configPath?: string): AgentConfigResult;
-/** Load agent credentials from environment variables (prefix defaults to `THENVOI_`). */
+/**
+ * Load agent credentials from environment variables. With no explicit prefix the
+ * default is `BAND_` with a per-field fallback to the legacy `THENVOI_` variable
+ * (Band wins independently for each of AGENT_ID/API_KEY/WS_URL/REST_URL, and each
+ * legacy variable used warns once per process). An explicit prefix — including an
+ * empty string — is used exactly, with no fallback or warning.
+ */
 declare function loadAgentConfigFromEnv(options?: LoadAgentConfigFromEnvOptions): AgentCredentials;
 
 export { type AgentConfigResult, type AgentCredentials, type LoadAgentConfigFromEnvOptions, loadAgentConfig, loadAgentConfigFromEnv };

package/dist/config.js

@@ -1,8 +1,8 @@
 import {
   loadAgentConfig,
   loadAgentConfigFromEnv
-} from "./chunk-IZPV6QS6.js";
-import "./chunk-YR3BOQNW.js";
+} from "./chunk-WL2HNJZ6.js";
+import "./chunk-JY75VSQK.js";
 export {
   loadAgentConfig,
   loadAgentConfigFromEnv