@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 2.0.0

package/dist/cjs/ai/mcp/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @module ai/mcp/types
+ * @description MCP (Model Context Protocol) types — protocol-level interfaces.
+ *
+ * These types follow the MCP specification (2024-11-05) and are independent
+ * of `@modelcontextprotocol/sdk` so the SDK has zero MCP runtime dependencies
+ * unless the user opts in.
+ *
+ * @see https://spec.modelcontextprotocol.io/specification/2024-11-05/
+ * @since 2.0.0
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+export interface McpCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, never>;
+}
+export interface McpInitializeParams {
+    protocolVersion: string;
+    capabilities?: McpCapabilities;
+    clientInfo: McpServerInfo;
+}
+export interface McpInitializeResult {
+    protocolVersion: string;
+    capabilities: McpCapabilities;
+    serverInfo: McpServerInfo;
+    instructions?: string;
+}
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+}
+export interface McpToolsListResult {
+    tools: McpToolDefinition[];
+    nextCursor?: string;
+}
+export interface McpToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+export interface McpContentItem {
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    resource?: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+    };
+}
+export interface McpToolCallResult {
+    content: McpContentItem[];
+    isError?: boolean;
+}
+export interface McpResourceDefinition {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpResourcesListResult {
+    resources: McpResourceDefinition[];
+    nextCursor?: string;
+}
+export interface McpResourceReadParams {
+    uri: string;
+}
+export interface McpResourceReadResult {
+    contents: Array<{
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    }>;
+}
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpPromptDefinition {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+export interface McpPromptMessage {
+    role: 'user' | 'assistant';
+    content: McpContentItem;
+}
+export interface McpGetPromptResult {
+    description?: string;
+    messages: McpPromptMessage[];
+}
+/**
+ * @description Abstract MCP transport — implement for stdio, SSE, WebSocket, etc.
+ */
+export interface McpTransport {
+    /** Start listening for messages. */
+    start(): Promise<void>;
+    /** Stop and cleanup. */
+    close(): Promise<void>;
+    /** Send a JSON-RPC message. */
+    send(message: JsonRpcResponse | JsonRpcNotification): Promise<void>;
+    /** Register handler for incoming messages. */
+    onMessage(handler: (message: JsonRpcRequest | JsonRpcNotification) => void): void;
+    /** Register close handler. */
+    onClose(handler: () => void): void;
+    /** Register error handler. */
+    onError(handler: (error: Error) => void): void;
+}
+export interface McpServerConfig {
+    /** Server name (shown to MCP clients). */
+    name?: string;
+    /** Server version. */
+    version?: string;
+    /** Server instructions/description shown to the connecting LLM. */
+    instructions?: string;
+    /** Transport mode. Default: 'stdio'. */
+    transport?: 'stdio' | 'sse';
+    /** SSE port (only for 'sse' transport). Default: 3001. */
+    ssePort?: number;
+    /** SSE path prefix. Default: '/mcp'. */
+    ssePath?: string;
+    /** Enable request logging. Default: false. */
+    debug?: boolean;
+    /** Custom capabilities to advertise. */
+    capabilities?: Partial<McpCapabilities>;
+}
+/**
+ * @description Configuration for connecting to an external MCP server.
+ */
+export interface McpExternalServerConfig {
+    /** Unique identifier for this connection. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Transport type. */
+    transport: 'stdio' | 'sse';
+    /** Command to spawn (for stdio). */
+    command?: string;
+    /** Command arguments (for stdio). */
+    args?: string[];
+    /** Environment variables (for stdio). */
+    env?: Record<string, string>;
+    /** SSE endpoint URL (for sse transport). */
+    url?: string;
+    /** SSE auth headers. */
+    headers?: Record<string, string>;
+    /** Tool name prefix to avoid collisions (e.g. 'github_'). */
+    toolPrefix?: string;
+    /** Whether to auto-reconnect on disconnect. */
+    reconnect?: boolean;
+    /** Connection timeout in ms. */
+    timeout?: number;
+}
+/**
+ * @description Status of an external MCP server connection.
+ */
+export interface McpConnectionStatus {
+    id: string;
+    name: string;
+    status: 'connected' | 'connecting' | 'disconnected' | 'error';
+    toolCount: number;
+    resourceCount: number;
+    serverInfo?: McpServerInfo;
+    error?: string;
+    connectedAt?: number;
+}
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+export declare const MCP_JSONRPC_VERSION: "2.0";
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/ai/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/ai/mcp/types.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/mcp/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @module ai/mcp/types
+ * @description MCP (Model Context Protocol) types — protocol-level interfaces.
+ *
+ * These types follow the MCP specification (2024-11-05) and are independent
+ * of `@modelcontextprotocol/sdk` so the SDK has zero MCP runtime dependencies
+ * unless the user opts in.
+ *
+ * @see https://spec.modelcontextprotocol.io/specification/2024-11-05/
+ * @since 2.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_JSONRPC_VERSION = exports.MCP_PROTOCOL_VERSION = void 0;
+exports.MCP_PROTOCOL_VERSION = '2024-11-05';
+exports.MCP_JSONRPC_VERSION = '2.0';
+//# sourceMappingURL=types.js.map

package/dist/cjs/ai/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/ai/mcp/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAoPU,QAAA,oBAAoB,GAAG,YAAY,CAAC;AACpC,QAAA,mBAAmB,GAAG,KAAc,CAAC"}

package/dist/cjs/ai/persistence/helpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module ai/persistence/helpers
+ * @description Serialization utilities, key builders, and PostgreSQL schema
+ * for the Synapse AI persistence layer.
+ *
+ * @since 1.2.2
+ */
+/**
+ * Serialize a value to a JSON string, converting `BigInt` to strings.
+ *
+ * @param value - Any value (may contain `BigInt`, `Map`, nested objects).
+ * @returns JSON string safe for storage.
+ * @since 1.2.2
+ */
+export declare function serialize(value: unknown): string;
+/**
+ * Deserialize a JSON string back to a typed value.
+ *
+ * @typeParam T - Expected return type.
+ * @param json - JSON string from the store.
+ * @returns Parsed value.
+ * @since 1.2.2
+ */
+export declare function deserialize<T = unknown>(json: string): T;
+/**
+ * Build a namespaced Redis key from segments.
+ *
+ * @example
+ * ```ts
+ * buildKey('synapse', 'agent', 'did:agent:1');
+ * // → 'synapse:agent:did:agent:1'
+ * ```
+ *
+ * @param parts - Key segments joined by `:`.
+ * @returns Colon-delimited key string.
+ * @since 1.2.2
+ */
+export declare function buildKey(...parts: string[]): string;
+/**
+ * Strip a prefix from a Redis key and return the remaining segments.
+ *
+ * @param prefix - The prefix to strip (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:id1'`).
+ * @returns Remaining segments after the prefix (e.g. `['agent', 'id1']`).
+ * @since 1.2.2
+ */
+export declare function parseKey(prefix: string, key: string): string[];
+/**
+ * Extract the agent ID from a namespaced Redis key.
+ *
+ * @param prefix - Key prefix (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:my-agent'`).
+ * @returns The agent ID segment, or the full key if pattern doesn't match.
+ * @since 1.2.2
+ */
+export declare function extractAgentId(prefix: string, key: string): string;
+/** Current schema version. Bump when adding migrations. */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Generate the full PostgreSQL DDL for a given table prefix.
+ *
+ * Creates tables:
+ * - `{prefix}_agents`   — agent snapshots (JSONB)
+ * - `{prefix}_sessions` — session records (JSONB)
+ * - `{prefix}_receipts` — payment receipts (JSONB)
+ * - `{prefix}_metrics`  — time-series metric points
+ * - `{prefix}_kv`       — generic key-value store
+ * - `{prefix}_schema_version` — migration tracking
+ *
+ * @param prefix - Table name prefix (default: `'synapse'`).
+ * @returns SQL DDL string ready for `client.query()`.
+ * @since 1.2.2
+ */
+export declare function buildSchema(prefix?: string): string;
+/**
+ * SQL to clean up expired rows from the KV table.
+ *
+ * @param prefix - Table name prefix.
+ * @returns DELETE statement string.
+ * @since 1.2.2
+ */
+export declare function buildKvCleanupSql(prefix?: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cjs/ai/persistence/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/ai/persistence/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAExD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlE;AAMD,2DAA2D;AAC3D,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAE,MAAkB,GAAG,MAAM,CA2E9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,MAAkB,GAAG,MAAM,CAEpE"}

package/dist/cjs/ai/persistence/helpers.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * @module ai/persistence/helpers
+ * @description Serialization utilities, key builders, and PostgreSQL schema
+ * for the Synapse AI persistence layer.
+ *
+ * @since 1.2.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+exports.serialize = serialize;
+exports.deserialize = deserialize;
+exports.buildKey = buildKey;
+exports.parseKey = parseKey;
+exports.extractAgentId = extractAgentId;
+exports.buildSchema = buildSchema;
+exports.buildKvCleanupSql = buildKvCleanupSql;
+const helpers_1 = require("../../utils/helpers");
+/* ═══════════════════════════════════════════════════════════════
+ *  Serialization
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Serialize a value to a JSON string, converting `BigInt` to strings.
+ *
+ * @param value - Any value (may contain `BigInt`, `Map`, nested objects).
+ * @returns JSON string safe for storage.
+ * @since 1.2.2
+ */
+function serialize(value) {
+    return JSON.stringify((0, helpers_1.toJsonSafe)(value));
+}
+/**
+ * Deserialize a JSON string back to a typed value.
+ *
+ * @typeParam T - Expected return type.
+ * @param json - JSON string from the store.
+ * @returns Parsed value.
+ * @since 1.2.2
+ */
+function deserialize(json) {
+    return JSON.parse(json);
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Redis key builders
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Build a namespaced Redis key from segments.
+ *
+ * @example
+ * ```ts
+ * buildKey('synapse', 'agent', 'did:agent:1');
+ * // → 'synapse:agent:did:agent:1'
+ * ```
+ *
+ * @param parts - Key segments joined by `:`.
+ * @returns Colon-delimited key string.
+ * @since 1.2.2
+ */
+function buildKey(...parts) {
+    return parts.join(':');
+}
+/**
+ * Strip a prefix from a Redis key and return the remaining segments.
+ *
+ * @param prefix - The prefix to strip (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:id1'`).
+ * @returns Remaining segments after the prefix (e.g. `['agent', 'id1']`).
+ * @since 1.2.2
+ */
+function parseKey(prefix, key) {
+    const stripped = key.startsWith(prefix + ':') ? key.slice(prefix.length + 1) : key;
+    return stripped.split(':');
+}
+/**
+ * Extract the agent ID from a namespaced Redis key.
+ *
+ * @param prefix - Key prefix (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:my-agent'`).
+ * @returns The agent ID segment, or the full key if pattern doesn't match.
+ * @since 1.2.2
+ */
+function extractAgentId(prefix, key) {
+    const parts = parseKey(prefix, key);
+    // Keys are: agent:{id}, session:{agentId}:{sessionId}, etc.
+    return parts.length >= 2 ? parts[1] : key;
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  PostgreSQL schema
+ * ═══════════════════════════════════════════════════════════════ */
+/** Current schema version. Bump when adding migrations. */
+exports.SCHEMA_VERSION = 1;
+/**
+ * Generate the full PostgreSQL DDL for a given table prefix.
+ *
+ * Creates tables:
+ * - `{prefix}_agents`   — agent snapshots (JSONB)
+ * - `{prefix}_sessions` — session records (JSONB)
+ * - `{prefix}_receipts` — payment receipts (JSONB)
+ * - `{prefix}_metrics`  — time-series metric points
+ * - `{prefix}_kv`       — generic key-value store
+ * - `{prefix}_schema_version` — migration tracking
+ *
+ * @param prefix - Table name prefix (default: `'synapse'`).
+ * @returns SQL DDL string ready for `client.query()`.
+ * @since 1.2.2
+ */
+function buildSchema(prefix = 'synapse') {
+    const p = prefix;
+    return `
+-- ═══════════════════════════════════════════════════════════════
+--  Synapse AI Persistence — Schema v${exports.SCHEMA_VERSION}
+--  Prefix: ${p}
+-- ═══════════════════════════════════════════════════════════════
+
+-- Agent snapshots
+CREATE TABLE IF NOT EXISTS ${p}_agents (
+  agent_id   TEXT PRIMARY KEY,
+  snapshot   JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Session records
+CREATE TABLE IF NOT EXISTS ${p}_sessions (
+  id         TEXT NOT NULL,
+  agent_id   TEXT NOT NULL,
+  state      JSONB NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'active',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (agent_id, id)
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_sessions_agent
+  ON ${p}_sessions (agent_id);
+CREATE INDEX IF NOT EXISTS idx_${p}_sessions_status
+  ON ${p}_sessions (status);
+
+-- Payment receipts
+CREATE TABLE IF NOT EXISTS ${p}_receipts (
+  id             TEXT PRIMARY KEY,
+  agent_id       TEXT NOT NULL,
+  session_id     TEXT,
+  receipt        JSONB NOT NULL,
+  amount_charged TEXT NOT NULL DEFAULT '0',
+  settled_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_receipts_agent
+  ON ${p}_receipts (agent_id);
+CREATE INDEX IF NOT EXISTS idx_${p}_receipts_settled
+  ON ${p}_receipts (settled_at DESC);
+
+-- Metric time-series
+CREATE TABLE IF NOT EXISTS ${p}_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  agent_id    TEXT NOT NULL,
+  metric_key  TEXT NOT NULL,
+  value       DOUBLE PRECISION NOT NULL,
+  labels      JSONB DEFAULT '{}',
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_metrics_agent_key
+  ON ${p}_metrics (agent_id, metric_key);
+CREATE INDEX IF NOT EXISTS idx_${p}_metrics_time
+  ON ${p}_metrics (recorded_at DESC);
+
+-- Generic key-value store
+CREATE TABLE IF NOT EXISTS ${p}_kv (
+  key        TEXT PRIMARY KEY,
+  value      JSONB NOT NULL,
+  expires_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS ${p}_schema_version (
+  version    INTEGER PRIMARY KEY,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+INSERT INTO ${p}_schema_version (version) VALUES (${exports.SCHEMA_VERSION})
+  ON CONFLICT (version) DO NOTHING;
+`.trim();
+}
+/**
+ * SQL to clean up expired rows from the KV table.
+ *
+ * @param prefix - Table name prefix.
+ * @returns DELETE statement string.
+ * @since 1.2.2
+ */
+function buildKvCleanupSql(prefix = 'synapse') {
+    return `DELETE FROM ${prefix}_kv WHERE expires_at IS NOT NULL AND expires_at < NOW()`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cjs/ai/persistence/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/ai/persistence/helpers.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAeH,8BAEC;AAUD,kCAEC;AAmBD,4BAEC;AAUD,4BAGC;AAUD,wCAIC;AAwBD,kCA2EC;AASD,8CAEC;AAzLD,iDAAiD;AAEjD;;qEAEqE;AAErE;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,KAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAA,oBAAU,EAAC,KAAK,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAc,IAAY;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;qEAEqE;AAErE;;;;;;;;;;;;GAYG;AACH,SAAgB,QAAQ,CAAC,GAAG,KAAe;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,QAAQ,CAAC,MAAc,EAAE,GAAW;IAClD,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnF,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,MAAc,EAAE,GAAW;IACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED;;qEAEqE;AAErE,2DAA2D;AAC9C,QAAA,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,SAAgB,WAAW,CAAC,SAAiB,SAAS;IACpD,MAAM,CAAC,GAAG,MAAM,CAAC;IACjB,OAAO;;uCAE8B,sBAAc;cACvC,CAAC;;;;6BAIc,CAAC;;;;;;;;6BAQD,CAAC;;;;;;;;;iCASG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;iCAQG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;iCAQG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;6BAQD,CAAC;;;;cAIhB,CAAC,qCAAqC,sBAAc;;CAEjE,CAAC,IAAI,EAAE,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,SAAiB,SAAS;IAC1D,OAAO,eAAe,MAAM,yDAAyD,CAAC;AACxF,CAAC"}

package/dist/cjs/ai/persistence/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module ai/persistence
+ * @description Synapse AI Persistence Layer — Redis, PostgreSQL, and in-memory
+ * adapters for long-term storage of agent snapshots, sessions, receipts,
+ * and metrics.
+ *
+ * ## Architecture
+ *
+ * All adapters implement the universal {@link PersistenceStore} interface
+ * **and** the `PersistenceAdapter` interface from {@link AgentRegistry},
+ * so they work everywhere:
+ *
+ * ```ts
+ * // As a standalone store
+ * const store = new RedisPersistence({ client: redis });
+ * await store.saveAgent(snapshot);
+ *
+ * // As AgentRegistry backend
+ * const registry = new AgentRegistry({ persistence: store });
+ * ```
+ *
+ * ## Adapters
+ *
+ * | Adapter | Backing store | Best for |
+ * |---|---|---|
+ * | {@link MemoryStore} | In-process `Map` | Testing, dev, CLI tools |
+ * | {@link RedisPersistence} | Redis / Valkey | Sessions, caching, pub/sub |
+ * | {@link PostgresPersistence} | PostgreSQL | Analytics, receipts, audit |
+ *
+ * ## Dependency injection
+ *
+ * Redis and PostgreSQL adapters accept a pre-configured client instance
+ * via their constructor config. No runtime dependencies are bundled —
+ * install `ioredis` or `pg` as needed.
+ *
+ * @example Redis quick start
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisPersistence({ client: redis, defaultTtl: 3600 });
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * await store.saveSession(sessionRecord);
+ * await store.recordMetric('agent-1', 'calls', 42);
+ * ```
+ *
+ * @example PostgreSQL quick start
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = new PostgresPersistence({ client: pool });
+ * await store.connect(); // auto-creates tables
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const receipts = await store.listReceipts('agent-1', { limit: 50 });
+ * const stats = await store.getTableStats();
+ * ```
+ *
+ * @example Dual-store pattern (Redis cache + PostgreSQL archive)
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { Pool } from 'pg';
+ * import { RedisPersistence, PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const cache   = new RedisPersistence({ client: new Redis(), defaultTtl: 300 });
+ * const archive = new PostgresPersistence({ client: new Pool() });
+ * await Promise.all([cache.connect(), archive.connect()]);
+ *
+ * // Write to both, read from cache first
+ * async function saveAgent(snapshot) {
+ *   await Promise.all([cache.saveAgent(snapshot), archive.saveAgent(snapshot)]);
+ * }
+ *
+ * async function loadAgent(id) {
+ *   return (await cache.loadAgent(id)) ?? archive.loadAgent(id);
+ * }
+ * ```
+ *
+ * @since 1.2.2
+ */
+export { PersistenceError, type PersistenceStore, type RedisLike, type PgLike, type SessionRecord, type ReceiptRecord, type MetricPoint, type SetOptions, type ListOptions, type MetricQueryOpts, type StoreConfig, type RedisStoreConfig, type PostgresStoreConfig, type MemoryStoreConfig, } from './types';
+export { serialize, deserialize, buildKey, parseKey, extractAgentId, buildSchema, buildKvCleanupSql, SCHEMA_VERSION, } from './helpers';
+export { MemoryStore } from './memory';
+export { RedisPersistence } from './redis';
+export { PostgresPersistence } from './postgresql';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}