@maximem/synap-js-sdk 0.4.4 → 0.4.6

package/dist/index.d.cts

@@ -234,6 +234,12 @@ interface TimeoutConfig {
     connect: number;
     read: number;
     write: number;
+    /**
+     * gRPC stream idle timeout. Not used by the HTTP transport; the stream
+     * client reads it. Present so a config object round-trips between the two
+     * SDKs, and because Python's TimeoutConfig has it.
+     */
+    streamIdle: number;
 }
 declare const DEFAULT_TIMEOUTS: TimeoutConfig;
 interface Credentials {
@@ -987,6 +993,16 @@ interface SendMessageOptions {
 }
 interface RecordThinkingOptions {
     content: string;
+    /**
+     * Ordinal of this thought within the current turn. Sent as a `step_index`
+     * metadata key, which is how Python's `record_thinking` transmits it: the
+     * proto has no dedicated field.
+     */
+    step_index?: number;
+    stepIndex?: number;
+    /** Free-form label for the kind of reasoning. Sent as `thought_type`. */
+    thought_type?: string;
+    thoughtType?: string;
     conversation_id?: string;
     conversationId?: string;
     user_id?: string;
@@ -1133,6 +1149,16 @@ type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
  * They return different shapes on purpose. See gotcha G-B.
  */
 
+/** Levels the SDK emits. Mirrors the subset of Python's logging it uses. */
+type SynapLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Receives every diagnostic the SDK would otherwise write to the console.
+ *
+ * Python routes these through the stdlib `logging` module, which is why it
+ * takes `log_level` and `logger`. There is no global logger in JavaScript, so
+ * the SDK takes the sink directly instead of a level plus a framework.
+ */
+type SynapLogger = (level: SynapLogLevel, message: string) => void;
 interface SynapClientOptions {
     /**
      * The four identity fields are `| undefined` rather than plain optional so a
@@ -1144,6 +1170,9 @@ interface SynapClientOptions {
     clientId?: string | undefined;
     instanceId?: string | undefined;
     baseUrl?: string | undefined;
+    /** Python spells this `api_base_url`; both are accepted so one config
+     *  object works against either SDK. */
+    api_base_url?: string | undefined;
     timeouts?: HttpTransportOptions['timeouts'];
     retryPolicy?: HttpTransportOptions['retryPolicy'];
     keepAlive?: HttpTransportOptions['keepAlive'];
@@ -1155,6 +1184,29 @@ interface SynapClientOptions {
      */
     heartbeat?: boolean;
     fetchImpl?: typeof fetch;
+    /**
+     * Splice locally-recorded turns into the next conversation-scope fetch, so a
+     * just-written turn is visible before the server compacts. Defaults to true,
+     * matching Python's `st_verbatim_overlay`. `SYNAP_ST_VERBATIM_OVERLAY`
+     * overrides this either way.
+     */
+    st_verbatim_overlay?: boolean | undefined;
+    stVerbatimOverlay?: boolean | undefined;
+    /**
+     * Let the SDK answer `get_context_for_prompt` and `get_compacted` from its
+     * own short-term store when the conversation is warm, skipping the cloud
+     * round trip. Off by default. `SYNAP_SDK_ST_AUTHORITATIVE` also enables it.
+     *
+     * This is the COST switch. `st_verbatim_overlay` is the correctness one and
+     * is independent of it.
+     */
+    sdk_st_authoritative?: boolean | undefined;
+    sdkStAuthoritative?: boolean | undefined;
+    /**
+     * Where the SDK's diagnostics go. Defaults to `console.warn` prefixed with
+     * `[synap]`. Pass a no-op to silence them, or your own logger to route them.
+     */
+    logger?: SynapLogger | undefined;
     /**
      * Bypass the process registry and build a genuinely separate client.
      *
@@ -1188,8 +1240,8 @@ interface ConfigureOptions {
     session_timeout_minutes?: number;
     /** Accepted and ignored. Python-only. */
     log_level?: string;
-    /** Accepted and ignored. Python-only. */
-    logger?: unknown;
+    /** Replaces the diagnostic sink, same as the constructor option. */
+    logger?: SynapLogger | undefined;
 }
 /** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
 interface UnifiedFetchOptions {
@@ -1315,11 +1367,12 @@ declare class SynapClient {
      * 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?: ConfigureOptions): void;
     /**
@@ -1654,4 +1707,4 @@ interface SynapSdkLike {
     };
 }
 
-export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, type SynapLogLevel, type SynapLogger, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };

package/dist/index.d.ts

@@ -234,6 +234,12 @@ interface TimeoutConfig {
     connect: number;
     read: number;
     write: number;
+    /**
+     * gRPC stream idle timeout. Not used by the HTTP transport; the stream
+     * client reads it. Present so a config object round-trips between the two
+     * SDKs, and because Python's TimeoutConfig has it.
+     */
+    streamIdle: number;
 }
 declare const DEFAULT_TIMEOUTS: TimeoutConfig;
 interface Credentials {
@@ -987,6 +993,16 @@ interface SendMessageOptions {
 }
 interface RecordThinkingOptions {
     content: string;
+    /**
+     * Ordinal of this thought within the current turn. Sent as a `step_index`
+     * metadata key, which is how Python's `record_thinking` transmits it: the
+     * proto has no dedicated field.
+     */
+    step_index?: number;
+    stepIndex?: number;
+    /** Free-form label for the kind of reasoning. Sent as `thought_type`. */
+    thought_type?: string;
+    thoughtType?: string;
     conversation_id?: string;
     conversationId?: string;
     user_id?: string;
@@ -1133,6 +1149,16 @@ type ToolDefinition = OpenAiToolDefinition | AnthropicToolDefinition;
  * They return different shapes on purpose. See gotcha G-B.
  */
 
+/** Levels the SDK emits. Mirrors the subset of Python's logging it uses. */
+type SynapLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Receives every diagnostic the SDK would otherwise write to the console.
+ *
+ * Python routes these through the stdlib `logging` module, which is why it
+ * takes `log_level` and `logger`. There is no global logger in JavaScript, so
+ * the SDK takes the sink directly instead of a level plus a framework.
+ */
+type SynapLogger = (level: SynapLogLevel, message: string) => void;
 interface SynapClientOptions {
     /**
      * The four identity fields are `| undefined` rather than plain optional so a
@@ -1144,6 +1170,9 @@ interface SynapClientOptions {
     clientId?: string | undefined;
     instanceId?: string | undefined;
     baseUrl?: string | undefined;
+    /** Python spells this `api_base_url`; both are accepted so one config
+     *  object works against either SDK. */
+    api_base_url?: string | undefined;
     timeouts?: HttpTransportOptions['timeouts'];
     retryPolicy?: HttpTransportOptions['retryPolicy'];
     keepAlive?: HttpTransportOptions['keepAlive'];
@@ -1155,6 +1184,29 @@ interface SynapClientOptions {
      */
     heartbeat?: boolean;
     fetchImpl?: typeof fetch;
+    /**
+     * Splice locally-recorded turns into the next conversation-scope fetch, so a
+     * just-written turn is visible before the server compacts. Defaults to true,
+     * matching Python's `st_verbatim_overlay`. `SYNAP_ST_VERBATIM_OVERLAY`
+     * overrides this either way.
+     */
+    st_verbatim_overlay?: boolean | undefined;
+    stVerbatimOverlay?: boolean | undefined;
+    /**
+     * Let the SDK answer `get_context_for_prompt` and `get_compacted` from its
+     * own short-term store when the conversation is warm, skipping the cloud
+     * round trip. Off by default. `SYNAP_SDK_ST_AUTHORITATIVE` also enables it.
+     *
+     * This is the COST switch. `st_verbatim_overlay` is the correctness one and
+     * is independent of it.
+     */
+    sdk_st_authoritative?: boolean | undefined;
+    sdkStAuthoritative?: boolean | undefined;
+    /**
+     * Where the SDK's diagnostics go. Defaults to `console.warn` prefixed with
+     * `[synap]`. Pass a no-op to silence them, or your own logger to route them.
+     */
+    logger?: SynapLogger | undefined;
     /**
      * Bypass the process registry and build a genuinely separate client.
      *
@@ -1188,8 +1240,8 @@ interface ConfigureOptions {
     session_timeout_minutes?: number;
     /** Accepted and ignored. Python-only. */
     log_level?: string;
-    /** Accepted and ignored. Python-only. */
-    logger?: unknown;
+    /** Replaces the diagnostic sink, same as the constructor option. */
+    logger?: SynapLogger | undefined;
 }
 /** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
 interface UnifiedFetchOptions {
@@ -1315,11 +1367,12 @@ declare class SynapClient {
      * 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?: ConfigureOptions): void;
     /**
@@ -1654,4 +1707,4 @@ interface SynapSdkLike {
     };
 }
 
-export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { AgentUnavailableError, type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, AuthenticationError, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, ConflictError, ConnectionError, type ContextMetadata, ContextNotFoundError, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DocumentType, ENDPOINTS, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, type Fact, type FetchOptions, type FlatMemory, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, InsufficientCreditsError, InvalidConversationIdError, InvalidInputError, InvalidInstanceIdError, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, ListeningAlreadyActiveError, ListeningNotActiveError, type MemoriesInterface, NetworkTimeoutError, type NormalisedContext, type OpenAiToolDefinition, PermanentError, type Preference, RateLimitError, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDKError, SDK_VERSION, type Scope, type SendMessageOptions, ServiceUnavailableError, SessionExpiredError, SynapClient, type SynapClientOptions, SynapError, type SynapErrorCode, type SynapErrorOptions, type SynapLogLevel, type SynapLogger, SynapPermanentError, type SynapSdkLike, SynapTransientError, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, TranscriptConflictError, type TranscriptIngestResult, type TranscriptTurn, TransientError, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, isSynapError, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };

package/dist/index.js

@@ -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 = class {
   baseUrl;
   // 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 : v.conversation_id ?? v.conversationId;
     if (!id) throw new 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, options.style ?? "structured");
+        if (local !== null) return local;
         const result = await transport.request("context_for_prompt", {
           pathParams: { conversation_id: id },
           query: { style: 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, options.format ?? "structured");
+          if (local !== null) return local;
+        }
         const query = { format: 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 = { ...options.metadata ?? {} };
+  const step = options.step_index ?? options.stepIndex;
+  if (step !== void 0 && md["step_index"] === void 0) {
+    md["step_index"] = String(step);
+  }
+  const kind = 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: options.user_id ?? options.userId ?? "",
         customer_id: options.customer_id ?? options.customerId ?? "",
         session_id: options.session_id ?? options.sessionId ?? "",
-        metadata: 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 = (getEnv("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 configured ?? true;
 }
 function estimateTokens(turn) {
   return Math.max(1, Math.floor(String(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 = 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 JSON.stringify(value) ?? "";
+  } catch {
+    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 (turns ?? []).map((t, idx) => ({
+    role: t.role || "user",
+    content: 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 = 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 = 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(entry.currentState ?? {})) {
+    parts.push(`- ${k}: ${stringify(v)}`);
+  }
+  for (const [cat, items] of Object.entries(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;
@@ -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 = options.st_verbatim_overlay ?? options.stVerbatimOverlay;
+    this.#logger = options.logger;
+    this.#stAuthoritative = 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);
@@ -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(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,7 +2819,7 @@ 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 {
@@ -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 = (getEnv("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 = options.baseUrl ?? options.api_base_url;
+  if (explicit !== void 0) return explicit;
   const fromEnv = getEnv("SYNAP_BASE_URL")?.trim();
   return fromEnv !== void 0 && fromEnv !== "" ? fromEnv : void 0;
 }