@hydradb/mcp 1.0.0 → 1.1.0

package/dist/descriptions.js

@@ -1,92 +1,183 @@
 /**
  * Tool descriptions for the Hydra DB MCP server.
  * Kept in a separate file for easy editing and localisation.
+ *
+ * Every canonical tool (CONTRACT §3) and every deprecated alias has an entry.
+ * Alias descriptions are prefixed with a DEPRECATED notice naming the canonical
+ * replacement so the model prefers the new name.
  */
-import { TOOL_NAMES } from "./tool-names.js";
+import { ALIAS_REPLACEMENTS, TOOL_NAMES } from "./tool-names.js";
+// Shared parameter blurbs, reused across canonical tools and their aliases.
+const PARAM = {
+    query: "The search query to find relevant memories",
+    max_results: "Maximum number of memory chunks to return (1-50, default: 10)",
+    mode: "Recall mode: 'fast' for quick semantic search, 'thinking' for deeper personalised recall with graph traversal (default: 'thinking')",
+    graph_context: "Whether to include knowledge graph relations in results (default: true)",
+    text: "The information to store in memory",
+    title: "Optional title for the memory entry (default: 'MCP Memory')",
+    source_id: "Optional source identifier to group related memories together. You can use this as " +
+        "your session ID or any other unique identifier for a conversation",
+    infer: "Whether Hydra DB should extract insights and build knowledge graph from this text (default: true)",
+    is_markdown: "Whether the text is in markdown format (default: false)",
+    turns: "Array of conversation turns, each with a 'user' and 'assistant' field",
+    user_name: "Optional name of the user for personalisation (default: 'User')",
+    kind: "Which context family to list: 'memory' or 'knowledge' (default: 'memory')",
+    source_ids: "Optional array of specific source IDs to filter by. If omitted, lists all sources.",
+    fetch_source_id: "The source ID to fetch content for",
+    fetch_mode: "Fetch mode: 'content' for text, 'url' for presigned URL, 'both' for both (default: 'content')",
+    delete_id: "The ID of the item to delete",
+    delete_kind: "Which context family the ID belongs to: 'memory' or 'knowledge' (default: 'memory')",
+    memory_id: "The ID of the memory to delete",
+};
+function deprecated(alias, body) {
+    return `DEPRECATED — use \`${ALIAS_REPLACEMENTS[alias]}\` instead. ${body}`;
+}
+const SEARCH_BODY = "Search through Hydra DB State-of-the-art agentic memories. Returns relevant chunks with " +
+    "graph-enriched context including entity paths and knowledge graph relations. " +
+    "Use this to find previously stored information, past conversations, user preferences, " +
+    "or any knowledge that has been ingested into Hydra DB memory. " +
+    "Supports both fast semantic search and deeper thinking mode with graph traversal.";
+const STORE_BODY = "Save important information to Hydra DB State-of-the-art agentic memory. Use this to persist " +
+    "facts, preferences, decisions, notes, or any text the user wants remembered across " +
+    "sessions. Hydra DB automatically extracts insights, preferences, and builds a knowledge " +
+    "graph from the stored content. Supports plain text and markdown.";
+const CONVERSATION_BODY = "Ingest one or more user-assistant conversation turns into Hydra DB memory. " +
+    "Hydra DB will extract insights, preferences, and knowledge graph entities from the " +
+    "conversation. Use this to store conversation history so it can be recalled later. " +
+    "Each turn is a pair of user message and assistant response.";
+const LIST_MEMORIES_BODY = "List all stored user memories in Hydra DB. Returns memory IDs and their content. " +
+    "Use this to browse what has been stored, verify memories exist, or find memory IDs " +
+    "for deletion.";
+const LIST_SOURCES_BODY = "List all ingested sources in Hydra DB memory. Returns source IDs, titles, types, " +
+    "and metadata. Use this to see what data sources have been ingested and to find " +
+    "source IDs for fetching content.";
+const INSPECT_BODY = "Fetch the full content of a specific source by its source ID from Hydra DB. " +
+    "Returns the original text content that was ingested. Use this to retrieve " +
+    "the complete content of a previously stored source.";
 export const TOOL_DESCRIPTIONS = {
+    // --- Canonical tools (CONTRACT §3) ---
+    [TOOL_NAMES.QUERY]: {
+        title: "Query Hydra DB",
+        description: SEARCH_BODY,
+        params: {
+            query: PARAM.query,
+            max_results: PARAM.max_results,
+            mode: PARAM.mode,
+            graph_context: PARAM.graph_context,
+        },
+    },
+    [TOOL_NAMES.INGEST]: {
+        title: "Ingest into Hydra DB",
+        description: STORE_BODY +
+            " To ingest a conversation instead of a single note, provide `turns` " +
+            "(user/assistant pairs) rather than `text`.",
+        params: {
+            text: PARAM.text,
+            title: PARAM.title,
+            source_id: PARAM.source_id,
+            infer: PARAM.infer,
+            is_markdown: PARAM.is_markdown,
+            turns: "Optional conversation turns to ingest instead of `text`; each has a 'user' and 'assistant' field",
+            user_name: PARAM.user_name,
+        },
+    },
+    [TOOL_NAMES.LIST]: {
+        title: "List Hydra DB Context",
+        description: "List stored memories or ingested knowledge sources in Hydra DB. " +
+            "Use `kind` to choose which family to browse.",
+        params: {
+            kind: PARAM.kind,
+            source_ids: PARAM.source_ids,
+        },
+    },
+    [TOOL_NAMES.INSPECT]: {
+        title: "Inspect Hydra DB Source",
+        description: INSPECT_BODY,
+        params: {
+            source_id: PARAM.fetch_source_id,
+            mode: PARAM.fetch_mode,
+        },
+    },
+    [TOOL_NAMES.DELETE]: {
+        title: "Delete from Hydra DB",
+        description: "Delete a memory or knowledge source from Hydra DB by its ID. " +
+            "Use `kind` to select which family the ID belongs to. This action is irreversible.",
+        params: {
+            id: PARAM.delete_id,
+            kind: PARAM.delete_kind,
+        },
+    },
+    // --- Deprecated aliases ---
     [TOOL_NAMES.SEARCH]: {
-        title: "Search Hydra DB Memory",
-        description: "Search through Hydra DB State-of-the-art agentic memories. Returns relevant chunks with " +
-            "graph-enriched context including entity paths and knowledge graph relations. " +
-            "Use this to find previously stored information, past conversations, user preferences, " +
-            "or any knowledge that has been ingested into Hydra DB memory. " +
-            "Supports both fast semantic search and deeper thinking mode with graph traversal.",
+        title: "Search Hydra DB Memory (deprecated)",
+        description: deprecated(TOOL_NAMES.SEARCH, SEARCH_BODY),
         params: {
-            query: "The search query to find relevant memories",
-            max_results: "Maximum number of memory chunks to return (1-50, default: 10)",
-            mode: "Recall mode: 'fast' for quick semantic search, 'thinking' for deeper personalised recall with graph traversal (default: 'thinking')",
-            graph_context: "Whether to include knowledge graph relations in results (default: true)",
+            query: PARAM.query,
+            max_results: PARAM.max_results,
+            mode: PARAM.mode,
+            graph_context: PARAM.graph_context,
         },
     },
     [TOOL_NAMES.STORE]: {
-        title: "Store to Hydra DB Memory",
-        description: "Save important information to Hydra DB State-of-the-art agentic memory. Use this to persist " +
-            "facts, preferences, decisions, notes, or any text the user wants remembered across " +
-            "sessions. Hydra DB automatically extracts insights, preferences, and builds a knowledge " +
-            "graph from the stored content. Supports plain text and markdown.",
+        title: "Store to Hydra DB Memory (deprecated)",
+        description: deprecated(TOOL_NAMES.STORE, STORE_BODY),
         params: {
-            text: "The information to store in memory",
-            title: "Optional title for the memory entry (default: 'MCP Memory')",
-            source_id: "Optional source identifier to group related memories together. You can use this as " +
-                "your session ID or any other unique identifier for a conversation",
-            infer: "Whether Hydra DB should extract insights and build knowledge graph from this text (default: true)",
-            is_markdown: "Whether the text is in markdown format (default: false)",
+            text: PARAM.text,
+            title: PARAM.title,
+            source_id: PARAM.source_id,
+            infer: PARAM.infer,
+            is_markdown: PARAM.is_markdown,
         },
     },
     [TOOL_NAMES.INGEST_CONVERSATION]: {
-        title: "Ingest Conversation",
-        description: "Ingest one or more user-assistant conversation turns into Hydra DB memory. " +
-            "Hydra DB will extract insights, preferences, and knowledge graph entities from the " +
-            "conversation. Use this to store conversation history so it can be recalled later. " +
-            "Each turn is a pair of user message and assistant response.",
+        title: "Ingest Conversation (deprecated)",
+        description: deprecated(TOOL_NAMES.INGEST_CONVERSATION, CONVERSATION_BODY),
         params: {
-            turns: "Array of conversation turns, each with a 'user' and 'assistant' field",
+            turns: PARAM.turns,
             source_id: "Source identifier to group all turns from the same session together",
-            user_name: "Optional name of the user for personalisation (default: 'User')",
+            user_name: PARAM.user_name,
         },
     },
     [TOOL_NAMES.LIST_MEMORIES]: {
-        title: "List Memories",
-        description: "List all stored user memories in Hydra DB. Returns memory IDs and their content. " +
-            "Use this to browse what has been stored, verify memories exist, or find memory IDs " +
-            "for deletion.",
+        title: "List Memories (deprecated)",
+        description: deprecated(TOOL_NAMES.LIST_MEMORIES, LIST_MEMORIES_BODY),
     },
-    [TOOL_NAMES.DELETE_MEMORY]: {
-        title: "Delete Memory",
-        description: "Delete a specific user memory from Hydra DB by its memory ID. " +
-            `Use ${TOOL_NAMES.LIST_MEMORIES} first to find the memory ID you want to delete. ` +
-            "This action is irreversible.",
+    [TOOL_NAMES.LIST_SOURCES]: {
+        title: "List Sources (deprecated)",
+        description: deprecated(TOOL_NAMES.LIST_SOURCES, LIST_SOURCES_BODY),
         params: {
-            memory_id: "The ID of the memory to delete",
+            source_ids: PARAM.source_ids,
         },
     },
     [TOOL_NAMES.FETCH_CONTENT]: {
-        title: "Fetch Source Content",
-        description: "Fetch the full content of a specific source by its source ID from Hydra DB. " +
-            "Returns the original text content that was ingested. Use this to retrieve " +
-            "the complete content of a previously stored source.",
+        title: "Fetch Source Content (deprecated)",
+        description: deprecated(TOOL_NAMES.FETCH_CONTENT, INSPECT_BODY),
         params: {
-            source_id: "The source ID to fetch content for",
-            mode: "Fetch mode: 'content' for text, 'url' for presigned URL, 'both' for both (default: 'content')",
+            source_id: PARAM.fetch_source_id,
+            mode: PARAM.fetch_mode,
         },
     },
-    [TOOL_NAMES.LIST_SOURCES]: {
-        title: "List Sources",
-        description: "List all ingested sources in Hydra DB memory. Returns source IDs, titles, types, " +
-            "and metadata. Use this to see what data sources have been ingested and to find " +
-            "source IDs for fetching content.",
+    [TOOL_NAMES.DELETE_MEMORY]: {
+        title: "Delete Memory (deprecated)",
+        description: deprecated(TOOL_NAMES.DELETE_MEMORY, "Delete a specific user memory from Hydra DB by its memory ID. This action is irreversible."),
         params: {
-            source_ids: "Optional array of specific source IDs to filter by. If omitted, lists all sources.",
+            memory_id: PARAM.memory_id,
         },
     },
 };
 export const SERVER_INSTRUCTIONS = "Hydra DB MCP server for State-of-the-art agentic memory management. " +
-    `Use ${TOOL_NAMES.SEARCH} to find relevant memories and knowledge graph context. ` +
-    `Use ${TOOL_NAMES.STORE} to save important information for future recall. ` +
-    `Use ${TOOL_NAMES.INGEST_CONVERSATION} to store conversation history. ` +
-    `Use ${TOOL_NAMES.LIST_MEMORIES} to browse stored memories. ` +
-    `Use ${TOOL_NAMES.DELETE_MEMORY} to remove specific memories. ` +
-    `Use ${TOOL_NAMES.FETCH_CONTENT} to retrieve full source content. ` +
-    `Use ${TOOL_NAMES.LIST_SOURCES} to see all ingested data sources. ` +
+    `Use ${TOOL_NAMES.QUERY} to find relevant memories and knowledge graph context. ` +
+    `Use ${TOOL_NAMES.INGEST} to save information (a note via 'text', or a conversation via 'turns'). ` +
+    `Use ${TOOL_NAMES.LIST} to browse stored memories or knowledge sources. ` +
+    `Use ${TOOL_NAMES.INSPECT} to retrieve the full content of a source. ` +
+    `Use ${TOOL_NAMES.DELETE} to remove a memory or knowledge source. ` +
+    "Deprecated aliases remain available for backward compatibility but should not be used in new integrations: " +
+    `${TOOL_NAMES.SEARCH} → ${TOOL_NAMES.QUERY}, ` +
+    `${TOOL_NAMES.STORE} → ${TOOL_NAMES.INGEST}, ` +
+    `${TOOL_NAMES.INGEST_CONVERSATION} → ${TOOL_NAMES.INGEST}, ` +
+    `${TOOL_NAMES.LIST_MEMORIES} → ${TOOL_NAMES.LIST}, ` +
+    `${TOOL_NAMES.LIST_SOURCES} → ${TOOL_NAMES.LIST}, ` +
+    `${TOOL_NAMES.FETCH_CONTENT} → ${TOOL_NAMES.INSPECT}, ` +
+    `${TOOL_NAMES.DELETE_MEMORY} → ${TOOL_NAMES.DELETE}. ` +
     "All tools require a valid Hydra DB API key and tenant ID configured via environment variables.";
 //# sourceMappingURL=descriptions.js.map

package/dist/descriptions.js.map

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

package/dist/hydra/client.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Thin, hand-owned wrapper around the generated `@hydradb/sdk`.
+ *
+ * This is the single place the MCP server (and, later, the OpenClaw port of
+ * this same pattern) touches the SDK. It:
+ *   - owns the SDK at an EXACT pin (see package.json `"@hydradb/sdk": "2.1.2"`),
+ *   - exposes the canonical vocabulary from CONTRACT.md §2 (camelCase in TS),
+ *   - injects scope (`database` / `collection`) that the SDK reads from no env,
+ *   - unwraps the `HandlerEnvelope` by shape (see ./envelope),
+ *   - translates SDK errors into a stable host error (see ./errors).
+ *
+ * Injected DEFAULTS (alpha, recency bias, mode, upsert, ingest instructions)
+ * are deliberately NOT baked in here — per CONTRACT §2 rule 5 those are host
+ * behaviour and are supplied by the caller, so this wrapper stays portable.
+ */
+import { HydraDBClient } from "@hydradb/sdk";
+import type { HydraDB as SDK } from "@hydradb/sdk";
+export type ContextKind = "memory" | "knowledge";
+export interface HydraConfig {
+    /** Bearer token (the HydraDB API key). */
+    token: string;
+    /** Database scope (canonical name for the tenant). */
+    database: string;
+    /** Collection scope (canonical name for the sub-tenant). */
+    collection?: string;
+    /** Optional base URL override; defaults to the SDK's environment. */
+    baseUrl?: string;
+}
+export interface QueryParams {
+    query: string;
+    kind?: ContextKind;
+    operator?: "or" | "and" | "phrase";
+    maxResults?: number;
+    mode?: "fast" | "thinking" | "auto";
+    graphContext?: boolean;
+    alpha?: number;
+    recencyBias?: number;
+    /** Per-call collection override. */
+    collection?: string;
+}
+export interface ConversationTurn {
+    user: string;
+    assistant: string;
+}
+export interface IngestParams {
+    kind: ContextKind;
+    /** Free text to ingest (memory note or knowledge document body). */
+    text?: string;
+    /** Conversation turns to ingest as a memory. */
+    pairs?: ConversationTurn[];
+    title?: string;
+    sourceId?: string;
+    userName?: string;
+    infer?: boolean;
+    isMarkdown?: boolean;
+    /** Passed through only when `infer` is truthy (host-owned default text). */
+    customInstructions?: string;
+    upsert?: boolean;
+    /** Filename to attach when ingesting knowledge text as a document. */
+    filename?: string;
+    collection?: string;
+}
+export interface ListParams {
+    kind?: ContextKind;
+    ids?: string[];
+    page?: number;
+    pageSize?: number;
+    collection?: string;
+}
+export interface InspectParams {
+    id: string;
+    mode?: string;
+    expirySeconds?: number;
+    collection?: string;
+}
+export interface IngestionStatusParams {
+    ids: string | string[];
+    collection?: string;
+}
+export interface RelationsParams {
+    id?: string;
+    kind?: ContextKind;
+    limit?: number;
+    cursor?: number;
+    collection?: string;
+}
+export interface DeleteParams {
+    ids: string[];
+    kind: ContextKind;
+    collection?: string;
+}
+export interface CreateDatabaseParams {
+    database: string;
+    databaseMetadataSchema?: SDK.TenantsCustomPropertyDefinition[];
+    embeddingsDimension?: number;
+}
+type ScopeFields = {
+    database: string;
+    collection?: string;
+};
+declare abstract class Resource {
+    protected readonly sdk: HydraDBClient;
+    private readonly database;
+    private readonly collection?;
+    protected constructor(sdk: HydraDBClient, database: string, collection?: string | undefined);
+    protected scope(override?: string): ScopeFields;
+    protected call<T>(path: string, fn: () => Promise<unknown>): Promise<T>;
+}
+export declare class ContextResource extends Resource {
+    constructor(sdk: HydraDBClient, database: string, collection?: string);
+    /** The single retrieval entry point (SDK `client.query`). */
+    query(params: QueryParams): Promise<SDK.SearchV2RetrievalResult>;
+    /** Ingest a memory or knowledge item (SDK `context.ingest`, multipart). */
+    ingest(params: IngestParams): Promise<SDK.IngestionV2SourceUploadResponse>;
+    /** List memories or knowledge sources (SDK `context.list`). */
+    list(params?: ListParams): Promise<SDK.ListV2SourceListResponse>;
+    /** Fetch a source's content (SDK `context.inspect`; was "fetch content"). */
+    inspect(params: InspectParams): Promise<SDK.FetchV2SourceFetchResponse>;
+    /** Per-source indexing progress (SDK `context.status`). */
+    ingestionStatus(params: IngestionStatusParams): Promise<SDK.IngestionV2BatchProcessingStatus>;
+    /** Knowledge-graph relations (SDK `context.relations`). */
+    relations(params?: RelationsParams): Promise<SDK.GraphGraphRelationsResponse>;
+    /** Delete memories or knowledge sources (SDK `context.delete`). */
+    delete(params: DeleteParams): Promise<SDK.SourcesMemoryDeleteResponse>;
+}
+export declare class DatabasesResource extends Resource {
+    constructor(sdk: HydraDBClient, database: string, collection?: string);
+    create(params: CreateDatabaseParams): Promise<SDK.TenantsTenantCreateAcceptedResponse>;
+    delete(database: string): Promise<SDK.TenantsTenantDeleteResponse>;
+    list(): Promise<SDK.TenantsTenantIdsResponse>;
+    collections(database: string): Promise<SDK.TenantsSubTenantIdsResponse>;
+    stats(database: string): Promise<SDK.TenantsTenantStatsResponse>;
+    /** Infra provisioning readiness — renamed away from `status` (SDK `databases.status`). */
+    readiness(database: string): Promise<SDK.TenantsInfraStatusResponseV2>;
+}
+/**
+ * The canonical HydraDB client surface. Construct once per process from config;
+ * pass an existing `HydraDBClient` as the second argument to inject a mocked
+ * SDK transport (used by the conformance runner).
+ */
+export declare class HydraDB {
+    readonly context: ContextResource;
+    readonly databases: DatabasesResource;
+    constructor(config: HydraConfig, sdk?: HydraDBClient);
+}
+export {};

package/dist/hydra/client.js

@@ -0,0 +1,197 @@
+/**
+ * Thin, hand-owned wrapper around the generated `@hydradb/sdk`.
+ *
+ * This is the single place the MCP server (and, later, the OpenClaw port of
+ * this same pattern) touches the SDK. It:
+ *   - owns the SDK at an EXACT pin (see package.json `"@hydradb/sdk": "2.1.2"`),
+ *   - exposes the canonical vocabulary from CONTRACT.md §2 (camelCase in TS),
+ *   - injects scope (`database` / `collection`) that the SDK reads from no env,
+ *   - unwraps the `HandlerEnvelope` by shape (see ./envelope),
+ *   - translates SDK errors into a stable host error (see ./errors).
+ *
+ * Injected DEFAULTS (alpha, recency bias, mode, upsert, ingest instructions)
+ * are deliberately NOT baked in here — per CONTRACT §2 rule 5 those are host
+ * behaviour and are supplied by the caller, so this wrapper stays portable.
+ */
+import { Buffer } from "node:buffer";
+import { HydraDBClient } from "@hydradb/sdk";
+import { unwrap } from "./envelope.js";
+import { translateError } from "./errors.js";
+function kindToType(kind) {
+    return kind;
+}
+class Resource {
+    constructor(sdk, database, collection) {
+        this.sdk = sdk;
+        this.database = database;
+        this.collection = collection;
+    }
+    scope(override) {
+        const collection = override ?? this.collection;
+        return collection != null
+            ? { database: this.database, collection }
+            : { database: this.database };
+    }
+    async call(path, fn) {
+        try {
+            return unwrap(await fn());
+        }
+        catch (err) {
+            throw translateError(path, err);
+        }
+    }
+}
+export class ContextResource extends Resource {
+    constructor(sdk, database, collection) {
+        super(sdk, database, collection);
+    }
+    /** The single retrieval entry point (SDK `client.query`). */
+    query(params) {
+        return this.call("/query", () => this.sdk.query({
+            ...this.scope(params.collection),
+            query: params.query,
+            type: kindToType(params.kind),
+            operator: params.operator,
+            maxResults: params.maxResults,
+            mode: params.mode,
+            graphContext: params.graphContext,
+            alpha: params.alpha,
+            recencyBias: params.recencyBias,
+        }));
+    }
+    /** Ingest a memory or knowledge item (SDK `context.ingest`, multipart). */
+    ingest(params) {
+        const request = {
+            ...this.scope(params.collection),
+            type: kindToType(params.kind),
+        };
+        if (params.upsert != null) {
+            request.upsert = String(params.upsert);
+        }
+        if (params.kind === "memory") {
+            const infer = params.infer ?? true;
+            const item = {};
+            if (params.pairs != null)
+                item.user_assistant_pairs = params.pairs;
+            if (params.text != null)
+                item.text = params.text;
+            item.infer = infer;
+            item.is_markdown = params.isMarkdown ?? false;
+            // Preserve the v1 omission behaviour: custom_instructions is only
+            // attached when inference is enabled.
+            if (infer && params.customInstructions != null) {
+                item.custom_instructions = params.customInstructions;
+            }
+            if (params.sourceId != null)
+                item.source_id = params.sourceId;
+            if (params.title != null)
+                item.title = params.title;
+            if (params.userName != null)
+                item.user_name = params.userName;
+            request.memories = JSON.stringify([item]);
+        }
+        else {
+            // Knowledge is multipart with the document as a file part — never the
+            // `app_knowledge` JSON field (guards the DX-G-002 class of bug).
+            if (params.text != null) {
+                request.documents = {
+                    data: Buffer.from(params.text, "utf-8"),
+                    // The title rides on the filename; the server's
+                    // document_metadata does not accept a `title` key.
+                    filename: params.filename ?? `${params.title ?? "document"}.md`,
+                    contentType: "text/markdown",
+                };
+            }
+        }
+        return this.call("/context/ingest", () => this.sdk.context.ingest(request));
+    }
+    /** List memories or knowledge sources (SDK `context.list`). */
+    list(params = {}) {
+        return this.call("/context/list", () => this.sdk.context.list({
+            ...this.scope(params.collection),
+            type: kindToType(params.kind),
+            ids: params.ids,
+            page: params.page,
+            pageSize: params.pageSize,
+        }));
+    }
+    /** Fetch a source's content (SDK `context.inspect`; was "fetch content"). */
+    inspect(params) {
+        return this.call("/context/inspect", () => this.sdk.context.inspect({
+            ...this.scope(params.collection),
+            id: params.id,
+            mode: params.mode,
+            expirySeconds: params.expirySeconds,
+        }));
+    }
+    /** Per-source indexing progress (SDK `context.status`). */
+    ingestionStatus(params) {
+        return this.call("/context/status", () => this.sdk.context.status({
+            ...this.scope(params.collection),
+            ids: params.ids,
+        }));
+    }
+    /** Knowledge-graph relations (SDK `context.relations`). */
+    relations(params = {}) {
+        return this.call("/context/relations", () => this.sdk.context.relations({
+            ...this.scope(params.collection),
+            id: params.id,
+            type: kindToType(params.kind),
+            limit: params.limit,
+            cursor: params.cursor,
+        }));
+    }
+    /** Delete memories or knowledge sources (SDK `context.delete`). */
+    delete(params) {
+        return this.call("/context", () => this.sdk.context.delete({
+            ...this.scope(params.collection),
+            ids: params.ids,
+            type: kindToType(params.kind),
+        }));
+    }
+}
+export class DatabasesResource extends Resource {
+    constructor(sdk, database, collection) {
+        super(sdk, database, collection);
+    }
+    create(params) {
+        return this.call("/databases", () => this.sdk.databases.create({
+            database: params.database,
+            databaseMetadataSchema: params.databaseMetadataSchema,
+            embeddingsDimension: params.embeddingsDimension,
+        }));
+    }
+    delete(database) {
+        return this.call("/databases", () => this.sdk.databases.delete({ database }));
+    }
+    list() {
+        return this.call("/databases", () => this.sdk.databases.list());
+    }
+    collections(database) {
+        return this.call("/databases/collections", () => this.sdk.databases.collections({ database }));
+    }
+    stats(database) {
+        return this.call("/databases/stats", () => this.sdk.databases.stats({ database }));
+    }
+    /** Infra provisioning readiness — renamed away from `status` (SDK `databases.status`). */
+    readiness(database) {
+        return this.call("/databases/status", () => this.sdk.databases.status({ database }));
+    }
+}
+/**
+ * The canonical HydraDB client surface. Construct once per process from config;
+ * pass an existing `HydraDBClient` as the second argument to inject a mocked
+ * SDK transport (used by the conformance runner).
+ */
+export class HydraDB {
+    constructor(config, sdk) {
+        const client = sdk ??
+            new HydraDBClient({
+                token: config.token,
+                ...(config.baseUrl != null ? { baseUrl: config.baseUrl } : {}),
+            });
+        this.context = new ContextResource(client, config.database, config.collection);
+        this.databases = new DatabasesResource(client, config.database, config.collection);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/hydra/client.js.map

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

package/dist/hydra/envelope.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HandlerEnvelope unwrapping.
+ *
+ * Most `@hydradb/sdk` methods resolve to a `HandlerEnvelope{ data, success, meta,
+ * error }` and we want the inner `data`. But not every method is enveloped
+ * (`databases.updateMetadataSchema` and most `connectors.*` return bare
+ * objects), so we unwrap by *checking the envelope shape* rather than assuming
+ * it: a value is an envelope only if it carries a top-level `data` property
+ * alongside one of the envelope siblings (`success` / `meta` / `error`).
+ *
+ * Payload types (e.g. `FetchV2SourceFetchResponse`) may themselves carry a
+ * `success` field, but never a top-level `data`, so they are correctly left
+ * untouched when they arrive already unwrapped.
+ */
+export declare function unwrap<T>(value: unknown): T;

package/dist/hydra/envelope.js

@@ -0,0 +1,28 @@
+/**
+ * HandlerEnvelope unwrapping.
+ *
+ * Most `@hydradb/sdk` methods resolve to a `HandlerEnvelope{ data, success, meta,
+ * error }` and we want the inner `data`. But not every method is enveloped
+ * (`databases.updateMetadataSchema` and most `connectors.*` return bare
+ * objects), so we unwrap by *checking the envelope shape* rather than assuming
+ * it: a value is an envelope only if it carries a top-level `data` property
+ * alongside one of the envelope siblings (`success` / `meta` / `error`).
+ *
+ * Payload types (e.g. `FetchV2SourceFetchResponse`) may themselves carry a
+ * `success` field, but never a top-level `data`, so they are correctly left
+ * untouched when they arrive already unwrapped.
+ */
+function isEnvelope(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    if (!("data" in value))
+        return false;
+    return "success" in value || "meta" in value || "error" in value;
+}
+export function unwrap(value) {
+    if (isEnvelope(value)) {
+        return value.data;
+    }
+    return value;
+}
+//# sourceMappingURL=envelope.js.map