@band-ai/sdk 0.3.4 → 0.4.1

package/dist/{chunk-XWHWJP4I.js → chunk-JDW5WSGF.js}

@@ -4,11 +4,11 @@ import {
   MEMORY_TOOL_NAMES,
   TOOL_MODELS,
   getToolDescription
-} from "./chunk-MQY74R7D.js";
+} from "./chunk-SHZBLLDQ.js";
 import {
   isToolExecutorError,
   toLegacyToolExecutorErrorMessage
-} from "./chunk-JADCAMZY.js";
+} from "./chunk-TGDDFBYS.js";
 
 // src/mcp/registrations.ts
 function buildRoomScopedRegistrations(resolver, options = {}) {

package/dist/{chunk-KXJ74J73.js → chunk-JIZE4EC6.js}

@@ -1,6 +1,6 @@
 import {
   toLegacyToolExecutorErrorMessage
-} from "./chunk-JADCAMZY.js";
+} from "./chunk-TGDDFBYS.js";
 
 // src/adapters/shared/coercion.ts
 function asOptionalRecord(value) {
@@ -43,7 +43,8 @@ function toDisplayText(value) {
     return "";
   }
   try {
-    return JSON.stringify(value);
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? json : String(value);
   } catch {
     return String(value);
   }
@@ -63,12 +64,6 @@ function toWireString(value) {
     return String(value);
   }
 }
-function asErrorMessage(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return String(error);
-}
 
 export {
   asOptionalRecord,
@@ -77,6 +72,5 @@ export {
   asString,
   asNullableString,
   toDisplayText,
-  toWireString,
-  asErrorMessage
+  toWireString
 };

package/dist/chunk-OGOXY43L.js

@@ -0,0 +1,119 @@
+import {
+  asErrorMessage
+} from "./chunk-6BE2EG5P.js";
+import {
+  RecoverableTurnError
+} from "./chunk-4OVNFDD7.js";
+
+// src/core/simpleAdapter.ts
+var SimpleAdapter = class {
+  historyConverter;
+  agentName = "";
+  agentDescription = "";
+  constructor(options) {
+    this.historyConverter = options?.historyConverter;
+  }
+  async onCleanup(_roomId) {
+  }
+  async onStarted(agentName, agentDescription) {
+    this.agentName = agentName;
+    this.agentDescription = agentDescription;
+  }
+  async onEvent(input) {
+    const history = this.convertHistory(input.history);
+    await this.onMessage(
+      input.message,
+      input.tools,
+      history,
+      input.participantsMessage,
+      input.contactsMessage,
+      {
+        isSessionBootstrap: input.isSessionBootstrap,
+        roomId: input.roomId
+      }
+    );
+  }
+  convertHistory(provider) {
+    if (!this.historyConverter) {
+      return provider;
+    }
+    return provider.convert(this.historyConverter);
+  }
+};
+
+// src/core/deliveryFailedError.ts
+var DeliveryFailedError = class extends RecoverableTurnError {
+  constructor(cause) {
+    super(asErrorMessage(cause), cause);
+    this.cause = cause;
+    this.name = "DeliveryFailedError";
+  }
+};
+async function deliverReply(tools, content, mentions = []) {
+  try {
+    return await tools.sendMessage(content, mentions);
+  } catch (error) {
+    throw new DeliveryFailedError(error);
+  }
+}
+
+// src/core/providerFailure.ts
+import { AgentFailure } from "@band-ai/band-sdk-core";
+var FAILURE_CODE_TIMEOUT = "timeout";
+var ProviderTurnFailedError = class extends RecoverableTurnError {
+  constructor(failure) {
+    super(failure.message);
+    this.failure = failure;
+    this.name = "ProviderTurnFailedError";
+  }
+};
+async function trySendFailure(tools, failure, logger, logContext) {
+  logger?.warn("provider_failure.reported", {
+    provider: failure.provider,
+    code: failure.code,
+    ...logContext
+  });
+  try {
+    await tools.sendFailure(failure);
+  } catch (error) {
+    logger?.warn("provider_failure.report_failed", {
+      provider: failure.provider,
+      code: failure.code,
+      ...logContext,
+      error
+    });
+  }
+}
+async function reportTurnFailure(tools, failure, logger, logContext) {
+  await trySendFailure(tools, failure, logger, logContext);
+  throw new ProviderTurnFailedError(failure);
+}
+async function reportProviderTurnFailure(tools, logger, provider, logLabel, error, logContext) {
+  logger.error(logLabel, { ...logContext, error });
+  return reportTurnFailure(tools, agentFailure(provider, asErrorMessage(error)), logger, logContext);
+}
+async function safeSendFailure(tools, failure, logger, logContext) {
+  await trySendFailure(tools, failure, logger, logContext);
+}
+function agentFailure(provider, message, code, detail) {
+  if (detail === void 0) {
+    return new AgentFailure(provider, message, code);
+  }
+  try {
+    return new AgentFailure(provider, message, code, detail);
+  } catch {
+    return new AgentFailure(provider, message, code);
+  }
+}
+
+export {
+  SimpleAdapter,
+  DeliveryFailedError,
+  deliverReply,
+  FAILURE_CODE_TIMEOUT,
+  ProviderTurnFailedError,
+  reportTurnFailure,
+  reportProviderTurnFailure,
+  safeSendFailure,
+  agentFailure
+};

package/dist/{chunk-W5IAI6Z4.js → chunk-OVXVZUPO.js}

@@ -2,14 +2,14 @@ import {
   asNullableString,
   asOptionalRecord,
   asString
-} from "./chunk-KXJ74J73.js";
+} from "./chunk-JIZE4EC6.js";
 import {
-  NoopLogger
-} from "./chunk-OD2G5LFQ.js";
+  resolveLogger
+} from "./chunk-ZYOXI4JL.js";
 import {
   UnsupportedFeatureError,
   ValidationError
-} from "./chunk-JY75VSQK.js";
+} from "./chunk-4OVNFDD7.js";
 
 // src/client/rest/pagination.ts
 var DEFAULT_PAGE_SIZE = 100;
@@ -802,7 +802,7 @@ var RestFacade = class {
   logger;
   constructor(options) {
     this.api = options.api;
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
   }
   async getAgentMe(options) {
     return this.forward("getAgentMe", () => this.api.getAgentMe(options));

package/dist/{chunk-YJ42AZO4.js → chunk-RJNJUISR.js}

@@ -5,7 +5,7 @@ import {
   MEMORY_SYSTEM_TYPES,
   MEMORY_TYPE,
   TOOL_MODELS
-} from "./chunk-MQY74R7D.js";
+} from "./chunk-SHZBLLDQ.js";
 
 // src/runtime/prompts/base.ts
 var ENVIRONMENT_SECTION = `
@@ -105,6 +105,7 @@ function longTermPattern(label, type, segment, scope) {
   };
 }
 var COMMON_MEMORY_PATTERNS = [
+  longTermPattern("Private notes for this agent only", MEMORY_TYPE.semantic, MEMORY_SEGMENT.guideline, MEMORY_STORE_SCOPE.agent),
   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),
@@ -117,7 +118,9 @@ 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
+var MEMORY_SCOPE_GUIDANCE = `Use \`scope="${MEMORY_STORE_SCOPE.agent}"\` for information private to this agent that is not about an
+identified subject. Omitting \`scope\` and \`subject_id\` on store defaults to agent scope on the platform.
+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

package/dist/{chunk-MQY74R7D.js → chunk-SHZBLLDQ.js}

@@ -1,8 +1,9 @@
 import {
   CHAT_EVENT_TYPES
-} from "./chunk-F63TPOI3.js";
+} from "./chunk-TGDDFBYS.js";
 
 // src/contracts/memory.ts
+import { validateMemoryTypeForSystem } from "@band-ai/band-sdk-core";
 var SENSORY_MEMORY_TYPES = [
   "iconic",
   // Visual input
@@ -46,18 +47,22 @@ var MEMORY_SEGMENTS = [
   // Behavioral rules or policies
 ];
 var MEMORY_STORE_SCOPES = [
+  "agent",
+  // Private to the storing agent; omit subject_id
   "subject",
   // About one person/agent; requires subject_id
   "organization"
   // Shared org-wide
 ];
 var MEMORY_LIST_SCOPES = [
+  "agent",
+  // Caller's private agent-scoped memories only
   "subject",
   // Subject-scoped memories only
   "organization",
   // Organization-scoped memories only
   "all"
-  // Both scopes (no scope filter)
+  // All scopes (no scope filter)
 ];
 var MEMORY_STATUSES = [
   "active",
@@ -80,7 +85,15 @@ function isMemoryType(value) {
   return MEMORY_TYPES.includes(value);
 }
 function isMemoryTypeForSystem(system, type) {
-  return MEMORY_SYSTEM_TYPES[system].includes(type);
+  try {
+    validateMemoryTypeForSystem(system, type);
+    return true;
+  } catch (err) {
+    if (err instanceof Error && "issues" in err) {
+      return false;
+    }
+    throw err;
+  }
 }
 function isMemorySegment(value) {
   return MEMORY_SEGMENTS.includes(value);
@@ -283,7 +296,7 @@ var TOOL_MODELS = {
     required: ["action"]
   },
   band_list_memories: {
-    description: "List memories accessible to the agent. Returns memories about the specified subject (cross-agent sharing) and organization-wide shared memories.",
+    description: `List memories accessible to the agent. Use scope="agent" for the caller's private memories, scope="subject" for memories about a specific person or agent, and scope="organization" for org-wide shared memories. Omit scope or use scope="all" to search across scopes.`,
     properties: {
       subject_id: {
         type: "string",
@@ -292,7 +305,7 @@ var TOOL_MODELS = {
       scope: {
         type: "string",
         enum: [...MEMORY_LIST_SCOPES],
-        description: "Filter by scope."
+        description: `Filter by scope. "agent" returns the caller's private memories; "subject" and "organization" filter to those audiences; "all" omits the filter.`
       },
       system: {
         type: "string",
@@ -328,7 +341,7 @@ var TOOL_MODELS = {
     required: []
   },
   band_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.",
+    description: 'Store a new memory entry. The memory will be associated with the authenticated agent as the source. Use scope="agent" for information private to this agent (no subject_id). Use scope="subject" with a subject_id for memories about a specific person or agent. Use scope="organization" for knowledge genuinely shared across the organization.',
     properties: {
       content: {
         type: "string",
@@ -356,11 +369,11 @@ var TOOL_MODELS = {
       scope: {
         type: "string",
         enum: [...MEMORY_STORE_SCOPES],
-        description: "Visibility scope."
+        description: 'Visibility scope. "agent" is private to this agent; "subject" requires subject_id; "organization" is shared org-wide.'
       },
       subject_id: {
         type: "string",
-        description: "UUID of the subject this memory is about (required for subject scope)."
+        description: "UUID of the subject this memory is about (required for subject scope; omit for agent scope)."
       },
       metadata: {
         type: "object",
@@ -453,7 +466,6 @@ export {
   isMemoryListScope,
   isMemoryStatus,
   expectedList,
-  expectedMemoryTypesForSystem,
   memoryTypeForSystemError,
   TOOL_MODELS,
   ALL_TOOL_NAMES,

package/dist/{chunk-JADCAMZY.js → chunk-TGDDFBYS.js}

@@ -1,4 +1,40 @@
+import {
+  ValidationError
+} from "./chunk-4OVNFDD7.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(", ")}`
+    );
+  }
+}
+var VISIBLE_CONTENT_PATTERN = /[\p{L}\p{N}\p{P}\p{S}]/u;
+function isBlankEventContent(content) {
+  return !VISIBLE_CONTENT_PATTERN.test(content);
+}
+
 // src/contracts/protocols.ts
+var FAILURE_EVENT_TYPE = "error";
+var FAILURE_METADATA_KEY = "failure";
+function sendFailureViaEvent(sendEvent, failure) {
+  const { content, messageType, metadata } = toFailureEvent(failure);
+  return sendEvent(content, messageType, metadata);
+}
+function toFailureEvent(failure) {
+  const content = isBlankEventContent(failure.message) ? `${failure.provider} failed without an error message.` : failure.message;
+  return {
+    content,
+    messageType: FAILURE_EVENT_TYPE,
+    metadata: { [FAILURE_METADATA_KEY]: failure.toObject() }
+  };
+}
 var TOOL_EXECUTOR_ERROR_TYPES = [
   "ToolArgumentsValidationError",
   "ToolNotFoundError",
@@ -44,6 +80,15 @@ var DEFAULT_AGENT_TOOLS_CAPABILITIES = {
 };
 
 export {
+  CHAT_EVENT_TYPES,
+  CHAT_MESSAGE_TYPES,
+  isChatEventType,
+  assertChatEventType,
+  isBlankEventContent,
+  FAILURE_EVENT_TYPE,
+  FAILURE_METADATA_KEY,
+  sendFailureViaEvent,
+  toFailureEvent,
   createToolExecutorError,
   isToolExecutorError,
   isStructuredToolFailure,

package/dist/{chunk-US226AS4.js → chunk-UENIC5FJ.js}

@@ -1,5 +1,6 @@
 // src/platform/streaming/disconnectReason.ts
 import { z } from "zod";
+import { validateEventPayload } from "@band-ai/band-sdk-core";
 var UPGRADE_CODES = [
   "invalid_on_conflict",
   "connection_conflict",
@@ -50,7 +51,7 @@ var upgradeErrorSchema = z.object({
       })
     })
   ),
-  headers: z.record(z.unknown()).optional()
+  headers: z.record(z.string(), z.unknown()).optional()
 });
 var WebSocketDisconnectError = class extends Error {
   reason;
@@ -61,18 +62,20 @@ var WebSocketDisconnectError = class extends Error {
   }
 };
 function parseSupersedeDisconnectReason(payload) {
-  if (typeof payload.reason !== "string" || typeof payload.message !== "string") {
+  try {
+    const normalized = validateEventPayload("supersede", payload);
+    return {
+      source: "agent_control",
+      code: normalized.reason,
+      message: normalized.message,
+      retryable: normalized.retryable,
+      retryAfter: normalized.retry_after ?? null,
+      targetSocketId: normalized.target_socket_id ?? null,
+      correlationId: normalized.correlation_id
+    };
+  } catch {
     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);