@darkiceinteractive/mcp-conductor 2.0.0-alpha.1 → 3.0.0-beta.2

package/dist/registry/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Tool Registry — authoritative catalog of all backend MCP tools with
+ * auto-generated TypeScript declarations, ajv-based input validation,
+ * snapshot persistence, and hot-reload change events.
+ *
+ * Every v3 agent imports from this module. Do not change the public API
+ * without coordinating with all agents.
+ *
+ * @module registry
+ */
+export type { RegistryEventType, RegistryEvent } from './events.js';
+export { ToolRegistry } from './registry.js';
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    enum?: unknown[];
+    items?: JsonSchema | JsonSchema[];
+    additionalProperties?: boolean | JsonSchema;
+    description?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    not?: JsonSchema;
+    if?: JsonSchema;
+    then?: JsonSchema;
+    else?: JsonSchema;
+    const?: unknown;
+    format?: string;
+    default?: unknown;
+    title?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    nullable?: boolean;
+}
+/**
+ * Per-tool reliability overrides. Populated fully by Phase 3 (Agent C).
+ * Defined here so Phase 1 ToolDefinition can reference it without circular deps.
+ */
+export interface ReliabilityProfile {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+    retryMaxDelayMs?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerWindowMs?: number;
+    circuitBreakerMinCalls?: number;
+    halfOpenProbeIntervalMs?: number;
+}
+/**
+ * A single tool in the registry catalog.
+ *
+ * Core fields mirror the MCP `tools/list` response.
+ * Conductor-extension fields are optional and opt-in.
+ *
+ * Plan amendments (consolidated plan §3 Part B):
+ * - `routing`  — for X1 passthrough adapter (Agent H)
+ * - `redact`   — for X4 PII tokenization (Agent J)
+ * - `examples` — Anthropic Tool Use Examples pattern; emitted as @example JSDoc
+ */
+export interface ToolDefinition {
+    /** Backend server name (matches key in ~/.mcp-conductor.json) */
+    server: string;
+    /** Tool name as reported by the backend */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for the tool's input parameters */
+    inputSchema: JsonSchema;
+    /** JSON Schema for the tool's output (optional; not all servers provide this) */
+    outputSchema?: JsonSchema;
+    /** Estimated call cost; used by cache policy and observability */
+    cost?: 'low' | 'medium' | 'high';
+    /** Whether this tool's results are safe to cache */
+    cacheable?: boolean;
+    /** Cache TTL in milliseconds (requires cacheable: true) */
+    cacheTtl?: number;
+    /** Per-tool reliability overrides (Phase 3) */
+    reliability?: ReliabilityProfile;
+    /**
+     * Execution routing decision.
+     * - `execute_code` (default) — route through the Deno sandbox
+     * - `passthrough`            — expose as a first-class MCP tool (X1 / Agent H)
+     * - `hidden`                 — suppress from Claude's tool list
+     */
+    routing?: 'passthrough' | 'execute_code' | 'hidden';
+    /**
+     * PII redaction config applied to this tool's response before it enters
+     * the sandbox or Claude's context. (X4 — Agent J)
+     */
+    redact?: {
+        response?: Array<'email' | 'phone' | 'ssn' | 'credit_card' | string>;
+    };
+    /**
+     * Worked examples. Emitted as `@example` JSDoc blocks in generated .d.ts
+     * so both the sandbox TS LSP and Claude see concrete usage without extra
+     * round-trips. (Anthropic Tool Use Examples pattern)
+     */
+    examples?: Array<{
+        args: unknown;
+        result: unknown;
+        description?: string;
+    }>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Minimal interface that ToolRegistry needs from the backend connection layer.
+ * MCPHub satisfies this interface; tests can pass a lightweight mock.
+ */
+export interface BackendBridge {
+    /** Returns names of all currently-known servers and their connection status */
+    listServers(): Array<{
+        name: string;
+        status: string;
+        toolCount: number;
+    }>;
+    /**
+     * Returns raw tool descriptors for a server.
+     * Shape matches the MCP SDK's Tool type (name + description + inputSchema).
+     */
+    getServerTools(serverName: string): Array<{
+        name: string;
+        description?: string;
+        inputSchema?: JsonSchema;
+        outputSchema?: JsonSchema;
+    }>;
+    /** Register for server lifecycle events */
+    on(event: 'serverConnected' | 'serverDisconnected', listener: (name: string) => void): void;
+    /** Deregister server lifecycle event listeners */
+    off(event: 'serverConnected' | 'serverDisconnected', listener: (name: string) => void): void;
+}
+export interface RegistryOptions {
+    /** Backend connection layer (MCPHub or compatible mock) */
+    bridge: BackendBridge;
+    /** Path to persist/load the registry snapshot */
+    snapshotPath?: string;
+    /** Directory where generated .d.ts files are written */
+    typesDir?: string;
+    /** Run ajv validation before every backend call (default: true) */
+    validateInputs?: boolean;
+    /** Regenerate .d.ts files when a server reconnects (default: true) */
+    regenerateOnConnect?: boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.d.ts.map

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

package/dist/registry/index.js

@@ -0,0 +1,12 @@
+/**
+ * Tool Registry — authoritative catalog of all backend MCP tools with
+ * auto-generated TypeScript declarations, ajv-based input validation,
+ * snapshot persistence, and hot-reload change events.
+ *
+ * Every v3 agent imports from this module. Do not change the public API
+ * without coordinating with all agents.
+ *
+ * @module registry
+ */
+export { ToolRegistry } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/registry/registry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * ToolRegistry — authoritative catalog of backend MCP tools.
+ *
+ * Responsibilities:
+ * - Populate the catalog from all connected backends (`refresh()`)
+ * - Validate tool call arguments before they hit the backend (`validateInput()`)
+ * - Generate TypeScript declarations for sandbox preload (`generateTypes()`,
+ *   `writeTypesToDir()`)
+ * - Persist and restore the catalog across restarts (`saveSnapshot()`,
+ *   `loadSnapshot()`)
+ * - Emit change events on hot-reload (`watch()`)
+ * - Allow out-of-band annotation of conductor-extension metadata (`annotate()`)
+ *
+ * @module registry/registry
+ */
+import type { ToolDefinition, ValidationResult, RegistryOptions } from './index.js';
+import type { RegistryEvent } from './events.js';
+export declare class ToolRegistry {
+    private catalog;
+    private emitter;
+    private options;
+    /** Stable catalog key: `<server>/<name>` */
+    private static key;
+    constructor(options: RegistryOptions);
+    /**
+     * Populate the catalog from all currently-connected backends.
+     * Errors from individual backends are logged and skipped — the registry
+     * always ends in a consistent state.
+     * Returns the full catalog after refresh.
+     */
+    refresh(): Promise<ToolDefinition[]>;
+    /**
+     * Refresh a single server's tools, diffing against the current catalog
+     * and emitting per-tool change events.
+     */
+    private refreshServer;
+    private emit;
+    /** Look up a single tool. Returns null if not found. */
+    getTool(server: string, name: string): ToolDefinition | null;
+    /** All tools across all servers as a flat array. */
+    getAllTools(): ToolDefinition[];
+    /** Tools for a specific server. */
+    getServerTools(server: string): ToolDefinition[];
+    /**
+     * Validate input args against the tool's inputSchema.
+     * Returns `{ valid: true }` for unknown tools (fail-open).
+     * When `validateInputs: false`, always returns `{ valid: true }`.
+     */
+    validateInput(server: string, name: string, args: unknown): ValidationResult;
+    /**
+     * Generate combined TypeScript declarations for all servers as a single string.
+     * Use `writeTypesToDir()` for writing to disk.
+     */
+    generateTypes(): Promise<string>;
+    /**
+     * Write generated .d.ts and .routing.json files to `dir`.
+     * Creates `dir` if it does not exist.
+     * Returns the list of written file paths.
+     */
+    writeTypesToDir(dir: string): Promise<string[]>;
+    private uniqueServerNames;
+    /**
+     * Subscribe to registry change events.
+     * Returns an object with `unsubscribe()` for cleanup.
+     */
+    watch(callback: (event: RegistryEvent) => void): {
+        unsubscribe: () => void;
+    };
+    /**
+     * Persist the current catalog to disk.
+     * Uses `options.snapshotPath` when `path` is omitted.
+     */
+    saveSnapshot(path?: string): Promise<void>;
+    /**
+     * Load a previously saved snapshot from disk.
+     * Falls back silently when the file is missing, malformed, or version-mismatched.
+     */
+    loadSnapshot(path?: string): Promise<void>;
+    /**
+     * Update conductor-extension metadata for a tool.
+     * Annotations persist across `refresh()` calls.
+     * Calling `annotate()` for an unknown tool is a no-op (metadata will be
+     * applied the next time the tool appears via refresh).
+     */
+    annotate(server: string, name: string, metadata: Partial<ToolDefinition>): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAEhB,eAAe,EAEhB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,OAAO,CAA4B;IAE3C,4CAA4C;IAC5C,OAAO,CAAC,MAAM,CAAC,GAAG;gBAIN,OAAO,EAAE,eAAe;IA2CpC;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAY1C;;;OAGG;YACW,aAAa;IAqF3B,OAAO,CAAC,IAAI;IAQZ,wDAAwD;IACxD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI5D,oDAAoD;IACpD,WAAW,IAAI,cAAc,EAAE;IAI/B,mCAAmC;IACnC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE;IAQhD;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,gBAAgB;IAW5E;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAYtC;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQrD,OAAO,CAAC,iBAAiB;IAQzB;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE;IAS5E;;;OAGG;IACG,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD;;;OAGG;IACG,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBhD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;CAwBhF"}

package/dist/registry/registry.js

@@ -0,0 +1,294 @@
+/**
+ * ToolRegistry — authoritative catalog of backend MCP tools.
+ *
+ * Responsibilities:
+ * - Populate the catalog from all connected backends (`refresh()`)
+ * - Validate tool call arguments before they hit the backend (`validateInput()`)
+ * - Generate TypeScript declarations for sandbox preload (`generateTypes()`,
+ *   `writeTypesToDir()`)
+ * - Persist and restore the catalog across restarts (`saveSnapshot()`,
+ *   `loadSnapshot()`)
+ * - Emit change events on hot-reload (`watch()`)
+ * - Allow out-of-band annotation of conductor-extension metadata (`annotate()`)
+ *
+ * @module registry/registry
+ */
+import { logger } from '../utils/index.js';
+import { RegistryEmitter } from './events.js';
+import { validateToolInput } from './validator.js';
+import { saveSnapshot as persistSnapshot, loadSnapshot as restoreSnapshot, } from './snapshot.js';
+import { generateServerTypes, generateIndexTypes, writeTypesToDir as writeTypeFiles, } from './typegen.js';
+export class ToolRegistry {
+    catalog = new Map();
+    emitter = new RegistryEmitter();
+    options;
+    /** Stable catalog key: `<server>/<name>` */
+    static key(server, name) {
+        return `${server}/${name}`;
+    }
+    constructor(options) {
+        this.options = {
+            snapshotPath: '',
+            typesDir: '',
+            validateInputs: true,
+            regenerateOnConnect: true,
+            ...options,
+        };
+        // Wire hot-reload listeners: when a backend reconnects, re-fetch its
+        // tools, diff against the current catalog, emit change events, and
+        // optionally regenerate .d.ts files.
+        const onConnect = async (serverName) => {
+            logger.debug(`ToolRegistry: server reconnected — refreshing ${serverName}`);
+            await this.refreshServer(serverName);
+            if (this.options.regenerateOnConnect && this.options.typesDir) {
+                try {
+                    await this.writeTypesToDir(this.options.typesDir);
+                }
+                catch (err) {
+                    logger.warn(`ToolRegistry: type regeneration failed for ${serverName}`, {
+                        error: String(err),
+                    });
+                }
+            }
+        };
+        const onDisconnect = (serverName) => {
+            this.emitter.emit('change', {
+                type: 'server-disconnected',
+                server: serverName,
+                at: Date.now(),
+            });
+        };
+        this.options.bridge.on('serverConnected', onConnect);
+        this.options.bridge.on('serverDisconnected', onDisconnect);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Refresh
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Populate the catalog from all currently-connected backends.
+     * Errors from individual backends are logged and skipped — the registry
+     * always ends in a consistent state.
+     * Returns the full catalog after refresh.
+     */
+    async refresh() {
+        const servers = this.options.bridge.listServers();
+        await Promise.all(servers
+            .filter((s) => s.status === 'connected')
+            .map((s) => this.refreshServer(s.name)));
+        return this.getAllTools();
+    }
+    /**
+     * Refresh a single server's tools, diffing against the current catalog
+     * and emitting per-tool change events.
+     */
+    async refreshServer(serverName) {
+        let rawTools;
+        try {
+            rawTools = this.options.bridge.getServerTools(serverName);
+        }
+        catch (err) {
+            logger.warn(`ToolRegistry: failed to fetch tools for ${serverName}`, {
+                error: String(err),
+            });
+            return;
+        }
+        const incoming = new Map();
+        for (const raw of rawTools) {
+            const def = {
+                server: serverName,
+                name: raw.name,
+                description: raw.description ?? '',
+                inputSchema: raw.inputSchema ?? {},
+                ...(raw.outputSchema ? { outputSchema: raw.outputSchema } : {}),
+            };
+            // Preserve existing conductor-extension metadata (annotations survive refresh)
+            const existing = this.catalog.get(ToolRegistry.key(serverName, raw.name));
+            if (existing) {
+                def.cost = existing.cost;
+                def.cacheable = existing.cacheable;
+                def.cacheTtl = existing.cacheTtl;
+                def.reliability = existing.reliability;
+                def.routing = existing.routing;
+                def.redact = existing.redact;
+                def.examples = existing.examples;
+            }
+            incoming.set(ToolRegistry.key(serverName, raw.name), def);
+        }
+        // Keys currently in the catalog for this server
+        const currentKeys = new Set([...this.catalog.keys()].filter((k) => k.startsWith(`${serverName}/`)));
+        // Detect removed tools
+        for (const key of currentKeys) {
+            if (!incoming.has(key)) {
+                const before = this.catalog.get(key);
+                this.catalog.delete(key);
+                this.emit({ type: 'tool-removed', server: serverName, tool: before.name, before });
+            }
+        }
+        // Detect added / updated tools
+        for (const [key, def] of incoming) {
+            const existing = this.catalog.get(key);
+            if (!existing) {
+                this.catalog.set(key, def);
+                this.emit({ type: 'tool-added', server: serverName, tool: def.name, after: def });
+            }
+            else if (existing.description !== def.description ||
+                JSON.stringify(existing.inputSchema) !== JSON.stringify(def.inputSchema)) {
+                this.catalog.set(key, def);
+                this.emit({
+                    type: 'tool-updated',
+                    server: serverName,
+                    tool: def.name,
+                    before: existing,
+                    after: def,
+                });
+            }
+            else {
+                // No schema change — update in-place so any raw value changes land
+                this.catalog.set(key, def);
+            }
+        }
+        this.emit({ type: 'server-connected', server: serverName });
+        logger.debug(`ToolRegistry: refreshed ${serverName}`, { toolCount: incoming.size });
+    }
+    emit(event) {
+        this.emitter.emit('change', { ...event, at: Date.now() });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Lookup
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Look up a single tool. Returns null if not found. */
+    getTool(server, name) {
+        return this.catalog.get(ToolRegistry.key(server, name)) ?? null;
+    }
+    /** All tools across all servers as a flat array. */
+    getAllTools() {
+        return [...this.catalog.values()];
+    }
+    /** Tools for a specific server. */
+    getServerTools(server) {
+        return [...this.catalog.values()].filter((t) => t.server === server);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Validation
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Validate input args against the tool's inputSchema.
+     * Returns `{ valid: true }` for unknown tools (fail-open).
+     * When `validateInputs: false`, always returns `{ valid: true }`.
+     */
+    validateInput(server, name, args) {
+        if (!this.options.validateInputs) {
+            return { valid: true };
+        }
+        return validateToolInput(this.getTool(server, name), args);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Type generation
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Generate combined TypeScript declarations for all servers as a single string.
+     * Use `writeTypesToDir()` for writing to disk.
+     */
+    async generateTypes() {
+        const sections = [];
+        const names = this.uniqueServerNames();
+        for (const serverName of names) {
+            sections.push(await generateServerTypes(serverName, this.getServerTools(serverName)));
+        }
+        sections.push(generateIndexTypes(names));
+        return sections.join('\n');
+    }
+    /**
+     * Write generated .d.ts and .routing.json files to `dir`.
+     * Creates `dir` if it does not exist.
+     * Returns the list of written file paths.
+     */
+    async writeTypesToDir(dir) {
+        const toolsByServer = new Map();
+        for (const name of this.uniqueServerNames()) {
+            toolsByServer.set(name, this.getServerTools(name));
+        }
+        return writeTypeFiles(dir, toolsByServer);
+    }
+    uniqueServerNames() {
+        return [...new Set([...this.catalog.values()].map((t) => t.server))];
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Watch
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to registry change events.
+     * Returns an object with `unsubscribe()` for cleanup.
+     */
+    watch(callback) {
+        this.emitter.on('change', callback);
+        return { unsubscribe: () => this.emitter.off('change', callback) };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Snapshot persistence
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Persist the current catalog to disk.
+     * Uses `options.snapshotPath` when `path` is omitted.
+     */
+    async saveSnapshot(path) {
+        const target = path ?? this.options.snapshotPath;
+        if (!target)
+            throw new Error('ToolRegistry.saveSnapshot: no snapshotPath configured');
+        await persistSnapshot(target, this.getAllTools());
+        logger.debug(`ToolRegistry: snapshot saved to ${target}`);
+    }
+    /**
+     * Load a previously saved snapshot from disk.
+     * Falls back silently when the file is missing, malformed, or version-mismatched.
+     */
+    async loadSnapshot(path) {
+        const target = path ?? this.options.snapshotPath;
+        if (!target)
+            return;
+        const catalog = await restoreSnapshot(target);
+        if (catalog === null) {
+            logger.debug(`ToolRegistry: no valid snapshot at ${target} — will refresh from backends`);
+            return;
+        }
+        for (const def of catalog) {
+            const key = ToolRegistry.key(def.server, def.name);
+            if (!this.catalog.has(key)) {
+                this.catalog.set(key, def);
+            }
+        }
+        logger.debug(`ToolRegistry: loaded ${catalog.length} tools from snapshot at ${target}`);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Annotations
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Update conductor-extension metadata for a tool.
+     * Annotations persist across `refresh()` calls.
+     * Calling `annotate()` for an unknown tool is a no-op (metadata will be
+     * applied the next time the tool appears via refresh).
+     */
+    annotate(server, name, metadata) {
+        const key = ToolRegistry.key(server, name);
+        const existing = this.catalog.get(key);
+        if (!existing) {
+            logger.debug(`ToolRegistry.annotate: tool not yet in catalog — ${key}`);
+            return;
+        }
+        const allowed = [
+            'cost',
+            'cacheable',
+            'cacheTtl',
+            'reliability',
+            'routing',
+            'redact',
+            'examples',
+        ];
+        for (const field of allowed) {
+            if (field in metadata) {
+                existing[field] = metadata[field];
+            }
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry/registry.js.map

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

package/dist/registry/snapshot.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Disk persistence for the tool catalog.
+ *
+ * Snapshot format (JSON):
+ * {
+ *   "version": "1",
+ *   "savedAt": 1714816000000,   // epoch ms
+ *   "catalog": [ ...ToolDefinition[] ]
+ * }
+ *
+ * On load, if the `version` field is missing or does not match SNAPSHOT_VERSION,
+ * the snapshot is rejected and the caller must fall back to a live refresh.
+ *
+ * @module registry/snapshot
+ */
+import type { ToolDefinition } from './index.js';
+/** Bump this when the ToolDefinition shape changes in a breaking way. */
+export declare const SNAPSHOT_VERSION = "1";
+export interface SnapshotFile {
+    version: string;
+    savedAt: number;
+    catalog: ToolDefinition[];
+}
+/**
+ * Persist `catalog` to `path` as a formatted JSON file.
+ * Creates intermediate directories if needed.
+ * Throws on I/O error — callers should handle gracefully.
+ */
+export declare function saveSnapshot(path: string, catalog: ToolDefinition[]): Promise<void>;
+/**
+ * Load a previously saved snapshot from `path`.
+ *
+ * Returns the catalog if the file exists and the version matches.
+ * Returns `null` if:
+ * - The file does not exist
+ * - The file is not valid JSON
+ * - The version field is missing or does not match SNAPSHOT_VERSION
+ *
+ * Never throws — callers fall back to a live refresh on null.
+ */
+export declare function loadSnapshot(path: string): Promise<ToolDefinition[] | null>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/registry/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/registry/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,CA4BjF"}