@band-ai/sdk 0.1.2

package/dist/chunk-GVEQ3RAH.js

@@ -0,0 +1,373 @@
+import {
+  ValidationError
+} from "./chunk-YR3BOQNW.js";
+
+// src/contracts/chatEvents.ts
+var CHAT_EVENT_TYPES = ["tool_call", "tool_result", "thought", "error", "task"];
+var CHAT_MESSAGE_TYPES = ["text", ...CHAT_EVENT_TYPES];
+function isChatEventType(value) {
+  return CHAT_EVENT_TYPES.includes(value);
+}
+function assertChatEventType(value) {
+  if (!isChatEventType(value)) {
+    throw new ValidationError(
+      `Invalid event message_type '${value}'. Expected one of: ${CHAT_EVENT_TYPES.join(", ")}`
+    );
+  }
+}
+
+// src/runtime/tools/schemas.ts
+var TOOL_MODELS = {
+  thenvoi_send_message: {
+    description: "Send a message to the chat room. Use this to respond to users or other agents. Messages require at least one @mention in the mentions array. You MUST use this tool to communicate \u2014 plain text responses won't reach users. When delegating, send the full task context in this message instead of assuming hidden state.",
+    properties: {
+      content: {
+        type: "string",
+        description: "The message content to send."
+      },
+      mentions: {
+        type: "array",
+        items: { type: "string" },
+        minItems: 1,
+        description: "List of participant handles to @mention. At least one required. For users: @<username> (e.g., '@john'). For agents: @<username>/<agent-name> (e.g., '@john/weather-agent'). Use the handle of someone already in the room."
+      }
+    },
+    required: ["content", "mentions"]
+  },
+  thenvoi_send_event: {
+    description: "Send an event to the chat room. No mentions required. 'thought': Share your reasoning or plan BEFORE taking actions. Explain what you're about to do and why. 'error': Report an error or problem that occurred. 'task': Report task progress or completion status. Always send a thought before complex actions to keep users informed.",
+    properties: {
+      content: {
+        type: "string",
+        description: "Human-readable event content."
+      },
+      message_type: {
+        type: "string",
+        enum: [...CHAT_EVENT_TYPES],
+        description: "Type of event."
+      },
+      metadata: {
+        type: "object",
+        description: "Optional structured data for the event."
+      }
+    },
+    required: ["content", "message_type"]
+  },
+  thenvoi_add_participant: {
+    description: "Add a participant (agent or user) to the chat room by name. IMPORTANT: Use thenvoi_lookup_peers() first to find available agents. Pass the exact peer name from thenvoi_lookup_peers, not the handle. For normal delegation, omit role or use 'member'.",
+    properties: {
+      name: {
+        type: "string",
+        description: "Name of participant to add (must match a name from thenvoi_lookup_peers)."
+      },
+      role: {
+        type: "string",
+        enum: ["owner", "admin", "member"],
+        description: "Role for the participant in this room."
+      }
+    },
+    required: ["name"]
+  },
+  thenvoi_remove_participant: {
+    description: "Remove a participant from the chat room by name.",
+    properties: {
+      name: {
+        type: "string",
+        description: "Name of the participant to remove."
+      }
+    },
+    required: ["name"]
+  },
+  thenvoi_get_participants: {
+    description: "Get a list of all participants in the current chat room.",
+    properties: {},
+    required: []
+  },
+  thenvoi_lookup_peers: {
+    description: "List available peers (agents and users) that can be added to this room. Automatically excludes peers already in the room. Returns dict with 'peers' list and 'metadata' (page, page_size, total_count, total_pages). Use this to find specialized agents (e.g., Weather Agent) when you cannot answer a question directly.",
+    properties: {
+      page: {
+        type: "integer",
+        description: "Page number."
+      },
+      page_size: {
+        type: "integer",
+        description: "Items per page (max 100).",
+        maximum: 100
+      }
+    },
+    required: []
+  },
+  thenvoi_create_chatroom: {
+    description: "Create a new chat room for a specific task or conversation.",
+    properties: {
+      task_id: {
+        type: "string",
+        description: "Associated task ID (optional)."
+      }
+    },
+    required: []
+  },
+  thenvoi_list_contacts: {
+    description: "List agent's contacts with pagination.",
+    properties: {
+      page: {
+        type: "integer",
+        description: "Page number.",
+        minimum: 1
+      },
+      page_size: {
+        type: "integer",
+        description: "Items per page.",
+        minimum: 1,
+        maximum: 100
+      }
+    },
+    required: []
+  },
+  thenvoi_add_contact: {
+    description: "Send a contact request to add someone as a contact. Returns 'pending' when request is created. Returns 'approved' when inverse request existed and was auto-accepted.",
+    properties: {
+      handle: {
+        type: "string",
+        description: "Handle of user/agent to add (e.g., '@john' or '@john/agent-name')."
+      },
+      message: {
+        type: "string",
+        description: "Optional message with the request."
+      }
+    },
+    required: ["handle"]
+  },
+  thenvoi_remove_contact: {
+    description: "Remove an existing contact by handle or ID.",
+    properties: {
+      handle: {
+        type: "string",
+        description: "Contact's handle."
+      },
+      contact_id: {
+        type: "string",
+        description: "Or contact record ID (UUID)."
+      }
+    },
+    required: []
+  },
+  thenvoi_list_contact_requests: {
+    description: "List both received and sent contact requests. Received requests are always filtered to pending status. Sent requests can be filtered by status.",
+    properties: {
+      page: {
+        type: "integer",
+        description: "Page number.",
+        minimum: 1
+      },
+      page_size: {
+        type: "integer",
+        description: "Items per page per direction (max 100).",
+        minimum: 1,
+        maximum: 100
+      },
+      sent_status: {
+        type: "string",
+        enum: ["pending", "approved", "rejected", "cancelled", "all"],
+        description: "Filter sent requests by status."
+      }
+    },
+    required: []
+  },
+  thenvoi_respond_contact_request: {
+    description: "Respond to a contact request. 'approve'/'reject': For requests you RECEIVED (handle = requester's handle). 'cancel': For requests you SENT (handle = recipient's handle).",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["approve", "reject", "cancel"],
+        description: "Action to take."
+      },
+      handle: {
+        type: "string",
+        description: "Other party's handle."
+      },
+      request_id: {
+        type: "string",
+        description: "Or request ID (UUID)."
+      }
+    },
+    required: ["action"]
+  },
+  thenvoi_list_memories: {
+    description: "List memories accessible to the agent. Returns memories about the specified subject (cross-agent sharing) and organization-wide shared memories.",
+    properties: {
+      subject_id: {
+        type: "string",
+        description: "Filter by subject UUID (required for subject-scoped queries)."
+      },
+      scope: {
+        type: "string",
+        enum: ["subject", "organization", "all"],
+        description: "Filter by scope."
+      },
+      system: {
+        type: "string",
+        enum: ["sensory", "working", "long_term"],
+        description: "Filter by memory system."
+      },
+      type: {
+        type: "string",
+        enum: [
+          "iconic",
+          "echoic",
+          "haptic",
+          "episodic",
+          "semantic",
+          "procedural"
+        ],
+        description: "Filter by memory type."
+      },
+      segment: {
+        type: "string",
+        enum: ["user", "agent", "tool", "guideline"],
+        description: "Filter by segment."
+      },
+      content_query: {
+        type: "string",
+        description: "Full-text search query."
+      },
+      page_size: {
+        type: "integer",
+        description: "Number of results per page.",
+        minimum: 1,
+        maximum: 50
+      },
+      status: {
+        type: "string",
+        enum: ["active", "superseded", "archived", "all"],
+        description: "Filter by status."
+      }
+    },
+    required: []
+  },
+  thenvoi_store_memory: {
+    description: "Store a new memory entry. The memory will be associated with the authenticated agent as the source. For subject-scoped memories, provide a subject_id. For organization-scoped memories, omit subject_id.",
+    properties: {
+      content: {
+        type: "string",
+        description: "The memory content."
+      },
+      system: {
+        type: "string",
+        enum: ["sensory", "working", "long_term"],
+        description: "Memory system tier."
+      },
+      type: {
+        type: "string",
+        enum: [
+          "iconic",
+          "echoic",
+          "haptic",
+          "episodic",
+          "semantic",
+          "procedural"
+        ],
+        description: "Memory type (must be valid for selected system)."
+      },
+      segment: {
+        type: "string",
+        enum: ["user", "agent", "tool", "guideline"],
+        description: "Logical segment."
+      },
+      thought: {
+        type: "string",
+        description: "Agent's reasoning for storing this memory."
+      },
+      scope: {
+        type: "string",
+        enum: ["subject", "organization"],
+        description: "Visibility scope."
+      },
+      subject_id: {
+        type: "string",
+        description: "UUID of the subject this memory is about (required for subject scope)."
+      },
+      metadata: {
+        type: "object",
+        description: "Additional metadata (tags, references)."
+      }
+    },
+    required: ["content", "system", "type", "segment", "thought"]
+  },
+  thenvoi_get_memory: {
+    description: "Retrieve a specific memory by ID.",
+    properties: {
+      memory_id: {
+        type: "string",
+        description: "Memory ID (UUID)."
+      }
+    },
+    required: ["memory_id"]
+  },
+  thenvoi_supersede_memory: {
+    description: "Mark a memory as superseded (soft delete). Use when information is outdated or incorrect. The memory remains for audit trail but won't appear in normal queries. Only the source agent can supersede.",
+    properties: {
+      memory_id: {
+        type: "string",
+        description: "Memory ID (UUID)."
+      }
+    },
+    required: ["memory_id"]
+  },
+  thenvoi_archive_memory: {
+    description: "Archive a memory (hide but preserve). Use when memory is valid but not currently needed. Archived memories can be restored later by humans. Only the source agent can archive.",
+    properties: {
+      memory_id: {
+        type: "string",
+        description: "Memory ID (UUID)."
+      }
+    },
+    required: ["memory_id"]
+  }
+};
+var ALL_TOOL_NAMES = new Set(Object.keys(TOOL_MODELS));
+var MEMORY_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "thenvoi_list_memories",
+  "thenvoi_store_memory",
+  "thenvoi_get_memory",
+  "thenvoi_supersede_memory",
+  "thenvoi_archive_memory"
+]);
+var CONTACT_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "thenvoi_list_contacts",
+  "thenvoi_add_contact",
+  "thenvoi_remove_contact",
+  "thenvoi_list_contact_requests",
+  "thenvoi_respond_contact_request"
+]);
+var BASE_TOOL_NAMES = new Set(
+  [...ALL_TOOL_NAMES].filter((name) => !MEMORY_TOOL_NAMES.has(name))
+);
+var CHAT_TOOL_NAMES = new Set(
+  [...BASE_TOOL_NAMES].filter((name) => !CONTACT_TOOL_NAMES.has(name))
+);
+var MCP_TOOL_PREFIX = "mcp__thenvoi__";
+function mcpToolNames(names) {
+  return [...names].sort((a, b) => a.localeCompare(b)).map((name) => `${MCP_TOOL_PREFIX}${name}`);
+}
+function getToolDescription(name) {
+  const model = TOOL_MODELS[name];
+  return model?.description ?? `Execute ${name}`;
+}
+
+export {
+  CHAT_EVENT_TYPES,
+  CHAT_MESSAGE_TYPES,
+  isChatEventType,
+  assertChatEventType,
+  TOOL_MODELS,
+  ALL_TOOL_NAMES,
+  MEMORY_TOOL_NAMES,
+  CONTACT_TOOL_NAMES,
+  BASE_TOOL_NAMES,
+  CHAT_TOOL_NAMES,
+  MCP_TOOL_PREFIX,
+  mcpToolNames,
+  getToolDescription
+};

package/dist/chunk-INA6YZTZ.js

@@ -0,0 +1,88 @@
+// src/runtime/formatters.ts
+function isMetadataMap(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function replaceUuidMentions(content, participants) {
+  if (!content || participants.length === 0) {
+    return content;
+  }
+  let next = content;
+  for (const participant of participants) {
+    const participantId = participant.id;
+    const handle = participant.handle;
+    if (typeof participantId === "string" && typeof handle === "string") {
+      next = next.replaceAll(`@[[${participantId}]]`, `@${handle}`);
+    }
+  }
+  return next;
+}
+function formatMessageForLlm(message, participants) {
+  const senderType = String(message.sender_type ?? "");
+  const senderName = String(message.sender_name ?? message.name ?? senderType);
+  const content = participants ? replaceUuidMentions(String(message.content ?? ""), participants) : String(message.content ?? "");
+  return {
+    role: senderType === "Agent" ? "assistant" : "user",
+    content,
+    sender_name: senderName,
+    sender_type: senderType,
+    message_type: String(message.message_type ?? "text"),
+    metadata: isMetadataMap(message.metadata) ? message.metadata : {}
+  };
+}
+function formatHistoryForLlm(messages, options) {
+  const excludeId = options?.excludeId;
+  const participants = options?.participants;
+  return messages.filter((message) => String(message.id ?? "") !== excludeId).map((message) => formatMessageForLlm(message, participants));
+}
+function buildParticipantsMessage(participants) {
+  if (participants.length === 0) {
+    return "## Current Participants\nNo other participants in this room.";
+  }
+  const lines = ["## Current Participants"];
+  for (const participant of participants) {
+    const participantType = String(participant.type ?? "Unknown");
+    const participantName = String(participant.name ?? "Unknown");
+    const participantHandle = String(participant.handle ?? "Unknown");
+    lines.push(`- @${participantHandle} \u2014 ${participantName} (${participantType})`);
+  }
+  lines.push("");
+  lines.push(
+    "IMPORTANT: In thenvoi_send_message mentions, always use the exact handle shown above (e.g. '@john' for users, '@john/weather-agent' for agents), NOT the display name. Handles are lowercase with no spaces."
+  );
+  return lines.join("\n");
+}
+
+// src/runtime/types.ts
+var HistoryProvider = class {
+  raw;
+  constructor(raw) {
+    this.raw = raw;
+  }
+  convert(converter) {
+    return converter.convert(this.raw);
+  }
+  get length() {
+    return this.raw.length;
+  }
+};
+var SYNTHETIC_SENDER_TYPE = "System";
+var SYNTHETIC_CONTACT_EVENTS_SENDER_ID = "contact-events";
+var SYNTHETIC_CONTACT_EVENTS_SENDER_NAME = "Contact Events";
+function ensureHandlePrefix(handle) {
+  if (!handle) {
+    return null;
+  }
+  return handle.startsWith("@") ? handle : `@${handle}`;
+}
+
+export {
+  replaceUuidMentions,
+  formatMessageForLlm,
+  formatHistoryForLlm,
+  buildParticipantsMessage,
+  HistoryProvider,
+  SYNTHETIC_SENDER_TYPE,
+  SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
+  SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
+  ensureHandlePrefix
+};

package/dist/chunk-IZPV6QS6.js

@@ -0,0 +1,115 @@
+import {
+  ValidationError
+} from "./chunk-YR3BOQNW.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 REQUIRED_FIELDS = ["agent_id", "api_key"];
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype", "toString", "valueOf"]);
+function toSnakeCase(key) {
+  return key.replace(/([A-Z])/g, "_$1").toLowerCase();
+}
+function normalizeKeys(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[toSnakeCase(key)] = value;
+  }
+  return result;
+}
+function toAgentConfigResult(section, sourceLabel) {
+  const missing = REQUIRED_FIELDS.filter((field) => !section[field]);
+  if (missing.length > 0) {
+    throw new ValidationError(
+      `Missing required fields in ${sourceLabel}: ${missing.join(", ")}`
+    );
+  }
+  const invalid = REQUIRED_FIELDS.filter(
+    (field) => {
+      const value = section[field];
+      return typeof value !== "string" || value.trim() === "";
+    }
+  );
+  if (invalid.length > 0) {
+    throw new ValidationError(
+      `Invalid fields in ${sourceLabel}: ${invalid.join(", ")} must be non-empty strings`
+    );
+  }
+  const { agent_id, api_key, ws_url, rest_url, ...rest } = section;
+  if (ws_url !== void 0 && typeof ws_url !== "string") {
+    throw new ValidationError(`ws_url in ${sourceLabel} must be a string`);
+  }
+  if (rest_url !== void 0 && typeof rest_url !== "string") {
+    throw new ValidationError(`rest_url in ${sourceLabel} must be a string`);
+  }
+  const safeRest = {};
+  for (const [key, value] of Object.entries(rest)) {
+    if (!UNSAFE_KEYS.has(key)) {
+      safeRest[key] = value;
+    }
+  }
+  return {
+    agentId: agent_id.trim(),
+    apiKey: api_key.trim(),
+    ...typeof ws_url === "string" && ws_url.trim() !== "" ? { wsUrl: ws_url.trim() } : {},
+    ...typeof rest_url === "string" && rest_url.trim() !== "" ? { restUrl: rest_url.trim() } : {},
+    ...safeRest
+  };
+}
+function loadAgentConfig(agentKey, configPath) {
+  const filePath = configPath ?? DEFAULT_CONFIG_PATH;
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch {
+    throw new ValidationError(
+      `Config file not found: ${filePath}. Copy agent_config.yaml.example to agent_config.yaml and configure your agents.`
+    );
+  }
+  const parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+  if (!parsed || typeof parsed !== "object") {
+    throw new ValidationError(`Invalid config file: ${filePath}. Expected a YAML object.`);
+  }
+  const config = parsed;
+  let section;
+  if (agentKey && agentKey in config) {
+    const keyed = config[agentKey];
+    if (!keyed || typeof keyed !== "object") {
+      throw new ValidationError(
+        `Config key "${agentKey}" in ${filePath} must be an object with agent_id and api_key.`
+      );
+    }
+    section = normalizeKeys(keyed);
+  } else {
+    section = normalizeKeys(config);
+  }
+  const sourceLabel = agentKey && agentKey in config ? `${filePath} under key "${agentKey}"` : filePath;
+  return toAgentConfigResult(section, sourceLabel);
+}
+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`]
+  });
+  try {
+    return toAgentConfigResult(section, `environment variables (${prefix}AGENT_ID, ${prefix}API_KEY)`);
+  } 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.`
+      );
+    }
+    throw error;
+  }
+}
+
+export {
+  loadAgentConfig,
+  loadAgentConfigFromEnv
+};