@maximem/synap-js-sdk 0.5.7 → 0.5.9

package/dist/{errors-Bl3vY1eb.d.ts → errors-Bdayqlzy.d.ts}

@@ -1,3 +1,22 @@
+/**
+ * Local search over a conversation's earlier turns.
+ *
+ * Port of `maximem_synap/cache/history_search.py`; see it for the design.
+ * Cascade, cheapest first: literal values in the query, then BM25 (the
+ * anticipation cache's tokenizer and parameters), then an embedding model
+ * when one is supplied. Ranks are fused by reciprocal rank with a small recency prior, and
+ * excerpts are shown in conversation order. The rendered block reaches the
+ * LLM prompt and is byte-identical to Python's.
+ */
+
+/** A local embedding model. `model` names it, so vectors from another model are never compared. */
+interface Encoder {
+    model: string;
+    encode(texts: string[]): number[][] | Promise<number[][]>;
+    /** Optional: a model trained with a query prefix (e5) encodes queries here and turns with `encode`. */
+    encodeQuery?(texts: string[]): number[][] | Promise<number[][]>;
+}
+
 /**
  * In-memory TTL cache for context bundles pushed over gRPC.
  *
@@ -22,6 +41,7 @@
  *
  * All thresholds come from the shared behavior contract.
  */
+
 /** Sentinel scope that matches any requester. */
 declare const ANY_SCOPE = "_any";
 interface BundleItem {
@@ -47,11 +67,18 @@ interface ContextBundle {
      */
     scopeRung?: string | null;
 }
+declare const MATCHERS: readonly ["bm25", "semantic"];
+type Matcher = (typeof MATCHERS)[number];
 interface LookupResult {
     itemsByType: Record<string, BundleItem[]>;
     bundleIds: string[];
     score: number;
     coverage: number;
+    /**
+     * A semantic match below the sure bar is "borderline": the caller may still
+     * ask the server, with a short deadline. Python: `_match_band`.
+     */
+    band?: 'sure' | 'borderline';
 }
 interface LookupParams {
     searchQuery?: readonly string[] | null;
@@ -67,8 +94,13 @@ interface LookupParams {
      */
     scopeRung?: string | null;
     maxItems?: number;
+    /**
+     * The search queries' vectors under the cache's encoder, from `lookupAsync`.
+     * With them (and matcher "semantic") the lookup matches by meaning.
+     */
+    queryVectors?: readonly (readonly number[])[] | null;
 }
-type ExitReason = 'empty' | 'recall_bypass' | 'no_query_tokens' | 'novel_term_gate' | 'empty_corpus' | 'no_items_above_threshold' | 'coverage_gate' | 'hit';
+type ExitReason = 'empty' | 'recall_bypass' | 'no_query_tokens' | 'novel_term_gate' | 'empty_corpus' | 'no_items_above_threshold' | 'coverage_gate' | 'asked_kind_missing' | 'hit';
 interface LookupTelemetry {
     searchQuery: string[];
     entityId: string | null;
@@ -122,6 +154,19 @@ interface AnticipationCacheOptions {
     /** Injected in tests. Defaults to a monotonic clock. */
     now?: () => number;
     onLookup?: (telemetry: LookupTelemetry) => void;
+    /**
+     * The local embedding model, usually handed over later with `setEncoder`
+     * once it has loaded. Until then, and with matcher "bm25", lookups are BM25.
+     */
+    encoder?: Encoder | null;
+    matcher?: Matcher;
+    minCosine?: number;
+    serveMinCosine?: number;
+    askedKind?: boolean;
+    itemQuestions?: boolean;
+    canonical?: 'off' | 'canon' | 'both';
+    bundleServeMinCosine?: number;
+    sureMinCosine?: number;
 }
 declare class AnticipationCache {
     #private;
@@ -134,11 +179,52 @@ declare class AnticipationCache {
     private corpusVocab;
     private bm25;
     private bm25Dirty;
+    private encoder;
+    private readonly matcher;
+    private readonly minCosine;
+    private readonly serveMinCosine;
+    private readonly askedKind;
+    private readonly itemQuestions;
+    private readonly canonical;
+    private readonly bundleServeMinCosine;
+    private readonly sureMinCosine;
+    /** Embedding runs one batch after another; `whenEmbedded` awaits the queue. */
+    private embedding;
     constructor(options?: AnticipationCacheOptions);
+    /**
+     * Hand over the local embedding model once it has loaded. Items already
+     * cached are embedded off the lookup path.
+     */
+    setEncoder(encoder: Encoder | null): void;
+    /** True when lookups match by meaning: matcher "semantic" and a model loaded. */
+    get semantic(): boolean;
+    /** Resolves once every item stored so far has had its turn to be embedded. */
+    whenEmbedded(): Promise<void>;
+    /**
+     * Give `items` their vectors, queued behind any earlier batch, so neither a
+     * bundle arriving on the stream nor a lookup waits for the model. A lookup
+     * before they are ready matches those items by BM25 alone.
+     */
+    private embedItems;
     get size(): number;
     get itemCount(): number;
     store(bundle: ContextBundle): void;
+    /**
+     * `lookup`, matching by meaning when a model is loaded: embeds the queries,
+     * then looks up with their vectors. A query the model cannot embed is looked
+     * up by BM25, as without a model. Python does this inside `lookup`.
+     */
+    lookupAsync(params: LookupParams): Promise<LookupResult | null>;
     lookup(params: LookupParams): LookupResult | null;
+    /**
+     * Match by meaning: a lookup is a hit when an item's cosine to a query
+     * reaches `minCosine`, and the hit also serves the items at `serveMinCosine`
+     * or above. An item with no vector yet is matched by BM25 with its novel-term
+     * gate, as before. Python: `_semantic_lookup`, which explains the choices.
+     */
+    private semanticLookup;
+    /** A hit: renew the leases of the bundles used, report, merge the items. */
+    private serve;
     /**
      * Drop this entity's bundles after a write, so the cache stops serving a
      * pre-write view. Gated on the flag: this is the write-path hook.
@@ -379,4 +465,4 @@ declare const TransientError: typeof SynapTransientError;
 declare const PermanentError: typeof SynapPermanentError;
 declare const ConnectionError: typeof NetworkTimeoutError;
 
-export { AnticipationCache as A, type BundleItem as B, ConflictError as C, isSynapError as D, type ExitReason as E, InsufficientCreditsError as I, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, InvalidConversationIdError as i, InvalidInputError as j, InvalidInstanceIdError as k, ListeningNotActiveError as l, type LookupParams as m, type LookupResult as n, type LookupTelemetry as o, SDKError as p, ServiceUnavailableError as q, SessionExpiredError as r, type SnapshotBundle as s, type SnapshotItemPreview as t, type SnapshotItemRecord as u, type SynapErrorCode as v, type SynapErrorOptions as w, SynapPermanentError as x, SynapTransientError as y, TransientError as z };
+export { AnticipationCache as A, type BundleItem as B, ConflictError as C, TransientError as D, type Encoder as E, isSynapError as F, InsufficientCreditsError as I, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, type ExitReason as i, InvalidConversationIdError as j, InvalidInputError as k, InvalidInstanceIdError as l, ListeningNotActiveError as m, type LookupParams as n, type LookupResult as o, type LookupTelemetry as p, SDKError as q, ServiceUnavailableError as r, SessionExpiredError as s, type SnapshotBundle as t, type SnapshotItemPreview as u, type SnapshotItemRecord as v, type SynapErrorCode as w, type SynapErrorOptions as x, SynapPermanentError as y, SynapTransientError as z };

package/dist/grpc/index.cjs

@@ -1,7 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 
-var _chunkHCULAVJCcjs = require('../chunk-HCULAVJC.cjs');
+var _chunkRE4DDIWOcjs = require('../chunk-RE4DDIWO.cjs');
 
 
 var _chunkT372OL3Qcjs = require('../chunk-T372OL3Q.cjs');
@@ -39,8 +39,8 @@ async function listen(options) {
     throw new (0, _chunkT372OL3Qcjs.ListeningNotActiveError)(availability.detail);
   }
   const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([
-    Promise.resolve().then(() => _interopRequireWildcard(require("../stream-client-N46JBT5A.cjs"))),
-    Promise.resolve().then(() => _interopRequireWildcard(require("../anticipation-cache-LRE3TLK4.cjs"))),
+    Promise.resolve().then(() => _interopRequireWildcard(require("../stream-client-L6OQPZN7.cjs"))),
+    Promise.resolve().then(() => _interopRequireWildcard(require("../anticipation-cache-LPNKMRBH.cjs"))),
     Promise.resolve().then(() => _interopRequireWildcard(require("../env-55ULHNJZ.cjs")))
   ]);
   const apiKey = _nullishCoalesce(_nullishCoalesce(options.apiKey, () => ( getEnv("SYNAP_API_KEY"))), () => ( ""));
@@ -83,5 +83,5 @@ async function listen(options) {
 
 
 
-exports.GrpcStreamClient = _chunkHCULAVJCcjs.GrpcStreamClient; exports.PROTO_SHA = _chunkHCULAVJCcjs.PROTO_SHA; exports.checkGrpcAvailability = checkGrpcAvailability; exports.listen = listen;
+exports.GrpcStreamClient = _chunkRE4DDIWOcjs.GrpcStreamClient; exports.PROTO_SHA = _chunkRE4DDIWOcjs.PROTO_SHA; exports.checkGrpcAvailability = checkGrpcAvailability; exports.listen = listen;
 //# sourceMappingURL=index.cjs.map

package/dist/grpc/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/scaler/maximem_synap/synap/sdk/js/dist/grpc/index.cjs","../../src/grpc/index.ts"],"names":[],"mappings":"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","file":"/Users/scaler/maximem_synap/synap/sdk/js/dist/grpc/index.cjs","sourcesContent":[null,"/**\n * gRPC anticipation stream: availability and loading.\n *\n * This is a SUBPATH export (`@maximem/synap-js-sdk/grpc`) and is never\n * imported by the main entry point. Three reasons, all of which have bitten\n * someone already:\n *\n *  1. `@grpc/grpc-js` plus its protos is roughly 5MB. HTTP-only and Edge users\n *     should not pay for it (gotcha G-Q).\n *  2. grpc-js is built on `node:http2`, `node:net` and `node:tls`. Merely\n *     importing it on Edge or Workers fails the *build*, not the call. Keeping\n *     it behind a subpath plus a lazy `import()` means importing the SDK on\n *     Edge stays safe.\n *  3. It is an `optionalDependency`, so it may legitimately be absent.\n *\n * ## Proto loading\n *\n * The stream is live. The proto ships as an INLINED JSON descriptor\n * (./descriptor.ts) loaded through `proto-loader.fromJSON`, not through\n * `loadSync(path)`. proto-loader's file-based path reads the `.proto` off disk\n * at runtime, which breaks under webpack/turbopack bundling and Vercel's `nft`\n * file tracing: at deploy time rather than at test time (gotcha G-P). Inlining\n * gets the same result as ts-proto codegen without a codegen toolchain.\n */\n\nimport { ListeningNotActiveError } from '../errors.js';\nexport { GrpcStreamClient } from './stream-client.js';\nexport type {\n  StreamState, StreamCredentials, StreamClientOptions, ConversationEventInput,\n} from './stream-client.js';\nexport { PROTO_SHA } from './descriptor.js';\n\nexport type GrpcAvailability =\n  | { available: true }\n  | { available: false; reason: 'not-node' | 'module-missing'; detail: string };\n\n/**\n * Whether a gRPC stream could run here.\n *\n * Deliberately does not throw: callers use this to decide whether to offer the\n * stream at all, and a hard failure at that point is unhelpful.\n */\nexport async function checkGrpcAvailability(): Promise<GrpcAvailability> {\n  const isNode =\n    typeof process !== 'undefined' &&\n    process.versions?.node !== undefined &&\n    typeof (globalThis as { EdgeRuntime?: unknown }).EdgeRuntime === 'undefined';\n\n  if (!isNode) {\n    return {\n      available: false,\n      reason: 'not-node',\n      detail:\n        'gRPC needs raw TCP and node:http2, which Edge runtimes and Workers do ' +\n        'not provide. HTTP context fetching works normally here; only the ' +\n        'anticipation stream is unavailable. Reaching Edge would require a ' +\n        'gRPC-Web or Connect endpoint on the server, which does not exist yet.',\n    };\n  }\n\n  try {\n    await import(/* @vite-ignore */ '@grpc/grpc-js');\n    return { available: true };\n  } catch (error) {\n    return {\n      available: false,\n      reason: 'module-missing',\n      detail:\n        '@grpc/grpc-js is an optional dependency and is not installed. Run ' +\n        '`npm install @grpc/grpc-js` to enable the anticipation stream. ' +\n        `(${(error as Error)?.message ?? String(error)})`,\n    };\n  }\n}\n\nexport interface ListenOptions {\n  conversationId: string;\n  userId?: string;\n  customerId?: string;\n  onBundle?: (bundle: unknown) => void;\n}\n\nexport interface ListeningSession {\n  stop(): Promise<void>;\n  readonly active: boolean;\n}\n\n/**\n * Start the anticipation stream directly, without a SynapClient.\n *\n * Most callers want `client.instance.listen()` instead, which shares the\n * client's credentials and anticipation cache. This exists for the case where\n * only the stream is wanted.\n *\n * **Opt-in, and off by default.** The removed wrapper called `listen()`\n * unconditionally during init, so every user had a stream whether they asked\n * for one or not. Making it opt-in is the right default, but it is not a\n * neutral change: fewer streams means fewer anticipation hits and therefore\n * MORE billed cloud fetches for existing users. That has to be announced\n * rather than discovered (gotcha G-Y).\n */\nexport async function listen(\n  options: ListenOptions & {\n    apiKey?: string;\n    clientId?: string;\n    instanceId?: string;\n    host?: string;\n    port?: number;\n    useTls?: boolean;\n  },\n): Promise<ListeningSession> {\n  if (!options.conversationId) {\n    // conversation_id is not a scope tier, but the stream genuinely requires\n    // one: it is what the server keys the anticipation session on.\n    throw new ListeningNotActiveError('conversation_id is required to start a listening stream');\n  }\n\n  const availability = await checkGrpcAvailability();\n  if (!availability.available) {\n    throw new ListeningNotActiveError(availability.detail);\n  }\n\n  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([\n    import('./stream-client.js'),\n    import('../context/anticipation-cache.js'),\n    import('../util/env.js'),\n  ]);\n\n  const apiKey = options.apiKey ?? getEnv('SYNAP_API_KEY') ?? '';\n  if (apiKey === '') {\n    throw new ListeningNotActiveError(\n      'No Synap API key found. Set SYNAP_API_KEY or pass apiKey.',\n    );\n  }\n\n  const cache = new AnticipationCache();\n  const client = new StreamClient(\n    {\n      apiKey,\n      clientId: options.clientId ?? getEnv('SYNAP_CLIENT_ID') ?? '',\n      instanceId: options.instanceId ?? getEnv('SYNAP_INSTANCE_ID') ?? '',\n    },\n    cache,\n    {\n      ...(options.host !== undefined ? { host: options.host } : {}),\n      ...(options.port !== undefined ? { port: options.port } : {}),\n      ...(options.useTls !== undefined ? { useTls: options.useTls } : {}),\n      ...(options.onBundle !== undefined ? { onContext: options.onBundle } : {}),\n    },\n  );\n  await client.connect();\n  client.sendSessionControl({\n    action: 'start',\n    conversation_id: options.conversationId,\n    ...(options.userId !== undefined ? { user_id: options.userId } : {}),\n    ...(options.customerId !== undefined ? { customer_id: options.customerId } : {}),\n  });\n\n  return {\n    stop: () => client.disconnect(),\n    get active() { return client.isConnected; },\n  };\n}\n"]}
+{"version":3,"sources":["/Users/anish/maximemai/maximem_synap/synap/sdk/js/dist/grpc/index.cjs","../../src/grpc/index.ts"],"names":[],"mappings":"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","file":"/Users/anish/maximemai/maximem_synap/synap/sdk/js/dist/grpc/index.cjs","sourcesContent":[null,"/**\n * gRPC anticipation stream: availability and loading.\n *\n * This is a SUBPATH export (`@maximem/synap-js-sdk/grpc`) and is never\n * imported by the main entry point. Three reasons, all of which have bitten\n * someone already:\n *\n *  1. `@grpc/grpc-js` plus its protos is roughly 5MB. HTTP-only and Edge users\n *     should not pay for it (gotcha G-Q).\n *  2. grpc-js is built on `node:http2`, `node:net` and `node:tls`. Merely\n *     importing it on Edge or Workers fails the *build*, not the call. Keeping\n *     it behind a subpath plus a lazy `import()` means importing the SDK on\n *     Edge stays safe.\n *  3. It is an `optionalDependency`, so it may legitimately be absent.\n *\n * ## Proto loading\n *\n * The stream is live. The proto ships as an INLINED JSON descriptor\n * (./descriptor.ts) loaded through `proto-loader.fromJSON`, not through\n * `loadSync(path)`. proto-loader's file-based path reads the `.proto` off disk\n * at runtime, which breaks under webpack/turbopack bundling and Vercel's `nft`\n * file tracing: at deploy time rather than at test time (gotcha G-P). Inlining\n * gets the same result as ts-proto codegen without a codegen toolchain.\n */\n\nimport { ListeningNotActiveError } from '../errors.js';\nexport { GrpcStreamClient } from './stream-client.js';\nexport type {\n  StreamState, StreamCredentials, StreamClientOptions, ConversationEventInput,\n} from './stream-client.js';\nexport { PROTO_SHA } from './descriptor.js';\n\nexport type GrpcAvailability =\n  | { available: true }\n  | { available: false; reason: 'not-node' | 'module-missing'; detail: string };\n\n/**\n * Whether a gRPC stream could run here.\n *\n * Deliberately does not throw: callers use this to decide whether to offer the\n * stream at all, and a hard failure at that point is unhelpful.\n */\nexport async function checkGrpcAvailability(): Promise<GrpcAvailability> {\n  const isNode =\n    typeof process !== 'undefined' &&\n    process.versions?.node !== undefined &&\n    typeof (globalThis as { EdgeRuntime?: unknown }).EdgeRuntime === 'undefined';\n\n  if (!isNode) {\n    return {\n      available: false,\n      reason: 'not-node',\n      detail:\n        'gRPC needs raw TCP and node:http2, which Edge runtimes and Workers do ' +\n        'not provide. HTTP context fetching works normally here; only the ' +\n        'anticipation stream is unavailable. Reaching Edge would require a ' +\n        'gRPC-Web or Connect endpoint on the server, which does not exist yet.',\n    };\n  }\n\n  try {\n    await import(/* @vite-ignore */ '@grpc/grpc-js');\n    return { available: true };\n  } catch (error) {\n    return {\n      available: false,\n      reason: 'module-missing',\n      detail:\n        '@grpc/grpc-js is an optional dependency and is not installed. Run ' +\n        '`npm install @grpc/grpc-js` to enable the anticipation stream. ' +\n        `(${(error as Error)?.message ?? String(error)})`,\n    };\n  }\n}\n\nexport interface ListenOptions {\n  conversationId: string;\n  userId?: string;\n  customerId?: string;\n  onBundle?: (bundle: unknown) => void;\n}\n\nexport interface ListeningSession {\n  stop(): Promise<void>;\n  readonly active: boolean;\n}\n\n/**\n * Start the anticipation stream directly, without a SynapClient.\n *\n * Most callers want `client.instance.listen()` instead, which shares the\n * client's credentials and anticipation cache. This exists for the case where\n * only the stream is wanted.\n *\n * **Opt-in, and off by default.** The removed wrapper called `listen()`\n * unconditionally during init, so every user had a stream whether they asked\n * for one or not. Making it opt-in is the right default, but it is not a\n * neutral change: fewer streams means fewer anticipation hits and therefore\n * MORE billed cloud fetches for existing users. That has to be announced\n * rather than discovered (gotcha G-Y).\n */\nexport async function listen(\n  options: ListenOptions & {\n    apiKey?: string;\n    clientId?: string;\n    instanceId?: string;\n    host?: string;\n    port?: number;\n    useTls?: boolean;\n  },\n): Promise<ListeningSession> {\n  if (!options.conversationId) {\n    // conversation_id is not a scope tier, but the stream genuinely requires\n    // one: it is what the server keys the anticipation session on.\n    throw new ListeningNotActiveError('conversation_id is required to start a listening stream');\n  }\n\n  const availability = await checkGrpcAvailability();\n  if (!availability.available) {\n    throw new ListeningNotActiveError(availability.detail);\n  }\n\n  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([\n    import('./stream-client.js'),\n    import('../context/anticipation-cache.js'),\n    import('../util/env.js'),\n  ]);\n\n  const apiKey = options.apiKey ?? getEnv('SYNAP_API_KEY') ?? '';\n  if (apiKey === '') {\n    throw new ListeningNotActiveError(\n      'No Synap API key found. Set SYNAP_API_KEY or pass apiKey.',\n    );\n  }\n\n  const cache = new AnticipationCache();\n  const client = new StreamClient(\n    {\n      apiKey,\n      clientId: options.clientId ?? getEnv('SYNAP_CLIENT_ID') ?? '',\n      instanceId: options.instanceId ?? getEnv('SYNAP_INSTANCE_ID') ?? '',\n    },\n    cache,\n    {\n      ...(options.host !== undefined ? { host: options.host } : {}),\n      ...(options.port !== undefined ? { port: options.port } : {}),\n      ...(options.useTls !== undefined ? { useTls: options.useTls } : {}),\n      ...(options.onBundle !== undefined ? { onContext: options.onBundle } : {}),\n    },\n  );\n  await client.connect();\n  client.sendSessionControl({\n    action: 'start',\n    conversation_id: options.conversationId,\n    ...(options.userId !== undefined ? { user_id: options.userId } : {}),\n    ...(options.customerId !== undefined ? { customer_id: options.customerId } : {}),\n  });\n\n  return {\n    stop: () => client.disconnect(),\n    get active() { return client.isConnected; },\n  };\n}\n"]}

package/dist/grpc/index.d.cts

@@ -1,4 +1,4 @@
-import { A as AnticipationCache, S as SynapError } from '../errors-Bl3vY1eb.cjs';
+import { A as AnticipationCache, S as SynapError } from '../errors-Bdayqlzy.cjs';
 
 /**
  * Bidirectional gRPC stream client for the Synap anticipation channel.
@@ -36,6 +36,11 @@ interface StreamClientOptions {
     onContext?: (bundle: Record<string, unknown>) => void;
     /** Fires only for `compaction_update` bundles. Backs the compaction subscriptions. */
     onCompactionUpdate?: (conversationId: string, bundle: Record<string, unknown>) => void;
+    /**
+     * The server's message count for a conversation, sent after it has written a
+     * streamed message. See `ConversationState` in the proto.
+     */
+    onConversationState?: (conversationId: string, messageCount: number) => void;
     /**
      * Where the outbox journal lives, so buffered events survive a restart.
      * Defaults to `~/.synap`, the same root Python uses. `''` turns it off, and
@@ -128,14 +133,14 @@ declare class GrpcStreamClient {
  *
  * Source:    synap/proto/synap_service.proto
  * Generator: synap/sdk/scripts/gen_proto_descriptor.mjs
- * Proto SHA: a0813b78a8c5d8dc
+ * Proto SHA: 9857182b0cf458b4
  *
  * The proto is inlined as a JSON descriptor rather than loaded from disk so
  * that bundlers and Vercel file tracing cannot lose it. Regenerate with
  * `npm run sync-behavior` in synap/sdk/js.
  */
 /** sha256 (first 16 hex chars) of the proto this descriptor was built from. */
-declare const PROTO_SHA = "2cf2b5663f67394b";
+declare const PROTO_SHA = "9857182b0cf458b4";
 
 /**
  * gRPC anticipation stream: availability and loading.

package/dist/grpc/index.d.ts

@@ -1,4 +1,4 @@
-import { A as AnticipationCache, S as SynapError } from '../errors-Bl3vY1eb.js';
+import { A as AnticipationCache, S as SynapError } from '../errors-Bdayqlzy.js';
 
 /**
  * Bidirectional gRPC stream client for the Synap anticipation channel.
@@ -36,6 +36,11 @@ interface StreamClientOptions {
     onContext?: (bundle: Record<string, unknown>) => void;
     /** Fires only for `compaction_update` bundles. Backs the compaction subscriptions. */
     onCompactionUpdate?: (conversationId: string, bundle: Record<string, unknown>) => void;
+    /**
+     * The server's message count for a conversation, sent after it has written a
+     * streamed message. See `ConversationState` in the proto.
+     */
+    onConversationState?: (conversationId: string, messageCount: number) => void;
     /**
      * Where the outbox journal lives, so buffered events survive a restart.
      * Defaults to `~/.synap`, the same root Python uses. `''` turns it off, and
@@ -128,14 +133,14 @@ declare class GrpcStreamClient {
  *
  * Source:    synap/proto/synap_service.proto
  * Generator: synap/sdk/scripts/gen_proto_descriptor.mjs
- * Proto SHA: a0813b78a8c5d8dc
+ * Proto SHA: 9857182b0cf458b4
  *
  * The proto is inlined as a JSON descriptor rather than loaded from disk so
  * that bundlers and Vercel file tracing cannot lose it. Regenerate with
  * `npm run sync-behavior` in synap/sdk/js.
  */
 /** sha256 (first 16 hex chars) of the proto this descriptor was built from. */
-declare const PROTO_SHA = "2cf2b5663f67394b";
+declare const PROTO_SHA = "9857182b0cf458b4";
 
 /**
  * gRPC anticipation stream: availability and loading.

package/dist/grpc/index.js

@@ -1,7 +1,7 @@
 import {
   GrpcStreamClient,
   PROTO_SHA
-} from "../chunk-FXGLT6AT.js";
+} from "../chunk-I7TWR4S6.js";
 import {
   ListeningNotActiveError
 } from "../chunk-BWMPKLFG.js";
@@ -39,8 +39,8 @@ async function listen(options) {
     throw new ListeningNotActiveError(availability.detail);
   }
   const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([
-    import("../stream-client-VWKINE47.js"),
-    import("../anticipation-cache-WLU4NMD5.js"),
+    import("../stream-client-3WHXGW4U.js"),
+    import("../anticipation-cache-RWKF55J4.js"),
     import("../env-QCUKKW36.js")
   ]);
   const apiKey = options.apiKey ?? getEnv("SYNAP_API_KEY") ?? "";