@wrenai/genbi 0.0.1

package/dist-server/harness/tools/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Thrown when an `agent.tools[]` entry declares `source: "native"` under a
+ * name the injected native-tool registry has no factory for.
+ */
+export declare class UnknownNativeToolError extends Error {
+    constructor(name: string);
+}
+/**
+ * Thrown when an `agent.tools[]` entry declares `source: "mcp:<server>/<name>"`
+ * for a server id that has no entry in the runtime-injected `McpServerConfigMap`.
+ * This is the "server-missing" half of tool-level fail-fast — it fires before
+ * any MCP connection is attempted.
+ */
+export declare class McpServerNotConfiguredError extends Error {
+    constructor(serverId: string);
+}
+/**
+ * Thrown when a declared `mcp:<server>/<name>` tool's server connects
+ * successfully but its discovered tool set does not include `<name>`. This
+ * is the "tool-missing" half of tool-level fail-fast.
+ */
+export declare class McpToolNotExposedError extends Error {
+    constructor(serverId: string, toolName: string);
+}
+/** Thrown when an `agent.tools[]` entry's `source` is not `"native"` or `"mcp:<server>/<name>"`. */
+export declare class UnsupportedToolSourceError extends Error {
+    constructor(source: string);
+}
+/** Thrown when the native `query` tool's underlying `wren` CLI invocation exits non-zero. */
+export declare class WrenQueryExecutionError extends Error {
+    constructor(sql: string, exitCode: number, stderr: string);
+}
+/**
+ * Thrown when the `wren` binary cannot be found — either at preflight (not on
+ * `PATH` before a native-tool run even starts, see `resolveWrenBinary`) or
+ * mid-run (a spawn `ENOENT` on a `query` tool call, e.g. `wren` was
+ * uninstalled/moved after preflight passed; see `ExecResult.notFound` in
+ * `harness/exec/types.ts`). Deliberately its own error, distinct from
+ * `WrenQueryExecutionError`, so a missing binary is never mistaken for an
+ * ordinary nonzero exit (which the repair-fold loop may otherwise retry).
+ */
+export declare class WrenBinaryNotFoundError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Thrown when the native `semantic_introspect` tool's underlying
+ * `wren context show -o json` invocation either exits non-zero or exits zero
+ * but prints stdout that doesn't parse as JSON. Both cases share this one
+ * error type because introspection has no per-call input (no SQL) to report
+ * alongside an exit-code failure — `detail` carries whichever of the two
+ * happened. (The `query` tool only wraps its non-zero-exit case in
+ * `WrenQueryExecutionError`; a `parseWrenJsonl` failure there surfaces as a
+ * raw parse error — introspection wraps both.) Kept distinct from
+ * `WrenQueryExecutionError` so a caller can still tell "the query tool
+ * failed" from "introspection failed" apart; a missing binary still surfaces
+ * as `WrenBinaryNotFoundError`, checked before either failure mode here.
+ */
+export declare class WrenIntrospectExecutionError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Thrown when the `setup_execution` native tool's `exec` action is asked to
+ * run a command matching the destructive/redirection denylist (verbatim
+ * from warble's claude-agent-sdk dispatcher guardrails — see
+ * `harness/tools/setup-native.ts`'s doc comment). Thrown BEFORE the command
+ * is ever handed to `ExecutionEnv.exec`, so a rejection has zero side
+ * effects — nothing is spawned.
+ */
+export declare class SetupCommandDeniedError extends Error {
+    constructor(command: string, reason: string);
+}
+/**
+ * Thrown when the `setup_execution` native tool's `write` action is asked to
+ * write outside the setup workspace root — either the nominal
+ * `path.relative`-based check, or the realpath-based re-check that catches a
+ * symlink escape (mirroring `harness/route/artifact-content.ts`'s two-phase
+ * containment pattern). Thrown BEFORE `ExecutionEnv.writeFile` is ever
+ * called, so a rejection has zero side effects — nothing is written.
+ */
+export declare class SetupWriteScopeError extends Error {
+    constructor(requestedPath: string, scope: string);
+}
+/**
+ * Thrown when the `setup_execution` native tool's `exec` action is given a
+ * `cwd` that resolves outside the setup workspace root — the same two-phase
+ * containment check as `SetupWriteScopeError` (nominal `path.relative`, then
+ * a realpath re-check for a symlink escape), applied to the exec cwd instead
+ * of a write path. Thrown BEFORE `ExecutionEnv.exec` is ever called, so a
+ * rejection has zero side effects — nothing is spawned.
+ */
+export declare class SetupExecCwdScopeError extends Error {
+    constructor(requestedCwd: string, scope: string);
+}
+/**
+ * Thrown when the `setup_execution` native tool's flat input object is
+ * missing the field its declared `action` requires — e.g. `action: "exec"`
+ * with no `command`, or `action: "write"` with no `path`/`content`. The
+ * tool's exposed `inputSchema` must be a single top-level object rather than
+ * a discriminated union (see `harness/tools/setup-native.ts`'s module doc
+ * comment for why), so the per-action required-field combination a
+ * discriminated union would otherwise enforce at the schema level is instead
+ * checked in `execute`, BEFORE `assertCommandAllowed`/`assertWriteWithinScope`
+ * or any actual exec/write — a rejection here has zero side effects.
+ */
+export declare class SetupExecutionInputError extends Error {
+    constructor(action: string, missingField: string);
+}

package/dist-server/harness/tools/errors.js

@@ -0,0 +1,141 @@
+/**
+ * Thrown when an `agent.tools[]` entry declares `source: "native"` under a
+ * name the injected native-tool registry has no factory for.
+ */
+export class UnknownNativeToolError extends Error {
+    constructor(name) {
+        super(`no native tool registered for name: "${name}"`);
+        this.name = "UnknownNativeToolError";
+    }
+}
+/**
+ * Thrown when an `agent.tools[]` entry declares `source: "mcp:<server>/<name>"`
+ * for a server id that has no entry in the runtime-injected `McpServerConfigMap`.
+ * This is the "server-missing" half of tool-level fail-fast — it fires before
+ * any MCP connection is attempted.
+ */
+export class McpServerNotConfiguredError extends Error {
+    constructor(serverId) {
+        super(`agent declares a tool from MCP server "${serverId}" but no server ` +
+            `config was provided (expected an entry in the McpServerConfigMap)`);
+        this.name = "McpServerNotConfiguredError";
+    }
+}
+/**
+ * Thrown when a declared `mcp:<server>/<name>` tool's server connects
+ * successfully but its discovered tool set does not include `<name>`. This
+ * is the "tool-missing" half of tool-level fail-fast.
+ */
+export class McpToolNotExposedError extends Error {
+    constructor(serverId, toolName) {
+        super(`MCP server "${serverId}" does not expose a tool named "${toolName}"`);
+        this.name = "McpToolNotExposedError";
+    }
+}
+/** Thrown when an `agent.tools[]` entry's `source` is not `"native"` or `"mcp:<server>/<name>"`. */
+export class UnsupportedToolSourceError extends Error {
+    constructor(source) {
+        super(`unsupported tool source: "${source}" (expected "native" or "mcp:<server>/<name>")`);
+        this.name = "UnsupportedToolSourceError";
+    }
+}
+/** Thrown when the native `query` tool's underlying `wren` CLI invocation exits non-zero. */
+export class WrenQueryExecutionError extends Error {
+    constructor(sql, exitCode, stderr) {
+        super(`wren query failed with exit code ${exitCode} for SQL: ${sql}\n${stderr}`);
+        this.name = "WrenQueryExecutionError";
+    }
+}
+/**
+ * Thrown when the `wren` binary cannot be found — either at preflight (not on
+ * `PATH` before a native-tool run even starts, see `resolveWrenBinary`) or
+ * mid-run (a spawn `ENOENT` on a `query` tool call, e.g. `wren` was
+ * uninstalled/moved after preflight passed; see `ExecResult.notFound` in
+ * `harness/exec/types.ts`). Deliberately its own error, distinct from
+ * `WrenQueryExecutionError`, so a missing binary is never mistaken for an
+ * ordinary nonzero exit (which the repair-fold loop may otherwise retry).
+ */
+export class WrenBinaryNotFoundError extends Error {
+    constructor(detail) {
+        super(`could not find the "wren" binary: ${detail}\nfix: install wren and ensure it is on PATH.`);
+        this.name = "WrenBinaryNotFoundError";
+    }
+}
+/**
+ * Thrown when the native `semantic_introspect` tool's underlying
+ * `wren context show -o json` invocation either exits non-zero or exits zero
+ * but prints stdout that doesn't parse as JSON. Both cases share this one
+ * error type because introspection has no per-call input (no SQL) to report
+ * alongside an exit-code failure — `detail` carries whichever of the two
+ * happened. (The `query` tool only wraps its non-zero-exit case in
+ * `WrenQueryExecutionError`; a `parseWrenJsonl` failure there surfaces as a
+ * raw parse error — introspection wraps both.) Kept distinct from
+ * `WrenQueryExecutionError` so a caller can still tell "the query tool
+ * failed" from "introspection failed" apart; a missing binary still surfaces
+ * as `WrenBinaryNotFoundError`, checked before either failure mode here.
+ */
+export class WrenIntrospectExecutionError extends Error {
+    constructor(detail) {
+        super(`wren context show failed: ${detail}`);
+        this.name = "WrenIntrospectExecutionError";
+    }
+}
+/**
+ * Thrown when the `setup_execution` native tool's `exec` action is asked to
+ * run a command matching the destructive/redirection denylist (verbatim
+ * from warble's claude-agent-sdk dispatcher guardrails — see
+ * `harness/tools/setup-native.ts`'s doc comment). Thrown BEFORE the command
+ * is ever handed to `ExecutionEnv.exec`, so a rejection has zero side
+ * effects — nothing is spawned.
+ */
+export class SetupCommandDeniedError extends Error {
+    constructor(command, reason) {
+        super(`setup command denied (${reason}): ${command}`);
+        this.name = "SetupCommandDeniedError";
+    }
+}
+/**
+ * Thrown when the `setup_execution` native tool's `write` action is asked to
+ * write outside the setup workspace root — either the nominal
+ * `path.relative`-based check, or the realpath-based re-check that catches a
+ * symlink escape (mirroring `harness/route/artifact-content.ts`'s two-phase
+ * containment pattern). Thrown BEFORE `ExecutionEnv.writeFile` is ever
+ * called, so a rejection has zero side effects — nothing is written.
+ */
+export class SetupWriteScopeError extends Error {
+    constructor(requestedPath, scope) {
+        super(`setup write path "${requestedPath}" escapes the setup workspace scope "${scope}"`);
+        this.name = "SetupWriteScopeError";
+    }
+}
+/**
+ * Thrown when the `setup_execution` native tool's `exec` action is given a
+ * `cwd` that resolves outside the setup workspace root — the same two-phase
+ * containment check as `SetupWriteScopeError` (nominal `path.relative`, then
+ * a realpath re-check for a symlink escape), applied to the exec cwd instead
+ * of a write path. Thrown BEFORE `ExecutionEnv.exec` is ever called, so a
+ * rejection has zero side effects — nothing is spawned.
+ */
+export class SetupExecCwdScopeError extends Error {
+    constructor(requestedCwd, scope) {
+        super(`setup exec cwd "${requestedCwd}" escapes the setup workspace scope "${scope}"`);
+        this.name = "SetupExecCwdScopeError";
+    }
+}
+/**
+ * Thrown when the `setup_execution` native tool's flat input object is
+ * missing the field its declared `action` requires — e.g. `action: "exec"`
+ * with no `command`, or `action: "write"` with no `path`/`content`. The
+ * tool's exposed `inputSchema` must be a single top-level object rather than
+ * a discriminated union (see `harness/tools/setup-native.ts`'s module doc
+ * comment for why), so the per-action required-field combination a
+ * discriminated union would otherwise enforce at the schema level is instead
+ * checked in `execute`, BEFORE `assertCommandAllowed`/`assertWriteWithinScope`
+ * or any actual exec/write — a rejection here has zero side effects.
+ */
+export class SetupExecutionInputError extends Error {
+    constructor(action, missingField) {
+        super(`setup_execution action "${action}" requires a "${missingField}" field`);
+        this.name = "SetupExecutionInputError";
+    }
+}

package/dist-server/harness/tools/index.d.ts

@@ -0,0 +1,13 @@
+export { McpServerNotConfiguredError, McpToolNotExposedError, SetupCommandDeniedError, SetupWriteScopeError, UnknownNativeToolError, UnsupportedToolSourceError, WrenBinaryNotFoundError, WrenIntrospectExecutionError, WrenQueryExecutionError, } from "./errors.js";
+export { parseToolSource } from "./parse.js";
+export type { ParsedToolSource } from "./parse.js";
+export { resolveWrenBinary } from "./resolve-wren-binary.js";
+export { assembleDashboardBlocks, BUILD_DASHBOARD_TOOL_NAME, buildDashboardInputSchema, createBuildDashboardTool, createDefaultNativeToolRegistry, createNativeToolRegistry, createWrenNativeToolRegistry, createWrenQueryTool, createWrenSemanticIntrospectTool, createWriteArtifactTool, SEMANTIC_INTROSPECT_TOOL_NAME, WREN_QUERY_TOOL_NAME, WRITE_ARTIFACT_TOOL_NAME, } from "./native.js";
+export type { BuildDashboardInput, BuildDashboardResult, NativeToolFactory, NativeToolRegistry, WrenNativeToolOptions, WrenQueryResult, WrenQueryToolOptions, WrenSemanticIntrospectResult, } from "./native.js";
+export { createSetupExecutionTool, executeSetupExecution, setupExecutionInputSchema, SETUP_EXECUTION_TOOL_NAME, } from "./setup-native.js";
+export type { SetupExecutionInput, SetupExecutionResult, SetupExecutionToolOptions } from "./setup-native.js";
+export { connectMcpServer } from "./mcp.js";
+export type { McpServerConfig, McpServerConfigMap } from "./mcp.js";
+export { resolveTools } from "./resolve.js";
+export type { ResolvedTools, ResolveToolsContext } from "./resolve.js";
+export { withResolvedTools } from "./wiring.js";

package/dist-server/harness/tools/index.js

@@ -0,0 +1,8 @@
+export { McpServerNotConfiguredError, McpToolNotExposedError, SetupCommandDeniedError, SetupWriteScopeError, UnknownNativeToolError, UnsupportedToolSourceError, WrenBinaryNotFoundError, WrenIntrospectExecutionError, WrenQueryExecutionError, } from "./errors.js";
+export { parseToolSource } from "./parse.js";
+export { resolveWrenBinary } from "./resolve-wren-binary.js";
+export { assembleDashboardBlocks, BUILD_DASHBOARD_TOOL_NAME, buildDashboardInputSchema, createBuildDashboardTool, createDefaultNativeToolRegistry, createNativeToolRegistry, createWrenNativeToolRegistry, createWrenQueryTool, createWrenSemanticIntrospectTool, createWriteArtifactTool, SEMANTIC_INTROSPECT_TOOL_NAME, WREN_QUERY_TOOL_NAME, WRITE_ARTIFACT_TOOL_NAME, } from "./native.js";
+export { createSetupExecutionTool, executeSetupExecution, setupExecutionInputSchema, SETUP_EXECUTION_TOOL_NAME, } from "./setup-native.js";
+export { connectMcpServer } from "./mcp.js";
+export { resolveTools } from "./resolve.js";
+export { withResolvedTools } from "./wiring.js";

package/dist-server/harness/tools/mcp.d.ts

@@ -0,0 +1,26 @@
+import { type MCPClient, type MCPClientConfig } from "@ai-sdk/mcp";
+/**
+ * Connection config for one MCP server, keyed by server id (e.g. `"wren"`)
+ * in `McpServerConfigMap`. Two shapes: `"stdio"` spawns a local process
+ * (the real `mcp:wren` wiring — a `wren` MCP process over a jaffle DuckDB —
+ * is this shape), and `"transport"` accepts any `@ai-sdk/mcp` transport config/instance
+ * directly (http/sse, or a hand-rolled `MCPTransport` such as the hermetic
+ * mock server this package's tests spawn over stdio).
+ *
+ * This is always supplied by the caller at run time — never read from the
+ * bundle (the bundle only names the server id via `mcp:<server>/<name>`).
+ */
+export type McpServerConfig = {
+    readonly kind: "stdio";
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cwd?: string;
+} | {
+    readonly kind: "transport";
+    readonly transport: MCPClientConfig["transport"];
+};
+/** Runtime-injected map of MCP server id -> connection config. */
+export type McpServerConfigMap = Readonly<Record<string, McpServerConfig>>;
+/** Connects to one configured MCP server, returning the live client. */
+export declare function connectMcpServer(config: McpServerConfig): Promise<MCPClient>;

package/dist-server/harness/tools/mcp.js

@@ -0,0 +1,15 @@
+import { createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+const DEFAULT_CLIENT_NAME = "wren-harness";
+/** Connects to one configured MCP server, returning the live client. */
+export async function connectMcpServer(config) {
+    const transport = config.kind === "stdio"
+        ? new Experimental_StdioMCPTransport({
+            command: config.command,
+            ...(config.args ? { args: [...config.args] } : {}),
+            ...(config.env ? { env: { ...config.env } } : {}),
+            ...(config.cwd ? { cwd: config.cwd } : {}),
+        })
+        : config.transport;
+    return createMCPClient({ transport, clientName: DEFAULT_CLIENT_NAME });
+}

package/dist-server/harness/tools/native.d.ts

@@ -0,0 +1,179 @@
+import { type Tool } from "ai";
+import { z } from "zod";
+import type { ExecutionEnv, ExecutionPolicy } from "../exec/index.js";
+/** Builds a fresh AI SDK tool instance for a registered native tool name. */
+export type NativeToolFactory = () => Tool;
+/**
+ * Injectable registry mapping a harness-native tool name (open string, e.g.
+ * `write_artifact`) to a factory that builds the AI SDK `Tool` for it.
+ * Mirrors the shape of `ProviderRegistry` (harness/providers/registry.ts):
+ * an empty registry callers populate, plus a default-populated convenience
+ * constructor.
+ */
+export interface NativeToolRegistry {
+    register(name: string, factory: NativeToolFactory): void;
+    has(name: string): boolean;
+    create(name: string): Tool;
+}
+export declare function createNativeToolRegistry(): NativeToolRegistry;
+export declare const WRITE_ARTIFACT_TOOL_NAME = "write_artifact";
+/**
+ * `write_artifact`: routes the write through the injected `ExecutionEnv`,
+ * confined to `policy.artifactWriteScope`. The policy is the
+ * `deriveEnforcement`-computed `EnforcementPolicy` for the owning
+ * agent — a locked `scoped_write` guardrail is what grants
+ * `artifactWriteScope` in the first place, so an agent with no such
+ * guardrail gets a policy with no scope and every call fails closed with
+ * `WriteScopeNotGrantedError` (thrown by the `ExecutionEnv`, not here).
+ * This coexists with a locked `read_only_execution` guardrail by design:
+ * `readOnly` gates *data-access* execution (`exec`/non-allowlisted
+ * `fetch`), never the scoped artifact write.
+ */
+export declare function createWriteArtifactTool(env: ExecutionEnv, policy: ExecutionPolicy): Tool;
+/** A native-tool registry pre-populated with the built-in `write_artifact` and `build_dashboard` tools, bound to `env`/`policy`. */
+export declare function createDefaultNativeToolRegistry(env: ExecutionEnv, policy: ExecutionPolicy): NativeToolRegistry;
+export declare const BUILD_DASHBOARD_TOOL_NAME = "build_dashboard";
+export declare const buildDashboardInputSchema: z.ZodObject<{
+    kpi_cards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        unit: z.ZodOptional<z.ZodString>;
+        delta: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    chart: z.ZodOptional<z.ZodObject<{
+        chart_type: z.ZodEnum<{
+            area: "area";
+            bar: "bar";
+            line: "line";
+            pie: "pie";
+            scatter: "scatter";
+        }>;
+        x: z.ZodString;
+        series: z.ZodArray<z.ZodString>;
+        rows: z.ZodArray<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodUnknown>]>>;
+    }, z.core.$strip>>;
+    table: z.ZodOptional<z.ZodObject<{
+        columns: z.ZodArray<z.ZodString>;
+        rows: z.ZodArray<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodUnknown>]>>;
+    }, z.core.$strip>>;
+    definition: z.ZodOptional<z.ZodObject<{
+        sql: z.ZodString;
+        source_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        filters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BuildDashboardInput = z.infer<typeof buildDashboardInputSchema>;
+/** The deterministically-assembled `{blocks}` payload `build_dashboard` returns — already the render-envelope shape `generate_dashboard`'s `output_schema` expects. */
+export interface BuildDashboardResult {
+    readonly blocks: Record<string, unknown>[];
+    readonly summary?: string;
+    /**
+     * CAVEAT: `verified` here is SELF-DECLARED by the tool's structured input,
+     * NOT earned from a real successful `query` call the way the `toolTable`
+     * path's `verified` is (that one is tied to `run.ts`'s
+     * `sawSuccessfulDataAccessCall`). This is inert today because
+     * `generate_dashboard` declares NO locked `gated_check` guardrail, so the
+     * deterministic gate never inspects it. If a future profile ever adds a
+     * `gated_check` to `generate_dashboard`, this capture path must ALSO be
+     * updated to earn `verified` from the real per-panel `query` calls —
+     * otherwise the gate would be trivially satisfiable by any `build_dashboard`
+     * call carrying hallucinated panel data.
+     */
+    readonly verified: true;
+}
+/**
+ * Deterministically assembles the typed panels the model composed
+ * (`kpi_cards`/`chart`/`table`/`definition`) into `generate_dashboard`'s
+ * `{blocks}` render contract — one `kpi_card` block per KPI, then `chart`,
+ * then `table`, then `definition` (this is the "sensible dashboard order":
+ * headline numbers first, then the visual trend/breakdown, then the
+ * supporting detail, then the query provenance), each only when the
+ * corresponding panel is present in `input`. No LLM call, no I/O — pure
+ * reshaping of model-supplied, schema-validated structure, which is what
+ * makes this safe to trust as `verified: true` (see `WrenQueryResult`'s own
+ * reasoning for why a real, non-erroring data-access result earns
+ * `verified`): every panel here was composed by the model from its own
+ * queried results, not fabricated by this function.
+ */
+export declare function assembleDashboardBlocks(input: BuildDashboardInput): BuildDashboardResult;
+/**
+ * `build_dashboard` (native realization): a schema-enforced, purely
+ * deterministic assembly tool. The zod `inputSchema` is what makes the model
+ * reliably supply *structured* panels (typed kpi/chart/table/definition
+ * shapes) instead of prose it would otherwise have to be trusted to format
+ * correctly; `execute` then just reshapes that already-validated input into
+ * the render contract — no LLM call, no I/O, so it can never itself fail
+ * non-deterministically the way a render-LLM synthesis step can.
+ */
+export declare function createBuildDashboardTool(): Tool;
+export declare const WREN_QUERY_TOOL_NAME = "query";
+export interface WrenQueryToolOptions {
+    /** Backend the CLI invocation runs through — never a direct child_process call (mirrors write_artifact's own routing through the injected `ExecutionEnv`). */
+    readonly env: ExecutionEnv;
+    readonly policy: ExecutionPolicy;
+    /** Directory containing `wren_project.yml` + a built `target/mdl.json`; becomes the CLI invocation's cwd. */
+    readonly projectDir: string;
+}
+/** The parsed result of a `query` tool call: `wren -o json`'s JSONL stdout, reshaped into columns + row objects. */
+export interface WrenQueryResult {
+    readonly columns: readonly string[];
+    readonly rows: readonly Record<string, unknown>[];
+}
+/**
+ * `query` (native realization): runs a read-only SQL query through the real
+ * `wren` CLI — `wren -q -o json [-l <limit>] -s '<sql>'` — executed via the
+ * injected `ExecutionEnv` with `cwd: projectDir`, exactly like
+ * `write_artifact` routes through `env.writeFile` instead of touching the
+ * filesystem directly. Declared `mode: "read"` so a locked
+ * `read_only_execution` guardrail (which `answer_query` always carries)
+ * never blocks it — only `mode: "write"` commands are rejected by a
+ * read-only policy (see `ExecutionEnv.exec`'s doc comment).
+ *
+ * `policy.rowLimit` (guardrail-enforcement fix): clamps `input.limit` via
+ * `clampRowLimit`, so a locked `row_limit` guardrail actually bounds `-l`
+ * instead of being derived and then ignored. `policy.statementTimeoutSec`
+ * becomes `ExecCommand.timeoutMs` on the `wren` invocation, so a locked
+ * `statement_timeout` guardrail actually kills a runaway query instead of
+ * letting it run unbounded.
+ *
+ * `wren -o json` prints one JSON object per result row (JSONL, not a JSON
+ * array) — this parses that into `{ columns, rows }`, where `columns` are
+ * the first row's keys (an empty result set yields `columns: []`).
+ */
+export declare function createWrenQueryTool(options: WrenQueryToolOptions): Tool;
+export declare const SEMANTIC_INTROSPECT_TOOL_NAME = "semantic_introspect";
+/** The parsed result of a `semantic_introspect` tool call: `wren context show -o json`'s single JSON object, passed through as-is (models/relationships/views/cubes/dataSource — the model reads it directly, this tool does no reshaping). */
+export type WrenSemanticIntrospectResult = Record<string, unknown>;
+/**
+ * `semantic_introspect` (native realization): introspects the bound
+ * semantic layer via the real `wren` CLI — `wren context show -o json` —
+ * executed via the injected `ExecutionEnv` with `cwd: projectDir`, the same
+ * shape as {@link createWrenQueryTool}. Declared `mode: "read"` for the same
+ * reason `query` is: `explore_model` always carries a locked
+ * `read_only_execution` guardrail, and this must never be blocked by it.
+ *
+ * Unlike `query`, `wren context show -o json` prints a SINGLE JSON object
+ * (not JSONL), so this parses with a plain `JSON.parse` rather than
+ * `parseWrenJsonl`, and takes no per-call input (introspection covers the
+ * whole project, not one statement) — `inputSchema` is deliberately empty.
+ *
+ * NOTE: `wren cube list` enrichment (cubes/metrics, "if available" per the
+ * component's step prompt) is intentionally deferred — it prints plain,
+ * non-JSON text (e.g. "No cubes defined.") rather than structured output,
+ * which would need its own ad hoc parser for a v1 that's optional per the
+ * step prompt anyway.
+ */
+export declare function createWrenSemanticIntrospectTool(options: WrenQueryToolOptions): Tool;
+/** Options for {@link createWrenNativeToolRegistry} — the `query` tool's options, reused as the registry's binding. */
+export type WrenNativeToolOptions = WrenQueryToolOptions;
+/**
+ * A native-tool registry carrying both the built-in `write_artifact` tool
+ * (bound to `options.env`/`options.policy`, same as
+ * `createDefaultNativeToolRegistry`) and the real `query` tool wired to
+ * `options.projectDir`. Pass this as `RunAgentContext.nativeTools` to
+ * resolve an `answer_query` agent whose `query` tool declares
+ * `source: "native"` to a real `wren` CLI invocation instead of an MCP
+ * server.
+ */
+export declare function createWrenNativeToolRegistry(options: WrenNativeToolOptions): NativeToolRegistry;