@maximem/synap-js-sdk 0.4.8 → 0.5.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as AnticipationCacheSnapshot } from './anticipation-cache-C1rUEpaW.cjs';
-export { b as ANY_SCOPE, A as AnticipationCache, c as AnticipationCacheOptions, B as BundleItem, C as ContextBundle, E as ExitReason, L as LookupParams, d as LookupResult, e as LookupTelemetry, S as SnapshotBundle, f as SnapshotItemPreview, g as SnapshotItemRecord } from './anticipation-cache-C1rUEpaW.cjs';
+import { a as AnticipationCacheSnapshot } from './errors-Bl3vY1eb.cjs';
+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.cjs';
 
 /**
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -739,6 +739,20 @@ interface RecordMessageOptions {
     session_id?: string;
     sessionId?: string;
     metadata?: Json;
+    /**
+     * The rung this conversation belongs to, named in full, e.g.
+     * `{ tenant: 'acme', practice: 'high_street' }`.
+     *
+     * Only relevant to a client whose ladder is deeper than the default three
+     * rungs (root, tenant, person). On the default ladder `customer_id` and
+     * `user_id` already say everything a path could.
+     *
+     * Sent as `scope` on the wire, matching Python's `scope_path`. Sending it
+     * once per conversation is enough: the server fills a missing path and never
+     * overwrites one.
+     */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 interface TranscriptTurn {
     role: string;
@@ -761,6 +775,20 @@ interface IngestTranscriptOptions {
     startedAt?: string | Date;
     ended_at?: string | Date;
     endedAt?: string | Date;
+    /**
+     * The rung this conversation belongs to, named in full, e.g.
+     * `{ tenant: 'acme', practice: 'high_street' }`.
+     *
+     * Only relevant to a client whose ladder is deeper than the default three
+     * rungs (root, tenant, person). On the default ladder `customer_id` and
+     * `user_id` already say everything a path could.
+     *
+     * Sent as `scope` on the wire, matching Python's `scope_path`. Sending it
+     * once per conversation is enough: the server fills a missing path and never
+     * overwrites one.
+     */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 /**
  * Compaction levels, mirroring Python's `CompactionLevel` enum. The JS SDK
@@ -1016,6 +1044,16 @@ interface SendMessageOptions {
     toolName?: string;
     tool_args?: Record<string, unknown>;
     toolArgs?: Record<string, unknown>;
+    /**
+     * What a tool returned. Travels in its own proto field, not in `content`: a
+     * result is not something a person said, and everything that filters on
+     * messages reads `content`.
+     */
+    tool_result?: unknown;
+    toolResult?: unknown;
+    /** Ties a result to the call that asked for it. */
+    tool_call_id?: string;
+    toolCallId?: string;
     search_queries?: string[];
     searchQueries?: string[];
     context_types?: string[];
@@ -1043,11 +1081,48 @@ interface RecordThinkingOptions {
     sessionId?: string;
     metadata?: Record<string, string>;
 }
+interface RecordToolCallOptions {
+    tool_name?: string;
+    toolName?: string;
+    tool_args?: Record<string, unknown>;
+    toolArgs?: Record<string, unknown>;
+    tool_call_id?: string;
+    toolCallId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Record<string, string>;
+}
+interface RecordToolResultOptions {
+    /** JSON-encodable, or a plain string. A string is sent as itself. */
+    result: unknown;
+    tool_name?: string;
+    toolName?: string;
+    tool_call_id?: string;
+    toolCallId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Record<string, string>;
+}
 interface InstanceNamespace {
     listen(options?: ListenOptions): Promise<void>;
     stop_listening(): Promise<void>;
     send_message(options: SendMessageOptions): Promise<void>;
     record_thinking(options: RecordThinkingOptions): Promise<void>;
+    record_tool_call(options: RecordToolCallOptions): Promise<void>;
+    record_tool_result(options: RecordToolResultOptions): Promise<void>;
+    end_session(conversationId: string): Promise<void>;
     /** Property, not a method, matching Python's InstanceInterface.is_listening. */
     readonly is_listening: boolean;
     /** Not in Python: lets the compaction subscriptions share this one stream. */
@@ -1273,11 +1348,20 @@ interface ConfigureOptions {
     /** Replaces the diagnostic sink, same as the constructor option. */
     logger?: SynapLogger | undefined;
 }
-/** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
+/** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs.
+ *
+ * The three identifiers accept `null` as well as `undefined`, because that is
+ * what callers actually pass: `conversation_id: convId || null` is the normal
+ * way to say "there is no conversation here", and `validateConversationId`
+ * has always treated `null` as absent. The declared type said otherwise, so
+ * the `SynapClient`-to-`SynapSdkLike` assignability test in
+ * `synap-claude-agent` (TS) could not typecheck, and the scope guards below
+ * did not agree with the validator either. See the guards for that half.
+ */
 interface UnifiedFetchOptions {
-    conversation_id?: string;
-    user_id?: string;
-    customer_id?: string;
+    conversation_id?: string | null;
+    user_id?: string | null;
+    customer_id?: string | null;
     search_query?: string[];
     max_results?: number;
     types?: string[];
@@ -1446,149 +1530,14 @@ declare class SynapClient {
  * Until that step existed nothing kept it in sync, so this constant sat at
  * 1.0.0-beta.0 while the package shipped 0.4.x, and every request's User-Agent
  * and every telemetry event reported a version that was never released.
- */
-declare const SDK_VERSION = "0.4.7";
-
-/**
- * Synap SDK error taxonomy.
- *
- * Mirrors `maximem_synap/models/errors.py` 1:1, including the four
- * backward-compatibility aliases at the bottom. If you add an error to one
- * SDK, add it to the other in the same change.
- *
- * ## Why every error carries a `.code`
- *
- * This package ships dual ESM + CJS. A consumer whose dependency graph pulls
- * in both formats gets *two* copies of every class in this file, and then:
- *
- *     try { ... } catch (e) { if (e instanceof SynapError) { ... } }
- *
- * silently evaluates to `false` against the copy from the other format. Error
- * handling stops working and nothing throws to tell you. `.code` is a plain
- * string, so it is immune. Prefer it at package boundaries:
- *
- *     if (isSynapError(e) && e.code === 'rate_limit') { ... }
- *
- * `Symbol.hasInstance` is also wired up on the base class, so `instanceof`
- * works across realms too -- but `.code` is the documented contract.
- */
-/** Stable, format-independent discriminators. Never renumber or reuse. */
-type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
-interface SynapErrorOptions {
-    correlationId?: string | null;
-    cause?: unknown;
-}
-declare class SynapError extends Error {
-    /**
-     * The single declaration site for each subclass's code.
-     *
-     * It is `static` rather than a class field on purpose. Under
-     * `useDefineForClassFields` (the default at our ES2022 target) a class field
-     * is an *instance* property, so it is invisible from the constructor object.
-     * `Symbol.hasInstance` below only has the constructor to work with, so a
-     * field would leave it unable to tell `AuthenticationError` from
-     * `RateLimitError` -- it would report every Synap error as an instance of
-     * every other one.
-     */
-    static readonly errorCode: SynapErrorCode;
-    /** True for errors where a retry may succeed. Static for the same reason. */
-    static readonly isTransient: boolean;
-    /** Own, enumerable, so logs and JSON.stringify include it. */
-    readonly code: SynapErrorCode;
-    readonly correlationId: string | null;
-    readonly transient: boolean;
-    constructor(message: string, options?: SynapErrorOptions);
-    static [Symbol.hasInstance](instance: unknown): boolean;
-}
-/** Type guard that works across ESM/CJS copies and realms. */
-declare function isSynapError(e: unknown): e is SynapError;
-declare class SynapTransientError extends SynapError {
-    static readonly errorCode: SynapErrorCode;
-    static readonly isTransient: boolean;
-}
-declare class SynapPermanentError extends SynapError {
-    static readonly errorCode: SynapErrorCode;
-    static readonly isTransient: boolean;
-}
-declare class NetworkTimeoutError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class RateLimitError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-    readonly retryAfterSeconds: number | null;
-    constructor(message: string, options?: SynapErrorOptions & {
-        retryAfterSeconds?: number | null;
-    });
-}
-declare class ServiceUnavailableError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class AgentUnavailableError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-    constructor(message?: string, options?: SynapErrorOptions);
-}
-/**
- * The caller's credit wallet cannot cover this request.
  *
- * HTTP 402, and gRPC RESOURCE_EXHAUSTED with credit-related trailing metadata.
- * Permanent by design: retrying without topping up burns quota and never
- * succeeds. This is the error behind "the agent forgot" reports where retrieval
- * silently returns nothing.
- */
-declare class InsufficientCreditsError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-    readonly balanceCredits: number | null;
-    readonly requiredCredits: number | null;
-    /** Where the balance can be viewed. Python calls this `recovery_url`. */
-    readonly recoveryUrl: string | null;
-    /** Where a redeem code can be entered. Python calls this `redeem_url`. */
-    readonly redeemUrl: string | null;
-    constructor(message: string, options?: SynapErrorOptions & {
-        balanceCredits?: number | null;
-        requiredCredits?: number | null;
-        recoveryUrl?: string | null;
-        redeemUrl?: string | null;
-    });
-}
-declare class InvalidInputError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-/**
- * Raised by `validateInstanceId` before any network call, matching Python's
- * `utils/validators.py`. The message text is identical in both SDKs.
+ * ⚠ The workflow only covers a workflow release. 0.4.8 was published by hand
+ * and shipped reporting 0.4.7, so every request from it carries a User-Agent
+ * for a version it is not. `version-matches-package.test.ts` now fails the
+ * build when the two disagree, which is the only thing that makes a manual
+ * publish safe.
  */
-declare class InvalidInstanceIdError extends InvalidInputError {
-    static readonly errorCode: SynapErrorCode;
-}
-/** See the note on InvalidInstanceIdError. Raised by `validateConversationId`. */
-declare class InvalidConversationIdError extends InvalidInputError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class AuthenticationError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ContextNotFoundError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ConflictError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class TranscriptConflictError extends ConflictError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class SessionExpiredError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ListeningAlreadyActiveError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ListeningNotActiveError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare const SDKError: typeof SynapError;
-declare const TransientError: typeof SynapTransientError;
-declare const PermanentError: typeof SynapPermanentError;
-declare const ConnectionError: typeof NetworkTimeoutError;
+declare const SDK_VERSION = "0.5.2";
 
 /**
  * BM25 scorer for the anticipation cache.
@@ -1744,4 +1693,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, 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 };
+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, type Fact, type FetchOptions, type FlatMemory, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as AnticipationCacheSnapshot } from './anticipation-cache-C1rUEpaW.js';
-export { b as ANY_SCOPE, A as AnticipationCache, c as AnticipationCacheOptions, B as BundleItem, C as ContextBundle, E as ExitReason, L as LookupParams, d as LookupResult, e as LookupTelemetry, S as SnapshotBundle, f as SnapshotItemPreview, g as SnapshotItemRecord } from './anticipation-cache-C1rUEpaW.js';
+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';
 
 /**
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -739,6 +739,20 @@ interface RecordMessageOptions {
     session_id?: string;
     sessionId?: string;
     metadata?: Json;
+    /**
+     * The rung this conversation belongs to, named in full, e.g.
+     * `{ tenant: 'acme', practice: 'high_street' }`.
+     *
+     * Only relevant to a client whose ladder is deeper than the default three
+     * rungs (root, tenant, person). On the default ladder `customer_id` and
+     * `user_id` already say everything a path could.
+     *
+     * Sent as `scope` on the wire, matching Python's `scope_path`. Sending it
+     * once per conversation is enough: the server fills a missing path and never
+     * overwrites one.
+     */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 interface TranscriptTurn {
     role: string;
@@ -761,6 +775,20 @@ interface IngestTranscriptOptions {
     startedAt?: string | Date;
     ended_at?: string | Date;
     endedAt?: string | Date;
+    /**
+     * The rung this conversation belongs to, named in full, e.g.
+     * `{ tenant: 'acme', practice: 'high_street' }`.
+     *
+     * Only relevant to a client whose ladder is deeper than the default three
+     * rungs (root, tenant, person). On the default ladder `customer_id` and
+     * `user_id` already say everything a path could.
+     *
+     * Sent as `scope` on the wire, matching Python's `scope_path`. Sending it
+     * once per conversation is enough: the server fills a missing path and never
+     * overwrites one.
+     */
+    scope_path?: Record<string, string>;
+    scopePath?: Record<string, string>;
 }
 /**
  * Compaction levels, mirroring Python's `CompactionLevel` enum. The JS SDK
@@ -1016,6 +1044,16 @@ interface SendMessageOptions {
     toolName?: string;
     tool_args?: Record<string, unknown>;
     toolArgs?: Record<string, unknown>;
+    /**
+     * What a tool returned. Travels in its own proto field, not in `content`: a
+     * result is not something a person said, and everything that filters on
+     * messages reads `content`.
+     */
+    tool_result?: unknown;
+    toolResult?: unknown;
+    /** Ties a result to the call that asked for it. */
+    tool_call_id?: string;
+    toolCallId?: string;
     search_queries?: string[];
     searchQueries?: string[];
     context_types?: string[];
@@ -1043,11 +1081,48 @@ interface RecordThinkingOptions {
     sessionId?: string;
     metadata?: Record<string, string>;
 }
+interface RecordToolCallOptions {
+    tool_name?: string;
+    toolName?: string;
+    tool_args?: Record<string, unknown>;
+    toolArgs?: Record<string, unknown>;
+    tool_call_id?: string;
+    toolCallId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Record<string, string>;
+}
+interface RecordToolResultOptions {
+    /** JSON-encodable, or a plain string. A string is sent as itself. */
+    result: unknown;
+    tool_name?: string;
+    toolName?: string;
+    tool_call_id?: string;
+    toolCallId?: string;
+    conversation_id?: string;
+    conversationId?: string;
+    user_id?: string;
+    userId?: string;
+    customer_id?: string;
+    customerId?: string;
+    session_id?: string;
+    sessionId?: string;
+    metadata?: Record<string, string>;
+}
 interface InstanceNamespace {
     listen(options?: ListenOptions): Promise<void>;
     stop_listening(): Promise<void>;
     send_message(options: SendMessageOptions): Promise<void>;
     record_thinking(options: RecordThinkingOptions): Promise<void>;
+    record_tool_call(options: RecordToolCallOptions): Promise<void>;
+    record_tool_result(options: RecordToolResultOptions): Promise<void>;
+    end_session(conversationId: string): Promise<void>;
     /** Property, not a method, matching Python's InstanceInterface.is_listening. */
     readonly is_listening: boolean;
     /** Not in Python: lets the compaction subscriptions share this one stream. */
@@ -1273,11 +1348,20 @@ interface ConfigureOptions {
     /** Replaces the diagnostic sink, same as the constructor option. */
     logger?: SynapLogger | undefined;
 }
-/** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs. */
+/** Options for the cross-scope `fetch()`. Snake_case, matching Python's kwargs.
+ *
+ * The three identifiers accept `null` as well as `undefined`, because that is
+ * what callers actually pass: `conversation_id: convId || null` is the normal
+ * way to say "there is no conversation here", and `validateConversationId`
+ * has always treated `null` as absent. The declared type said otherwise, so
+ * the `SynapClient`-to-`SynapSdkLike` assignability test in
+ * `synap-claude-agent` (TS) could not typecheck, and the scope guards below
+ * did not agree with the validator either. See the guards for that half.
+ */
 interface UnifiedFetchOptions {
-    conversation_id?: string;
-    user_id?: string;
-    customer_id?: string;
+    conversation_id?: string | null;
+    user_id?: string | null;
+    customer_id?: string | null;
     search_query?: string[];
     max_results?: number;
     types?: string[];
@@ -1446,149 +1530,14 @@ declare class SynapClient {
  * Until that step existed nothing kept it in sync, so this constant sat at
  * 1.0.0-beta.0 while the package shipped 0.4.x, and every request's User-Agent
  * and every telemetry event reported a version that was never released.
- */
-declare const SDK_VERSION = "0.4.7";
-
-/**
- * Synap SDK error taxonomy.
- *
- * Mirrors `maximem_synap/models/errors.py` 1:1, including the four
- * backward-compatibility aliases at the bottom. If you add an error to one
- * SDK, add it to the other in the same change.
- *
- * ## Why every error carries a `.code`
- *
- * This package ships dual ESM + CJS. A consumer whose dependency graph pulls
- * in both formats gets *two* copies of every class in this file, and then:
- *
- *     try { ... } catch (e) { if (e instanceof SynapError) { ... } }
- *
- * silently evaluates to `false` against the copy from the other format. Error
- * handling stops working and nothing throws to tell you. `.code` is a plain
- * string, so it is immune. Prefer it at package boundaries:
- *
- *     if (isSynapError(e) && e.code === 'rate_limit') { ... }
- *
- * `Symbol.hasInstance` is also wired up on the base class, so `instanceof`
- * works across realms too -- but `.code` is the documented contract.
- */
-/** Stable, format-independent discriminators. Never renumber or reuse. */
-type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
-interface SynapErrorOptions {
-    correlationId?: string | null;
-    cause?: unknown;
-}
-declare class SynapError extends Error {
-    /**
-     * The single declaration site for each subclass's code.
-     *
-     * It is `static` rather than a class field on purpose. Under
-     * `useDefineForClassFields` (the default at our ES2022 target) a class field
-     * is an *instance* property, so it is invisible from the constructor object.
-     * `Symbol.hasInstance` below only has the constructor to work with, so a
-     * field would leave it unable to tell `AuthenticationError` from
-     * `RateLimitError` -- it would report every Synap error as an instance of
-     * every other one.
-     */
-    static readonly errorCode: SynapErrorCode;
-    /** True for errors where a retry may succeed. Static for the same reason. */
-    static readonly isTransient: boolean;
-    /** Own, enumerable, so logs and JSON.stringify include it. */
-    readonly code: SynapErrorCode;
-    readonly correlationId: string | null;
-    readonly transient: boolean;
-    constructor(message: string, options?: SynapErrorOptions);
-    static [Symbol.hasInstance](instance: unknown): boolean;
-}
-/** Type guard that works across ESM/CJS copies and realms. */
-declare function isSynapError(e: unknown): e is SynapError;
-declare class SynapTransientError extends SynapError {
-    static readonly errorCode: SynapErrorCode;
-    static readonly isTransient: boolean;
-}
-declare class SynapPermanentError extends SynapError {
-    static readonly errorCode: SynapErrorCode;
-    static readonly isTransient: boolean;
-}
-declare class NetworkTimeoutError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class RateLimitError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-    readonly retryAfterSeconds: number | null;
-    constructor(message: string, options?: SynapErrorOptions & {
-        retryAfterSeconds?: number | null;
-    });
-}
-declare class ServiceUnavailableError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class AgentUnavailableError extends SynapTransientError {
-    static readonly errorCode: SynapErrorCode;
-    constructor(message?: string, options?: SynapErrorOptions);
-}
-/**
- * The caller's credit wallet cannot cover this request.
  *
- * HTTP 402, and gRPC RESOURCE_EXHAUSTED with credit-related trailing metadata.
- * Permanent by design: retrying without topping up burns quota and never
- * succeeds. This is the error behind "the agent forgot" reports where retrieval
- * silently returns nothing.
- */
-declare class InsufficientCreditsError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-    readonly balanceCredits: number | null;
-    readonly requiredCredits: number | null;
-    /** Where the balance can be viewed. Python calls this `recovery_url`. */
-    readonly recoveryUrl: string | null;
-    /** Where a redeem code can be entered. Python calls this `redeem_url`. */
-    readonly redeemUrl: string | null;
-    constructor(message: string, options?: SynapErrorOptions & {
-        balanceCredits?: number | null;
-        requiredCredits?: number | null;
-        recoveryUrl?: string | null;
-        redeemUrl?: string | null;
-    });
-}
-declare class InvalidInputError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-/**
- * Raised by `validateInstanceId` before any network call, matching Python's
- * `utils/validators.py`. The message text is identical in both SDKs.
+ * ⚠ The workflow only covers a workflow release. 0.4.8 was published by hand
+ * and shipped reporting 0.4.7, so every request from it carries a User-Agent
+ * for a version it is not. `version-matches-package.test.ts` now fails the
+ * build when the two disagree, which is the only thing that makes a manual
+ * publish safe.
  */
-declare class InvalidInstanceIdError extends InvalidInputError {
-    static readonly errorCode: SynapErrorCode;
-}
-/** See the note on InvalidInstanceIdError. Raised by `validateConversationId`. */
-declare class InvalidConversationIdError extends InvalidInputError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class AuthenticationError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ContextNotFoundError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ConflictError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class TranscriptConflictError extends ConflictError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class SessionExpiredError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ListeningAlreadyActiveError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare class ListeningNotActiveError extends SynapPermanentError {
-    static readonly errorCode: SynapErrorCode;
-}
-declare const SDKError: typeof SynapError;
-declare const TransientError: typeof SynapTransientError;
-declare const PermanentError: typeof SynapPermanentError;
-declare const ConnectionError: typeof NetworkTimeoutError;
+declare const SDK_VERSION = "0.5.2";
 
 /**
  * BM25 scorer for the anticipation cache.
@@ -1744,4 +1693,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, 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 };
+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, type Fact, type FetchOptions, type FlatMemory, 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 };