sql-ai-harness 0.0.0-stage → 0.1.0

package/dist/core/agent/agent.js

@@ -0,0 +1,323 @@
+// agent.ts
+import { dynamicTool } from "ai";
+import { z } from "zod";
+import { noopAgentObserver } from "./observability.js";
+import { getTools } from "../tools/registry.js";
+const emptyInput = z.object({}).strict();
+const schemas = {
+    list_tables: emptyInput,
+    describe_tables: z.object({
+        tables: z.array(z.string().min(1)).min(1).max(10),
+    }),
+    describe_table: z.object({
+        table: z
+            .string()
+            .min(1)
+            .describe("The exact database table name to inspect."),
+    }),
+    get_relationships: z.object({
+        table: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Optional table name. Omit to inspect all foreign-key relationships."),
+    }),
+    execute_query: z.object({
+        sql: z.string().min(1).describe("A read-only SELECT or WITH SQL query."),
+    }),
+    explain_query: z.object({
+        sql: z
+            .string()
+            .min(1)
+            .describe("A read-only SELECT or WITH SQL query to explain."),
+    }),
+};
+const DEFAULT_MAX_QUERY_ATTEMPTS = 3;
+/**
+ * Normalize insignificant SQL formatting differences while preserving
+ * the contents and case of quoted strings and identifiers.
+ */
+function normalizeSql(sql) {
+    let normalized = "";
+    let quote = null;
+    let pendingSpace = false;
+    for (let i = 0; i < sql.length; i++) {
+        const char = sql[i];
+        const next = sql[i + 1];
+        if (quote) {
+            normalized += char;
+            // Handle SQL escaped quotes, e.g. 'it''s'.
+            if (char === quote) {
+                if (next === quote) {
+                    normalized += next;
+                    i++;
+                }
+                else {
+                    quote = null;
+                }
+            }
+            else if (char === "\\" && next) {
+                normalized += next;
+                i++;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`") {
+            if (pendingSpace && normalized.length > 0) {
+                normalized += " ";
+            }
+            pendingSpace = false;
+            quote = char;
+            normalized += char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            pendingSpace = true;
+            continue;
+        }
+        if (pendingSpace && normalized.length > 0) {
+            normalized += " ";
+        }
+        pendingSpace = false;
+        normalized += char.toLowerCase();
+    }
+    return normalized.trim().replace(/;+\s*$/, "");
+}
+/**
+ * Application-level agent. Provider-specific model calls stay behind AiProvider;
+ * database access stays behind ToolContext and the tool registry.
+ */
+export class Agent {
+    provider;
+    context;
+    options;
+    constructor(provider, context, options = {}) {
+        this.provider = provider;
+        this.context = context;
+        this.options = options;
+    }
+    async ask(question) {
+        const prompt = question.trim();
+        if (!prompt)
+            throw new Error("Question is required.");
+        const runtime = {
+            relationshipsInspected: false,
+            queryAttempts: 0,
+            attemptedQueries: new Set(),
+        };
+        const relationshipResult = await this.discoverRelationships();
+        runtime.relationshipsInspected = relationshipResult.success;
+        const relationshipContext = relationshipResult.success
+            ? [
+                "",
+                "GLOBAL FOREIGN-KEY DISCOVERY RESULTS:",
+                JSON.stringify(relationshipResult.data),
+                "Use these actual relationships when constructing joins. Global relationship discovery has already been completed; do not repeat it unless more information is needed.",
+            ]
+            : [
+                "",
+                "GLOBAL FOREIGN-KEY DISCOVERY FAILED:",
+                relationshipResult.error ?? "Unknown error",
+                "Do not execute SQL until relationship discovery succeeds.",
+            ];
+        const tools = this.buildTools(runtime);
+        const result = await this.provider.generate({
+            system: [
+                "You are SQL AI Harness, a database analysis assistant.",
+                "Answer questions using the connected relational database.",
+                "Do not invent schema, columns, rows, or results.",
+                "Use schema discovery tools before writing SQL when the schema is not known.",
+                "When several tables are relevant, prefer describe_tables to multiple separate describe_table calls.",
+                "Global foreign-key discovery has already been performed before this model call. Use its results when planning joins. Call get_relationships again only when additional relationship information is needed.",
+                ...relationshipContext,
+                "Plan the query before writing SQL: identify the requested entities, relevant tables, output fields, filters, and any foreign-key path needed to connect those tables.",
+                "When the question requires data from related tables, use explicit JOINs that follow the discovered foreign-key relationships. Do not guess join columns or substitute foreign-key IDs for the related entity’s descriptive fields.",
+                "Choose result columns that answer the user’s wording. For requests to list or show people or named entities, prefer available human-readable fields such as names, usernames, or email addresses rather than returning only numeric IDs. Use IDs when the user asks for identifiers, counts, or when no descriptive fields exist.",
+                "After each query, inspect the actual result. A successful query returning zero rows is a valid result, not automatically a query failure. Report that no matching records were found when that is what the result establishes. Do not broaden filters or remove conditions merely to obtain rows.",
+                "If a query returns zero rows, retry only when you can identify a specific, evidence-based reason the query may be wrong, such as an incorrect join, column, or filter. Do not retry an unchanged query.",
+                `You may execute at most ${DEFAULT_MAX_QUERY_ATTEMPTS} SQL queries for this question. The tool enforces this limit. Once it is reached, do not call execute_query again; answer using the evidence already collected and clearly state any limitation.`,
+                ...this.responseInstructions(),
+                ...(this.options.databaseContext?.content
+                    ? [
+                        "",
+                        "The user has provided the following optional database context.",
+                        "Use it to understand the business/domain meaning of the database, but treat the live database schema and query results as authoritative for what actually exists.",
+                        "",
+                        "<DATABASE_CONTEXT>",
+                        this.options.databaseContext.content,
+                        "</DATABASE_CONTEXT>",
+                    ]
+                    : []),
+            ].join("\n"),
+            prompt,
+            tools,
+            temperature: this.options.temperature ?? 0,
+            maxSteps: this.options.maxSteps ?? 8,
+        });
+        return {
+            text: result.text,
+            steps: result.steps ?? 1,
+            toolCalls: result.toolCalls ?? 0,
+            raw: result.raw,
+        };
+    }
+    responseInstructions() {
+        switch (this.options.responseMode ?? "natural") {
+            case "technical":
+                return [
+                    "Give a concise final answer based on the actual query results.",
+                    "Use technical terminology where useful and include the SQL used when relevant.",
+                    "Do not expose hidden chain-of-thought.",
+                ];
+            case "debug":
+                return [
+                    "Give a concise final answer based on the actual query results.",
+                    "Include useful technical details such as SQL, assumptions, and relevant execution information.",
+                    "Do not expose hidden chain-of-thought.",
+                ];
+            case "natural":
+            default:
+                return [
+                    "Give a clear, direct answer in plain language suitable for a non-technical audience.",
+                    "Use business-friendly terminology and completely avoid technical jargon, database names, or raw SQL.",
+                    "Focus on practical insights and answers rather than how the data was gathered or calculated.",
+                    "Do not expose hidden chain-of-thought.",
+                ];
+        }
+    }
+    buildTools(runtime) {
+        const registered = getTools();
+        const toolSet = {};
+        for (const registeredTool of registered) {
+            const schema = schemas[registeredTool.name];
+            toolSet[registeredTool.name] = dynamicTool({
+                description: registeredTool.description,
+                inputSchema: schema,
+                // input is typed as 'unknown' — validate/cast at runtime
+                execute: async (input) => {
+                    const observer = this.options.observer ?? noopAgentObserver;
+                    const startedAt = performance.now();
+                    observer.onToolEvent({
+                        type: "tool-start",
+                        name: registeredTool.name,
+                        input,
+                    });
+                    try {
+                        let result;
+                        const isQuery = registeredTool.name === "execute_query";
+                        const queryInput = input;
+                        const sql = typeof queryInput?.sql === "string" ? queryInput.sql.trim() : "";
+                        const normalizedSql = isQuery ? normalizeSql(sql) : "";
+                        if (isQuery && !runtime.relationshipsInspected) {
+                            result = {
+                                success: false,
+                                executionAttempted: false,
+                                error: "Query planning requires global foreign-key discovery first. Call get_relationships without a table argument, then build SQL using the returned relationships where relevant.",
+                            };
+                        }
+                        else if (isQuery &&
+                            runtime.attemptedQueries.has(normalizedSql)) {
+                            result = {
+                                success: false,
+                                error: "This SQL query has already been attempted. Do not retry it unchanged. Use the previous result or error to identify a concrete correction, or provide the best supported answer.",
+                            };
+                        }
+                        else if (isQuery &&
+                            runtime.queryAttempts >= DEFAULT_MAX_QUERY_ATTEMPTS) {
+                            result = {
+                                success: false,
+                                executionAttempted: false,
+                                error: `Maximum of ${DEFAULT_MAX_QUERY_ATTEMPTS} SQL query attempts reached. Use the existing results to provide the best supported answer, and clearly state any limitation.`,
+                            };
+                        }
+                        else {
+                            if (isQuery) {
+                                // Count only queries that are actually passed to the registered tool.
+                                runtime.attemptedQueries.add(normalizedSql);
+                                runtime.queryAttempts += 1;
+                            }
+                            result = await registeredTool.execute(input, this.context);
+                            if (registeredTool.name === "get_relationships" &&
+                                result.success) {
+                                const relationshipInput = input;
+                                if (!String(relationshipInput?.table ?? "").trim()) {
+                                    runtime.relationshipsInspected = true;
+                                }
+                            }
+                        }
+                        observer.onToolEvent({
+                            type: 'tool-end',
+                            name: registeredTool.name,
+                            input,
+                            success: result.success,
+                            durationMs: Math.round(performance.now() - startedAt),
+                            data: result.success ? result.data : undefined,
+                            error: result.success ? undefined : result.error,
+                            ...(registeredTool.name === 'execute_query'
+                                ? { databaseExecutionAttempted: result.executionAttempted ?? false }
+                                : {}),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        observer.onToolEvent({
+                            type: "tool-end",
+                            name: registeredTool.name,
+                            input,
+                            success: false,
+                            durationMs: Math.round(performance.now() - startedAt),
+                            error: message,
+                            databaseExecutionAttempted: false,
+                        });
+                        throw error;
+                    }
+                },
+            });
+        }
+        return toolSet;
+    }
+    async discoverRelationships() {
+        const relationshipTool = getTools().find((tool) => tool.name === "get_relationships");
+        if (!relationshipTool) {
+            return {
+                success: false,
+                error: "The get_relationships tool is not registered.",
+            };
+        }
+        const observer = this.options.observer ?? noopAgentObserver;
+        const startedAt = performance.now();
+        const input = {};
+        observer.onToolEvent({
+            type: "tool-start",
+            name: "get_relationships",
+            input,
+        });
+        try {
+            const result = await relationshipTool.execute(input, this.context);
+            observer.onToolEvent({
+                type: "tool-end",
+                name: "get_relationships",
+                input,
+                success: result.success,
+                durationMs: Math.round(performance.now() - startedAt),
+                data: result.success ? result.data : undefined,
+                error: result.success ? undefined : result.error,
+            });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            observer.onToolEvent({
+                type: "tool-end",
+                name: "get_relationships",
+                input,
+                success: false,
+                durationMs: Math.round(performance.now() - startedAt),
+                error: message,
+            });
+            return { success: false, error: message };
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent/agent.js.map

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

package/dist/core/agent/index.d.ts

@@ -0,0 +1,4 @@
+export { Agent } from './agent.js';
+export type { AgentOptions, AgentResult } from './agent.js';
+export type { AgentObserver, AgentToolEvent } from './observability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/core/agent/index.js

@@ -0,0 +1,2 @@
+export { Agent } from './agent.js';
+//# sourceMappingURL=index.js.map

package/dist/core/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/agent/observability.d.ts

@@ -0,0 +1,19 @@
+export type AgentToolEvent = {
+    type: 'tool-start';
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool-end';
+    name: string;
+    input: unknown;
+    success: boolean;
+    durationMs: number;
+    data?: unknown;
+    error?: string;
+    databaseExecutionAttempted?: boolean;
+};
+export interface AgentObserver {
+    onToolEvent(event: AgentToolEvent): void;
+}
+export declare const noopAgentObserver: AgentObserver;
+//# sourceMappingURL=observability.d.ts.map

package/dist/core/agent/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../../src/core/agent/observability.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CAC1C;AAED,eAAO,MAAM,iBAAiB,EAAE,aAE/B,CAAC"}

package/dist/core/agent/observability.js

@@ -0,0 +1,4 @@
+export const noopAgentObserver = {
+    onToolEvent: () => undefined,
+};
+//# sourceMappingURL=observability.js.map

package/dist/core/agent/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../../../src/core/agent/observability.ts"],"names":[],"mappings":"AAsBA,MAAM,CAAC,MAAM,iBAAiB,GAAkB;IAC9C,WAAW,EAAE,GAAG,EAAE,CAAC,SAAS;CAC7B,CAAC"}

package/dist/core/tools/describe-table.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface DescribeTableInput {
+    table: string;
+}
+export declare function describeTable(input: DescribeTableInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=describe-table.d.ts.map

package/dist/core/tools/describe-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-table.d.ts","sourceRoot":"","sources":["../../../src/core/tools/describe-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAyBxB"}

package/dist/core/tools/describe-table.js

@@ -0,0 +1,25 @@
+export async function describeTable(input, context) {
+    const table = input.table.trim();
+    if (!table) {
+        return {
+            success: false,
+            error: 'Table name is required.',
+        };
+    }
+    try {
+        const schema = context.schemaCache
+            ? await context.schemaCache.describeTable(context.database, table)
+            : await context.database.describeTable(table);
+        return {
+            success: true,
+            data: schema,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : `Failed to describe table "${table}".`,
+        };
+    }
+}
+//# sourceMappingURL=describe-table.js.map

package/dist/core/tools/describe-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-table.js","sourceRoot":"","sources":["../../../src/core/tools/describe-table.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAyB,EACzB,OAAoB;IAEpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAEjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,yBAAyB;SACjC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW;YAChC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC;YAClE,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAEhD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,KAAK,IAAI;SACvF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/describe-tables.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface DescribeTablesInput {
+    tables: string[];
+}
+export declare function describeTables(input: DescribeTablesInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=describe-tables.d.ts.map

package/dist/core/tools/describe-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-tables.d.ts","sourceRoot":"","sources":["../../../src/core/tools/describe-tables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAuBxB"}

package/dist/core/tools/describe-tables.js

@@ -0,0 +1,22 @@
+export async function describeTables(input, context) {
+    const tables = [...new Set((input.tables ?? []).map((table) => table.trim()).filter(Boolean))];
+    if (tables.length === 0) {
+        return { success: false, error: 'At least one table name is required.' };
+    }
+    if (tables.length > 10) {
+        return { success: false, error: 'A maximum of 10 tables can be described at once.' };
+    }
+    try {
+        const schemas = context.schemaCache
+            ? await context.schemaCache.describeTables(context.database, tables)
+            : await Promise.all(tables.map((table) => context.database.describeTable(table)));
+        return { success: true, data: schemas };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to describe tables.',
+        };
+    }
+}
+//# sourceMappingURL=describe-tables.js.map

package/dist/core/tools/describe-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-tables.js","sourceRoot":"","sources":["../../../src/core/tools/describe-tables.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAA0B,EAC1B,OAAoB;IAEpB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/F,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;IAC3E,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kDAAkD,EAAE,CAAC;IACvF,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW;YACjC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC;YACpE,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAEpF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,4BAA4B;SAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/execute-query.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface ExecuteQueryInput {
+    sql: string;
+}
+export declare function executeQuery(input: ExecuteQueryInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=execute-query.d.ts.map

package/dist/core/tools/execute-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-query.d.ts","sourceRoot":"","sources":["../../../src/core/tools/execute-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/core/tools/execute-query.js

@@ -0,0 +1,31 @@
+import { validateSql } from '../../safety/sql-validator.js';
+export async function executeQuery(input, context) {
+    const validation = validateSql(input.sql, context.safety);
+    if (!validation.valid || !validation.sql) {
+        return {
+            success: false,
+            executionAttempted: false,
+            error: validation.reason ?? 'SQL query failed validation.',
+        };
+    }
+    try {
+        const result = await context.database.executeQuery(validation.sql, {
+            maxRows: context.safety.maxRows,
+            timeoutMs: context.safety.queryTimeoutMs,
+            maxResultBytes: context.safety.maxResultBytes,
+        });
+        return {
+            success: true,
+            executionAttempted: true,
+            data: result,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            executionAttempted: true,
+            error: error instanceof Error ? error.message : 'Failed to execute query.',
+        };
+    }
+}
+//# sourceMappingURL=execute-query.js.map

package/dist/core/tools/execute-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-query.js","sourceRoot":"","sources":["../../../src/core/tools/execute-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAM5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,OAAoB;IAEpB,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACzC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,kBAAkB,EAAE,KAAK;YACzB,KAAK,EAAE,UAAU,CAAC,MAAM,IAAI,8BAA8B;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE;YACjE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc;YACxC,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc;SAC9C,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,IAAI;YACb,kBAAkB,EAAE,IAAI;YACxB,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,kBAAkB,EAAE,IAAI;YACxB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B;SAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/explain-query.d.ts

@@ -0,0 +1,10 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface ExplainQueryInput {
+    sql: string;
+}
+/**
+ * Produces a database query plan after passing the SQL through the harness
+ * safety boundary.
+ */
+export declare function explainQuery(input: ExplainQueryInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=explain-query.d.ts.map

package/dist/core/tools/explain-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-query.d.ts","sourceRoot":"","sources":["../../../src/core/tools/explain-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/core/tools/explain-query.js

@@ -0,0 +1,34 @@
+import { validateSql } from '../../safety/sql-validator.js';
+/**
+ * Produces a database query plan after passing the SQL through the harness
+ * safety boundary.
+ */
+export async function explainQuery(input, context) {
+    const validation = validateSql(input.sql, context.safety);
+    if (!validation.valid || !validation.sql) {
+        return {
+            success: false,
+            error: validation.reason ?? 'SQL query failed validation.',
+        };
+    }
+    if (!/^(SELECT|WITH)\b/i.test(validation.sql)) {
+        return {
+            success: false,
+            error: 'Only SELECT or WITH queries can be explained by this tool.',
+        };
+    }
+    try {
+        const result = await context.database.explainQuery(validation.sql);
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to explain query.',
+        };
+    }
+}
+//# sourceMappingURL=explain-query.js.map

package/dist/core/tools/explain-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-query.js","sourceRoot":"","sources":["../../../src/core/tools/explain-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAM5D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,OAAoB;IAEpB,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACzC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,UAAU,CAAC,MAAM,IAAI,8BAA8B;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,4DAA4D;SACpE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAEnE,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B;SAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/get-relationships.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface GetRelationshipsInput {
+    table?: string;
+}
+export declare function getRelationships(input: GetRelationshipsInput | undefined, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=get-relationships.d.ts.map

package/dist/core/tools/get-relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-relationships.d.ts","sourceRoot":"","sources":["../../../src/core/tools/get-relationships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,YAAK,EACjC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/core/tools/get-relationships.js

@@ -0,0 +1,23 @@
+export async function getRelationships(input = {}, context) {
+    const table = input.table?.trim() || undefined;
+    try {
+        const relationships = table
+            ? await context.database.getRelationships(table)
+            : context.schemaCache
+                ? await context.schemaCache.getRelationships(context.database)
+                : await context.database.getRelationships();
+        return {
+            success: true,
+            data: relationships,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error
+                ? error.message
+                : 'Failed to retrieve database relationships.',
+        };
+    }
+}
+//# sourceMappingURL=get-relationships.js.map

package/dist/core/tools/get-relationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-relationships.js","sourceRoot":"","sources":["../../../src/core/tools/get-relationships.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAK,GAA0B,EAAE,EACjC,OAAoB;IAEpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,KAAK;YACzB,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,CAAC;YAChD,CAAC,CAAC,OAAO,CAAC,WAAW;gBACnB,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC9D,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAEhD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,aAAa;SACpB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK;gBAC3B,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,4CAA4C;SACjD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/index.d.ts

@@ -0,0 +1,9 @@
+export { listTables } from './list-tables.js';
+export { describeTable } from './describe-table.js';
+export { describeTables } from './describe-tables.js';
+export { getRelationships } from './get-relationships.js';
+export { executeQuery } from './execute-query.js';
+export { explainQuery } from './explain-query.js';
+export { getTool, getTools, executeTool } from './registry.js';
+export type { ToolName, RegisteredTool } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}