@maximem/synap-js-sdk 0.4.4 → 0.4.6

package/dist/index.cjs

@@ -212,7 +212,12 @@ function checkCustomerId(isolation, customerId, where, instanceId) {
 
 // src/transport/http.ts
 var DEFAULT_BASE_URL = "https://synap-cloud-prod.maximem.ai";
-var DEFAULT_TIMEOUTS = { connect: 5, read: 30, write: 10 };
+var DEFAULT_TIMEOUTS = {
+  connect: 5,
+  read: 30,
+  write: 10,
+  streamIdle: 60
+};
 var HttpTransport = (_class2 = class {
   
   // Mutable so `configure()` can adjust them before the first request, and so
@@ -1121,7 +1126,7 @@ var CompactionSubscribers = class {
 function createConversationNamespace(transport, subscribers = new CompactionSubscribers(), onWrite = () => {
 }, onTurn = () => {
 }, onFetched = () => {
-}) {
+}, localShortTerm = { prompt: () => null, compacted: () => null }) {
   const convId = (v) => {
     const id = typeof v === "string" ? v : _nullishCoalesce(v.conversation_id, () => ( v.conversationId));
     if (!id) throw new (0, _chunk2TVL5IPQcjs.InvalidInputError)("conversation_id is required");
@@ -1202,6 +1207,8 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       },
       get_context_for_prompt: async (options = {}) => {
         const id = convId(options);
+        const local = localShortTerm.prompt(id, _nullishCoalesce(options.style, () => ( "structured")));
+        if (local !== null) return local;
         const result = await transport.request("context_for_prompt", {
           pathParams: { conversation_id: id },
           query: { style: _nullishCoalesce(options.style, () => ( "structured")) }
@@ -1213,6 +1220,10 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       },
       get_compacted: async (options) => {
         const id = convId(options);
+        if (options.version === void 0) {
+          const local = localShortTerm.compacted(id, _nullishCoalesce(options.format, () => ( "structured")));
+          if (local !== null) return local;
+        }
         const query = { format: _nullishCoalesce(options.format, () => ( "structured")) };
         if (options.version !== void 0) query["version"] = options.version;
         try {
@@ -1343,6 +1354,18 @@ function envTls() {
   if (raw === void 0 || raw === "") return void 0;
   return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
 }
+function thinkingMetadata(options) {
+  const md = { ..._nullishCoalesce(options.metadata, () => ( {})) };
+  const step = _nullishCoalesce(options.step_index, () => ( options.stepIndex));
+  if (step !== void 0 && md["step_index"] === void 0) {
+    md["step_index"] = String(step);
+  }
+  const kind = _nullishCoalesce(options.thought_type, () => ( options.thoughtType));
+  if (kind && md["thought_type"] === void 0) {
+    md["thought_type"] = kind;
+  }
+  return md;
+}
 function createInstanceNamespace(credentials, cache, onTurn) {
   let client = null;
   let dispatchCompaction = null;
@@ -1454,7 +1477,7 @@ function createInstanceNamespace(credentials, cache, onTurn) {
         user_id: _nullishCoalesce(_nullishCoalesce(options.user_id, () => ( options.userId)), () => ( "")),
         customer_id: _nullishCoalesce(_nullishCoalesce(options.customer_id, () => ( options.customerId)), () => ( "")),
         session_id: _nullishCoalesce(_nullishCoalesce(options.session_id, () => ( options.sessionId)), () => ( "")),
-        metadata: _nullishCoalesce(options.metadata, () => ( {})),
+        metadata: thinkingMetadata(options),
         timestamp_ms: Date.now()
       });
     },
@@ -1637,11 +1660,11 @@ var ShortTermStore = class {
 // src/context/overlay.ts
 var MAX_TURNS = 20;
 var TOKEN_BUDGET = 2e3;
-function verbatimOverlayEnabled() {
+function verbatimOverlayEnabled(configured) {
   const raw = (_nullishCoalesce(_chunkZKOJDUN4cjs.getEnv.call(void 0, "SYNAP_ST_VERBATIM_OVERLAY"), () => ( ""))).trim().toLowerCase();
   if (["0", "false", "no", "off"].includes(raw)) return false;
   if (["1", "true", "yes", "on"].includes(raw)) return true;
-  return true;
+  return _nullishCoalesce(configured, () => ( true));
 }
 function estimateTokens(turn) {
   return Math.max(1, Math.floor(String(_nullishCoalesce(turn.content, () => ( ""))).length / 4));
@@ -1655,13 +1678,13 @@ function budgetRecentTurns(turns) {
   }
   return windowed;
 }
-function overlayLocalRecentTurns(response, store, conversationId) {
+function overlayLocalRecentTurns(response, store, conversationId, configured) {
   if (conversationId === void 0 || conversationId === "") return;
   try {
     const entry = store.get(conversationId);
     if (entry === null) return;
     const existing = _nullishCoalesce(response.conversation_context, () => ( null));
-    if (existing !== null && !verbatimOverlayEnabled()) return;
+    if (existing !== null && !verbatimOverlayEnabled(configured)) return;
     const localTurns = budgetRecentTurns(entry.recentTurns);
     const serverField = (name) => existing === null ? void 0 : existing[name];
     const orLocal = (name, local) => {
@@ -1683,6 +1706,158 @@ function overlayLocalRecentTurns(response, store, conversationId) {
   }
 }
 
+// src/context/local-prompt.ts
+var SUPPORTED_STYLES = ["structured", "narrative", "bullet_points"];
+var DEFAULT_STYLE = "structured";
+function stringify(value) {
+  if (value === null || value === void 0) return "";
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return String(value);
+  try {
+    return _nullishCoalesce(JSON.stringify(value), () => ( ""));
+  } catch (e6) {
+    return String(value);
+  }
+}
+function asListOfObjects(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const v of value) {
+      if (v && typeof v === "object" && !Array.isArray(v)) out.push(v);
+      else if (typeof v === "string") out.push({ content: v });
+    }
+    return out;
+  }
+  if (typeof value === "object") return [value];
+  return [];
+}
+function itemText(item) {
+  return item["content"] || item["text"] || stringify(item);
+}
+function buildRecentMessages(turns) {
+  return (_nullishCoalesce(turns, () => ( []))).map((t, idx) => ({
+    role: t.role || "user",
+    content: _nullishCoalesce(t.content, () => ( "")),
+    timestamp: t.timestamp,
+    message_id: `local-${idx}`
+  }));
+}
+function compactedMessageCount(_entry) {
+  return 0;
+}
+function formatStructured(entry, recent) {
+  const parts = [];
+  if (entry.summary) {
+    parts.push("## Summary");
+    parts.push(entry.summary.trim());
+  }
+  if (entry.factualParagraph) {
+    parts.push("## Facts");
+    parts.push(entry.factualParagraph.trim());
+  }
+  if (entry.conversationalParagraph) {
+    parts.push("## Conversation");
+    parts.push(entry.conversationalParagraph.trim());
+  }
+  const cs = _nullishCoalesce(entry.currentState, () => ( {}));
+  if (Object.keys(cs).length > 0) {
+    parts.push("## Current State");
+    for (const [k, v] of Object.entries(cs)) parts.push(`- ${k}: ${stringify(v)}`);
+  }
+  const ke = _nullishCoalesce(entry.keyExtractions, () => ( {}));
+  if (Object.keys(ke).length > 0) {
+    parts.push("## Key Extractions");
+    for (const [cat, items] of Object.entries(ke)) {
+      if (!items) continue;
+      parts.push(`### ${cat}`);
+      for (const it of asListOfObjects(items)) parts.push(`- ${itemText(it)}`);
+    }
+  }
+  if (recent.length > 0) {
+    parts.push(`## Recent Turns (${recent.length})`);
+    for (const m of recent) parts.push(`**${m.role}**: ${m.content}`);
+  }
+  return parts.filter(Boolean).join("\n\n").trim();
+}
+function formatNarrative(entry, recent) {
+  const parts = [];
+  if (entry.summary) parts.push(entry.summary.trim());
+  if (entry.conversationalParagraph) parts.push(entry.conversationalParagraph.trim());
+  else if (entry.factualParagraph) parts.push(entry.factualParagraph.trim());
+  if (recent.length > 0) {
+    const tail = recent.map((m) => `${m.role}: ${m.content}`).join("\n");
+    parts.push(`Recent exchanges:
+${tail}`);
+  }
+  return parts.filter(Boolean).join("\n\n").trim();
+}
+function formatBullets(entry, recent) {
+  const parts = [];
+  if (entry.summary) parts.push(`- Summary: ${entry.summary.trim()}`);
+  for (const [k, v] of Object.entries(_nullishCoalesce(entry.currentState, () => ( {})))) {
+    parts.push(`- ${k}: ${stringify(v)}`);
+  }
+  for (const [cat, items] of Object.entries(_nullishCoalesce(entry.keyExtractions, () => ( {})))) {
+    for (const it of asListOfObjects(items)) parts.push(`- (${cat}) ${itemText(it)}`);
+  }
+  for (const m of recent) parts.push(`- ${m.role}: ${m.content}`);
+  return parts.join("\n").trim();
+}
+function formatBlock(entry, recent, style) {
+  if (style === "narrative") return formatNarrative(entry, recent);
+  if (style === "bullet_points") return formatBullets(entry, recent);
+  return formatStructured(entry, recent);
+}
+function renderForPrompt(entry, style = DEFAULT_STYLE, now = Date.now) {
+  const chosen = SUPPORTED_STYLES.includes(style) ? style : DEFAULT_STYLE;
+  const recent = buildRecentMessages(entry.recentTurns);
+  const formatted = formatBlock(entry, recent, chosen);
+  const available = entry.compactionId !== null || entry.recentTurns.length > 0;
+  let compactionAge = null;
+  if (entry.compactedAt !== null) {
+    const parsed = Date.parse(entry.compactedAt);
+    if (!Number.isNaN(parsed)) compactionAge = Math.floor((now() - parsed) / 1e3);
+  }
+  const compacted = compactedMessageCount(entry);
+  return {
+    formatted_context: available ? formatted : null,
+    available,
+    is_stale: false,
+    compression_ratio: null,
+    validation_score: null,
+    compaction_age_seconds: compactionAge,
+    quality_warning: false,
+    recent_messages: recent,
+    recent_message_count: recent.length,
+    compacted_message_count: compacted,
+    total_message_count: recent.length + compacted
+  };
+}
+function renderCompacted(entry, format = "structured", correlationId = "") {
+  if (entry.compactionId === null) return null;
+  const formatted = formatBlock(
+    entry,
+    buildRecentMessages(entry.recentTurns),
+    format === "narrative" ? "narrative" : "structured"
+  );
+  return {
+    compacted_context: formatted,
+    compaction_id: entry.compactionId,
+    compacted_at: entry.compactedAt,
+    conversation_id: entry.conversationId,
+    current_state: entry.currentState,
+    correlation_id: correlationId,
+    original_token_count: null,
+    compacted_token_count: null,
+    compression_ratio: null,
+    level_applied: null,
+    validation_score: null,
+    validation_passed: null,
+    quality_warning: false
+  };
+}
+
 // src/context/user-summary.ts
 var USER_SUMMARY_INTERVAL = 5;
 var MAX_SUMMARY_ITEMS = 3;
@@ -1813,7 +1988,7 @@ function tryServeFromCache(cache, scope, params, maxItems) {
     });
     if (hit === null) return { response: null, hit: null };
     return { response: buildAnticipationResponse(hit), hit };
-  } catch (e6) {
+  } catch (e7) {
     return { response: null, hit: null };
   }
 }
@@ -2271,6 +2446,9 @@ var SynapClient = class {
   #registryKeys;
   #compactionSubscribers;
   #shortTerm;
+  #stVerbatimOverlay;
+  #logger;
+  #stAuthoritative;
   #turns;
   #fetchHooks;
   constructor(options = {}) {
@@ -2341,6 +2519,9 @@ var SynapClient = class {
     this.client = { context: { fetch: async (o2 = {}) => fetchContext(this.#transport, "client", o2, this.#fetchHooks) } };
     this.#compactionSubscribers = new CompactionSubscribers();
     this.#shortTerm = new ShortTermStore();
+    this.#stVerbatimOverlay = _nullishCoalesce(options.st_verbatim_overlay, () => ( options.stVerbatimOverlay));
+    this.#logger = options.logger;
+    this.#stAuthoritative = _nullishCoalesce(options.sdk_st_authoritative, () => ( options.sdkStAuthoritative));
     this.#turns = new TurnCounter();
     this.conversation = createConversationNamespace(
       this.#transport,
@@ -2361,8 +2542,12 @@ var SynapClient = class {
         this.#shortTerm.appendTurn(conversationId, role, content, timestamp);
       },
       (response, conversationId, userId) => {
-        overlayLocalRecentTurns(response, this.#shortTerm, conversationId);
+        overlayLocalRecentTurns(response, this.#shortTerm, conversationId, this.#stVerbatimOverlay);
         this.#injectUserSummary(response, conversationId, userId);
+      },
+      {
+        prompt: (conversationId, style) => this.#localPrompt(conversationId, style),
+        compacted: (conversationId, format) => this.#localCompacted(conversationId, format)
       }
     );
     this.memories = createMemoriesInterface(this.#transport);
@@ -2495,7 +2680,7 @@ var SynapClient = class {
           this.#registryKeys.push(resolvedInstanceId);
         }
       }
-    } catch (e7) {
+    } catch (e8) {
     }
   }
   /**
@@ -2521,11 +2706,12 @@ var SynapClient = class {
    * initialization: the transport and cache are already built by then and a
    * half-applied config is worse than a rejected one.
    *
-   * The Python-only keys (`storage_path`, `cache_backend`,
-   * `session_timeout_minutes`, `logger`) are accepted and ignored rather than
-   * rejected, because this SDK has no SQLite cache backend and no global
-   * logger to swap. Ignoring them keeps a shared config object portable
-   * between the two SDKs.
+   * `logger` is honoured here as well as on the constructor. The remaining
+   * Python-only keys (`storage_path`, `cache_backend`,
+   * `session_timeout_minutes`, `log_level`) are accepted and ignored rather
+   * than rejected, because this SDK has no SQLite cache backend and no global
+   * logging framework whose level there would be to set. Ignoring them keeps
+   * a shared config object portable between the two SDKs.
    */
   configure(options = {}) {
     if (this.#initialized) {
@@ -2535,6 +2721,7 @@ var SynapClient = class {
     if (options.retryPolicy !== void 0 || options.retry_policy !== void 0) {
       this.#transport.setRetryPolicy(_nullishCoalesce(_nullishCoalesce(options.retryPolicy, () => ( options.retry_policy)), () => ( null)));
     }
+    if (options.logger !== void 0) this.#logger = options.logger;
   }
   /**
    * Fetch and merge context across every scope with an identifier, in one call.
@@ -2632,14 +2819,14 @@ var SynapClient = class {
     }
     const merged = mergeScopeResults(successful);
     for (const [, response] of successful) {
-      overlayLocalRecentTurns(response, this.#shortTerm, conversationId);
+      overlayLocalRecentTurns(response, this.#shortTerm, conversationId, this.#stVerbatimOverlay);
     }
     if (includeConversationContext && conversationId !== void 0 && conversationId !== "") {
       try {
         merged.conversation_context = await this.conversation.context.get_context_for_prompt({
           conversation_id: conversationId
         });
-      } catch (e8) {
+      } catch (e9) {
       }
     }
     merged.formatted_context = formatForPrompt(merged, {
@@ -2686,7 +2873,7 @@ var SynapClient = class {
         source_bundle_ids: served.bundleId ? [served.bundleId] : [],
         timestamp_ms: Date.now()
       });
-    } catch (e9) {
+    } catch (e10) {
     }
   }
   /**
@@ -2711,7 +2898,7 @@ var SynapClient = class {
         }),
         scope
       });
-    } catch (e10) {
+    } catch (e11) {
     }
   }
   /**
@@ -2729,8 +2916,44 @@ var SynapClient = class {
     if (summary === null) return;
     mergeUserSummary(response, summary);
   }
-  /** Python logs via `logger.warning`; here it is one overridable seam. */
+  /**
+   * Whether the SDK is authoritative for short-term context.
+   *
+   * Resolution order matches Python's `_is_st_authoritative`: the explicit
+   * option first, then `SYNAP_SDK_ST_AUTHORITATIVE` (truthy strings only).
+   * Defaults to false, so nothing changes for a caller who never sets it.
+   */
+  #isStAuthoritative() {
+    if (this.#stAuthoritative === true) return true;
+    const raw = (_nullishCoalesce(_chunkZKOJDUN4cjs.getEnv.call(void 0, "SYNAP_SDK_ST_AUTHORITATIVE"), () => ( ""))).trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+  }
+  /**
+   * Render `get_context_for_prompt` from the local store, or null to fall
+   * through to the network. Warm means a compaction landed OR raw turns are
+   * buffered: with neither there is nothing to render and the server's answer
+   * is the only real one.
+   */
+  #localPrompt(conversationId, style) {
+    if (!this.#isStAuthoritative()) return null;
+    const entry = this.#shortTerm.get(conversationId);
+    if (entry === null) return null;
+    if (entry.compactionId === null && entry.recentTurns.length === 0) return null;
+    return renderForPrompt(entry, style);
+  }
+  /** Same, for `get_compacted`. Requires an actual compaction, not just turns. */
+  #localCompacted(conversationId, format) {
+    if (!this.#isStAuthoritative()) return null;
+    const entry = this.#shortTerm.get(conversationId);
+    if (entry === null || entry.compactionId === null) return null;
+    return renderCompacted(entry, format);
+  }
+  /** Every diagnostic the SDK emits passes through here. */
   #warn(message) {
+    if (this.#logger !== void 0) {
+      this.#logger("warn", message);
+      return;
+    }
     console.warn(`[synap] ${message}`);
   }
   /** Release timers and connections. Safe to call more than once. */
@@ -2751,7 +2974,8 @@ function pick3(o2, snake, camel) {
   return a !== void 0 ? a : o2[camel];
 }
 function resolveBaseUrl(options) {
-  if (options.baseUrl !== void 0) return options.baseUrl;
+  const explicit = _nullishCoalesce(options.baseUrl, () => ( options.api_base_url));
+  if (explicit !== void 0) return explicit;
   const fromEnv = _optionalChain([_chunkZKOJDUN4cjs.getEnv.call(void 0, "SYNAP_BASE_URL"), 'optionalAccess', _51 => _51.trim, 'call', _52 => _52()]);
   return fromEnv !== void 0 && fromEnv !== "" ? fromEnv : void 0;
 }