@sonzai-labs/agents 1.0.0 → 1.0.1

package/README.md

@@ -1,9 +1,9 @@
 # Sonzai TypeScript SDK
 
-[![npm version](https://img.shields.io/npm/v/@sonzai/sdk.svg)](https://www.npmjs.com/package/@sonzai/sdk)
+[![npm version](https://img.shields.io/npm/v/@sonzai-labs/agents.svg)](https://www.npmjs.com/package/@sonzai-labs/agents)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The official TypeScript SDK for the [Sonzai Character Engine API](https://sonz.ai). Build AI characters with persistent memory, evolving personality, and proactive behaviors.
+The official TypeScript SDK for the [Sonzai Mind Layer API](https://sonz.ai). Build AI agents with persistent memory, evolving personality, and proactive behaviors.
 
 **Zero runtime dependencies.** Uses the native `fetch` API. Works with Node.js (>=18), Bun, and Deno.
 
@@ -11,19 +11,19 @@ The official TypeScript SDK for the [Sonzai Character Engine API](https://sonz.a
 
 ```bash
 # npm
-npm install @sonzai/sdk
+npm install @sonzai-labs/agents
 
 # bun
-bun add @sonzai/sdk
+bun add @sonzai-labs/agents
 
 # deno
-import { Sonzai } from "npm:@sonzai/sdk";
+import { Sonzai } from "npm:@sonzai-labs/agents";
 ```
 
 ## Quick Start
 
 ```ts
-import { Sonzai } from "@sonzai/sdk";
+import { Sonzai } from "@sonzai-labs/agents";
 
 const client = new Sonzai({ apiKey: "your-api-key" });
 
@@ -371,7 +371,7 @@ import {
   BadRequestError,
   RateLimitError,
   SonzaiError,
-} from "@sonzai/sdk";
+} from "@sonzai-labs/agents";
 
 try {
   const res = await client.agents.chat("agent-id", { messages: [...] });

package/dist/index.cjs

@@ -32,9 +32,11 @@ var PermissionDeniedError = class extends SonzaiError {
   }
 };
 var RateLimitError = class extends SonzaiError {
-  constructor(message) {
+  retryAfter;
+  constructor(message, retryAfter) {
     super(message);
     this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
   }
 };
 var InternalServerError = class extends SonzaiError {
@@ -63,6 +65,7 @@ var HTTPClient = class {
   baseUrl;
   headers;
   timeout;
+  maxRetries;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.headers = {
@@ -71,27 +74,53 @@ var HTTPClient = class {
       "User-Agent": "sonzai-typescript/1.13.0"
     };
     this.timeout = options.timeout;
+    this.maxRetries = options.maxRetries;
   }
   async request(method, path, options) {
     const url = this.buildUrl(path, options?.params);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method,
-        headers: this.headers,
-        body: options?.body ? JSON.stringify(options.body) : void 0,
-        signal: controller.signal
-      });
-      await this.throwOnError(response);
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        return await response.json();
+    const isIdempotent = method === "GET" || method === "DELETE";
+    const maxAttempts = isIdempotent ? this.maxRetries + 1 : 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: this.headers,
+          body: options?.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        if (response.status >= 500 && isIdempotent && attempt < maxAttempts - 1) {
+          clearTimeout(timer);
+          await this.backoff(attempt);
+          continue;
+        }
+        await this.throwOnError(response);
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+          return await response.json();
+        }
+        return await response.text();
+      } catch (error) {
+        clearTimeout(timer);
+        if (isIdempotent && attempt < maxAttempts - 1 && this.isNetworkError(error)) {
+          await this.backoff(attempt);
+          continue;
+        }
+        throw error;
+      } finally {
+        clearTimeout(timer);
       }
-      return await response.text();
-    } finally {
-      clearTimeout(timer);
     }
+    throw new InternalServerError("Max retries exceeded");
+  }
+  async backoff(attempt) {
+    const delay = Math.min(1e3 * 2 ** attempt, 1e4) + Math.random() * 500;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+  isNetworkError(error) {
+    if (error instanceof SonzaiError) return false;
+    return error instanceof TypeError || error instanceof DOMException && error.name === "AbortError";
   }
   async get(path, params) {
     return this.request("GET", path, { params });
@@ -129,33 +158,47 @@ var HTTPClient = class {
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
       let buffer = "";
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed) continue;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            if (trimmed === "data: [DONE]") return;
+            if (trimmed.startsWith("data: ")) {
+              try {
+                yield JSON.parse(trimmed.slice(6));
+              } catch (e) {
+                console.warn(
+                  "[sonzai-sdk] Malformed SSE JSON event skipped:",
+                  trimmed.slice(6),
+                  e
+                );
+              }
+            }
+          }
+        }
+        if (buffer.trim()) {
+          const trimmed = buffer.trim();
           if (trimmed === "data: [DONE]") return;
           if (trimmed.startsWith("data: ")) {
             try {
               yield JSON.parse(trimmed.slice(6));
-            } catch {
+            } catch (e) {
+              console.warn(
+                "[sonzai-sdk] Malformed SSE JSON event skipped:",
+                trimmed.slice(6),
+                e
+              );
             }
           }
         }
-      }
-      if (buffer.trim()) {
-        const trimmed = buffer.trim();
-        if (trimmed === "data: [DONE]") return;
-        if (trimmed.startsWith("data: ")) {
-          try {
-            yield JSON.parse(trimmed.slice(6));
-          } catch {
-          }
-        }
+      } finally {
+        await reader.cancel();
       }
     } finally {
       clearTimeout(timer);
@@ -195,8 +238,14 @@ var HTTPClient = class {
         throw new NotFoundError(message);
       case 400:
         throw new BadRequestError(message);
-      case 429:
-        throw new RateLimitError(message);
+      case 429: {
+        const retryAfterRaw = response.headers.get("Retry-After");
+        const retryAfter = retryAfterRaw ? Number(retryAfterRaw) : void 0;
+        throw new RateLimitError(
+          message,
+          retryAfter && !Number.isNaN(retryAfter) ? retryAfter : void 0
+        );
+      }
       default:
         if (status >= 500) throw new InternalServerError(message);
         throw new APIError(status, message);
@@ -793,72 +842,42 @@ var Voice = class {
   constructor(http) {
     this.http = http;
   }
-  /** Convert text to speech using the agent's voice. */
-  async textToSpeech(agentId, options) {
-    const body = { text: options.text };
-    if (options.voiceName) body.voice_name = options.voiceName;
-    if (options.language) body.language = options.language;
-    if (options.emotionalContext)
-      body.emotional_context = options.emotionalContext;
-    return this.http.post(
-      `/api/v1/agents/${agentId}/voice/tts`,
-      body
-    );
-  }
-  /** Find the best matching voice for an agent based on personality. */
-  async voiceMatch(agentId, options = {}) {
-    const body = {};
-    if (options.big5) body.big5 = options.big5;
-    if (options.preferredGender)
-      body.preferred_gender = options.preferredGender;
-    return this.http.post(
-      `/api/v1/agents/${agentId}/voice/match`,
-      body
-    );
-  }
-  /** Perform a single-turn voice chat: send audio, receive text + audio response. */
-  async voiceChat(agentId, options) {
-    const body = { audio: options.audio };
-    if (options.userId) body.user_id = options.userId;
-    if (options.audioFormat) body.audio_format = options.audioFormat;
-    if (options.voiceName) body.voice_name = options.voiceName;
-    if (options.continuationToken)
-      body.continuation_token = options.continuationToken;
-    if (options.language) body.language = options.language;
-    return this.http.post(
-      `/api/v1/agents/${agentId}/voice/chat`,
-      body
-    );
-  }
   /**
-   * Get a short-lived token for WebSocket voice streaming.
+   * Get a short-lived token for voice live WebSocket streaming.
    * The token expires in 60 seconds and is single-use.
    */
   async getToken(agentId, options = {}) {
     const body = {};
     if (options.voiceName) body.voiceName = options.voiceName;
     if (options.language) body.language = options.language;
-    if (options.entityContext) body.entityContext = options.entityContext;
+    if (options.userId) body.userId = options.userId;
+    if (options.compiledSystemPrompt)
+      body.compiledSystemPrompt = options.compiledSystemPrompt;
     return this.http.post(
-      `/api/v1/agents/${agentId}/voice/ws-token`,
+      `/api/v1/agents/${agentId}/voice/live-ws-token`,
       body
     );
   }
   /**
-   * Open a bidirectional WebSocket for real-time voice chat.
+   * Open a bidirectional WebSocket for real-time voice chat via Gemini Live.
    *
    * @example
    * ```ts
    * const token = await client.agents.voice.getToken(agentId);
    * const stream = await client.agents.voice.stream(token);
    *
+   * // Send PCM audio chunks (16kHz, 16-bit, mono)
    * stream.sendAudio(audioChunk);
-   * stream.endOfSpeech();
+   *
+   * // Or send text input instead of audio
+   * stream.sendText("Hello!");
    *
    * for await (const event of stream) {
-   *   if (event.type === "transcript") console.log("User:", event.text);
-   *   if (event.type === "audio") playAudio(event.audio);
-   *   if (event.type === "turn_complete") break;
+   *   if (event.type === "input_transcript") console.log("User:", event.text);
+   *   if (event.type === "output_transcript") console.log("Agent:", event.text);
+   *   if (event.type === "audio") playPCMAudio(event.audio); // 24kHz PCM
+   *   if (event.type === "turn_complete") console.log("Turn done");
+   *   if (event.type === "session_ended") break;
    * }
    *
    * stream.close();
@@ -884,13 +903,25 @@ var VoiceStreamInstance = class _VoiceStreamInstance {
         const parsed = JSON.parse(evt.data);
         event = {
           type: parsed.type ?? "",
-          sessionId: parsed.session_id,
-          speaking: parsed.speaking,
+          sessionId: parsed.sessionId ?? parsed.session_id,
           text: parsed.text,
-          continuationToken: parsed.continuation_token,
-          contentType: parsed.content_type,
+          isFinal: parsed.isFinal,
+          speaking: parsed.speaking,
+          turnIndex: parsed.turnIndex,
+          name: parsed.name,
+          status: parsed.status,
+          facts: parsed.facts,
+          emotions: parsed.emotions,
+          relationshipDelta: parsed.relationshipDelta,
+          promptTokens: parsed.promptTokens,
+          completionTokens: parsed.completionTokens,
+          totalTokens: parsed.totalTokens,
+          reason: parsed.reason,
+          totalUsage: parsed.totalUsage,
+          turnCount: parsed.turnCount,
+          voiceName: parsed.voiceName,
           error: parsed.error,
-          errorCode: parsed.error_code
+          errorCode: parsed.errorCode ?? parsed.error_code ?? parsed.code
         };
       }
       if (this.waitResolve) {
@@ -944,16 +975,19 @@ var VoiceStreamInstance = class _VoiceStreamInstance {
   sendAudio(audio) {
     this.ws.send(audio);
   }
-  /** Signal the server that the user has finished speaking. */
-  endOfSpeech() {
-    this.ws.send(JSON.stringify({ type: "end_of_speech" }));
+  /** Send a text message to the agent instead of audio. */
+  sendText(text) {
+    this.ws.send(JSON.stringify({ type: "text_input", text }));
   }
-  /** Change audio format, voice, or language mid-session. */
+  /** Gracefully end the voice session. */
+  endSession() {
+    this.ws.send(JSON.stringify({ type: "end_session" }));
+  }
+  /** Change audio format or sample rate mid-session. */
   configure(options) {
     const msg = { type: "config" };
-    if (options.audioFormat) msg.audio_format = options.audioFormat;
-    if (options.voiceName) msg.voice_name = options.voiceName;
-    if (options.language) msg.language = options.language;
+    if (options.audioFormat) msg.audioFormat = options.audioFormat;
+    if (options.sampleRate) msg.sampleRate = options.sampleRate;
     this.ws.send(JSON.stringify(msg));
   }
   /** Close the voice stream. */
@@ -1003,6 +1037,11 @@ var Voices = class {
 };
 
 // src/resources/agents.ts
+function requireNonEmpty(value, name) {
+  if (!value || typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
 var Agents = class {
   constructor(http) {
     this.http = http;
@@ -1072,10 +1111,12 @@ var Agents = class {
   }
   /** Get an agent by ID. */
   async get(agentId) {
+    requireNonEmpty(agentId, "agentId");
     return this.http.get(`/api/v1/agents/${agentId}`);
   }
   /** Update an agent's profile. */
   async update(agentId, options) {
+    requireNonEmpty(agentId, "agentId");
     const body = {};
     if (options.name) body.name = options.name;
     if (options.bio) body.bio = options.bio;
@@ -1093,6 +1134,7 @@ var Agents = class {
   }
   /** Delete an agent. */
   async delete(agentId) {
+    requireNonEmpty(agentId, "agentId");
     await this.http.delete(`/api/v1/agents/${agentId}`);
   }
   // -- Chat --
@@ -1115,6 +1157,7 @@ var Agents = class {
   }
   /** Send a chat message and stream events as an async iterator. */
   async *chatStream(options) {
+    requireNonEmpty(options.agent, "agentId");
     const body = this.buildChatBody(options);
     for await (const event of this.http.streamSSE(
       "POST",