@mikesaintsg/core 0.0.4 → 0.0.5

package/README.md

@@ -12,7 +12,8 @@
 
 - ✅ **Shared Types** — Contracts used across multiple packages
 - ✅ **Result Pattern** — Functional error handling (`ok`, `err`, `map`, `chain`)
-- ✅ **Bridge Functions** — Connect packages without circular dependencies
+- ✅ **Bridge Classes** — Ready-to-use implementations for cross-package communication
+- ✅ **Factory Functions** — Simple API for creating bridge instances
 - ✅ **Adapter Interfaces** — Embedding, tool format, persistence, and policy adapters
 - ✅ **Base Error Class** — `EcosystemError` for all package-specific errors
 - ✅ **Content Hashing** — SHA-256 based deduplication support
@@ -141,6 +142,17 @@ const results = await bridge.execute([call1, call2, call3])
 | `createFormDirtyGuard(options)`     | Navigation guard for dirty forms |
 | `createSessionPersistence(options)` | Session storage adapter          |
 
+### Bridge Classes
+
+Implementation classes for cross-package bridges (also available via factory functions):
+
+| Class                | Factory                      | Description                      |
+|----------------------|------------------------------|----------------------------------|
+| `ToolCallBridge`     | `createToolCallBridge()`     | Executes tool calls via registry |
+| `RetrievalTool`      | `createRetrievalTool()`      | Vectorstore search tool          |
+| `FormDirtyGuard`     | `createFormDirtyGuard()`     | Navigation guard for dirty forms |
+| `SessionPersistence` | `createSessionPersistence()` | Session storage adapter          |
+
 ### Error Handling
 
 | Export                 | Description                        |
@@ -155,7 +167,7 @@ const results = await bridge.execute([call1, call2, call3])
 | `Result<T, E>`                            | Success or failure union              |
 | `Ok<T>`, `Err<E>`                         | Result discriminants                  |
 | `Unsubscribe`                             | Cleanup function type                 |
-| `DestroyFn`                               | Resource cleanup function             |
+| `Destroyable`                             | Interface for resources with cleanup  |
 | `SubscriptionToHook<T>`                   | Convert subscriptions to hooks        |
 | `Embedding`                               | Float32Array embedding vector         |
 | `ToolCall`, `ToolResult`, `ToolSchema`    | Tool-related types                    |
@@ -286,6 +298,29 @@ const guard = createFormDirtyGuard({
 router.beforeNavigate(guard)
 ```
 
+### Using Bridge Classes Directly
+
+```ts
+import { ToolCallBridge, RetrievalTool, SessionPersistence } from '@mikesaintsg/core'
+
+// Direct class instantiation (alternative to factory functions)
+const bridge = new ToolCallBridge({
+  registry,
+  timeout: 30000,
+})
+
+const tool = new RetrievalTool({
+  vectorStore,
+  name: 'search',
+  description: 'Search documents',
+})
+
+const persistence = new SessionPersistence({
+  database,
+  storeName: 'sessions',
+})
+```
+
 ---
 
 ## Constants

package/dist/index.d.ts

@@ -3,6 +3,54 @@ export declare interface AbortableOptions {
     readonly signal?: AbortSignal;
 }
 
+/**
+ * Activity tracker adapter interface.
+ *
+ * Tracks user engagement (active/idle/away) and dwell time per node.
+ * Implementations use browser APIs (visibility, pointer, keyboard events).
+ */
+export declare interface ActivityTrackerInterface extends ActivityTrackerSubscriptions, Destroyable {
+    /** Enter a node and start tracking dwell time */
+    enterNode(nodeId: string): void;
+    /** Exit current node and complete the dwell record */
+    exitNode(): DwellRecord | undefined;
+    /** Get current engagement state */
+    getEngagementState(): EngagementState;
+    /** Get current node ID being tracked */
+    getCurrentNodeId(): string | undefined;
+    /** Get current incomplete dwell record */
+    getCurrentDwell(): PartialDwellRecord | undefined;
+    /** Get all completed dwell records */
+    getDwellHistory(): readonly DwellRecord[];
+    /** Get total active time across all dwells */
+    getTotalActiveTime(): number;
+    /** Get total idle time across all dwells */
+    getTotalIdleTime(): number;
+    /** Clear dwell history */
+    clearHistory(): void;
+}
+
+/** Activity tracker configuration */
+export declare interface ActivityTrackerOptions extends SubscriptionToHook<ActivityTrackerSubscriptions> {
+    /** Idle threshold in milliseconds (default: 30000) */
+    readonly idleThreshold?: number;
+    /** Away threshold in milliseconds (default: 300000) */
+    readonly awayThreshold?: number;
+    /** Enable visibility-based tracking (default:  true) */
+    readonly trackVisibility?: boolean;
+}
+
+/** Activity tracker subscriptions */
+export declare interface ActivityTrackerSubscriptions {
+    /** Subscribe to engagement state changes */
+    onEngagementChange(callback: (state: EngagementState, nodeId: string) => void): Unsubscribe;
+    /** Subscribe to completed dwell records */
+    onDwellComplete(callback: (record: DwellRecord) => void): Unsubscribe;
+}
+
+/** Actor types for transition attribution */
+export declare type Actor = 'user' | 'system' | 'automation';
+
 /**
  * Batch adapter interface.
  * Controls batching behavior for bulk operations.
@@ -195,6 +243,17 @@ export declare function createSessionPersistence(options: SessionPersistenceOpti
  */
 export declare function createToolCallBridge(options: ToolCallBridgeOptions): ToolCallBridgeInterface;
 
+/** Decay algorithm types */
+export declare type DecayAlgorithm = 'halflife' | 'ewma' | 'linear' | 'none';
+
+/** Decay configuration */
+export declare interface DecayConfig {
+    readonly algorithm: DecayAlgorithm;
+    readonly halfLifeMs?: number;
+    readonly decayFactor?: number;
+    readonly minWeight?: number;
+}
+
 /**
  * Deduplication adapter interface.
  * Determines how to handle duplicate frames based on content hash.
@@ -225,6 +284,17 @@ export declare interface Destroyable {
     destroy(): void;
 }
 
+/** Dwell record capturing time spent on a node */
+export declare interface DwellRecord {
+    readonly nodeId: string;
+    readonly enterTime: number;
+    readonly exitTime: number;
+    readonly activeTime: number;
+    readonly idleTime: number;
+    readonly engagement: EngagementState;
+    readonly engagementScore: number;
+}
+
 /**
  * @mikesaintsg/core
  *
@@ -300,6 +370,9 @@ export declare interface EmbeddingModelMetadata {
     readonly dimensions: number;
 }
 
+/** Engagement state for activity tracking */
+export declare type EngagementState = 'active' | 'idle' | 'away' | 'unknown';
+
 /** Failure result */
 export declare interface Err<E> {
     readonly ok: false;
@@ -326,6 +399,70 @@ export declare type ErrorCode<T extends {
     readonly code: string;
 }> = T['code'];
 
+/** Filter options for querying events */
+export declare interface EventFilter {
+    readonly sessionId?: string;
+    readonly actor?: Actor;
+    readonly nodeId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly startTime?: number;
+    readonly endTime?: number;
+    readonly namespace?: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+
+/**
+ * Event store persistence adapter interface.
+ *
+ * Extends base persistence with event-specific storage operations.
+ * Persists transition events for audit trail and replay.
+ * Implementations: IndexedDB, OPFS, HTTP, in-memory.
+ */
+export declare interface EventStorePersistenceAdapterInterface extends PersistenceAdapterInterface {
+    /** Persist event(s) */
+    persist(event: TransitionEvent_2 | readonly TransitionEvent_2[]): Promise<void>;
+    /** Load events matching filter */
+    load(filter: EventFilter): Promise<readonly TransitionEvent_2[]>;
+    /** Get count of events matching filter */
+    getCount(filter?: EventFilter): Promise<number>;
+    /** Check if any events exist matching filter */
+    has(filter?: EventFilter): Promise<boolean>;
+    /**
+     * Clear events matching filter.
+     * Extends base clear() with optional filtering.
+     * Call without filter to clear all events.
+     */
+    clear(filter?: EventFilter): Promise<void>;
+    /** Export all events for backup */
+    export(namespace?: string): Promise<readonly TransitionEvent_2[]>;
+    /** Import events (for recovery/migration) */
+    import(events: readonly TransitionEvent_2[]): Promise<void>;
+}
+
+/** Exported predictive graph for persistence */
+export declare interface ExportedPredictiveGraph {
+    readonly version: number;
+    readonly exportedAt: number;
+    readonly modelId: string;
+    readonly namespace?: string;
+    readonly weights: readonly ExportedWeight[];
+    readonly decayConfig: DecayConfig;
+    readonly transitionCount: number;
+    readonly warmupThreshold?: number;
+}
+
+/** Exported weight entry */
+export declare interface ExportedWeight {
+    readonly from: string;
+    readonly to: string;
+    readonly actor: Actor;
+    readonly weight: number;
+    readonly lastUpdated: number;
+    readonly updateCount: number;
+}
+
 /** Generation finish reason */
 export declare type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
 
@@ -341,6 +478,20 @@ export declare const FORM_DIRTY_DEFAULT_MESSAGE = "You have unsaved changes. Are
  */
 export declare function formatScoredResult(result: ScoredResult): unknown;
 
+/**
+ * Form dirty guard implementation.
+ * Returns a navigation guard function that prompts when form has unsaved changes.
+ */
+export declare class FormDirtyGuard<TFormData = unknown, TPage extends string = string> {
+    #private;
+    constructor(options: FormDirtyGuardOptions<TFormData, TPage>);
+    /**
+     * Get the navigation guard function.
+     * This is the function to register with a router.
+     */
+    getGuard(): NavigationGuard<TPage>;
+}
+
 /** Form dirty guard options */
 export declare interface FormDirtyGuardOptions<TFormData = unknown, TPage extends string = string> {
     readonly form: FormMinimal<TFormData>;
@@ -643,6 +794,39 @@ export declare interface PackageErrorData<TCode extends string> {
     readonly cause?: Error;
 }
 
+/** Partial dwell record for in-progress tracking */
+export declare interface PartialDwellRecord {
+    readonly nodeId: string;
+    readonly enterTime: number;
+    readonly activeTime: number;
+    readonly idleTime: number;
+    readonly engagement: EngagementState;
+}
+
+/**
+ * Base persistence adapter interface.
+ *
+ * Defines common operations shared by all persistence adapters.
+ * Specialized persistence adapters extend this interface with
+ * domain-specific load, save, and query methods.
+ *
+ * All persistence adapters share:
+ * - Availability checking for backend validation
+ * - Clear operation for removing all persisted data
+ */
+export declare interface PersistenceAdapterInterface {
+    /**
+     * Check if the persistence backend is available.
+     * Use this before operations to handle unavailable storage gracefully.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Clear all persisted data.
+     * Use with caution — this removes all data managed by this adapter.
+     */
+    clear(): Promise<void>;
+}
+
 /**
  * Priority adapter interface.
  * Provides priority weights and comparison logic.
@@ -735,6 +919,17 @@ export declare const RETRIEVAL_DEFAULT_LIMIT = 10;
 /** Maximum retrieval limit for retrieval tool */
 export declare const RETRIEVAL_MAX_LIMIT = 100;
 
+/**
+ * Retrieval tool implementation.
+ * Provides a tool schema and handler for vectorstore search.
+ */
+export declare class RetrievalTool<TMetadata = unknown> implements RetrievalToolInterface {
+    #private;
+    readonly schema: ToolSchema;
+    constructor(options: RetrievalToolOptions<TMetadata>);
+    handler: (args: Readonly<Record<string, unknown>>) => Promise<readonly unknown[]>;
+}
+
 /** Retrieval tool created by factory */
 export declare interface RetrievalToolInterface {
     readonly schema: ToolSchema;
@@ -811,15 +1006,38 @@ export declare interface SerializedSessionMetadata {
     readonly system?: string;
 }
 
+/**
+ * Session persistence implementation.
+ * Stores and retrieves inference sessions from a database store.
+ */
+export declare class SessionPersistence implements SessionPersistenceInterface {
+    #private;
+    constructor(options: SessionPersistenceOptions);
+    isAvailable(): Promise<boolean>;
+    clear(): Promise<void>;
+    save(id: string, session: SerializableSession): Promise<void>;
+    load(id: string): Promise<SerializedSession | undefined>;
+    delete(id: string): Promise<void>;
+    list(): Promise<readonly string[]>;
+    prune(maxAgeMs: number): Promise<number>;
+}
+
 /**
  * Session persistence interface.
+ *
+ * Extends base persistence with session-specific storage operations.
  * Connects inference sessions to IndexedDB storage.
  */
-export declare interface SessionPersistenceInterface {
+export declare interface SessionPersistenceInterface extends PersistenceAdapterInterface {
+    /** Save a session by ID */
     save(id: string, session: SerializableSession): Promise<void>;
+    /** Load a session by ID */
     load(id: string): Promise<SerializedSession | undefined>;
+    /** Delete a session by ID */
     delete(id: string): Promise<void>;
+    /** List all session IDs */
     list(): Promise<readonly string[]>;
+    /** Prune sessions older than maxAgeMs, returns count pruned */
     prune(maxAgeMs: number): Promise<number>;
 }
 
@@ -853,6 +1071,71 @@ export declare interface SimilarityAdapterInterface {
     readonly name: string;
 }
 
+/**
+ * SSE (Server-Sent Events) event structure.
+ * Represents a single event from an SSE stream.
+ */
+export declare interface SSEEvent {
+    /** Event type (e.g., 'message', 'error') */
+    readonly event?: string;
+    /** Event data payload */
+    readonly data: string;
+    /** Event ID for resumption */
+    readonly id?: string;
+    /** Retry interval in milliseconds */
+    readonly retry?: number;
+}
+
+/**
+ * SSE parser adapter interface.
+ * Factory for creating SSE parser instances.
+ *
+ * **Used by server-side providers:**
+ * - OpenAI (chat completions streaming)
+ * - Anthropic (messages streaming)
+ * - Other API-based providers using SSE format
+ *
+ * **NOT used by local providers:**
+ * - Ollama (uses NDJSON, not SSE)
+ * - node-llama-cpp (direct token emission)
+ * - HuggingFace (TextStreamer callback)
+ *
+ * Implementations are in @mikesaintsg/adapters.
+ */
+export declare interface SSEParserAdapterInterface {
+    /** Create a new parser instance with the given options */
+    createParser(options: SSEParserOptions): SSEParserInterface;
+}
+
+/**
+ * SSE parser interface.
+ * Stateful parser that handles chunked SSE data.
+ *
+ * SSE is the streaming format used by server-side LLM providers
+ * (OpenAI, Anthropic, and other API-based services).
+ */
+export declare interface SSEParserInterface {
+    /** Feed data chunk to parser */
+    feed(chunk: string): void;
+    /** Signal end of stream */
+    end(): void;
+    /** Reset parser state */
+    reset(): void;
+}
+
+/**
+ * SSE parser options.
+ * Callbacks for handling SSE stream events.
+ */
+export declare interface SSEParserOptions {
+    /** Called for each parsed event */
+    readonly onEvent: (event: SSEEvent) => void;
+    /** Called on parse error */
+    readonly onError?: (error: Error) => void;
+    /** Called when stream ends */
+    readonly onEnd?: () => void;
+}
+
 /** Storage information (quota and usage) */
 export declare interface StorageInfo {
     readonly usage: number;
@@ -872,6 +1155,30 @@ export declare interface StoredDocument {
     readonly updatedAt?: number;
 }
 
+/**
+ * Streamer adapter interface for token emission.
+ *
+ * Streamers are the internal mechanism for emitting tokens during generation.
+ * They bridge the gap between provider-specific streaming (SSE, local generation)
+ * and the consumer-facing StreamHandleInterface.
+ *
+ * **Usage by provider type:**
+ * - **Server-side providers** (OpenAI, Anthropic): SSE parser feeds tokens to streamer
+ * - **Local providers** (Ollama, node-llama-cpp, HuggingFace): Direct token emission to streamer
+ *
+ * Implementations are in @mikesaintsg/adapters.
+ */
+export declare interface StreamerAdapterInterface {
+    /** Subscribe to token events */
+    onToken(callback: (token: string) => void): Unsubscribe;
+    /** Emit a token to all subscribers */
+    emit(token: string): void;
+    /** Signal end of streaming */
+    end(): void;
+    /** Signal an error during streaming */
+    error?(err: Error): void;
+}
+
 /**
  * Stream handle interface - async iteration over tokens.
  * Provides streaming access to generation with abort control.
@@ -957,6 +1264,18 @@ export declare interface ToolCall {
     readonly arguments: Readonly<Record<string, unknown>>;
 }
 
+/**
+ * Tool call bridge implementation.
+ * Executes tool calls against a tool registry with timeout and lifecycle hooks.
+ */
+export declare class ToolCallBridge implements ToolCallBridgeInterface {
+    #private;
+    constructor(options: ToolCallBridgeOptions);
+    execute(toolCalls: ToolCall): Promise<ToolResult>;
+    execute(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    hasTool(name: string): boolean;
+}
+
 /**
  * Tool call bridge interface.
  * Connects inference tool calls to contextprotocol tool registry.
@@ -1037,6 +1356,22 @@ export declare interface ToolSchema {
     readonly returns?: JSONSchema7;
 }
 
+/** Transition event for audit trail */
+declare interface TransitionEvent_2 {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly sessionId: string;
+    readonly actor: Actor;
+    readonly from: string;
+    readonly to: string;
+    readonly path: string;
+    readonly dwell?: DwellRecord;
+    readonly engagement: EngagementState;
+    readonly namespace?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export { TransitionEvent_2 as TransitionEvent }
+
 /**
  * Truncation adapter interface.
  * Determines which frames to remove when budget is exceeded.
@@ -1130,16 +1465,21 @@ export declare interface VectorStoreMinimal<TMetadata = unknown> {
 
 /**
  * VectorStore persistence adapter interface.
+ *
+ * Extends base persistence with document and metadata storage.
  * Implemented by IndexedDB, OPFS, and HTTP adapters.
  */
-export declare interface VectorStorePersistenceAdapterInterface {
+export declare interface VectorStorePersistenceAdapterInterface extends PersistenceAdapterInterface {
+    /** Load all stored documents */
     load(): Promise<readonly StoredDocument[]>;
+    /** Load store metadata (model info, counts) */
     loadMetadata(): Promise<VectorStoreMetadata | undefined>;
+    /** Save document(s) to storage */
     save(docs: StoredDocument | readonly StoredDocument[]): Promise<void>;
+    /** Save store metadata */
     saveMetadata(metadata: VectorStoreMetadata): Promise<void>;
+    /** Remove document(s) by ID(s) */
     remove(ids: string | readonly string[]): Promise<void>;
-    clear(): Promise<void>;
-    isAvailable(): Promise<boolean>;
 }
 
 /** VectorStore search options */
@@ -1148,4 +1488,24 @@ export declare interface VectorStoreSearchOptions<TMetadata = unknown> {
     readonly filter?: TMetadata;
 }
 
+/**
+ * Weight persistence adapter interface.
+ *
+ * Extends base persistence with weight-specific storage operations.
+ * Persists predictive graph weights for cold-start optimization.
+ * Implementations: IndexedDB, OPFS, HTTP, in-memory.
+ */
+export declare interface WeightPersistenceAdapterInterface extends PersistenceAdapterInterface {
+    /** Save weights snapshot */
+    save(weights: ExportedPredictiveGraph): Promise<void>;
+    /** Load weights by model ID */
+    load(modelId: string): Promise<ExportedPredictiveGraph | undefined>;
+    /** Check if weights exist for model */
+    has(modelId: string): Promise<boolean>;
+    /** Delete weights for model */
+    delete(modelId: string): Promise<void>;
+    /** List all stored model IDs */
+    list(): Promise<readonly string[]>;
+}
+
 export { }

package/dist/index.js

@@ -1,237 +1,261 @@
-class A extends Error {
-  /** Original error that caused this one */
-  cause;
-  constructor(t, s) {
-    super(t), this.name = this.constructor.name, this.cause = s;
-  }
+const A = 3e4, x = 10, I = 100, h = "You have unsaved changes. Are you sure you want to leave?";
+function m(r) {
+  return { ok: !0, value: r };
 }
-function b(e) {
-  return e instanceof A;
+function d(r) {
+  return { ok: !1, error: r };
 }
-function S(e) {
-  return { ok: !0, value: e };
+function S(r) {
+  return r.ok;
 }
-function I(e) {
-  return { ok: !1, error: e };
+function L(r) {
+  return !r.ok;
 }
-function F(e) {
-  return e.ok === !0;
+function R(r, e) {
+  return r.ok ? r.value : e;
 }
-function P(e) {
-  return !e.ok;
+function F(r) {
+  if (r.ok)
+    return r.value;
+  throw r.error instanceof Error ? r.error : new Error(String(r.error));
 }
-function q(e, t) {
-  return e.ok ? e.value : t;
+function M(r, e) {
+  return r.ok ? m(e(r.value)) : r;
 }
-function U(e) {
-  if (e.ok)
-    return e.value;
-  throw e.error instanceof Error ? e.error : new Error(String(e.error));
+function _(r, e) {
+  return r.ok ? r : d(e(r.error));
 }
-function B(e, t) {
-  return e.ok ? S(t(e.value)) : e;
+function D(r, e) {
+  return r.ok ? e(r.value) : r;
 }
-function G(e, t) {
-  return e.ok ? e : I(t(e.error));
+async function k(r) {
+  const t = new TextEncoder().encode(r), n = await crypto.subtle.digest("SHA-256", t);
+  return Array.from(new Uint8Array(n)).map((s) => s.toString(16).padStart(2, "0")).join("");
 }
-function O(e, t) {
-  return e.ok ? t(e.value) : e;
+function f(r) {
+  return typeof r == "object" && r !== null && "id" in r && "name" in r && "arguments" in r;
 }
-async function $(e) {
-  const s = new TextEncoder().encode(e), a = await crypto.subtle.digest("SHA-256", s);
-  return Array.from(new Uint8Array(a)).map((o) => o.toString(16).padStart(2, "0")).join("");
+function E(r, e, t, n) {
+  return t.includes(r) ? !0 : n !== void 0 && !n.includes(e);
 }
-function k(e) {
-  return typeof e == "object" && e !== null && "id" in e && "name" in e && "arguments" in e;
-}
-function l(e, t, s, a) {
-  return s.includes(e) ? !0 : a !== void 0 && !a.includes(t);
-}
-function M(e) {
+function y(r) {
   return {
-    content: e.content,
-    score: e.score,
-    metadata: e.metadata
+    content: r.content,
+    score: r.score,
+    metadata: r.metadata
   };
 }
-const R = 3e4, L = 10, _ = 100, D = "You have unsaved changes. Are you sure you want to leave?";
-function j(e) {
-  const {
-    registry: t,
-    timeout: s = R,
-    onError: a,
-    onBeforeExecute: c,
-    onAfterExecute: o
-  } = e;
-  async function u(r) {
-    if (!t.has(r.name))
+class l {
+  #e;
+  #r;
+  #t;
+  #n;
+  #s;
+  constructor(e) {
+    this.#e = e.registry, this.#r = e.timeout ?? 3e4, this.#t = "onError" in e ? e.onError : void 0, this.#n = "onBeforeExecute" in e ? e.onBeforeExecute : void 0, this.#s = "onAfterExecute" in e ? e.onAfterExecute : void 0;
+  }
+  execute(e) {
+    return f(e) ? this.#i(e) : Promise.all(
+      e.map((t) => this.#i(t))
+    );
+  }
+  hasTool(e) {
+    return this.#e.has(e);
+  }
+  async #i(e) {
+    if (!this.#e.has(e.name))
       return {
-        callId: r.id,
-        name: r.name,
+        callId: e.id,
+        name: e.name,
         success: !1,
-        error: `Tool not found: ${r.name}`
+        error: `Tool not found: ${e.name}`
       };
-    c?.(r);
+    this.#n?.(e);
     try {
-      const n = new Promise((f, m) => {
+      const t = new Promise((i, s) => {
         setTimeout(() => {
-          m(new Error(`Tool execution timed out after ${s}ms`));
-        }, s);
-      }), i = await Promise.race([
-        t.execute(r.name, r.arguments),
-        n
+          s(new Error(`Tool execution timed out after ${this.#r}ms`));
+        }, this.#r);
+      }), n = await Promise.race([
+        this.#e.execute(e.name, e.arguments),
+        t
       ]);
-      return o?.(r, i), {
-        callId: r.id,
-        name: r.name,
+      return this.#s?.(e, n), {
+        callId: e.id,
+        name: e.name,
         success: !0,
-        value: i
+        value: n
       };
-    } catch (n) {
-      a?.(n, r);
-      const i = n instanceof Error ? n.message : String(n);
+    } catch (t) {
+      this.#t?.(t, e);
+      const n = t instanceof Error ? t.message : String(t);
       return {
-        callId: r.id,
-        name: r.name,
+        callId: e.id,
+        name: e.name,
         success: !1,
-        error: i
+        error: n
       };
     }
   }
-  return {
-    execute(r) {
-      return k(r) ? u(r) : Promise.all(
-        r.map((n) => u(n))
-      );
-    },
-    hasTool(r) {
-      return t.has(r);
-    }
-  };
 }
-function H(e) {
-  const {
-    vectorStore: t,
-    name: s,
-    description: a,
-    defaultLimit: c = L,
-    maxLimit: o = _,
-    scoreThreshold: u,
-    formatResult: r = M,
-    extendParameters: n = {},
-    buildFilter: i
-  } = e, f = {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: "The search query to find relevant documents"
-      },
-      limit: {
-        type: "integer",
-        description: `Maximum number of results to return (default: ${c}, max: ${o})`,
-        minimum: 1,
-        maximum: o,
-        default: c
+class T {
+  schema;
+  #e;
+  #r;
+  #t;
+  #n;
+  #s;
+  #i;
+  constructor(e) {
+    this.#e = e.vectorStore, this.#r = e.defaultLimit ?? 10, this.#t = e.maxLimit ?? 100, this.#n = "scoreThreshold" in e ? e.scoreThreshold : void 0, this.#s = e.formatResult ?? y, this.#i = "buildFilter" in e ? e.buildFilter : void 0;
+    const t = {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query to find relevant documents"
+        },
+        limit: {
+          type: "integer",
+          description: `Maximum number of results to return (default: ${this.#r}, max: ${this.#t})`,
+          minimum: 1,
+          maximum: this.#t,
+          default: this.#r
+        },
+        ...e.extendParameters
       },
-      ...n
-    },
-    required: ["query"]
-  }, m = {
-    name: s,
-    description: a,
-    parameters: f
-  };
-  async function d(h) {
-    const y = h.query;
-    if (typeof y != "string" || y.length === 0)
+      required: ["query"]
+    };
+    this.schema = {
+      name: e.name,
+      description: e.description,
+      parameters: t
+    };
+  }
+  handler = async (e) => {
+    const t = e.query;
+    if (typeof t != "string" || t.length === 0)
       return [];
-    const p = h.limit;
-    let E = c;
-    typeof p == "number" && Number.isInteger(p) && (E = Math.min(Math.max(1, p), o));
-    const w = i?.(h), v = w !== void 0 ? { limit: E, filter: w } : { limit: E }, g = await t.search(y, v);
-    let T = g;
-    return u !== void 0 && (T = g.filter((x) => x.score >= u)), T.map(r);
-  }
-  return { schema: m, handler: d };
-}
-function N(e) {
-  const {
-    form: t,
-    confirmFn: s,
-    message: a = D,
-    excludePages: c = [],
-    onlyFromPages: o
-  } = e;
-  return async function(r, n) {
-    return l(r, n, c, o) || !t.isDirty() ? !0 : Promise.resolve(s(a));
+    const n = e.limit;
+    let i = this.#r;
+    typeof n == "number" && Number.isInteger(n) && (i = Math.min(Math.max(1, n), this.#t));
+    const s = this.#i?.(e), a = s !== void 0 ? { limit: i, filter: s } : { limit: i }, o = await this.#e.search(t, a);
+    let c = o;
+    return this.#n !== void 0 && (c = o.filter((u) => u.score >= this.#n)), c.map(this.#s);
   };
 }
-function V(e) {
-  const {
-    database: t,
-    storeName: s,
-    autoprune: a,
-    onSaveError: c
-  } = e, o = t.store(s);
-  async function u(r) {
-    const i = Date.now() - r, f = await o.all();
-    let m = 0;
-    for (const d of f)
-      d.updatedAt < i && (await o.remove(d.id), m++);
-    return m;
-  }
-  return a !== void 0 && a > 0 && u(a), {
-    async save(r, n) {
-      try {
-        const i = {
-          id: r,
-          messages: [...n.getMessages()],
-          metadata: n.getMetadata(),
-          updatedAt: Date.now()
-        };
-        await o.set(i, r);
-      } catch (i) {
-        throw c?.(i, r), i;
-      }
-    },
-    async load(r) {
-      return o.get(r);
-    },
-    async delete(r) {
-      await o.remove(r);
-    },
-    async list() {
-      return (await o.all()).map((n) => n.id);
-    },
-    async prune(r) {
-      return u(r);
+class g {
+  #e;
+  #r;
+  #t;
+  #n;
+  #s;
+  constructor(e) {
+    this.#e = e.form, this.#r = e.confirmFn, this.#t = e.message ?? h, this.#n = e.excludePages ?? [], this.#s = "onlyFromPages" in e ? e.onlyFromPages : void 0;
+  }
+  /**
+   * Get the navigation guard function.
+   * This is the function to register with a router.
+   */
+  getGuard() {
+    return async (e, t) => E(e, t, this.#n, this.#s) || !this.#e.isDirty() ? !0 : Promise.resolve(this.#r(this.#t));
+  }
+}
+class w {
+  #e;
+  #r;
+  constructor(e) {
+    this.#e = e.database.store(e.storeName), this.#r = "onSaveError" in e ? e.onSaveError : void 0, e.autoprune !== void 0 && e.autoprune > 0 && this.prune(e.autoprune);
+  }
+  async isAvailable() {
+    try {
+      return await this.#e.all(), !0;
+    } catch {
+      return !1;
     }
-  };
+  }
+  async clear() {
+    await this.#e.clear();
+  }
+  async save(e, t) {
+    try {
+      const n = {
+        id: e,
+        messages: [...t.getMessages()],
+        metadata: t.getMetadata(),
+        updatedAt: Date.now()
+      };
+      await this.#e.set(n, e);
+    } catch (n) {
+      throw this.#r?.(n, e), n;
+    }
+  }
+  async load(e) {
+    return this.#e.get(e);
+  }
+  async delete(e) {
+    await this.#e.remove(e);
+  }
+  async list() {
+    return (await this.#e.all()).map((t) => t.id);
+  }
+  async prune(e) {
+    const n = Date.now() - e, i = await this.#e.all();
+    let s = 0;
+    for (const a of i)
+      a.updatedAt < n && (await this.#e.remove(a.id), s++);
+    return s;
+  }
+}
+class v extends Error {
+  /** Original error that caused this one */
+  cause;
+  constructor(e, t) {
+    super(e), this.name = this.constructor.name, this.cause = t;
+  }
+}
+function P(r) {
+  return r instanceof v;
+}
+function b(r) {
+  return new l(r);
+}
+function p(r) {
+  return new T(r);
+}
+function B(r) {
+  return new g(r).getGuard();
+}
+function G(r) {
+  return new w(r);
 }
 export {
-  R as BRIDGE_DEFAULT_TIMEOUT,
-  A as EcosystemError,
-  D as FORM_DIRTY_DEFAULT_MESSAGE,
-  L as RETRIEVAL_DEFAULT_LIMIT,
-  _ as RETRIEVAL_MAX_LIMIT,
-  O as chain,
-  $ as computeContentHash,
-  N as createFormDirtyGuard,
-  H as createRetrievalTool,
-  V as createSessionPersistence,
-  j as createToolCallBridge,
-  I as err,
-  M as formatScoredResult,
-  b as isEcosystemError,
-  P as isErr,
-  F as isOk,
-  k as isToolCall,
-  B as map,
-  G as mapErr,
-  S as ok,
-  l as shouldSkipFormGuard,
-  q as unwrap,
-  U as unwrapOrThrow
+  A as BRIDGE_DEFAULT_TIMEOUT,
+  v as EcosystemError,
+  h as FORM_DIRTY_DEFAULT_MESSAGE,
+  g as FormDirtyGuard,
+  x as RETRIEVAL_DEFAULT_LIMIT,
+  I as RETRIEVAL_MAX_LIMIT,
+  T as RetrievalTool,
+  w as SessionPersistence,
+  l as ToolCallBridge,
+  D as chain,
+  k as computeContentHash,
+  B as createFormDirtyGuard,
+  p as createRetrievalTool,
+  G as createSessionPersistence,
+  b as createToolCallBridge,
+  d as err,
+  y as formatScoredResult,
+  P as isEcosystemError,
+  L as isErr,
+  S as isOk,
+  f as isToolCall,
+  M as map,
+  _ as mapErr,
+  m as ok,
+  E as shouldSkipFormGuard,
+  R as unwrap,
+  F as unwrapOrThrow
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/errors.ts","../src/helpers.ts","../src/constants.ts","../src/factories.ts"],"sourcesContent":["/**\n * @mikesaintsg/core\n *\n * Base error class and utilities for the ecosystem.\n */\n// ============================================================================\n// Base Ecosystem Error\n// ============================================================================\n/**\n * Base error class for all ecosystem errors.\n * All package-specific errors should extend this class.\n *\n * @example\n * ```ts\n * class StorageError extends EcosystemError {\n *   readonly code: StorageErrorCode\n *\n *   constructor(code: StorageErrorCode, message: string, cause?: Error) {\n *     super(message, cause)\n *     this.code = code\n *   }\n * }\n * ```\n */\nexport abstract class EcosystemError extends Error {\n\t/** Error code for programmatic handling */\n\tabstract readonly code: string\n\t/** Original error that caused this one */\n\toverride readonly cause: Error | undefined\n\n\tconstructor(message: string, cause?: Error) {\n\t\tsuper(message)\n\t\tthis.name = this.constructor.name\n\t\tthis.cause = cause\n\t}\n}\n/**\n * Type guard for ecosystem errors.\n *\n * @param error - The value to check\n * @returns True if the error is an EcosystemError\n *\n * @example\n * ```ts\n * try {\n *   await someOperation()\n * } catch (error) {\n *   if (isEcosystemError(error)) {\n *     console.log('Code:', error.code)\n *   }\n * }\n * ```\n */\nexport function isEcosystemError(error: unknown): error is EcosystemError {\n\treturn error instanceof EcosystemError\n}\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Helper functions and type guards.\r\n */\r\n\r\nimport type { Ok, Err, Result, ContentHash, ScoredResult } from './types.js'\r\n\r\n// ============================================================================\r\n// Result Pattern Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Create a success result.\r\n *\r\n * @param value - The success value\r\n * @returns An Ok result containing the value\r\n *\r\n * @example\r\n * ```ts\r\n * const result = ok(42)\r\n * // result.ok === true\r\n * // result.value === 42\r\n * ```\r\n */\r\nexport function ok<T>(value: T): Ok<T> {\r\n\treturn { ok: true, value }\r\n}\r\n\r\n/**\r\n * Create a failure result.\r\n *\r\n * @param error - The error value\r\n * @returns An Err result containing the error\r\n *\r\n * @example\r\n * ```ts\r\n * const result = err('NOT_FOUND')\r\n * // result.ok === false\r\n * // result.error === 'NOT_FOUND'\r\n * ```\r\n */\r\nexport function err<E>(error: E): Err<E> {\r\n\treturn { ok: false, error }\r\n}\r\n\r\n/**\r\n * Check if a result is a success.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Ok, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = ok(42)\r\n * if (isOk(result)) {\r\n *   console.log(result.value) // TypeScript knows result is Ok<number>\r\n * }\r\n * ```\r\n */\r\nexport function isOk<T, E>(result: Result<T, E>): result is Ok<T> {\r\n\treturn result.ok === true\r\n}\r\n\r\n/**\r\n * Check if a result is a failure.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Err, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = err('NOT_FOUND')\r\n * if (isErr(result)) {\r\n *   console.log(result.error) // TypeScript knows result is Err<string>\r\n * }\r\n * ```\r\n */\r\nexport function isErr<T, E>(result: Result<T, E>): result is Err<E> {\r\n\treturn !result.ok\r\n}\r\n\r\n/**\r\n * Unwrap a result, returning the value or a default.\r\n *\r\n * @param result - The result to unwrap\r\n * @param defaultValue - Value to return if result is an error\r\n * @returns The success value or the default value\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrap(ok(42), 0) // 42\r\n * const fallback = unwrap(err('oops'), 0) // 0\r\n * ```\r\n */\r\nexport function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T {\r\n\treturn result.ok ? result.value : defaultValue\r\n}\r\n\r\n/**\r\n * Unwrap a result, throwing if it's an error.\r\n *\r\n * @param result - The result to unwrap\r\n * @returns The success value\r\n * @throws The error if result is Err\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrapOrThrow(ok(42)) // 42\r\n * unwrapOrThrow(err(new Error('oops'))) // throws Error('oops')\r\n * ```\r\n */\r\nexport function unwrapOrThrow<T, E>(result: Result<T, E>): T {\r\n\tif (result.ok) {\r\n\t\treturn result.value\r\n\t}\r\n\tif (result.error instanceof Error) {\r\n\t\tthrow result.error\r\n\t}\r\n\tthrow new Error(String(result.error))\r\n}\r\n\r\n/**\r\n * Map a function over a success value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the success value\r\n * @returns A new result with the mapped value, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const doubled = map(ok(5), x => x * 2) // ok(10)\r\n * const failed = map(err('oops'), x => x * 2) // err('oops')\r\n * ```\r\n */\r\nexport function map<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => U,\r\n): Result<U, E> {\r\n\treturn result.ok ? ok(fn(result.value)) : result\r\n}\r\n\r\n/**\r\n * Map a function over an error value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the error value\r\n * @returns A new result with the mapped error, or the original value\r\n *\r\n * @example\r\n * ```ts\r\n * const wrapped = mapErr(err('oops'), e => new Error(e)) // err(Error('oops'))\r\n * const unchanged = mapErr(ok(42), e => new Error(e)) // ok(42)\r\n * ```\r\n */\r\nexport function mapErr<T, E, F>(\r\n\tresult: Result<T, E>,\r\n\tfn: (error: E) => F,\r\n): Result<T, F> {\r\n\treturn result.ok ? result : err(fn(result.error))\r\n}\r\n\r\n/**\r\n * Chain results (flatMap). Apply a function that returns a Result to a success value.\r\n *\r\n * @param result - The result to chain\r\n * @param fn - Function returning a new Result\r\n * @returns The result of applying fn, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const parsed = chain(ok('42'), s => {\r\n *   const n = parseInt(s, 10)\r\n *   return isNaN(n) ? err('PARSE_ERROR') : ok(n)\r\n * })\r\n * // parsed = ok(42)\r\n * ```\r\n */\r\nexport function chain<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => Result<U, E>,\r\n): Result<U, E> {\r\n\treturn result.ok ? fn(result.value) : result\r\n}\r\n\r\n// ============================================================================\r\n// Content Hashing Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Compute a SHA-256 content hash for text.\r\n *\r\n * @param text - The text to hash\r\n * @returns A hex string content hash\r\n *\r\n * @example\r\n * ```ts\r\n * const hash = await computeContentHash('Hello, world!')\r\n * // hash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'\r\n * ```\r\n */\r\nexport async function computeContentHash(text: string): Promise<ContentHash> {\r\n\tconst encoder = new TextEncoder()\r\n\tconst data = encoder.encode(text)\r\n\tconst hashBuffer = await crypto.subtle.digest('SHA-256', data)\r\n\tconst hashArray = Array.from(new Uint8Array(hashBuffer))\r\n\treturn hashArray.map(b => b.toString(16).padStart(2, '0')).join('')\r\n}\r\n\r\n// ============================================================================\r\n// Bridge Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Check if a value is a single ToolCall (not an array).\r\n *\r\n * @param value - Value to check\r\n * @returns True if the value is a single ToolCall\r\n */\r\nexport function isToolCall(value: unknown): value is { id: string; name: string; arguments: unknown } {\r\n\treturn (\r\n\t\ttypeof value === 'object' &&\r\n\t\tvalue !== null &&\r\n\t\t'id' in value &&\r\n\t\t'name' in value &&\r\n\t\t'arguments' in value\r\n\t)\r\n}\r\n\r\n/**\r\n * Determine if form dirty guard should be skipped for a navigation.\r\n *\r\n * @param to - Target page\r\n * @param from - Source page\r\n * @param excludePages - Pages to exclude from guard\r\n * @param onlyFromPages - Only guard from these pages (if specified)\r\n * @returns True if guard should be skipped\r\n */\r\nexport function shouldSkipFormGuard<TPage extends string>(\r\n\tto: TPage,\r\n\tfrom: TPage,\r\n\texcludePages: readonly TPage[],\r\n\tonlyFromPages: readonly TPage[] | undefined,\r\n): boolean {\r\n\t// Skip if navigating to excluded page\r\n\tif (excludePages.includes(to)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\t// Skip if from page is not in onlyFromPages (if specified)\r\n\treturn onlyFromPages !== undefined && !onlyFromPages.includes(from)\r\n}\r\n\r\n/**\r\n * Default result formatter for retrieval tools.\r\n * Returns content, score, and metadata.\r\n *\r\n * @param result - Scored result to format\r\n * @returns Formatted result object\r\n */\r\nexport function formatScoredResult(result: ScoredResult): unknown {\r\n\treturn {\r\n\t\tcontent: result.content,\r\n\t\tscore: result.score,\r\n\t\tmetadata: result.metadata,\r\n\t}\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Shared constants for the core library.\r\n */\r\n\r\n// ============================================================================\r\n// Bridge Constants\r\n// ============================================================================\r\n\r\n/** Default timeout for bridge operations in milliseconds */\r\nexport const BRIDGE_DEFAULT_TIMEOUT = 30000\r\n\r\n/** Default retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_DEFAULT_LIMIT = 10\r\n\r\n/** Maximum retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_MAX_LIMIT = 100\r\n\r\n/** Default form dirty guard message */\r\nexport const FORM_DIRTY_DEFAULT_MESSAGE = 'You have unsaved changes. Are you sure you want to leave?'\r\n","/**\n * @mikesaintsg/core\n *\n * Factory functions for creating bridge instances.\n */\n\nimport type {\n\tToolCall,\n\tToolResult,\n\tToolCallBridgeOptions,\n\tToolCallBridgeInterface,\n\tRetrievalToolOptions,\n\tRetrievalToolInterface,\n\tToolSchema,\n\tJSONSchema7,\n\tFormDirtyGuardOptions,\n\tNavigationGuard,\n\tSessionPersistenceOptions,\n\tSessionPersistenceInterface,\n\tSerializableSession,\n\tSerializedSession,\n} from './types.js'\nimport {\n\tBRIDGE_DEFAULT_TIMEOUT,\n\tRETRIEVAL_DEFAULT_LIMIT,\n\tRETRIEVAL_MAX_LIMIT,\n\tFORM_DIRTY_DEFAULT_MESSAGE,\n} from './constants.js'\nimport {\n\tisToolCall,\n\tshouldSkipFormGuard,\n\tformatScoredResult,\n} from './helpers.js'\n\n// ============================================================================\n// Tool Call Bridge Factory\n// ============================================================================\n\n/**\n * Create a tool call bridge.\n *\n * @param options - Bridge configuration options\n * @returns A tool call bridge instance\n *\n * @example\n * ```ts\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\n * import { createToolCallBridge } from '@mikesaintsg/core'\n *\n * const registry = createToolRegistry()\n * registry.register(weatherTool)\n *\n * const bridge = createToolCallBridge({\n *   registry,\n *   timeout: 30000,\n *   onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),\n * })\n *\n * // Execute tool calls from LLM response\n * const results = await bridge.execute(response.toolCalls)\n * ```\n */\nexport function createToolCallBridge(\n\toptions: ToolCallBridgeOptions,\n): ToolCallBridgeInterface {\n\tconst {\n\t\tregistry,\n\t\ttimeout = BRIDGE_DEFAULT_TIMEOUT,\n\t\tonError,\n\t\tonBeforeExecute,\n\t\tonAfterExecute,\n\t} = options\n\n\tasync function executeWithTimeout(toolCall: ToolCall): Promise<ToolResult> {\n\t\t// Check if tool exists\n\t\tif (!registry.has(toolCall.name)) {\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `Tool not found: ${toolCall.name}`,\n\t\t\t}\n\t\t}\n\n\t\t// Call lifecycle hook\n\t\tonBeforeExecute?.(toolCall)\n\n\t\ttry {\n\t\t\t// Create timeout promise\n\t\t\tconst timeoutPromise = new Promise<never>((_, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\treject(new Error(`Tool execution timed out after ${timeout}ms`))\n\t\t\t\t}, timeout)\n\t\t\t})\n\n\t\t\t// Execute tool with timeout\n\t\t\tconst value = await Promise.race([\n\t\t\t\tregistry.execute(toolCall.name, toolCall.arguments),\n\t\t\t\ttimeoutPromise,\n\t\t\t])\n\n\t\t\t// Call lifecycle hook\n\t\t\tonAfterExecute?.(toolCall, value)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: true,\n\t\t\t\tvalue,\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// Call error hook\n\t\t\tonError?.(error, toolCall)\n\n\t\t\tconst errorMessage = error instanceof Error\n\t\t\t\t? error.message\n\t\t\t\t: String(error)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: errorMessage,\n\t\t\t}\n\t\t}\n\t}\n\n\treturn {\n\t\texecute(toolCallOrCalls: ToolCall | readonly ToolCall[]) {\n\t\t\tif (isToolCall(toolCallOrCalls)) {\n\t\t\t\treturn executeWithTimeout(toolCallOrCalls)\n\t\t\t}\n\t\t\treturn Promise.all(\n\t\t\t\t(toolCallOrCalls).map(tc => executeWithTimeout(tc)),\n\t\t\t)\n\t\t},\n\n\t\thasTool(name: string): boolean {\n\t\t\treturn registry.has(name)\n\t\t},\n\t} as ToolCallBridgeInterface\n}\n\n// ============================================================================\n// Retrieval Tool Factory\n// ============================================================================\n\n/**\n * Create a retrieval tool for use with contextprotocol tool registry.\n *\n * @param options - Retrieval tool configuration options\n * @returns A tool schema and handler for registration\n *\n * @example\n * ```ts\n * import { createVectorStore } from '@mikesaintsg/vectorstore'\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\n * import { createRetrievalTool } from '@mikesaintsg/core'\n *\n * const vectorStore = createVectorStore({ ... })\n * const registry = createToolRegistry()\n *\n * const { schema, handler } = createRetrievalTool({\n *   vectorStore,\n *   name: 'search_docs',\n *   description: 'Search documentation for relevant information',\n *   defaultLimit: 5,\n *   scoreThreshold: 0.7,\n * })\n *\n * registry.register({ ...schema, execute: handler })\n * ```\n */\nexport function createRetrievalTool<TMetadata = unknown>(\n\toptions: RetrievalToolOptions<TMetadata>,\n): RetrievalToolInterface {\n\tconst {\n\t\tvectorStore,\n\t\tname,\n\t\tdescription,\n\t\tdefaultLimit = RETRIEVAL_DEFAULT_LIMIT,\n\t\tmaxLimit = RETRIEVAL_MAX_LIMIT,\n\t\tscoreThreshold,\n\t\tformatResult = formatScoredResult,\n\t\textendParameters = {},\n\t\tbuildFilter,\n\t} = options\n\n\t// Build tool schema parameters\n\tconst parameters: JSONSchema7 = {\n\t\ttype: 'object',\n\t\tproperties: {\n\t\t\tquery: {\n\t\t\t\ttype: 'string',\n\t\t\t\tdescription: 'The search query to find relevant documents',\n\t\t\t},\n\t\t\tlimit: {\n\t\t\t\ttype: 'integer',\n\t\t\t\tdescription: `Maximum number of results to return (default: ${defaultLimit}, max: ${maxLimit})`,\n\t\t\t\tminimum: 1,\n\t\t\t\tmaximum: maxLimit,\n\t\t\t\tdefault: defaultLimit,\n\t\t\t},\n\t\t\t...extendParameters,\n\t\t},\n\t\trequired: ['query'],\n\t}\n\n\tconst schema: ToolSchema = {\n\t\tname,\n\t\tdescription,\n\t\tparameters,\n\t}\n\n\tasync function handler(\n\t\targs: Readonly<Record<string, unknown>>,\n\t): Promise<readonly unknown[]> {\n\t\tconst query = args.query\n\t\tif (typeof query !== 'string' || query.length === 0) {\n\t\t\treturn []\n\t\t}\n\n\t\tconst requestedLimit = args.limit\n\t\tlet limit = defaultLimit\n\t\tif (typeof requestedLimit === 'number' && Number.isInteger(requestedLimit)) {\n\t\t\tlimit = Math.min(Math.max(1, requestedLimit), maxLimit)\n\t\t}\n\n\t\t// Build filter if provided\n\t\tconst filter = buildFilter?.(args)\n\n\t\t// Search vectorstore - only include filter if defined\n\t\tconst searchOptions = filter !== undefined\n\t\t\t? { limit, filter }\n\t\t\t: { limit }\n\t\tconst results = await vectorStore.search(query, searchOptions)\n\n\t\t// Filter by score threshold\n\t\tlet filteredResults = results\n\t\tif (scoreThreshold !== undefined) {\n\t\t\tfilteredResults = results.filter(r => r.score >= scoreThreshold)\n\t\t}\n\n\t\t// Format results\n\t\treturn filteredResults.map(formatResult)\n\t}\n\n\treturn { schema, handler }\n}\n\n// ============================================================================\n// Form Dirty Guard Factory\n// ============================================================================\n\n/**\n * Create a navigation guard that prevents leaving when form is dirty.\n *\n * @param options - Form dirty guard configuration options\n * @returns A navigation guard function\n *\n * @example\n * ```ts\n * import { createForm } from '@mikesaintsg/form'\n * import { createFormDirtyGuard } from '@mikesaintsg/core'\n *\n * const form = createForm({ ... })\n *\n * const guard = createFormDirtyGuard({\n *   form,\n *   confirmFn: (message) => window.confirm(message),\n *   message: 'You have unsaved changes. Continue?',\n *   excludePages: ['settings'],\n * })\n *\n * // Use with router\n * router.beforeNavigate(guard)\n * ```\n */\nexport function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(\n\toptions: FormDirtyGuardOptions<TFormData, TPage>,\n): NavigationGuard<TPage> {\n\tconst {\n\t\tform,\n\t\tconfirmFn,\n\t\tmessage = FORM_DIRTY_DEFAULT_MESSAGE,\n\t\texcludePages = [],\n\t\tonlyFromPages,\n\t} = options\n\n\treturn async function guard(to: TPage, from: TPage): Promise<boolean> {\n\t\t// Check if we should skip guard for this navigation\n\t\tif (shouldSkipFormGuard(to, from, excludePages, onlyFromPages)) {\n\t\t\treturn true\n\t\t}\n\n\t\t// If form is not dirty, allow navigation\n\t\tif (!form.isDirty()) {\n\t\t\treturn true\n\t\t}\n\n\t\t// Form is dirty, ask for confirmation\n\t\treturn Promise.resolve(confirmFn(message))\n\t}\n}\n\n// ============================================================================\n// Session Persistence Factory\n// ============================================================================\n\n/**\n * Create a session persistence adapter for storing inference sessions.\n *\n * @param options - Session persistence configuration options\n * @returns A session persistence instance\n *\n * @example\n * ```ts\n * import { createDatabase } from '@mikesaintsg/indexeddb'\n * import { createSessionPersistence } from '@mikesaintsg/core'\n *\n * const db = await createDatabase({ name: 'sessions' })\n * const persistence = createSessionPersistence({\n *   database: db,\n *   storeName: 'chat_sessions',\n *   autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days\n * })\n *\n * // Save session\n * await persistence.save('session-1', session)\n *\n * // Load session\n * const savedSession = await persistence.load('session-1')\n * ```\n */\nexport function createSessionPersistence(\n\toptions: SessionPersistenceOptions,\n): SessionPersistenceInterface {\n\tconst {\n\t\tdatabase,\n\t\tstoreName,\n\t\tautoprune,\n\t\tonSaveError,\n\t} = options\n\n\tconst store = database.store<SerializedSession>(storeName)\n\n\tasync function pruneOldSessions(maxAgeMs: number): Promise<number> {\n\t\tconst now = Date.now()\n\t\tconst cutoff = now - maxAgeMs\n\n\t\tconst allSessions = await store.all()\n\t\tlet prunedCount = 0\n\n\t\tfor (const session of allSessions) {\n\t\t\tif (session.updatedAt < cutoff) {\n\t\t\t\tawait store.remove(session.id)\n\t\t\t\tprunedCount++\n\t\t\t}\n\t\t}\n\n\t\treturn prunedCount\n\t}\n\n\t// Auto-prune on creation if configured\n\tif (autoprune !== undefined && autoprune > 0) {\n\t\tvoid pruneOldSessions(autoprune)\n\t}\n\n\treturn {\n\t\tasync save(id: string, session: SerializableSession): Promise<void> {\n\t\t\ttry {\n\t\t\t\tconst serialized: SerializedSession = {\n\t\t\t\t\tid,\n\t\t\t\t\tmessages: [...session.getMessages()],\n\t\t\t\t\tmetadata: session.getMetadata(),\n\t\t\t\t\tupdatedAt: Date.now(),\n\t\t\t\t}\n\n\t\t\t\tawait store.set(serialized, id)\n\t\t\t} catch (error) {\n\t\t\t\tonSaveError?.(error, id)\n\t\t\t\tthrow error\n\t\t\t}\n\t\t},\n\n\t\tasync load(id: string): Promise<SerializedSession | undefined> {\n\t\t\treturn store.get(id)\n\t\t},\n\n\t\tasync delete(id: string): Promise<void> {\n\t\t\tawait store.remove(id)\n\t\t},\n\n\t\tasync list(): Promise<readonly string[]> {\n\t\t\tconst allSessions = await store.all()\n\t\t\treturn allSessions.map(s => s.id)\n\t\t},\n\n\t\tasync prune(maxAgeMs: number): Promise<number> {\n\t\t\treturn pruneOldSessions(maxAgeMs)\n\t\t},\n\t}\n}\n"],"names":["EcosystemError","message","cause","isEcosystemError","error","ok","value","err","isOk","result","isErr","unwrap","defaultValue","unwrapOrThrow","map","fn","mapErr","chain","computeContentHash","text","data","hashBuffer","b","isToolCall","shouldSkipFormGuard","to","from","excludePages","onlyFromPages","formatScoredResult","BRIDGE_DEFAULT_TIMEOUT","RETRIEVAL_DEFAULT_LIMIT","RETRIEVAL_MAX_LIMIT","FORM_DIRTY_DEFAULT_MESSAGE","createToolCallBridge","options","registry","timeout","onError","onBeforeExecute","onAfterExecute","executeWithTimeout","toolCall","timeoutPromise","_","reject","errorMessage","toolCallOrCalls","tc","name","createRetrievalTool","vectorStore","description","defaultLimit","maxLimit","scoreThreshold","formatResult","extendParameters","buildFilter","parameters","schema","handler","args","query","requestedLimit","limit","filter","searchOptions","results","filteredResults","r","createFormDirtyGuard","form","confirmFn","createSessionPersistence","database","storeName","autoprune","onSaveError","store","pruneOldSessions","maxAgeMs","cutoff","allSessions","prunedCount","session","id","serialized","s"],"mappings":"AAwBO,MAAeA,UAAuB,MAAM;AAAA;AAAA,EAIhC;AAAA,EAElB,YAAYC,GAAiBC,GAAe;AAC3C,UAAMD,CAAO,GACb,KAAK,OAAO,KAAK,YAAY,MAC7B,KAAK,QAAQC;AAAA,EACd;AACD;AAkBO,SAASC,EAAiBC,GAAyC;AACzE,SAAOA,aAAiBJ;AACzB;AC9BO,SAASK,EAAMC,GAAiB;AACtC,SAAO,EAAE,IAAI,IAAM,OAAAA,EAAA;AACpB;AAeO,SAASC,EAAOH,GAAkB;AACxC,SAAO,EAAE,IAAI,IAAO,OAAAA,EAAA;AACrB;AAgBO,SAASI,EAAWC,GAAuC;AACjE,SAAOA,EAAO,OAAO;AACtB;AAgBO,SAASC,EAAYD,GAAwC;AACnE,SAAO,CAACA,EAAO;AAChB;AAeO,SAASE,EAAaF,GAAsBG,GAAoB;AACtE,SAAOH,EAAO,KAAKA,EAAO,QAAQG;AACnC;AAeO,SAASC,EAAoBJ,GAAyB;AAC5D,MAAIA,EAAO;AACV,WAAOA,EAAO;AAEf,QAAIA,EAAO,iBAAiB,QACrBA,EAAO,QAER,IAAI,MAAM,OAAOA,EAAO,KAAK,CAAC;AACrC;AAeO,SAASK,EACfL,GACAM,GACe;AACf,SAAON,EAAO,KAAKJ,EAAGU,EAAGN,EAAO,KAAK,CAAC,IAAIA;AAC3C;AAeO,SAASO,EACfP,GACAM,GACe;AACf,SAAON,EAAO,KAAKA,IAASF,EAAIQ,EAAGN,EAAO,KAAK,CAAC;AACjD;AAkBO,SAASQ,EACfR,GACAM,GACe;AACf,SAAON,EAAO,KAAKM,EAAGN,EAAO,KAAK,IAAIA;AACvC;AAkBA,eAAsBS,EAAmBC,GAAoC;AAE5E,QAAMC,IADU,IAAI,YAAA,EACC,OAAOD,CAAI,GAC1BE,IAAa,MAAM,OAAO,OAAO,OAAO,WAAWD,CAAI;AAE7D,SADkB,MAAM,KAAK,IAAI,WAAWC,CAAU,CAAC,EACtC,IAAI,CAAAC,MAAKA,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAAE,KAAK,EAAE;AACnE;AAYO,SAASC,EAAWjB,GAA2E;AACrG,SACC,OAAOA,KAAU,YACjBA,MAAU,QACV,QAAQA,KACR,UAAUA,KACV,eAAeA;AAEjB;AAWO,SAASkB,EACfC,GACAC,GACAC,GACAC,GACU;AAEV,SAAID,EAAa,SAASF,CAAE,IACpB,KAIDG,MAAkB,UAAa,CAACA,EAAc,SAASF,CAAI;AACnE;AASO,SAASG,EAAmBpB,GAA+B;AACjE,SAAO;AAAA,IACN,SAASA,EAAO;AAAA,IAChB,OAAOA,EAAO;AAAA,IACd,UAAUA,EAAO;AAAA,EAAA;AAEnB;AC/PO,MAAMqB,IAAyB,KAGzBC,IAA0B,IAG1BC,IAAsB,KAGtBC,IAA6B;AC0CnC,SAASC,EACfC,GAC0B;AAC1B,QAAM;AAAA,IACL,UAAAC;AAAA,IACA,SAAAC,IAAUP;AAAA,IACV,SAAAQ;AAAA,IACA,iBAAAC;AAAA,IACA,gBAAAC;AAAA,EAAA,IACGL;AAEJ,iBAAeM,EAAmBC,GAAyC;AAE1E,QAAI,CAACN,EAAS,IAAIM,EAAS,IAAI;AAC9B,aAAO;AAAA,QACN,QAAQA,EAAS;AAAA,QACjB,MAAMA,EAAS;AAAA,QACf,SAAS;AAAA,QACT,OAAO,mBAAmBA,EAAS,IAAI;AAAA,MAAA;AAKzC,IAAAH,IAAkBG,CAAQ;AAE1B,QAAI;AAEH,YAAMC,IAAiB,IAAI,QAAe,CAACC,GAAGC,MAAW;AACxD,mBAAW,MAAM;AAChB,UAAAA,EAAO,IAAI,MAAM,kCAAkCR,CAAO,IAAI,CAAC;AAAA,QAChE,GAAGA,CAAO;AAAA,MACX,CAAC,GAGK/B,IAAQ,MAAM,QAAQ,KAAK;AAAA,QAChC8B,EAAS,QAAQM,EAAS,MAAMA,EAAS,SAAS;AAAA,QAClDC;AAAA,MAAA,CACA;AAGD,aAAAH,IAAiBE,GAAUpC,CAAK,GAEzB;AAAA,QACN,QAAQoC,EAAS;AAAA,QACjB,MAAMA,EAAS;AAAA,QACf,SAAS;AAAA,QACT,OAAApC;AAAA,MAAA;AAAA,IAEF,SAASF,GAAO;AAEf,MAAAkC,IAAUlC,GAAOsC,CAAQ;AAEzB,YAAMI,IAAe1C,aAAiB,QACnCA,EAAM,UACN,OAAOA,CAAK;AAEf,aAAO;AAAA,QACN,QAAQsC,EAAS;AAAA,QACjB,MAAMA,EAAS;AAAA,QACf,SAAS;AAAA,QACT,OAAOI;AAAA,MAAA;AAAA,IAET;AAAA,EACD;AAEA,SAAO;AAAA,IACN,QAAQC,GAAiD;AACxD,aAAIxB,EAAWwB,CAAe,IACtBN,EAAmBM,CAAe,IAEnC,QAAQ;AAAA,QACbA,EAAiB,IAAI,CAAAC,MAAMP,EAAmBO,CAAE,CAAC;AAAA,MAAA;AAAA,IAEpD;AAAA,IAEA,QAAQC,GAAuB;AAC9B,aAAOb,EAAS,IAAIa,CAAI;AAAA,IACzB;AAAA,EAAA;AAEF;AAgCO,SAASC,EACff,GACyB;AACzB,QAAM;AAAA,IACL,aAAAgB;AAAA,IACA,MAAAF;AAAA,IACA,aAAAG;AAAA,IACA,cAAAC,IAAetB;AAAA,IACf,UAAAuB,IAAWtB;AAAA,IACX,gBAAAuB;AAAA,IACA,cAAAC,IAAe3B;AAAA,IACf,kBAAA4B,IAAmB,CAAA;AAAA,IACnB,aAAAC;AAAA,EAAA,IACGvB,GAGEwB,IAA0B;AAAA,IAC/B,MAAM;AAAA,IACN,YAAY;AAAA,MACX,OAAO;AAAA,QACN,MAAM;AAAA,QACN,aAAa;AAAA,MAAA;AAAA,MAEd,OAAO;AAAA,QACN,MAAM;AAAA,QACN,aAAa,iDAAiDN,CAAY,UAAUC,CAAQ;AAAA,QAC5F,SAAS;AAAA,QACT,SAASA;AAAA,QACT,SAASD;AAAA,MAAA;AAAA,MAEV,GAAGI;AAAA,IAAA;AAAA,IAEJ,UAAU,CAAC,OAAO;AAAA,EAAA,GAGbG,IAAqB;AAAA,IAC1B,MAAAX;AAAA,IACA,aAAAG;AAAA,IACA,YAAAO;AAAA,EAAA;AAGD,iBAAeE,EACdC,GAC8B;AAC9B,UAAMC,IAAQD,EAAK;AACnB,QAAI,OAAOC,KAAU,YAAYA,EAAM,WAAW;AACjD,aAAO,CAAA;AAGR,UAAMC,IAAiBF,EAAK;AAC5B,QAAIG,IAAQZ;AACZ,IAAI,OAAOW,KAAmB,YAAY,OAAO,UAAUA,CAAc,MACxEC,IAAQ,KAAK,IAAI,KAAK,IAAI,GAAGD,CAAc,GAAGV,CAAQ;AAIvD,UAAMY,IAASR,IAAcI,CAAI,GAG3BK,IAAgBD,MAAW,SAC9B,EAAE,OAAAD,GAAO,QAAAC,EAAA,IACT,EAAE,OAAAD,EAAA,GACCG,IAAU,MAAMjB,EAAY,OAAOY,GAAOI,CAAa;AAG7D,QAAIE,IAAkBD;AACtB,WAAIb,MAAmB,WACtBc,IAAkBD,EAAQ,OAAO,CAAAE,MAAKA,EAAE,SAASf,CAAc,IAIzDc,EAAgB,IAAIb,CAAY;AAAA,EACxC;AAEA,SAAO,EAAE,QAAAI,GAAQ,SAAAC,EAAA;AAClB;AA8BO,SAASU,EACfpC,GACyB;AACzB,QAAM;AAAA,IACL,MAAAqC;AAAA,IACA,WAAAC;AAAA,IACA,SAAAxE,IAAUgC;AAAA,IACV,cAAAN,IAAe,CAAA;AAAA,IACf,eAAAC;AAAA,EAAA,IACGO;AAEJ,SAAO,eAAqBV,GAAWC,GAA+B;AAOrE,WALIF,EAAoBC,GAAIC,GAAMC,GAAcC,CAAa,KAKzD,CAAC4C,EAAK,YACF,KAID,QAAQ,QAAQC,EAAUxE,CAAO,CAAC;AAAA,EAC1C;AACD;AA+BO,SAASyE,EACfvC,GAC8B;AAC9B,QAAM;AAAA,IACL,UAAAwC;AAAA,IACA,WAAAC;AAAA,IACA,WAAAC;AAAA,IACA,aAAAC;AAAA,EAAA,IACG3C,GAEE4C,IAAQJ,EAAS,MAAyBC,CAAS;AAEzD,iBAAeI,EAAiBC,GAAmC;AAElE,UAAMC,IADM,KAAK,IAAA,IACID,GAEfE,IAAc,MAAMJ,EAAM,IAAA;AAChC,QAAIK,IAAc;AAElB,eAAWC,KAAWF;AACrB,MAAIE,EAAQ,YAAYH,MACvB,MAAMH,EAAM,OAAOM,EAAQ,EAAE,GAC7BD;AAIF,WAAOA;AAAA,EACR;AAGA,SAAIP,MAAc,UAAaA,IAAY,KACrCG,EAAiBH,CAAS,GAGzB;AAAA,IACN,MAAM,KAAKS,GAAYD,GAA6C;AACnE,UAAI;AACH,cAAME,IAAgC;AAAA,UACrC,IAAAD;AAAA,UACA,UAAU,CAAC,GAAGD,EAAQ,aAAa;AAAA,UACnC,UAAUA,EAAQ,YAAA;AAAA,UAClB,WAAW,KAAK,IAAA;AAAA,QAAI;AAGrB,cAAMN,EAAM,IAAIQ,GAAYD,CAAE;AAAA,MAC/B,SAASlF,GAAO;AACf,cAAA0E,IAAc1E,GAAOkF,CAAE,GACjBlF;AAAA,MACP;AAAA,IACD;AAAA,IAEA,MAAM,KAAKkF,GAAoD;AAC9D,aAAOP,EAAM,IAAIO,CAAE;AAAA,IACpB;AAAA,IAEA,MAAM,OAAOA,GAA2B;AACvC,YAAMP,EAAM,OAAOO,CAAE;AAAA,IACtB;AAAA,IAEA,MAAM,OAAmC;AAExC,cADoB,MAAMP,EAAM,IAAA,GACb,IAAI,CAAAS,MAAKA,EAAE,EAAE;AAAA,IACjC;AAAA,IAEA,MAAM,MAAMP,GAAmC;AAC9C,aAAOD,EAAiBC,CAAQ;AAAA,IACjC;AAAA,EAAA;AAEF;"}
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/helpers.ts","../src/core/bridges/ToolCallBridge.ts","../src/core/bridges/RetrievalTool.ts","../src/core/bridges/FormDirtyGuard.ts","../src/core/bridges/SessionPersistence.ts","../src/errors.ts","../src/factories.ts"],"sourcesContent":["/**\r\n * @mikesaintsg/core\r\n *\r\n * Shared constants for the core library.\r\n */\r\n\r\n// ============================================================================\r\n// Bridge Constants\r\n// ============================================================================\r\n\r\n/** Default timeout for bridge operations in milliseconds */\r\nexport const BRIDGE_DEFAULT_TIMEOUT = 30000\r\n\r\n/** Default retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_DEFAULT_LIMIT = 10\r\n\r\n/** Maximum retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_MAX_LIMIT = 100\r\n\r\n/** Default form dirty guard message */\r\nexport const FORM_DIRTY_DEFAULT_MESSAGE = 'You have unsaved changes. Are you sure you want to leave?'\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Helper functions and type guards.\r\n */\r\n\r\nimport type { Ok, Err, Result, ContentHash, ScoredResult } from './types.js'\r\n\r\n// ============================================================================\r\n// Result Pattern Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Create a success result.\r\n *\r\n * @param value - The success value\r\n * @returns An Ok result containing the value\r\n *\r\n * @example\r\n * ```ts\r\n * const result = ok(42)\r\n * // result.ok === true\r\n * // result.value === 42\r\n * ```\r\n */\r\nexport function ok<T>(value: T): Ok<T> {\r\n\treturn { ok: true, value }\r\n}\r\n\r\n/**\r\n * Create a failure result.\r\n *\r\n * @param error - The error value\r\n * @returns An Err result containing the error\r\n *\r\n * @example\r\n * ```ts\r\n * const result = err('NOT_FOUND')\r\n * // result.ok === false\r\n * // result.error === 'NOT_FOUND'\r\n * ```\r\n */\r\nexport function err<E>(error: E): Err<E> {\r\n\treturn { ok: false, error }\r\n}\r\n\r\n/**\r\n * Check if a result is a success.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Ok, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = ok(42)\r\n * if (isOk(result)) {\r\n *   console.log(result.value) // TypeScript knows result is Ok<number>\r\n * }\r\n * ```\r\n */\r\nexport function isOk<T, E>(result: Result<T, E>): result is Ok<T> {\r\n\treturn result.ok\r\n}\r\n\r\n/**\r\n * Check if a result is a failure.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Err, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = err('NOT_FOUND')\r\n * if (isErr(result)) {\r\n *   console.log(result.error) // TypeScript knows result is Err<string>\r\n * }\r\n * ```\r\n */\r\nexport function isErr<T, E>(result: Result<T, E>): result is Err<E> {\r\n\treturn !result.ok\r\n}\r\n\r\n/**\r\n * Unwrap a result, returning the value or a default.\r\n *\r\n * @param result - The result to unwrap\r\n * @param defaultValue - Value to return if result is an error\r\n * @returns The success value or the default value\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrap(ok(42), 0) // 42\r\n * const fallback = unwrap(err('oops'), 0) // 0\r\n * ```\r\n */\r\nexport function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T {\r\n\treturn result.ok ? result.value : defaultValue\r\n}\r\n\r\n/**\r\n * Unwrap a result, throwing if it's an error.\r\n *\r\n * @param result - The result to unwrap\r\n * @returns The success value\r\n * @throws The error if result is Err\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrapOrThrow(ok(42)) // 42\r\n * unwrapOrThrow(err(new Error('oops'))) // throws Error('oops')\r\n * ```\r\n */\r\nexport function unwrapOrThrow<T, E>(result: Result<T, E>): T {\r\n\tif (result.ok) {\r\n\t\treturn result.value\r\n\t}\r\n\tif (result.error instanceof Error) {\r\n\t\tthrow result.error\r\n\t}\r\n\tthrow new Error(String(result.error))\r\n}\r\n\r\n/**\r\n * Map a function over a success value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the success value\r\n * @returns A new result with the mapped value, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const doubled = map(ok(5), x => x * 2) // ok(10)\r\n * const failed = map(err('oops'), x => x * 2) // err('oops')\r\n * ```\r\n */\r\nexport function map<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => U,\r\n): Result<U, E> {\r\n\treturn result.ok ? ok(fn(result.value)) : result\r\n}\r\n\r\n/**\r\n * Map a function over an error value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the error value\r\n * @returns A new result with the mapped error, or the original value\r\n *\r\n * @example\r\n * ```ts\r\n * const wrapped = mapErr(err('oops'), e => new Error(e)) // err(Error('oops'))\r\n * const unchanged = mapErr(ok(42), e => new Error(e)) // ok(42)\r\n * ```\r\n */\r\nexport function mapErr<T, E, F>(\r\n\tresult: Result<T, E>,\r\n\tfn: (error: E) => F,\r\n): Result<T, F> {\r\n\treturn result.ok ? result : err(fn(result.error))\r\n}\r\n\r\n/**\r\n * Chain results (flatMap). Apply a function that returns a Result to a success value.\r\n *\r\n * @param result - The result to chain\r\n * @param fn - Function returning a new Result\r\n * @returns The result of applying fn, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const parsed = chain(ok('42'), s => {\r\n *   const n = parseInt(s, 10)\r\n *   return isNaN(n) ? err('PARSE_ERROR') : ok(n)\r\n * })\r\n * // parsed = ok(42)\r\n * ```\r\n */\r\nexport function chain<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => Result<U, E>,\r\n): Result<U, E> {\r\n\treturn result.ok ? fn(result.value) : result\r\n}\r\n\r\n// ============================================================================\r\n// Content Hashing Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Compute a SHA-256 content hash for text.\r\n *\r\n * @param text - The text to hash\r\n * @returns A hex string content hash\r\n *\r\n * @example\r\n * ```ts\r\n * const hash = await computeContentHash('Hello, world!')\r\n * // hash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'\r\n * ```\r\n */\r\nexport async function computeContentHash(text: string): Promise<ContentHash> {\r\n\tconst encoder = new TextEncoder()\r\n\tconst data = encoder.encode(text)\r\n\tconst hashBuffer = await crypto.subtle.digest('SHA-256', data)\r\n\tconst hashArray = Array.from(new Uint8Array(hashBuffer))\r\n\treturn hashArray.map(b => b.toString(16).padStart(2, '0')).join('')\r\n}\r\n\r\n// ============================================================================\r\n// Bridge Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Check if a value is a single ToolCall (not an array).\r\n *\r\n * @param value - Value to check\r\n * @returns True if the value is a single ToolCall\r\n */\r\nexport function isToolCall(value: unknown): value is { id: string; name: string; arguments: unknown } {\r\n\treturn (\r\n\t\ttypeof value === 'object' &&\r\n\t\tvalue !== null &&\r\n\t\t'id' in value &&\r\n\t\t'name' in value &&\r\n\t\t'arguments' in value\r\n\t)\r\n}\r\n\r\n/**\r\n * Determine if form dirty guard should be skipped for a navigation.\r\n *\r\n * @param to - Target page\r\n * @param from - Source page\r\n * @param excludePages - Pages to exclude from guard\r\n * @param onlyFromPages - Only guard from these pages (if specified)\r\n * @returns True if guard should be skipped\r\n */\r\nexport function shouldSkipFormGuard<TPage extends string>(\r\n\tto: TPage,\r\n\tfrom: TPage,\r\n\texcludePages: readonly TPage[],\r\n\tonlyFromPages: readonly TPage[] | undefined,\r\n): boolean {\r\n\t// Skip if navigating to excluded page\r\n\tif (excludePages.includes(to)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\t// Skip if from page is not in onlyFromPages (if specified)\r\n\treturn onlyFromPages !== undefined && !onlyFromPages.includes(from)\r\n}\r\n\r\n/**\r\n * Default result formatter for retrieval tools.\r\n * Returns content, score, and metadata.\r\n *\r\n * @param result - Scored result to format\r\n * @returns Formatted result object\r\n */\r\nexport function formatScoredResult(result: ScoredResult): unknown {\r\n\treturn {\r\n\t\tcontent: result.content,\r\n\t\tscore: result.score,\r\n\t\tmetadata: result.metadata,\r\n\t}\r\n}\r\n","/**\n * @mikesaintsg/core\n *\n * Tool call bridge implementation.\n * Connects inference tool calls to contextprotocol tool registry.\n */\n\nimport type {\n\tToolCall,\n\tToolResult,\n\tToolCallBridgeOptions,\n\tToolCallBridgeInterface,\n\tToolRegistryMinimal,\n} from '../../types.js'\nimport { BRIDGE_DEFAULT_TIMEOUT } from '../../constants.js'\nimport { isToolCall } from '../../helpers.js'\n\n/**\n * Tool call bridge implementation.\n * Executes tool calls against a tool registry with timeout and lifecycle hooks.\n */\nexport class ToolCallBridge implements ToolCallBridgeInterface {\n\treadonly #registry: ToolRegistryMinimal\n\treadonly #timeout: number\n\treadonly #onError: ((error: unknown, toolCall: ToolCall) => void) | undefined\n\treadonly #onBeforeExecute: ((toolCall: ToolCall) => void) | undefined\n\treadonly #onAfterExecute: ((toolCall: ToolCall, result: unknown) => void) | undefined\n\n\tconstructor(options: ToolCallBridgeOptions) {\n\t\tthis.#registry = options.registry\n\t\tthis.#timeout = options.timeout ?? BRIDGE_DEFAULT_TIMEOUT\n\t\tthis.#onError = 'onError' in options ? options.onError : undefined\n\t\tthis.#onBeforeExecute = 'onBeforeExecute' in options ? options.onBeforeExecute : undefined\n\t\tthis.#onAfterExecute = 'onAfterExecute' in options ? options.onAfterExecute : undefined\n\t}\n\n\texecute(toolCalls: ToolCall): Promise<ToolResult>\n\texecute(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>\n\texecute(toolCallOrCalls: ToolCall | readonly ToolCall[]): Promise<ToolResult | readonly ToolResult[]> {\n\t\tif (isToolCall(toolCallOrCalls)) {\n\t\t\treturn this.#executeWithTimeout(toolCallOrCalls)\n\t\t}\n\t\treturn Promise.all(\n\t\t\ttoolCallOrCalls.map(tc => this.#executeWithTimeout(tc)),\n\t\t)\n\t}\n\n\thasTool(name: string): boolean {\n\t\treturn this.#registry.has(name)\n\t}\n\n\tasync #executeWithTimeout(toolCall: ToolCall): Promise<ToolResult> {\n\t\t// Check if tool exists\n\t\tif (!this.#registry.has(toolCall.name)) {\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `Tool not found: ${toolCall.name}`,\n\t\t\t}\n\t\t}\n\n\t\t// Call lifecycle hook\n\t\tthis.#onBeforeExecute?.(toolCall)\n\n\t\ttry {\n\t\t\t// Create timeout promise\n\t\t\tconst timeoutPromise = new Promise<never>((_, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\treject(new Error(`Tool execution timed out after ${this.#timeout}ms`))\n\t\t\t\t}, this.#timeout)\n\t\t\t})\n\n\t\t\t// Execute tool with timeout\n\t\t\tconst value = await Promise.race([\n\t\t\t\tthis.#registry.execute(toolCall.name, toolCall.arguments),\n\t\t\t\ttimeoutPromise,\n\t\t\t])\n\n\t\t\t// Call lifecycle hook\n\t\t\tthis.#onAfterExecute?.(toolCall, value)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: true,\n\t\t\t\tvalue,\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// Call error hook\n\t\t\tthis.#onError?.(error, toolCall)\n\n\t\t\tconst errorMessage = error instanceof Error\n\t\t\t\t? error.message\n\t\t\t\t: String(error)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: errorMessage,\n\t\t\t}\n\t\t}\n\t}\n}\n","/**\n * @mikesaintsg/core\n *\n * Retrieval tool implementation.\n * Creates a tool for vectorstore search that can be registered with contextprotocol.\n */\n\nimport type {\n\tRetrievalToolOptions,\n\tRetrievalToolInterface,\n\tToolSchema,\n\tJSONSchema7,\n\tVectorStoreMinimal,\n} from '../../types.js'\nimport {\n\tRETRIEVAL_DEFAULT_LIMIT,\n\tRETRIEVAL_MAX_LIMIT,\n} from '../../constants.js'\nimport { formatScoredResult } from '../../helpers.js'\n\n/**\n * Retrieval tool implementation.\n * Provides a tool schema and handler for vectorstore search.\n */\nexport class RetrievalTool<TMetadata = unknown> implements RetrievalToolInterface {\n\treadonly schema: ToolSchema\n\treadonly #vectorStore: VectorStoreMinimal<TMetadata>\n\treadonly #defaultLimit: number\n\treadonly #maxLimit: number\n\treadonly #scoreThreshold: number | undefined\n\treadonly #formatResult: (result: { id: string; content: string; score: number; metadata?: Readonly<Record<string, unknown>> }) => unknown\n\treadonly #buildFilter: ((params: Readonly<Record<string, unknown>>) => TMetadata | undefined) | undefined\n\n\tconstructor(options: RetrievalToolOptions<TMetadata>) {\n\t\tthis.#vectorStore = options.vectorStore\n\t\tthis.#defaultLimit = options.defaultLimit ?? RETRIEVAL_DEFAULT_LIMIT\n\t\tthis.#maxLimit = options.maxLimit ?? RETRIEVAL_MAX_LIMIT\n\t\tthis.#scoreThreshold = 'scoreThreshold' in options ? options.scoreThreshold : undefined\n\t\tthis.#formatResult = options.formatResult ?? formatScoredResult\n\t\tthis.#buildFilter = 'buildFilter' in options ? options.buildFilter : undefined\n\n\t\t// Build tool schema parameters\n\t\tconst parameters: JSONSchema7 = {\n\t\t\ttype: 'object',\n\t\t\tproperties: {\n\t\t\t\tquery: {\n\t\t\t\t\ttype: 'string',\n\t\t\t\t\tdescription: 'The search query to find relevant documents',\n\t\t\t\t},\n\t\t\t\tlimit: {\n\t\t\t\t\ttype: 'integer',\n\t\t\t\t\tdescription: `Maximum number of results to return (default: ${this.#defaultLimit}, max: ${this.#maxLimit})`,\n\t\t\t\t\tminimum: 1,\n\t\t\t\t\tmaximum: this.#maxLimit,\n\t\t\t\t\tdefault: this.#defaultLimit,\n\t\t\t\t},\n\t\t\t\t...options.extendParameters,\n\t\t\t},\n\t\t\trequired: ['query'],\n\t\t}\n\n\t\tthis.schema = {\n\t\t\tname: options.name,\n\t\t\tdescription: options.description,\n\t\t\tparameters,\n\t\t}\n\t}\n\n\thandler = async(args: Readonly<Record<string, unknown>>): Promise<readonly unknown[]> => {\n\t\tconst query = args.query\n\t\tif (typeof query !== 'string' || query.length === 0) {\n\t\t\treturn []\n\t\t}\n\n\t\tconst requestedLimit = args.limit\n\t\tlet limit = this.#defaultLimit\n\t\tif (typeof requestedLimit === 'number' && Number.isInteger(requestedLimit)) {\n\t\t\tlimit = Math.min(Math.max(1, requestedLimit), this.#maxLimit)\n\t\t}\n\n\t\t// Build filter if provided\n\t\tconst filter = this.#buildFilter?.(args)\n\n\t\t// Search vectorstore - only include filter if defined\n\t\tconst searchOptions = filter !== undefined\n\t\t\t? { limit, filter }\n\t\t\t: { limit }\n\t\tconst results = await this.#vectorStore.search(query, searchOptions)\n\n\t\t// Filter by score threshold\n\t\tlet filteredResults = results\n\t\tif (this.#scoreThreshold !== undefined) {\n\t\t\tfilteredResults = results.filter(r => r.score >= this.#scoreThreshold!)\n\t\t}\n\n\t\t// Format results\n\t\treturn filteredResults.map(this.#formatResult)\n\t}\n}\n","/**\n * @mikesaintsg/core\n *\n * Form dirty guard implementation.\n * Navigation guard that prevents leaving when form is dirty.\n */\n\nimport type {\n\tFormDirtyGuardOptions,\n\tNavigationGuard,\n\tFormMinimal,\n} from '../../types.js'\nimport { FORM_DIRTY_DEFAULT_MESSAGE } from '../../constants.js'\nimport { shouldSkipFormGuard } from '../../helpers.js'\n\n/**\n * Form dirty guard implementation.\n * Returns a navigation guard function that prompts when form has unsaved changes.\n */\nexport class FormDirtyGuard<TFormData = unknown, TPage extends string = string> {\n\treadonly #form: FormMinimal<TFormData>\n\treadonly #confirmFn: (message: string) => Promise<boolean> | boolean\n\treadonly #message: string\n\treadonly #excludePages: readonly TPage[]\n\treadonly #onlyFromPages: readonly TPage[] | undefined\n\n\tconstructor(options: FormDirtyGuardOptions<TFormData, TPage>) {\n\t\tthis.#form = options.form\n\t\tthis.#confirmFn = options.confirmFn\n\t\tthis.#message = options.message ?? FORM_DIRTY_DEFAULT_MESSAGE\n\t\tthis.#excludePages = options.excludePages ?? []\n\t\tthis.#onlyFromPages = 'onlyFromPages' in options ? options.onlyFromPages : undefined\n\t}\n\n\t/**\n\t * Get the navigation guard function.\n\t * This is the function to register with a router.\n\t */\n\tgetGuard(): NavigationGuard<TPage> {\n\t\treturn async(to: TPage, from: TPage): Promise<boolean> => {\n\t\t\t// Check if we should skip guard for this navigation\n\t\t\tif (shouldSkipFormGuard(to, from, this.#excludePages, this.#onlyFromPages)) {\n\t\t\t\treturn true\n\t\t\t}\n\n\t\t\t// If form is not dirty, allow navigation\n\t\t\tif (!this.#form.isDirty()) {\n\t\t\t\treturn true\n\t\t\t}\n\n\t\t\t// Form is dirty, ask for confirmation\n\t\t\treturn Promise.resolve(this.#confirmFn(this.#message))\n\t\t}\n\t}\n}\n","/**\n * @mikesaintsg/core\n *\n * Session persistence implementation.\n * Connects inference sessions to IndexedDB storage.\n */\n\nimport type {\n\tSessionPersistenceOptions,\n\tSessionPersistenceInterface,\n\tSerializableSession,\n\tSerializedSession,\n\tMinimalStoreAccess,\n} from '../../types.js'\n\n/**\n * Session persistence implementation.\n * Stores and retrieves inference sessions from a database store.\n */\nexport class SessionPersistence implements SessionPersistenceInterface {\n\treadonly #store: MinimalStoreAccess<SerializedSession>\n\treadonly #onSaveError: ((error: unknown, sessionId: string) => void) | undefined\n\n\tconstructor(options: SessionPersistenceOptions) {\n\t\tthis.#store = options.database.store<SerializedSession>(options.storeName)\n\t\tthis.#onSaveError = 'onSaveError' in options ? options.onSaveError : undefined\n\n\t\t// Auto-prune on creation if configured\n\t\tif (options.autoprune !== undefined && options.autoprune > 0) {\n\t\t\tvoid this.prune(options.autoprune)\n\t\t}\n\t}\n\n\tasync isAvailable(): Promise<boolean> {\n\t\ttry {\n\t\t\t// Try to access the store to verify availability\n\t\t\tawait this.#store.all()\n\t\t\treturn true\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\tasync clear(): Promise<void> {\n\t\tawait this.#store.clear()\n\t}\n\n\tasync save(id: string, session: SerializableSession): Promise<void> {\n\t\ttry {\n\t\t\tconst serialized: SerializedSession = {\n\t\t\t\tid,\n\t\t\t\tmessages: [...session.getMessages()],\n\t\t\t\tmetadata: session.getMetadata(),\n\t\t\t\tupdatedAt: Date.now(),\n\t\t\t}\n\n\t\t\tawait this.#store.set(serialized, id)\n\t\t} catch (error) {\n\t\t\tthis.#onSaveError?.(error, id)\n\t\t\tthrow error\n\t\t}\n\t}\n\n\tasync load(id: string): Promise<SerializedSession | undefined> {\n\t\treturn this.#store.get(id)\n\t}\n\n\tasync delete(id: string): Promise<void> {\n\t\tawait this.#store.remove(id)\n\t}\n\n\tasync list(): Promise<readonly string[]> {\n\t\tconst allSessions = await this.#store.all()\n\t\treturn allSessions.map(s => s.id)\n\t}\n\n\tasync prune(maxAgeMs: number): Promise<number> {\n\t\tconst now = Date.now()\n\t\tconst cutoff = now - maxAgeMs\n\n\t\tconst allSessions = await this.#store.all()\n\t\tlet prunedCount = 0\n\n\t\tfor (const session of allSessions) {\n\t\t\tif (session.updatedAt < cutoff) {\n\t\t\t\tawait this.#store.remove(session.id)\n\t\t\t\tprunedCount++\n\t\t\t}\n\t\t}\n\n\t\treturn prunedCount\n\t}\n}\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Base error class and utilities for the ecosystem.\r\n */\r\n// ============================================================================\r\n// Base Ecosystem Error\r\n// ============================================================================\r\n/**\r\n * Base error class for all ecosystem errors.\r\n * All package-specific errors should extend this class.\r\n *\r\n * @example\r\n * ```ts\r\n * class StorageError extends EcosystemError {\r\n *   readonly code: StorageErrorCode\r\n *\r\n *   constructor(code: StorageErrorCode, message: string, cause?: Error) {\r\n *     super(message, cause)\r\n *     this.code = code\r\n *   }\r\n * }\r\n * ```\r\n */\r\nexport abstract class EcosystemError extends Error {\r\n\t/** Error code for programmatic handling */\r\n\tabstract readonly code: string\r\n\t/** Original error that caused this one */\r\n\toverride readonly cause: Error | undefined\r\n\r\n\tconstructor(message: string, cause?: Error) {\r\n\t\tsuper(message)\r\n\t\tthis.name = this.constructor.name\r\n\t\tthis.cause = cause\r\n\t}\r\n}\r\n/**\r\n * Type guard for ecosystem errors.\r\n *\r\n * @param error - The value to check\r\n * @returns True if the error is an EcosystemError\r\n *\r\n * @example\r\n * ```ts\r\n * try {\r\n *   await someOperation()\r\n * } catch (error) {\r\n *   if (isEcosystemError(error)) {\r\n *     console.log('Code:', error.code)\r\n *   }\r\n * }\r\n * ```\r\n */\r\nexport function isEcosystemError(error: unknown): error is EcosystemError {\r\n\treturn error instanceof EcosystemError\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Factory functions for creating bridge instances.\r\n */\r\n\r\nimport type {\r\n\tToolCallBridgeOptions,\r\n\tToolCallBridgeInterface,\r\n\tRetrievalToolOptions,\r\n\tRetrievalToolInterface,\r\n\tFormDirtyGuardOptions,\r\n\tNavigationGuard,\r\n\tSessionPersistenceOptions,\r\n\tSessionPersistenceInterface,\r\n} from './types.js'\r\nimport {\r\n\tToolCallBridge,\r\n\tRetrievalTool,\r\n\tFormDirtyGuard,\r\n\tSessionPersistence,\r\n} from './core/index.js'\r\n\r\n// ============================================================================\r\n// Tool Call Bridge Factory\r\n// ============================================================================\r\n\r\n/**\r\n * Create a tool call bridge.\r\n *\r\n * @param options - Bridge configuration options\r\n * @returns A tool call bridge instance\r\n *\r\n * @example\r\n * ```ts\r\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\r\n * import { createToolCallBridge } from '@mikesaintsg/core'\r\n *\r\n * const registry = createToolRegistry()\r\n * registry.register(weatherTool)\r\n *\r\n * const bridge = createToolCallBridge({\r\n *   registry,\r\n *   timeout: 30000,\r\n *   onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),\r\n * })\r\n *\r\n * // Execute tool calls from LLM response\r\n * const results = await bridge.execute(response.toolCalls)\r\n * ```\r\n */\r\nexport function createToolCallBridge(\r\n\toptions: ToolCallBridgeOptions,\r\n): ToolCallBridgeInterface {\r\n\treturn new ToolCallBridge(options)\r\n}\r\n\r\n// ============================================================================\r\n// Retrieval Tool Factory\r\n// ============================================================================\r\n\r\n/**\r\n * Create a retrieval tool for use with contextprotocol tool registry.\r\n *\r\n * @param options - Retrieval tool configuration options\r\n * @returns A tool schema and handler for registration\r\n *\r\n * @example\r\n * ```ts\r\n * import { createVectorStore } from '@mikesaintsg/vectorstore'\r\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\r\n * import { createRetrievalTool } from '@mikesaintsg/core'\r\n *\r\n * const vectorStore = createVectorStore({ ... })\r\n * const registry = createToolRegistry()\r\n *\r\n * const { schema, handler } = createRetrievalTool({\r\n *   vectorStore,\r\n *   name: 'search_docs',\r\n *   description: 'Search documentation for relevant information',\r\n *   defaultLimit: 5,\r\n *   scoreThreshold: 0.7,\r\n * })\r\n *\r\n * registry.register({ ...schema, execute: handler })\r\n * ```\r\n */\r\nexport function createRetrievalTool<TMetadata = unknown>(\r\n\toptions: RetrievalToolOptions<TMetadata>,\r\n): RetrievalToolInterface {\r\n\treturn new RetrievalTool(options)\r\n}\r\n\r\n// ============================================================================\r\n// Form Dirty Guard Factory\r\n// ============================================================================\r\n\r\n/**\r\n * Create a navigation guard that prevents leaving when form is dirty.\r\n *\r\n * @param options - Form dirty guard configuration options\r\n * @returns A navigation guard function\r\n *\r\n * @example\r\n * ```ts\r\n * import { createForm } from '@mikesaintsg/form'\r\n * import { createFormDirtyGuard } from '@mikesaintsg/core'\r\n *\r\n * const form = createForm({ ... })\r\n *\r\n * const guard = createFormDirtyGuard({\r\n *   form,\r\n *   confirmFn: (message) => window.confirm(message),\r\n *   message: 'You have unsaved changes. Continue?',\r\n *   excludePages: ['settings'],\r\n * })\r\n *\r\n * // Use with router\r\n * router.beforeNavigate(guard)\r\n * ```\r\n */\r\nexport function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(\r\n\toptions: FormDirtyGuardOptions<TFormData, TPage>,\r\n): NavigationGuard<TPage> {\r\n\tconst guard = new FormDirtyGuard(options)\r\n\treturn guard.getGuard()\r\n}\r\n\r\n// ============================================================================\r\n// Session Persistence Factory\r\n// ============================================================================\r\n\r\n/**\r\n * Create a session persistence adapter for storing inference sessions.\r\n *\r\n * @param options - Session persistence configuration options\r\n * @returns A session persistence instance\r\n *\r\n * @example\r\n * ```ts\r\n * import { createDatabase } from '@mikesaintsg/indexeddb'\r\n * import { createSessionPersistence } from '@mikesaintsg/core'\r\n *\r\n * const db = await createDatabase({ name: 'sessions' })\r\n * const persistence = createSessionPersistence({\r\n *   database: db,\r\n *   storeName: 'chat_sessions',\r\n *   autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days\r\n * })\r\n *\r\n * // Save session\r\n * await persistence.save('session-1', session)\r\n *\r\n * // Load session\r\n * const savedSession = await persistence.load('session-1')\r\n * ```\r\n */\r\nexport function createSessionPersistence(\r\n\toptions: SessionPersistenceOptions,\r\n): SessionPersistenceInterface {\r\n\treturn new SessionPersistence(options)\r\n}\r\n"],"names":["BRIDGE_DEFAULT_TIMEOUT","RETRIEVAL_DEFAULT_LIMIT","RETRIEVAL_MAX_LIMIT","FORM_DIRTY_DEFAULT_MESSAGE","ok","value","err","error","isOk","result","isErr","unwrap","defaultValue","unwrapOrThrow","map","fn","mapErr","chain","computeContentHash","text","data","hashBuffer","b","isToolCall","shouldSkipFormGuard","to","from","excludePages","onlyFromPages","formatScoredResult","ToolCallBridge","#registry","#timeout","#onError","#onBeforeExecute","#onAfterExecute","options","toolCallOrCalls","#executeWithTimeout","tc","name","toolCall","timeoutPromise","_","reject","errorMessage","RetrievalTool","#vectorStore","#defaultLimit","#maxLimit","#scoreThreshold","#formatResult","#buildFilter","parameters","args","query","requestedLimit","limit","filter","searchOptions","results","filteredResults","r","FormDirtyGuard","#form","#confirmFn","#message","#excludePages","#onlyFromPages","SessionPersistence","#store","#onSaveError","id","session","serialized","s","maxAgeMs","cutoff","allSessions","prunedCount","EcosystemError","message","cause","isEcosystemError","createToolCallBridge","createRetrievalTool","createFormDirtyGuard","createSessionPersistence"],"mappings":"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"}

package/package.json

@@ -1,13 +1,15 @@
 {
 	"name": "@mikesaintsg/core",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"type": "module",
-	"description": "Type-safe FileSystem wrapper with full TypeScript support. Zero runtime dependencies.",
+	"description": "Shared types, contracts, and bridge functions for the @mikesaintsg ecosystem. Zero runtime dependencies.",
 	"keywords": [
 		"typescript",
-		"browser",
+		"types",
+		"contracts",
+		"bridge",
+		"result-pattern",
 		"type-safe",
-		"promise-based",
 		"zero-dependencies"
 	],
 	"author": "Mike Garcia",
@@ -55,7 +57,7 @@
 		"eslint": "^9.39.2",
 		"jiti": "^2.6.1",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.53.0",
+		"typescript-eslint": "^8.53.1",
 		"vite": "^7.3.1",
 		"vite-plugin-dts": "^4.5.4",
 		"vite-plugin-singlefile": "^2.3.0",