sql-ai-harness 0.0.0-stage → 0.1.0

package/.env.example

@@ -0,0 +1,31 @@
+# AI provider: openrouter | groq | google | cerebras | ollama
+AI_PROVIDER=openrouter
+AI_MODEL=your-model-id
+
+# Set the key for the selected provider only.
+OPENROUTER_API_KEY=
+GROQ_API_KEY=
+GOOGLE_GENERATIVE_AI_API_KEY=
+CEREBRAS_API_KEY=
+
+# Ollama-compatible OpenAI API endpoint (used when AI_PROVIDER=ollama)
+OLLAMA_BASE_URL=http://localhost:11434/v1
+
+# Optional OpenRouter application metadata
+AI_SITE_URL=
+AI_SITE_NAME=SQL AI Harness
+
+# MySQL connection (the current CLI adapter supports MySQL)
+DB_DRIVER=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=your_database
+DB_USER=your_read_only_user
+DB_PASSWORD=
+
+# Safety and runtime limits
+SQL_MAX_ROWS=500
+SQL_QUERY_TIMEOUT_MS=10000
+SQL_MAX_RESULT_BYTES=1048576
+AGENT_MAX_STEPS=8
+SCHEMA_CACHE_TTL_MS=300000

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, NegusDev
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# SQL AI Harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Open-source, privacy-first AI integration layer for existing relational databases.
+
+## CLI and TypeScript SDK
+
+The package provides a CLI and a supported TypeScript SDK entry point. The CLI currently connects to MySQL; the SDK accepts a `DatabaseAdapter` implementation so applications can supply their own database integration.
+
+### Run from a checkout
+
+```bash
+pnpm install
+cp .env.example .env
+pnpm dev ask "List active users"
+```
+
+Configure the AI provider and database values in `.env`. Use a database account with read-only permissions. Schema information and query results may be sent to the selected AI provider as part of inference; configure the provider according to your data-handling requirements.
+
+### Build and run the packaged CLI
+
+```bash
+pnpm build
+node dist/cli.js ask "List active users"
+```
+
+After the package is published, install it globally with:
+
+```bash
+npm install --global sql-ai-harness
+sql-ai-harness ask "List active users"
+```
+
+The CLI reads configuration from environment variables and a `.env` file in the current working directory. See `.env.example` for the supported options.
+
+### Use the TypeScript SDK
+
+```ts
+import {
+  Agent,
+  MySqlAdapter,
+  createAiProvider,
+  loadConfig,
+} from "sql-ai-harness";
+
+const config = loadConfig();
+const database = new MySqlAdapter({
+  host: config.database.host,
+  port: config.database.port,
+  database: config.database.name,
+  user: config.database.user,
+  password: config.database.password,
+});
+
+const provider = createAiProvider(config.ai);
+const agent = new Agent(
+  provider,
+  { database, safety: config.safety },
+  { maxSteps: config.agent.maxSteps, responseMode: "natural" },
+);
+
+try {
+  const result = await agent.ask("List active users");
+  console.log(result.text);
+} finally {
+  await database.close();
+}
+```
+
+The SDK also exports `DatabaseAdapter`, `ToolContext`, agent result/options types, provider interfaces, observer types, and `SchemaCache`. Consumers should import from `sql-ai-harness`, not internal `src/` paths. `createAiProvider` supports the providers configured by the current project; the available database adapter in this release is MySQL.
+
+### Package development checks
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+npm pack --dry-run
+```
+
+## CLI behavior
+
+The current milestone wires the CLI, OpenRouter, the database adapter, safety layer,
+and database tools into a multi-step agent loop.
+
+### Setup
+
+```bash
+pnpm install
+cp .env.example .env
+```
+
+Configure at minimum:
+
+```env
+OPENROUTER_API_KEY=your-key
+AI_MODEL=your-openrouter-model
+DB_NAME=your_database
+DB_USER=read_only_user
+DB_PASSWORD=your_password
+```
+
+The database connection currently supports MySQL.
+
+### Ask a question
+
+```bash
+pnpm dev ask "How many students are enrolled?"
+```
+
+The agent can use:
+
+- `list_tables`
+- `describe_table`
+- `get_relationships`
+- `execute_query`
+- `explain_query`
+
+Only read-only SQL is allowed by the safety layer.
+
+### Validation
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+### Optional database context
+
+The harness works without any database context file. If you want to give the
+agent additional knowledge about the business/domain represented by your
+existing database, create a `sql-ai.md` file in the project directory.
+
+For example:
+
+```md
+# Database Context
+
+## Overview
+
+This database belongs to a school management system. It stores information
+about students, parents, teachers, classes, enrollments and payments.
+
+## Business Rules
+
+- Only active enrollments represent currently enrolled students.
+- Completed payments are considered successful payments.
+- Cancelled payments should not be included in revenue.
+```
+
+The file is optional. Without it, the harness relies on the database schema,
+relationships, query results and other available tools exactly as before.
+With it, the agent has additional user-defined business/domain knowledge.
+
+A template is included as `sql-ai.example.md`.
+
+
+## Query correctness safeguards
+
+The agent now requires a successful global foreign-key discovery call before it can execute SQL. This ensures the model has access to the database relationship map during query planning. The system instructions also require it to plan relevant tables, use explicit FK-backed joins when related entities are needed, select meaningful descriptive columns for entity-list requests, and compare query results with the original question before answering.
+
+SQL execution is capped at three attempts per question so the agent can correct an invalid or inadequate query without retrying indefinitely. These controls improve the agent's behavior, but the FK map is not yet a full SQL AST-level proof that every generated JOIN follows a declared foreign key; databases with undeclared relationships or complex SQL still need live testing.
+
+## Response modes
+
+The CLI supports three response modes:
+
+```bash
+pnpm dev ask "How much revenue did we make last month?"
+pnpm dev ask --mode technical "How much revenue did we make last month?"
+pnpm dev ask --mode debug "How much revenue did we make last month?"
+```
+
+- `natural` (default): concise, business-friendly answers without unnecessary SQL details.
+- `technical`: includes useful SQL and technical details when relevant.
+- `debug`: technical answer plus tool execution diagnostics and timings.
+
+The shorthand flags `--technical` and `--debug` are also supported.
+
+## Schema discovery and caching
+
+The agent can describe several relevant tables in one tool call using `describe_tables`,
+which avoids unnecessary sequential schema calls when a question involves multiple tables.
+
+Schema metadata is also cached in memory for five minutes by default. The cache covers
+table listings, table descriptions, and global foreign-key relationships. Query results are
+never cached. Configure the TTL with `SCHEMA_CACHE_TTL_MS`.
+
+The cache is process-local and is cleared when the CLI process exits. This keeps the
+current CLI simple while reducing repeated metadata queries during an agent run or future
+long-lived interfaces.
+
+## Evaluation and benchmarking
+
+The `evals/` directory contains the fixed benchmark dataset, runner, and saved reports used to evaluate the harness. The runner records structured tool events, database execution attempts, latency, result equivalence, and configured answer checks. See [`evals/README.md`](evals/README.md) for dataset setup and scoring details.
+
+Run the benchmark against a disposable evaluation database, using the same provider/model, configuration, database snapshot, and dataset when comparing versions:
+
+```bash
+pnpm eval -- --tag local-check
+```
+
+A passing benchmark is evidence for the tested cases, not a guarantee of correctness for every schema or question. Review the generated JSON and Markdown reports when changing query-planning, tool, or safety behavior.

package/dist/ai/factory.d.ts

@@ -0,0 +1,4 @@
+import type { AppConfig } from '../config/config.js';
+import type { AiProvider } from './provider.js';
+export declare function createAiProvider(config: AppConfig['ai']): AiProvider;
+//# sourceMappingURL=factory.d.ts.map

package/dist/ai/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/ai/factory.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,UAAU,CAwDpE"}

package/dist/ai/factory.js

@@ -0,0 +1,48 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { createGroq } from '@ai-sdk/groq';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createCerebras } from '@ai-sdk/cerebras';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { SdkAiProvider } from './sdk-provider.js';
+export function createAiProvider(config) {
+    switch (config.provider) {
+        case 'openrouter': {
+            const provider = createOpenRouter({
+                apiKey: config.apiKey,
+                ...(config.siteUrl ? { appUrl: config.siteUrl } : {}),
+                ...(config.siteName ? { appName: config.siteName } : {}),
+            });
+            return new SdkAiProvider('openrouter', provider.chat(config.model));
+        }
+        case 'groq': {
+            const provider = createGroq({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('groq', provider(config.model));
+        }
+        case 'google': {
+            const provider = createGoogleGenerativeAI({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('google', provider(config.model));
+        }
+        case 'cerebras': {
+            const provider = createCerebras({
+                apiKey: config.apiKey,
+            });
+            return new SdkAiProvider('cerebras', provider(config.model));
+        }
+        case 'ollama': {
+            const provider = createOpenAICompatible({
+                name: 'ollama',
+                baseURL: config.baseUrl ?? 'http://localhost:11434/v1',
+            });
+            return new SdkAiProvider('ollama', provider.chatModel(config.model));
+        }
+        default: {
+            const exhaustiveCheck = config.provider;
+            throw new Error(`Unsupported AI provider: ${exhaustiveCheck}`);
+        }
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/ai/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/ai/factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAInE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,UAAU,gBAAgB,CAAC,MAAuB;IACtD,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,YAAY,EAAE,CAAC;YAClB,MAAM,QAAQ,GAAG,gBAAgB,CAAC;gBAChC,MAAM,EAAE,MAAM,CAAC,MAAO;gBACtB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CACtB,YAAY,EACZ,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAC5B,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,UAAU,CAAC;gBAC1B,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3D,CAAC;QAED,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,wBAAwB,CAAC;gBACxC,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;QAED,KAAK,UAAU,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAG,cAAc,CAAC;gBAC9B,MAAM,EAAE,MAAM,CAAC,MAAO;aACvB,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/D,CAAC;QAED,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,sBAAsB,CAAC;gBACtC,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,2BAA2B;aACvD,CAAC,CAAC;YAEH,OAAO,IAAI,aAAa,CACtB,QAAQ,EACR,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CACjC,CAAC;QACJ,CAAC;QAED,SAAS,CAAC;YACR,MAAM,eAAe,GAAU,MAAM,CAAC,QAAQ,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,4BAA4B,eAAe,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/ai/provider.d.ts

@@ -0,0 +1,13 @@
+import type { ToolSet } from 'ai';
+import type { ModelProvider, ModelRequest, ModelResponse } from '../core/types/index.js';
+export type { ModelProvider, ModelRequest, ModelResponse };
+export interface AiProvider extends ModelProvider {
+    generate(request: ModelRequest & {
+        tools?: ToolSet;
+        maxSteps?: number;
+    }): Promise<ModelResponse & {
+        steps?: number;
+        toolCalls?: number;
+    }>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEzF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;AAE3D,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG;QAChG,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ"}

package/dist/ai/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":""}

package/dist/ai/sdk-provider.d.ts

@@ -0,0 +1,13 @@
+import { type LanguageModel, type ToolSet } from 'ai';
+import type { ModelRequest, ModelResponse } from '../core/types/index.js';
+import type { AiProvider } from './provider.js';
+export declare class SdkAiProvider implements AiProvider {
+    readonly name: string;
+    private readonly model;
+    constructor(name: string, model: LanguageModel);
+    generate(request: ModelRequest & {
+        tools?: ToolSet;
+        maxSteps?: number;
+    }): Promise<ModelResponse>;
+}
+//# sourceMappingURL=sdk-provider.d.ts.map

package/dist/ai/sdk-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-provider.d.ts","sourceRoot":"","sources":["../../src/ai/sdk-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,qBAAa,aAAc,YAAW,UAAU;IAE5C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFxB,YACW,IAAI,EAAE,MAAM,EACJ,KAAK,EAAE,aAAa,EACnC;IAEE,QAAQ,CACZ,OAAO,EAAE,YAAY,GAAG;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC,aAAa,CAAC,CAuBxB;CACF"}

package/dist/ai/sdk-provider.js

@@ -0,0 +1,29 @@
+import { generateText, isStepCount, } from 'ai';
+export class SdkAiProvider {
+    name;
+    model;
+    constructor(name, model) {
+        this.name = name;
+        this.model = model;
+    }
+    async generate(request) {
+        const result = await generateText({
+            model: this.model,
+            system: request.system,
+            prompt: request.prompt,
+            tools: request.tools,
+            stopWhen: request.maxSteps
+                ? isStepCount(request.maxSteps)
+                : undefined,
+            temperature: request.temperature,
+        });
+        const toolCalls = result.steps.reduce((count, step) => count + (step.toolCalls?.length ?? 0), 0);
+        return {
+            text: result.text,
+            raw: result,
+            steps: result.steps.length,
+            toolCalls,
+        };
+    }
+}
+//# sourceMappingURL=sdk-provider.js.map

package/dist/ai/sdk-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-provider.js","sourceRoot":"","sources":["../../src/ai/sdk-provider.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,WAAW,GAGZ,MAAM,IAAI,CAAC;AAKZ,MAAM,OAAO,aAAa;IAEb,IAAI;IACI,KAAK;IAFxB,YACW,IAAY,EACJ,KAAoB;oBAD5B,IAAI;qBACI,KAAK;IACrB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CACZ,OAGC;QAED,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;YAChC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBACxB,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC/B,CAAC,CAAC,SAAS;YACb,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CACnC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,EACtD,CAAC,CACF,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM;YACX,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC1B,SAAS;SACV,CAAC;IACJ,CAAC;CACF"}

package/dist/cli-observer.d.ts

@@ -0,0 +1,5 @@
+import type { AgentObserver, AgentToolEvent } from './core/agent/observability.js';
+export declare class CliAgentObserver implements AgentObserver {
+    onToolEvent(event: AgentToolEvent): void;
+}
+//# sourceMappingURL=cli-observer.d.ts.map

package/dist/cli-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-observer.d.ts","sourceRoot":"","sources":["../src/cli-observer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACf,MAAM,+BAA+B,CAAC;AA8DvC,qBAAa,gBAAiB,YAAW,aAAa;IACpD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAyCvC;CACF"}

package/dist/cli-observer.js

@@ -0,0 +1,79 @@
+import process from 'node:process';
+function formatInput(input) {
+    if (!input || typeof input !== 'object') {
+        return String(input ?? '');
+    }
+    const value = input;
+    if (typeof value.sql === 'string') {
+        return value.sql;
+    }
+    return JSON.stringify(value);
+}
+function getRowCount(data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const value = data;
+    if (typeof value.rowCount === 'number') {
+        return value.rowCount;
+    }
+    if (Array.isArray(value.rows)) {
+        return value.rows.length;
+    }
+    return undefined;
+}
+function emitStructuredEvent(event) {
+    if (process.env.SQL_AI_TRACE_JSON !== '1')
+        return;
+    if (event.type !== 'tool-end')
+        return;
+    try {
+        const json = JSON.stringify({
+            source: 'sql-ai-harness',
+            ...event,
+        }, (_key, value) => typeof value === 'bigint' ? value.toString() : value);
+        if (json) {
+            // One complete JSON object per line, on stderr.
+            console.error(json);
+        }
+    }
+    catch (error) {
+        console.error(JSON.stringify({
+            source: 'sql-ai-harness',
+            type: 'trace-serialization-error',
+            message: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+export class CliAgentObserver {
+    onToolEvent(event) {
+        // Emit the structured event before the human-readable diagnostic.
+        emitStructuredEvent(event);
+        if (event.type === 'tool-start') {
+            console.error(`\n[tool] ${event.name}`);
+            const input = formatInput(event.input);
+            if (!input)
+                return;
+            if (typeof event.input === 'object' &&
+                event.input !== null &&
+                'sql' in event.input) {
+                console.error('[sql]');
+                console.error(input);
+            }
+            else {
+                console.error(`[input] ${input}`);
+            }
+            return;
+        }
+        if (event.success) {
+            const rowCount = getRowCount(event.data);
+            const rows = rowCount === undefined
+                ? ''
+                : `, ${rowCount} row${rowCount === 1 ? '' : 's'}`;
+            console.error(`[done] ${event.name} (${event.durationMs}ms${rows})`);
+        }
+        else {
+            console.error(`[error] ${event.name} (${event.durationMs}ms): ${event.error ?? 'Unknown error'}`);
+        }
+    }
+}
+//# sourceMappingURL=cli-observer.js.map

package/dist/cli-observer.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { Agent } from './core/agent/index.js';
+import { loadConfig } from './config/config.js';
+import { MySqlAdapter } from './database/index.js';
+import { createAiProvider } from './ai/factory.js';
+import { CliAgentObserver } from './cli-observer.js';
+import { SchemaCache } from './schema/cache.js';
+import { loadDatabaseContext } from './context/db-context.js';
+import { runInit } from './commands/init.js';
+function printUsage() {
+    console.log(`Usage:
+  sql-ai-harness init [--force]
+  sql-ai-harness ask [--mode natural|technical|debug] "your question"
+
+Modes:
+  natural    Business-friendly answer (default)
+  technical  Include useful SQL and technical details
+  debug      Technical answer plus tool execution diagnostics`);
+}
+function parseAskArgs(args) {
+    let mode = 'natural';
+    const questionParts = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--mode') {
+            const value = args[++i];
+            if (value !== 'natural' && value !== 'technical' && value !== 'debug') {
+                throw new Error('Invalid response mode. Use natural, technical, or debug.');
+            }
+            mode = value;
+            continue;
+        }
+        if (arg === '--technical') {
+            mode = 'technical';
+            continue;
+        }
+        if (arg === '--debug') {
+            mode = 'debug';
+            continue;
+        }
+        questionParts.push(arg);
+    }
+    return { mode, question: questionParts.join(' ').trim() };
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (command === 'init') {
+        await runInit(args);
+        return;
+    }
+    if (command !== 'ask') {
+        printUsage();
+        process.exitCode = command ? 1 : 0;
+        return;
+    }
+    const { mode, question } = parseAskArgs(args);
+    if (!question) {
+        console.error('Error: a question is required.');
+        process.exitCode = 1;
+        return;
+    }
+    const config = loadConfig();
+    if (config.database.driver !== 'mysql') {
+        throw new Error(`Database driver "${config.database.driver}" is not implemented yet. M4 currently supports MySQL.`);
+    }
+    const database = new MySqlAdapter({
+        host: config.database.host,
+        port: config.database.port,
+        database: config.database.name,
+        user: config.database.user,
+        password: config.database.password,
+    });
+    const provider = createAiProvider(config.ai);
+    const databaseContext = await loadDatabaseContext();
+    const schemaCache = new SchemaCache({ ttlMs: config.schema.cacheTtlMs });
+    const agent = new Agent(provider, {
+        database,
+        safety: config.safety,
+        schemaCache,
+    }, {
+        maxSteps: config.agent.maxSteps,
+        observer: mode === 'debug' ? new CliAgentObserver() : undefined,
+        databaseContext,
+        responseMode: mode,
+    });
+    try {
+        const result = await agent.ask(question);
+        console.log('\n' + result.text);
+        if (mode === 'debug') {
+            console.error(`\n[agent] ${result.steps} step${result.steps === 1 ? '' : 's'}, ${result.toolCalls} tool call${result.toolCalls === 1 ? '' : 's'}`);
+        }
+    }
+    finally {
+        await database.close();
+    }
+}
+main().catch((error) => {
+    console.error(`\nError: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+export declare function runInit(args?: string[]): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA+GA,wBAAsB,OAAO,CAAC,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiHhE"}