@maximem/synap-js-sdk 0.5.8 → 0.5.9

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AnticipationCacheSnapshot } from './errors-Bl3vY1eb.js';
-export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, E as ExitReason, I as InsufficientCreditsError, i as InvalidConversationIdError, j as InvalidInputError, k as InvalidInstanceIdError, L as ListeningAlreadyActiveError, l as ListeningNotActiveError, m as LookupParams, n as LookupResult, o as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, p as SDKError, q as ServiceUnavailableError, r as SessionExpiredError, s as SnapshotBundle, t as SnapshotItemPreview, u as SnapshotItemRecord, S as SynapError, v as SynapErrorCode, w as SynapErrorOptions, x as SynapPermanentError, y as SynapTransientError, T as TranscriptConflictError, z as TransientError, D as isSynapError } from './errors-Bl3vY1eb.js';
+import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-Bdayqlzy.js';
+export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as ExitReason, I as InsufficientCreditsError, j as InvalidConversationIdError, k as InvalidInputError, l as InvalidInstanceIdError, L as ListeningAlreadyActiveError, m as ListeningNotActiveError, n as LookupParams, o as LookupResult, p as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, q as SDKError, r as ServiceUnavailableError, s as SessionExpiredError, t as SnapshotBundle, u as SnapshotItemPreview, v as SnapshotItemRecord, S as SynapError, w as SynapErrorCode, x as SynapErrorOptions, y as SynapPermanentError, z as SynapTransientError, T as TranscriptConflictError, D as TransientError, F as isSynapError } from './errors-Bdayqlzy.js';
 
 /**
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -90,6 +90,11 @@ declare const ENDPOINTS: {
         readonly path: "/v1/conversations/{conversation_id}/context-for-prompt";
         readonly idempotent: true;
     };
+    readonly conversation_turns: {
+        readonly method: "GET";
+        readonly path: "/v1/conversations/{conversation_id}/messages";
+        readonly idempotent: true;
+    };
     readonly conversations_ingest: {
         readonly method: "POST";
         readonly path: "/v1/conversations/ingest";
@@ -422,6 +427,14 @@ interface RawContext {
     episodes?: RawContextItem[];
     emotions?: RawContextItem[];
     temporal_events?: RawContextItem[];
+    /**
+     * `response_shape: "ranked"` only: every item once, best first across
+     * types, each with `rank`, `category` and `metadata.rank_score`. The five
+     * lists above are then views of these same items, by type.
+     */
+    items?: RawContextItem[];
+    /** `response_shape: "ranked"` only: the chunks, quotes from source documents. */
+    excerpts?: RawContextItem[];
     conversation_context?: RawConversationContext | null;
     metadata?: Json;
     [key: string]: unknown;
@@ -533,6 +546,25 @@ interface ContextMetadata {
     retrievedAt: string | null;
     compactionApplied: boolean | null;
 }
+/**
+ * Why a fetch may be thinner than the stores can support. Null when healthy.
+ *
+ * `degraded` says something went wrong, `level` how thin the answer is
+ * ("partial" | "minimal" | "failed"), and `code` whether a retry is worth it
+ * ("timeout" | "overloaded" | "unavailable" | "internal"). The server never
+ * names which of its services broke.
+ *
+ * It had no slot here, and that is how a real failure stayed invisible: a
+ * retrieval that lost its embedding call returned 200 with zero items for a
+ * user holding 122 memories, and the caller could not tell that from "no
+ * relevant memories".
+ */
+interface RetrievalHealth {
+    degraded: boolean;
+    level: string | null;
+    code: string | null;
+    warnings: string[];
+}
 interface NormalisedContext {
     facts: Fact[];
     preferences: Preference[];
@@ -541,7 +573,17 @@ interface NormalisedContext {
     temporalEvents: TemporalEvent[];
     conversationContext: ConversationContext | null;
     metadata: ContextMetadata;
+    retrieval: RetrievalHealth | null;
     rawResponse: Json;
+    /**
+     * `response_shape: "ranked"` only, and absent otherwise: every item once, best
+     * first across types, as the wire sends it (snake_case, with `rank`,
+     * `category` and `metadata.rank_score`). The five lists above hold the same
+     * items by type, except the chunks, which are in `excerpts`.
+     */
+    items?: RawContextItem[];
+    /** `response_shape: "ranked"` only, and absent otherwise: the chunks, quotes from source documents. */
+    excerpts?: RawContextItem[];
 }
 /**
  * Fetch options.
@@ -611,6 +653,18 @@ interface FetchOptions {
     /** Explicit scope ladder. Sent as `scope` when supplied. */
     scope_path?: Record<string, string>;
     scopePath?: Record<string, string>;
+    /**
+     * `"by_type"` (default): the five typed lists, as every earlier SDK version
+     * got them. `"ranked"`: also `items`, every item once in the order the
+     * server ranked them across types, with chunks typed as `excerpts`; the
+     * typed lists are then views of those items.
+     *
+     * Sent only when `"ranked"`, so a default fetch sends the body it always
+     * did. A server that predates the parameter returns the five lists, and the
+     * SDK then builds `items` from them by `metadata.rank_score`.
+     */
+    response_shape?: string;
+    responseShape?: string;
 }
 
 /**
@@ -913,6 +967,15 @@ interface RecordMessageOptions {
      */
     scope_path?: Record<string, string>;
     scopePath?: Record<string, string>;
+    /**
+     * The model the agent runs on, e.g. `'gpt-4o'`. Overrides the client's
+     * `agent_model` for this turn. The server sizes compaction to this model's
+     * context window. Python's `model=`.
+     */
+    model?: string;
+    /** The agent model's context window in tokens, for a model the server would not know. */
+    context_window?: number;
+    contextWindow?: number;
 }
 interface TranscriptTurn {
     role: string;
@@ -995,6 +1058,11 @@ interface ConversationNamespace {
             conversation_id?: string;
             conversationId?: string;
             style?: string;
+            /** Search the earlier turns locally after a compaction (default true). */
+            search_history?: boolean;
+            searchHistory?: boolean;
+            /** What to search for; defaults to the latest user message. */
+            query?: string;
         }): Promise<Json>;
         compact(options: CompactOptions): Promise<Json>;
         get_compacted(options: {
@@ -1195,6 +1263,10 @@ interface SendMessageOptions {
     event_type?: string;
     eventType?: string;
     metadata?: Record<string, string>;
+    /** The agent's model, as on `conversation.record_message`. Python's `model=`. */
+    model?: string;
+    context_window?: number;
+    contextWindow?: number;
     /**
      * Report a tool call on the stream. Python's `send_message` takes both, and
      * the proto has `tool_name` / `tool_args_json`; the JS surface simply never
@@ -1293,6 +1365,16 @@ interface InstanceInternals {
     onCompactionUpdate(conversationId: string, bundle: Record<string, unknown>): void;
     /** Set by the client so a compaction can prune the locally buffered tail. */
     setCompactionApplier(apply: (bundle: Record<string, unknown>) => void): void;
+    /**
+     * Set by the client: called when `listen()` starts, which is when prefetched
+     * bundles begin to arrive, so the local embedding model loads then.
+     */
+    setOnListen(handle: () => void): void;
+    /**
+     * Set by the client. Receives the server's message count for a conversation
+     * after each streamed write has been stored.
+     */
+    setConversationStateHandler(handle: (conversationId: string, messageCount: number) => void): void;
     /** Learning-loop event, fired after a fetch is served from the cache. */
     sendContextUsed(event: Record<string, unknown>): void;
     /** Audit event, fired after every fetch resolves. */
@@ -1321,6 +1403,13 @@ interface UnifiedContext {
     episodes: RawContextItem[];
     emotions: RawContextItem[];
     temporal_events: RawContextItem[];
+    /**
+     * `response_shape: "ranked"` only: every item once, best first across
+     * scopes and types, renumbered from 1. Empty for a by-type fetch.
+     */
+    items: RawContextItem[];
+    /** `response_shape: "ranked"` only: the chunks (quotes from source documents). */
+    excerpts: RawContextItem[];
     /** item id -> the scope that supplied it. */
     scope_map: Record<string, string>;
     conversation_context: Json | null;
@@ -1457,16 +1546,57 @@ interface SynapClientOptions {
      */
     st_verbatim_overlay?: boolean | undefined;
     stVerbatimOverlay?: boolean | undefined;
+    /**
+     * The model the agent runs on, and optionally its context window. Sent with
+     * every recorded turn so the server sizes compaction to the agent's window
+     * (it compacts at ~11.7% of it: 15K tokens on a 128K model). A name is
+     * enough; the server knows common models' windows. Unset = 128K. Python's
+     * `SDKConfig.agent_model` / `agent_context_window`; per-call `model` /
+     * `context_window` override them.
+     */
+    agent_model?: string | undefined;
+    agentModel?: string | undefined;
+    agent_context_window?: number | undefined;
+    agentContextWindow?: number | 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.
+     * round trip. Off by default. `SYNAP_SDK_ST_AUTHORITATIVE` overrides this in
+     * either direction.
+     *
+     * Leave it off for an application that runs more than one process against
+     * the same conversation. A process learns the server's message count only
+     * when it writes. If it reads before it writes (build the prompt, then
+     * record the turn), it cannot know that another process recorded a turn in
+     * between, and it answers without that turn. Turn it on where one process
+     * owns a conversation for its whole life, such as a voice agent.
      *
      * 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;
+    /**
+     * Your own embedding model for history search after compaction
+     * (cache/history-search.ts), any `{ model, encode }`. It replaces the
+     * SDK's model for history search; the anticipation cache uses it only if it
+     * is the model its thresholds were tuned on (`history_search_model`).
+     */
+    history_search_encoder?: Encoder | undefined;
+    historySearchEncoder?: Encoder | undefined;
+    /**
+     * The local embedding model, as Python's `history_search_model`: history
+     * search after compaction, and matching fetch queries to prefetched items by
+     * meaning. "auto" (default) runs the SDK's multilingual model in Node when
+     * the optional `onnxruntime-node` and `@huggingface/tokenizers` packages are
+     * installed: downloaded once (about 135 MB) into ~/.synap/models when the
+     * first stream starts or the first history search runs, then loaded in the
+     * background. An "onnx:<repo>@<revision>/<file>" names another (history
+     * search only). null keeps keyword matching. Never loaded on Edge or in a
+     * browser.
+     */
+    history_search_model?: string | null | undefined;
+    historySearchModel?: string | null | 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.
@@ -1505,6 +1635,11 @@ interface ConfigureOptions {
     session_timeout_minutes?: number;
     /** Accepted and ignored. Python-only. */
     log_level?: string;
+    /** The agent's model; see `SynapClientOptions.agent_model`. */
+    agent_model?: string;
+    agentModel?: string;
+    agent_context_window?: number;
+    agentContextWindow?: number;
     /** Replaces the diagnostic sink, same as the constructor option. */
     logger?: SynapLogger | undefined;
 }
@@ -1537,6 +1672,13 @@ interface UnifiedFetchOptions {
     context_mode?: string;
     include_profile?: boolean;
     last_n_conversations?: number;
+    /**
+     * `"by_type"` (default) or `"ranked"`. Ranked asks every scope for its
+     * ranked list and merges them into `items`, best first across scopes and
+     * types, by each item's `rank_score`; `formatted_context` is then one
+     * numbered list in that order. The typed lists are filled either way.
+     */
+    response_shape?: string;
 }
 declare class SynapClient {
     #private;
@@ -1683,6 +1825,19 @@ declare class SynapClient {
      * snake_case shape, since this output gets logged and compared across SDKs.
      */
     anticipation_cache_snapshot(): AnticipationCacheSnapshot;
+    /**
+     * Keep what a tool returned in this process's turn archive, so history search
+     * can find it after a compaction. Never sent anywhere: the server's
+     * conversation holds what people said, and a compaction is made from that.
+     * `instance.record_tool_result` calls this too. Python: `archive_tool_result`.
+     */
+    archive_tool_result(conversationId: string, result: unknown, options?: {
+        tool_name?: string | null;
+        toolName?: string | null;
+        timestamp?: string;
+    }): void;
+    static readonly BACKFILL_COOLDOWN_MS = 60000;
+    static readonly BACKFILL_PAGE = 500;
     /** Release timers and connections. Safe to call more than once. */
     shutdown(): Promise<void>;
 }
@@ -1701,7 +1856,55 @@ declare class SynapClient {
  * build when the two disagree, which is the only thing that makes a manual
  * publish safe.
  */
-declare const SDK_VERSION = "0.5.8";
+declare const SDK_VERSION = "0.5.9";
+
+/**
+ * `response_shape: "ranked"`: one list in the order the server ranked it.
+ *
+ * Ports the ranked half of Python's `models/context.py` (`rank_items`,
+ * `_wire_rank_score`, `_wire_category` and the ranked branch of
+ * `ContextResponse.from_cloud_response`). The cases are pinned in
+ * `CONTRACT/conformance/ranked_shape.json`, captured from Python.
+ *
+ * Opt-in. A by-type fetch, the default, is returned exactly as the server sent
+ * it, so nothing here touches a caller who does not ask for the ranked shape.
+ */
+
+/** The two shapes a context fetch can ask for. */
+declare const RESPONSE_SHAPES: readonly ["by_type", "ranked"];
+type ResponseShape = (typeof RESPONSE_SHAPES)[number];
+/** The memory types, in the order the by-type response lists them. */
+declare const MEMORY_TYPES: readonly ["facts", "preferences", "episodes", "emotions", "temporal_events"];
+/**
+ * The type of a chunk in a ranked response: a quote from a source document,
+ * not an extracted memory. A by-type response files it under `facts`.
+ */
+declare const EXCERPT_CATEGORY = "excerpts";
+/**
+ * An item's rank score: `metadata.rank_score` on the HTTP response, a
+ * top-level `rank_score` on a prefetched (gRPC) item. `null` when neither is a
+ * number, which is how a server that predates ranking reads.
+ */
+declare function wireRankScore(item: RawContextItem): number | null;
+/**
+ * Merge per-type item lists into one list in rank order, numbered from 1.
+ *
+ * For a server that predates `response_shape` (it returned the five lists) and
+ * for a prefetched cache hit. Each returned item is a copy carrying `rank`,
+ * `category` and `id` (a prefetched item names it `item_id`), so the input is
+ * not changed. `Array.prototype.sort` is stable, like Python's.
+ */
+declare function rankItems(byType: RawContext): RawContextItem[];
+/**
+ * The raw context in the shape the caller asked for.
+ *
+ * "ranked": `items` in rank order (the server's own list, or one rebuilt by
+ * rank score when the server or the cache predates the parameter), the five
+ * typed lists as views of those items, and `excerpts` for the chunks. A
+ * response that already carries `items` is read the same way even when the
+ * caller did not ask, as Python does. Anything else is returned untouched.
+ */
+declare function applyResponseShape(raw: RawContext, shape?: string): RawContext;
 
 /**
  * BM25 scorer for the anticipation cache.
@@ -1806,6 +2009,56 @@ interface BehaviorContract {
             note: string;
         };
     };
+    semantic_match: {
+        model: string;
+        mode: 'bm25' | 'semantic';
+        min_cosine: number;
+        serve_min_cosine: number;
+        asked_kind: boolean;
+        max_queries: number;
+        item_questions: boolean;
+        canonical_query: 'off' | 'canon' | 'both';
+        self_pronouns: Record<string, [string, string][] | string>;
+        asked_details: Record<string, {
+            query: string;
+            value: string;
+        } | string>;
+        bundle_serve_min_cosine: number;
+        sure_min_cosine: number;
+        race_deadline_ms: number;
+    };
+    history_search: {
+        max_excerpts: number;
+        max_words_per_excerpt: number;
+        min_matched_terms: number;
+        rrf_k: number;
+        recency_weight: number;
+        min_cosine?: number;
+        previous_turns?: number;
+        previous_turn_words?: number;
+        rare_term_max_share?: number;
+        tool_result_max_chars?: number;
+        passages?: boolean;
+        passages_per_turn?: number;
+        early_query?: {
+            pattern: string;
+            flags?: string;
+            note?: string;
+        };
+        asked_kinds?: Record<string, {
+            query: string;
+            value: string;
+        } | string>;
+        irregular_forms?: Record<string, string>;
+        heading: string;
+        store_limits: {
+            max_conversations: number;
+            max_turns_per_conversation: number;
+            max_bytes_per_conversation: number;
+            idle_ttl_seconds: number;
+            max_file_bytes: number;
+        };
+    };
 }
 declare const CONTRACT: BehaviorContract;
 declare const THRESHOLDS: {
@@ -1857,4 +2110,4 @@ interface SynapSdkLike {
     };
 }
 
-export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, 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, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, resolvePath, shouldRetry, stem, tokenize };
+export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, 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, EXCERPT_CATEGORY, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, MEMORY_TYPES, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, RESPONSE_SHAPES, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type ResponseShape, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, applyResponseShape, flattenContextItems, formatForPrompt, isOutcomeUnknown, isRecallQuery, mergeScopeResults, rankItems, resolvePath, shouldRetry, stem, tokenize, wireRankScore };