@maximem/synap-js-sdk 0.4.7 → 0.5.1

package/dist/index.js

@@ -1,3 +1,17 @@
+import {
+  ANY_SCOPE,
+  AnticipationCache,
+  BM25,
+  CONTRACT,
+  THRESHOLDS,
+  isRecallQuery,
+  rungKey,
+  stem,
+  tokenize
+} from "./chunk-ODVOQOSO.js";
+import {
+  getEnv
+} from "./chunk-QBCVMPGK.js";
 import {
   AgentUnavailableError,
   AuthenticationError,
@@ -21,38 +35,9 @@ import {
   SynapTransientError,
   TranscriptConflictError,
   TransientError,
-  isSynapError
-} from "./chunk-OCMM2Z5P.js";
-import {
-  ANY_SCOPE,
-  AnticipationCache,
-  BM25,
-  CONTRACT,
-  THRESHOLDS,
-  isRecallQuery,
-  stem,
-  tokenize
-} from "./chunk-6LDUDKHS.js";
-import {
-  getEnv
-} from "./chunk-QBCVMPGK.js";
-
-// src/util/correlation.ts
-function newCorrelationId() {
-  const c = globalThis.crypto;
-  if (typeof c?.randomUUID === "function") return c.randomUUID();
-  if (typeof c?.getRandomValues === "function") {
-    const b = c.getRandomValues(new Uint8Array(16));
-    b[6] = (b[6] ?? 0) & 15 | 64;
-    b[8] = (b[8] ?? 0) & 63 | 128;
-    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
-    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
-  }
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
-    const r = Math.random() * 16 | 0;
-    return (ch === "x" ? r : r & 3 | 8).toString(16);
-  });
-}
+  isSynapError,
+  newCorrelationId
+} from "./chunk-BWMPKLFG.js";
 
 // src/transport/endpoints.ts
 var ENDPOINTS = {
@@ -422,6 +407,16 @@ function toTransportError(error, correlationId) {
     { correlationId, cause: error }
   );
 }
+var CREDIT_ERRORS = /* @__PURE__ */ new Set(["insufficient_credits", "trial_limit_reached"]);
+function creditPayload(parsed, detailObject) {
+  return detailObject ?? parsed;
+}
+function creditReason(payload) {
+  const reason = stringOrNull(payload["reason"]);
+  if (reason !== null) return reason;
+  const error = stringOrNull(payload["error"]);
+  return error !== null && CREDIT_ERRORS.has(error) ? error : null;
+}
 async function toHttpError(response, correlationId) {
   const body = await response.text().catch(() => "");
   let parsed = {};
@@ -443,14 +438,18 @@ async function toHttpError(response, correlationId) {
       return new AuthenticationError(message, opts);
     case 404:
       return new ContextNotFoundError(message, opts);
-    case 402:
+    case 402: {
+      const credit = creditPayload(parsed, detailObject);
       return new InsufficientCreditsError(message, {
         ...opts,
-        balanceCredits: numberOrNull(parsed["balance_credits"]),
-        requiredCredits: numberOrNull(parsed["minimum_required_credits"]) ?? numberOrNull(parsed["required_credits"]),
-        recoveryUrl: stringOrNull(parsed["recovery_url"]),
-        redeemUrl: stringOrNull(parsed["redeem_url"])
+        balanceCredits: numberOrNull(credit["balance_credits"]),
+        requiredCredits: numberOrNull(credit["minimum_required_credits"]) ?? numberOrNull(credit["required_credits"]),
+        recoveryUrl: stringOrNull(credit["recovery_url"]),
+        redeemUrl: stringOrNull(credit["redeem_url"]),
+        reason: creditReason(credit),
+        manageUrl: stringOrNull(credit["manage_url"])
       });
+    }
     case 409:
       if (detailObject !== null && detailObject["code"] === "transcript_conflict") {
         return new TranscriptConflictError(message, opts);
@@ -459,9 +458,13 @@ async function toHttpError(response, correlationId) {
     case 429: {
       const header = response.headers.get("retry-after");
       const retryAfter = header !== null && header.trim() !== "" ? Number(header) : null;
+      const credit = creditPayload(parsed, detailObject);
       return new RateLimitError(message, {
         ...opts,
-        retryAfterSeconds: retryAfter !== null && Number.isFinite(retryAfter) ? retryAfter : null
+        retryAfterSeconds: retryAfter !== null && Number.isFinite(retryAfter) ? retryAfter : null,
+        reason: creditReason(credit),
+        upgradeUrl: stringOrNull(credit["upgrade_url"]),
+        manageUrl: stringOrNull(credit["manage_url"])
       });
     }
     case 503:
@@ -1046,6 +1049,8 @@ function buildRecordMessageBody(options) {
   };
   const sessionId = either2(o2, "session_id", "sessionId");
   if (sessionId !== void 0) body["session_id"] = sessionId;
+  const scopePath = either2(o2, "scope_path", "scopePath");
+  if (scopePath !== void 0) body["scope"] = scopePath;
   return body;
 }
 function buildIngestTranscriptBody(options) {
@@ -1072,6 +1077,8 @@ function buildIngestTranscriptBody(options) {
   if (options.metadata !== void 0) body["metadata"] = options.metadata;
   if (startedAt !== void 0) body["started_at"] = startedAt;
   if (endedAt !== void 0) body["ended_at"] = endedAt;
+  const scopePath = either2(o2, "scope_path", "scopePath");
+  if (scopePath !== void 0) body["scope"] = scopePath;
   return body;
 }
 function buildCompactBody(options) {
@@ -1205,7 +1212,8 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
         onFetched(
           response,
           id,
-          options.user_id ?? options.userId
+          options.user_id ?? options.userId,
+          options.scope_path ?? options.scopePath
         );
         return response;
       },
@@ -1370,8 +1378,24 @@ function thinkingMetadata(options) {
   }
   return md;
 }
+var KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "user_message",
+  "assistant_message",
+  "tool_call",
+  "tool_result",
+  "agent_thinking",
+  "context_request",
+  "context_fetch",
+  "session_start",
+  "session_end"
+]);
+function toolResultJson(result) {
+  if (result === void 0 || result === null) return "";
+  return typeof result === "string" ? result : JSON.stringify(result);
+}
 function createInstanceNamespace(credentials, cache, onTurn) {
   let client = null;
+  const openSessions = /* @__PURE__ */ new Map();
   let dispatchCompaction = null;
   let applyCompaction = null;
   const internals = {
@@ -1395,16 +1419,33 @@ function createInstanceNamespace(credentials, cache, onTurn) {
       return client !== null && client.isConnected;
     }
   };
+  function ensureSession(conversationId, userId, customerId) {
+    if (!conversationId || !userId || client === null) return;
+    if (openSessions.has(conversationId)) return;
+    const sessionId = newCorrelationId();
+    try {
+      client.sendSessionControl({
+        action: "start",
+        session_id: sessionId,
+        conversation_id: conversationId,
+        ...userId ? { user_id: userId } : {},
+        ...customerId ? { customer_id: customerId } : {}
+      });
+      openSessions.set(conversationId, sessionId);
+    } catch {
+    }
+  }
   const namespace = {
     async listen(options = {}) {
       if (client !== null) {
         throw new ListeningAlreadyActiveError("Listening is already active on this instance");
       }
-      const { GrpcStreamClient } = await import("./stream-client-6V4FGKZ3.js");
+      const { GrpcStreamClient } = await import("./stream-client-6OWRYOA4.js");
       const onContext = options.on_context ?? options.onContext;
       const onDisconnect = options.on_disconnect ?? options.onDisconnect;
       const onReconnect = options.on_reconnect ?? options.onReconnect;
       let reconnectAttempts = 0;
+      let stream = null;
       const created = new GrpcStreamClient(credentials(), cache, {
         host: options.host ?? getEnv("SYNAP_GRPC_HOST") ?? DEFAULT_GRPC_HOST,
         port: options.port ?? envPort() ?? DEFAULT_GRPC_PORT,
@@ -1414,14 +1455,18 @@ function createInstanceNamespace(credentials, cache, onTurn) {
           internals.onCompactionUpdate(conversationId, bundle);
         },
         onStateChange: (state) => {
+          if (state !== "connected") openSessions.clear();
           if (state === "reconnecting") {
             reconnectAttempts += 1;
             onReconnect?.(reconnectAttempts);
           } else if (state === "disconnected") {
-            onDisconnect?.("stream disconnected");
+            const stopped = stream?.lastError ?? null;
+            const reason = stopped === null ? "stream disconnected" : `credit_stop:${stopped.reason ?? "unknown"}`;
+            onDisconnect?.(reason);
           }
         }
       });
+      stream = created;
       try {
         await created.connect();
       } catch (error) {
@@ -1435,29 +1480,58 @@ function createInstanceNamespace(credentials, cache, onTurn) {
     },
     async stop_listening() {
       if (client === null) return;
+      for (const conversationId of [...openSessions.keys()]) {
+        await namespace.end_session(conversationId);
+      }
       const active = client;
       client = null;
       await active.disconnect();
     },
+    async end_session(conversationId) {
+      const sessionId = openSessions.get(conversationId);
+      if (sessionId === void 0 || client === null) return;
+      openSessions.delete(conversationId);
+      try {
+        client.sendSessionControl({
+          action: "end",
+          session_id: sessionId,
+          conversation_id: conversationId
+        });
+      } catch {
+      }
+    },
     async send_message(options) {
       if (client === null) throw new ListeningNotActiveError("Listening is not active");
       if (options.content === void 0) {
         throw new ListeningNotActiveError("content is required");
       }
+      const eventType = options.event_type ?? options.eventType ?? "user_message";
+      if (!KNOWN_EVENT_TYPES.has(eventType)) {
+        throw new SynapError(
+          `unknown event_type '${eventType}'. Expected one of: ` + [...KNOWN_EVENT_TYPES].sort().join(", ")
+        );
+      }
       const conversationId = options.conversation_id ?? options.conversationId ?? "";
-      onTurn?.({
+      ensureSession(
         conversationId,
-        role: options.role ?? "user",
-        content: options.content
-      });
+        options.user_id ?? options.userId ?? "",
+        options.customer_id ?? options.customerId ?? ""
+      );
+      if (eventType === "user_message" || eventType === "assistant_message") {
+        onTurn?.({
+          conversationId,
+          role: options.role ?? "user",
+          content: options.content
+        });
+      }
       client.sendConversationEvent({
-        event_type: options.event_type ?? options.eventType ?? "user_message",
+        event_type: eventType,
         content: options.content,
         role: options.role ?? "user",
         conversation_id: options.conversation_id ?? options.conversationId ?? "",
         user_id: options.user_id ?? options.userId ?? "",
         customer_id: options.customer_id ?? options.customerId ?? "",
-        session_id: options.session_id ?? options.sessionId ?? "",
+        session_id: options.session_id ?? options.sessionId ?? openSessions.get(conversationId) ?? "",
         metadata: options.metadata ?? {},
         timestamp_ms: Date.now(),
         tool_name: options.tool_name ?? options.toolName ?? "",
@@ -1466,17 +1540,61 @@ function createInstanceNamespace(credentials, cache, onTurn) {
           const a = options.tool_args ?? options.toolArgs;
           return a === void 0 ? "" : JSON.stringify(a);
         })(),
+        tool_result_json: toolResultJson(options.tool_result ?? options.toolResult),
+        tool_call_id: options.tool_call_id ?? options.toolCallId ?? "",
         search_queries: options.search_queries ?? options.searchQueries ?? [],
         context_types: options.context_types ?? options.contextTypes ?? []
       });
     },
+    async record_tool_call(options) {
+      await namespace.send_message({
+        content: "",
+        role: "assistant",
+        event_type: "tool_call",
+        tool_name: options.tool_name ?? options.toolName ?? "",
+        ...options.tool_args ?? options.toolArgs ? { tool_args: options.tool_args ?? options.toolArgs } : {},
+        tool_call_id: options.tool_call_id ?? options.toolCallId ?? "",
+        conversation_id: options.conversation_id ?? options.conversationId ?? "",
+        user_id: options.user_id ?? options.userId ?? "",
+        customer_id: options.customer_id ?? options.customerId ?? "",
+        session_id: options.session_id ?? options.sessionId ?? "",
+        metadata: options.metadata ?? {}
+      });
+    },
+    async record_tool_result(options) {
+      await namespace.send_message({
+        content: "",
+        role: "tool",
+        event_type: "tool_result",
+        tool_result: options.result,
+        tool_name: options.tool_name ?? options.toolName ?? "",
+        tool_call_id: options.tool_call_id ?? options.toolCallId ?? "",
+        conversation_id: options.conversation_id ?? options.conversationId ?? "",
+        user_id: options.user_id ?? options.userId ?? "",
+        customer_id: options.customer_id ?? options.customerId ?? "",
+        session_id: options.session_id ?? options.sessionId ?? "",
+        metadata: options.metadata ?? {}
+      });
+    },
     async record_thinking(options) {
       if (client === null) throw new ListeningNotActiveError("Listening is not active");
+      const conversationId = options.conversation_id ?? options.conversationId ?? "";
+      ensureSession(
+        conversationId,
+        options.user_id ?? options.userId ?? "",
+        options.customer_id ?? options.customerId ?? ""
+      );
       client.sendConversationEvent({
         // Python emits reasoning as an `agent_thinking` conversation event.
         event_type: "agent_thinking",
         content: options.content,
-        role: "assistant",
+        // Deliberately no role. A thought is not the assistant's reply, and
+        // this went out as 'assistant' from the day it shipped: the server
+        // checked role before event_type, so every reasoning step any client
+        // sent was filed as the final answer and the reasoning path never ran.
+        // Sending no role is correct against both the fixed server and one that
+        // has not been updated yet.
+        role: "",
         conversation_id: options.conversation_id ?? options.conversationId ?? "",
         user_id: options.user_id ?? options.userId ?? "",
         customer_id: options.customer_id ?? options.customerId ?? "",
@@ -1494,7 +1612,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.0.0-beta.0";
+var SDK_VERSION = "0.5.1";
 
 // src/registry.ts
 var instances = /* @__PURE__ */ new Map();
@@ -1683,7 +1801,7 @@ function budgetRecentTurns(turns) {
   return windowed;
 }
 function overlayLocalRecentTurns(response, store, conversationId, configured) {
-  if (conversationId === void 0 || conversationId === "") return;
+  if (conversationId === void 0 || conversationId === null || conversationId === "") return;
   try {
     const entry = store.get(conversationId);
     if (entry === null) return;
@@ -1944,16 +2062,16 @@ function mergeUserSummary(response, bundle) {
 
 // src/context/anticipated.ts
 function scopeLookupParams(scope, params) {
-  const { searchQuery, entityId, customerId, clientId, conversationId } = params;
+  const { searchQuery, entityId, customerId, clientId, conversationId, scopeRung } = params;
   switch (scope) {
     case "conversation":
-      return { searchQuery, entityId, customerId, clientId, conversationId };
+      return { searchQuery, entityId, customerId, clientId, conversationId, scopeRung };
     case "user":
-      return { searchQuery, entityId, customerId, clientId };
+      return { searchQuery, entityId, customerId, clientId, scopeRung };
     case "customer":
-      return { searchQuery, entityId: null, customerId, clientId };
+      return { searchQuery, entityId: null, customerId, clientId, scopeRung };
     case "client":
-      return { searchQuery, entityId: null, customerId: null, clientId };
+      return { searchQuery, entityId: null, customerId: null, clientId, scopeRung };
   }
 }
 function buildAnticipationResponse(hit) {
@@ -1988,6 +2106,7 @@ function tryServeFromCache(cache, scope, params, maxItems) {
       customerId: scoped.customerId ?? null,
       clientId: scoped.clientId ?? null,
       conversationId: scoped.conversationId ?? null,
+      scopeRung: scoped.scopeRung ?? null,
       maxItems
     });
     if (hit === null) return { response: null, hit: null };
@@ -2500,7 +2619,15 @@ var SynapClient = class {
             entityId: o2["user_id"] ?? o2["userId"],
             customerId: o2["customer_id"] ?? o2["customerId"],
             clientId: this.#transport.currentCredentials().clientId || null,
-            conversationId: o2["conversation_id"] ?? o2["conversationId"]
+            conversationId: o2["conversation_id"] ?? o2["conversationId"],
+            // The rung this read is addressed to, in the same words the server
+            // stamped on the bundles it pushed. Without it the cache matched
+            // on entity and conversation alone, so a bundle prefetched for one
+            // rung answered a caller standing at another, entirely inside this
+            // process and invisible to every server log.
+            scopeRung: rungKey(
+              o2["scope_path"] ?? o2["scopePath"]
+            )
           },
           Number(o2["max_results"] ?? o2["maxResults"] ?? 10)
         );
@@ -2545,9 +2672,9 @@ var SynapClient = class {
       ({ conversationId, role, content, timestamp }) => {
         this.#shortTerm.appendTurn(conversationId, role, content, timestamp);
       },
-      (response, conversationId, userId) => {
+      (response, conversationId, userId, scopePath) => {
         overlayLocalRecentTurns(response, this.#shortTerm, conversationId, this.#stVerbatimOverlay);
-        this.#injectUserSummary(response, conversationId, userId);
+        this.#injectUserSummary(response, conversationId, userId, rungKey(scopePath));
       },
       {
         prompt: (conversationId, style) => this.#localPrompt(conversationId, style),
@@ -2770,7 +2897,8 @@ var SynapClient = class {
     };
     const labels = [];
     const tasks = [];
-    if (conversationId !== void 0 && conversationId !== "" && wants("conversation")) {
+    const present = (v) => v !== void 0 && v !== null && v !== "";
+    if (present(conversationId) && wants("conversation")) {
       labels.push("conversation");
       tasks.push(this.conversation.context.fetch({
         conversation_id: conversationId,
@@ -2779,7 +2907,7 @@ var SynapClient = class {
         customer_id: customerId
       }));
     }
-    if (userId !== void 0 && userId !== "" && wants("user")) {
+    if (present(userId) && wants("user")) {
       labels.push("user");
       tasks.push(this.user.context.fetch({
         user_id: userId,
@@ -2791,7 +2919,7 @@ var SynapClient = class {
         last_n_conversations: lastNConversations
       }));
     }
-    if (customerId !== void 0 && customerId !== "" && wants("customer")) {
+    if (present(customerId) && wants("customer")) {
       labels.push("customer");
       tasks.push(this.customer.context.fetch({
         customer_id: customerId,
@@ -2825,7 +2953,7 @@ var SynapClient = class {
     for (const [, response] of successful) {
       overlayLocalRecentTurns(response, this.#shortTerm, conversationId, this.#stVerbatimOverlay);
     }
-    if (includeConversationContext && conversationId !== void 0 && conversationId !== "") {
+    if (includeConversationContext && present(conversationId)) {
       try {
         merged.conversation_context = await this.conversation.context.get_context_for_prompt({
           conversation_id: conversationId
@@ -2912,11 +3040,11 @@ var SynapClient = class {
    * cannot be scoped, and an unscoped lookup is how user A's summary ends up in
    * user B's response.
    */
-  #injectUserSummary(response, conversationId, userId) {
+  #injectUserSummary(response, conversationId, userId, scopeRung) {
     this.#turns.increment(conversationId);
     if (userId === void 0 || userId === "") return;
     if (!this.#turns.shouldInject(conversationId)) return;
-    const summary = this.#anticipationCache.lookupUserSummary(userId);
+    const summary = this.#anticipationCache.lookupUserSummary(userId, scopeRung);
     if (summary === null) return;
     mergeUserSummary(response, summary);
   }