@wrenai/genbi 0.0.1

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

@@ -0,0 +1,322 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { UnknownNativeToolError, WrenBinaryNotFoundError, WrenIntrospectExecutionError, WrenQueryExecutionError, } from "./errors.js";
+export function createNativeToolRegistry() {
+    const factories = new Map();
+    return {
+        register(name, factory) {
+            factories.set(name, factory);
+        },
+        has(name) {
+            return factories.has(name);
+        },
+        create(name) {
+            const factory = factories.get(name);
+            if (!factory) {
+                throw new UnknownNativeToolError(name);
+            }
+            return factory();
+        },
+    };
+}
+export 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 function createWriteArtifactTool(env, policy) {
+    return tool({
+        description: "Write an artifact to the agent's scoped workspace.",
+        inputSchema: z.object({
+            path: z.string(),
+            content: z.string(),
+        }),
+        execute: async (input) => {
+            await env.writeFile(input.path, input.content, policy);
+            return {
+                written: true,
+                path: input.path,
+                bytes: input.content.length,
+            };
+        },
+    });
+}
+/** A native-tool registry pre-populated with the built-in `write_artifact` and `build_dashboard` tools, bound to `env`/`policy`. */
+export function createDefaultNativeToolRegistry(env, policy) {
+    const registry = createNativeToolRegistry();
+    registry.register(WRITE_ARTIFACT_TOOL_NAME, () => createWriteArtifactTool(env, policy));
+    registry.register(BUILD_DASHBOARD_TOOL_NAME, () => createBuildDashboardTool());
+    return registry;
+}
+export const BUILD_DASHBOARD_TOOL_NAME = "build_dashboard";
+/**
+ * A dashboard row, as the model may hand it in: either a column-keyed object
+ * (the shape `generate_dashboard`'s `chart`/`table` render blocks require),
+ * or a positional array aligned to that panel's known key order (`columns`
+ * for a table, `[x, ...series]` for a chart). Accepting both keeps the
+ * schema forgiving of how a model naturally emits rows it just queried,
+ * while `normalizeDashboardRow` below deterministically reshapes either
+ * form into the object shape the output contract needs.
+ */
+const dashboardRowSchema = z.union([z.record(z.string(), z.unknown()), z.array(z.unknown())]);
+const kpiCardInputSchema = z.object({
+    label: z.string(),
+    value: z.union([z.number(), z.string()]),
+    unit: z.string().optional(),
+    delta: z.number().optional(),
+});
+const chartInputSchema = z.object({
+    chart_type: z.enum(["bar", "line", "pie", "area", "scatter"]),
+    x: z.string(),
+    series: z.array(z.string()),
+    rows: z.array(dashboardRowSchema),
+});
+const tableInputSchema = z.object({
+    columns: z.array(z.string()),
+    rows: z.array(dashboardRowSchema),
+});
+const definitionInputSchema = z.object({
+    sql: z.string(),
+    source_tables: z.array(z.string()).optional(),
+    filters: z.array(z.string()).optional(),
+});
+export const buildDashboardInputSchema = z.object({
+    kpi_cards: z.array(kpiCardInputSchema).optional(),
+    chart: chartInputSchema.optional(),
+    table: tableInputSchema.optional(),
+    definition: definitionInputSchema.optional(),
+    summary: z.string().optional(),
+});
+/** Reshapes a row into a plain object: passes an already-object row through; zips a positional array row against `keys`. */
+function normalizeDashboardRow(row, keys) {
+    if (!Array.isArray(row))
+        return row;
+    return Object.fromEntries(keys.map((key, index) => [key, row[index]]));
+}
+/**
+ * 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 function assembleDashboardBlocks(input) {
+    const blocks = [];
+    for (const kpi of input.kpi_cards ?? []) {
+        blocks.push({
+            type: "kpi_card",
+            label: kpi.label,
+            value: kpi.value,
+            ...(kpi.unit !== undefined ? { unit: kpi.unit } : {}),
+            ...(kpi.delta !== undefined ? { delta: kpi.delta } : {}),
+        });
+    }
+    if (input.chart) {
+        const keys = [input.chart.x, ...input.chart.series];
+        blocks.push({
+            type: "chart",
+            chart_type: input.chart.chart_type,
+            x: input.chart.x,
+            series: input.chart.series,
+            rows: input.chart.rows.map((row) => normalizeDashboardRow(row, keys)),
+        });
+    }
+    if (input.table) {
+        const { columns } = input.table;
+        blocks.push({
+            type: "table",
+            columns,
+            rows: input.table.rows.map((row) => normalizeDashboardRow(row, columns)),
+        });
+    }
+    if (input.definition) {
+        blocks.push({
+            type: "definition",
+            sql: input.definition.sql,
+            source_tables: input.definition.source_tables ?? [],
+            filters: input.definition.filters ?? [],
+        });
+    }
+    return {
+        blocks,
+        ...(input.summary !== undefined ? { summary: input.summary } : {}),
+        verified: true,
+    };
+}
+/**
+ * `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 function createBuildDashboardTool() {
+    return tool({
+        description: "Assemble queried dashboard panels (KPI cards, a chart, a table, and/or the query definition) " +
+            "into the final dashboard's render blocks, in dashboard order.",
+        inputSchema: buildDashboardInputSchema,
+        execute: async (input) => assembleDashboardBlocks(input),
+    });
+}
+export const WREN_QUERY_TOOL_NAME = "query";
+/**
+ * Clamps the model-volunteered `requestedLimit` to the guardrail-derived
+ * `policyLimit` (`EnforcementPolicy.rowLimit`), always preferring the
+ * smaller. When the model volunteers nothing, the policy limit itself
+ * becomes the applied `-l` — a locked-in cap, not just a ceiling on a value
+ * the model chose not to supply. When there is no policy limit at all (an
+ * agent whose guardrails carry no `row_limit` threshold), the model's
+ * requested limit (if any) passes through unclamped.
+ */
+function clampRowLimit(policyLimit, requestedLimit) {
+    if (policyLimit === undefined)
+        return requestedLimit;
+    if (requestedLimit === undefined)
+        return policyLimit;
+    return Math.min(policyLimit, requestedLimit);
+}
+/**
+ * `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 function createWrenQueryTool(options) {
+    const { env, policy, projectDir } = options;
+    return tool({
+        description: "Run a read-only SQL query against the wren semantic layer via the native `wren` CLI.",
+        inputSchema: z.object({
+            sql: z.string(),
+            limit: z.number().int().positive().optional(),
+        }),
+        execute: async (input) => {
+            const limit = clampRowLimit(policy.rowLimit, input.limit);
+            const args = ["-q", "-o", "json", ...(limit !== undefined ? ["-l", String(limit)] : []), "-s", input.sql];
+            const timeoutMs = policy.statementTimeoutSec !== undefined ? policy.statementTimeoutSec * 1000 : undefined;
+            const result = await env.exec({ mode: "read", command: "wren", args, cwd: projectDir, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }, policy);
+            // A mid-run disappearance of the `wren` binary (e.g.
+            // uninstalled/moved after `resolveWrenBinary`'s preflight passed)
+            // surfaces here as `ExecResult.notFound`, not just a nonzero
+            // `exitCode` — checked first so it throws the specific
+            // `WrenBinaryNotFoundError` instead of the generic
+            // `WrenQueryExecutionError`, which the repair-fold loop treats as a
+            // retryable tool error even though retrying can never help.
+            if (result.notFound) {
+                throw new WrenBinaryNotFoundError(`"wren" was not found while running this query (spawn ENOENT)`);
+            }
+            if (result.exitCode !== 0) {
+                throw new WrenQueryExecutionError(input.sql, result.exitCode, result.stderr);
+            }
+            return parseWrenJsonl(result.stdout);
+        },
+    });
+}
+function parseWrenJsonl(stdout) {
+    const rows = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+    const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+    return { columns, rows };
+}
+export const SEMANTIC_INTROSPECT_TOOL_NAME = "semantic_introspect";
+/**
+ * `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 function createWrenSemanticIntrospectTool(options) {
+    const { env, policy, projectDir } = options;
+    return tool({
+        description: "Introspect the wren semantic layer's models, columns, relationships, and metrics via the native `wren` CLI.",
+        inputSchema: z.object({}),
+        execute: async () => {
+            const timeoutMs = policy.statementTimeoutSec !== undefined ? policy.statementTimeoutSec * 1000 : undefined;
+            const result = await env.exec({
+                mode: "read",
+                command: "wren",
+                args: ["context", "show", "-o", "json"],
+                cwd: projectDir,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            }, policy);
+            // Same reasoning as `query`: a mid-run disappearance of the
+            // `wren` binary surfaces as `notFound`, checked first so it throws the
+            // specific `WrenBinaryNotFoundError` rather than the generic
+            // `WrenIntrospectExecutionError`.
+            if (result.notFound) {
+                throw new WrenBinaryNotFoundError(`"wren" was not found while introspecting the semantic layer (spawn ENOENT)`);
+            }
+            if (result.exitCode !== 0) {
+                throw new WrenIntrospectExecutionError(`exit code ${result.exitCode}\n${result.stderr}`);
+            }
+            try {
+                return JSON.parse(result.stdout);
+            }
+            catch (error) {
+                throw new WrenIntrospectExecutionError(`could not parse "wren context show -o json" output as JSON: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+}
+/**
+ * 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 function createWrenNativeToolRegistry(options) {
+    const registry = createDefaultNativeToolRegistry(options.env, options.policy);
+    registry.register(WREN_QUERY_TOOL_NAME, () => createWrenQueryTool(options));
+    registry.register(SEMANTIC_INTROSPECT_TOOL_NAME, () => createWrenSemanticIntrospectTool(options));
+    return registry;
+}

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

@@ -0,0 +1,14 @@
+/** A tool declaration's `source` field, parsed into its harness-meaningful shape. */
+export type ParsedToolSource = {
+    readonly kind: "native";
+} | {
+    readonly kind: "mcp";
+    readonly server: string;
+    readonly toolName: string;
+};
+/**
+ * Parses an `agent.tools[].source` string. Two shapes are recognized:
+ * `"native"` and `"mcp:<server>/<name>"` (e.g. `"mcp:wren/query"`). Anything
+ * else is a load-time error — bundle producers only ever emit these two.
+ */
+export declare function parseToolSource(source: string): ParsedToolSource;

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

@@ -0,0 +1,18 @@
+import { UnsupportedToolSourceError } from "./errors.js";
+const MCP_SOURCE_PATTERN = /^mcp:([^/]+)\/(.+)$/;
+/**
+ * Parses an `agent.tools[].source` string. Two shapes are recognized:
+ * `"native"` and `"mcp:<server>/<name>"` (e.g. `"mcp:wren/query"`). Anything
+ * else is a load-time error — bundle producers only ever emit these two.
+ */
+export function parseToolSource(source) {
+    if (source === "native") {
+        return { kind: "native" };
+    }
+    const match = MCP_SOURCE_PATTERN.exec(source);
+    if (match) {
+        const [, server, toolName] = match;
+        return { kind: "mcp", server: server, toolName: toolName };
+    }
+    throw new UnsupportedToolSourceError(source);
+}

package/dist-server/harness/tools/resolve-wren-binary.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Preflights that a `wren` binary is resolvable on `PATH` (`wren --version`
+ * exits 0) — mirrors `resolveWarbleBinary`'s PATH tier
+ * (`../compile/resolve-binary.js`) for the `warble` binary. `wren` is a
+ * separately-installed CLI, not a sibling repo this package sits beside, so
+ * there is no explicit-override or sibling-repo-build tier here — just the
+ * one PATH check. Throws {@link WrenBinaryNotFoundError} (loud-fail) so a
+ * missing `wren` fails clearly before a native-tool run even starts, instead
+ * of surfacing later as an opaque exec failure once the tool loop is already
+ * mid-run (see `ExecResult.notFound` for the mid-run counterpart).
+ */
+export declare function resolveWrenBinary(): Promise<void>;

package/dist-server/harness/tools/resolve-wren-binary.js

@@ -0,0 +1,21 @@
+import { execFile } from "node:child_process";
+import { WrenBinaryNotFoundError } from "./errors.js";
+/**
+ * Preflights that a `wren` binary is resolvable on `PATH` (`wren --version`
+ * exits 0) — mirrors `resolveWarbleBinary`'s PATH tier
+ * (`../compile/resolve-binary.js`) for the `warble` binary. `wren` is a
+ * separately-installed CLI, not a sibling repo this package sits beside, so
+ * there is no explicit-override or sibling-repo-build tier here — just the
+ * one PATH check. Throws {@link WrenBinaryNotFoundError} (loud-fail) so a
+ * missing `wren` fails clearly before a native-tool run even starts, instead
+ * of surfacing later as an opaque exec failure once the tool loop is already
+ * mid-run (see `ExecResult.notFound` for the mid-run counterpart).
+ */
+export async function resolveWrenBinary() {
+    const onPath = await new Promise((resolve) => {
+        execFile("wren", ["--version"], (error) => resolve(!error));
+    });
+    if (!onPath) {
+        throw new WrenBinaryNotFoundError(`not found on PATH (tried running "wren --version")`);
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { ToolSet } from "ai";
+import type { Agent } from "../bundle/schema.js";
+import { type ExecutionEnv, type ExecutionPolicy } from "../exec/index.js";
+import { type McpServerConfigMap } from "./mcp.js";
+import { type NativeToolRegistry } from "./native.js";
+export interface ResolveToolsContext {
+    /**
+     * Defaults to a registry built from `executionEnv`/`enforcementPolicy`
+     * (built-in `write_artifact` tool only). Supplying this bypasses both of
+     * those fields entirely.
+     */
+    readonly nativeTools?: NativeToolRegistry;
+    /** Runtime-injected MCP server connection config, keyed by server id. Defaults to `{}`. */
+    readonly mcpServers?: McpServerConfigMap;
+    /** Backend native tools execute side effects through. Defaults to `createLocalExecutionEnv()`. */
+    readonly executionEnv?: ExecutionEnv;
+    /**
+     * The guardrail-derived policy passed to every native-tool call. Defaults
+     * to `{ readOnly: false }` (no scope, no allowlist) — the secure-by-default
+     * fallback: without a real `deriveEnforcement(agent)` result threaded in
+     * (as `runAgent` does), `write_artifact` rejects every call.
+     */
+    readonly enforcementPolicy?: ExecutionPolicy;
+}
+export interface ResolvedTools {
+    /** The AI SDK tool set the loop executor consumes as `ExecuteAgentContext.tools`. */
+    readonly tools: ToolSet;
+    /** Shuts down every MCP client this resolution opened. Always safe to call once. */
+    close(): Promise<void>;
+}
+/**
+ * Turns `agent.tools[]` into an AI SDK `ToolSet`, connecting whatever MCP
+ * servers the agent's tools declare and discovering their tools. This is
+ * the tool-level "second door" (mirroring the capability gate):
+ * every declared tool is resolved and validated *before* the loop executor
+ * ever runs a step, so a misconfigured or drifted tool fails loud at
+ * session start rather than surfacing as an opaque tool-call error mid-run.
+ *
+ * Fail-fast is two passes:
+ *  1. Before connecting anything: unknown `native` names
+ *     ({@link UnknownNativeToolError}) and MCP server ids with no entry in
+ *     `mcpServers` ({@link McpServerNotConfiguredError}).
+ *  2. After connecting + discovering each referenced server's tools: any
+ *     declared `mcp:<server>/<name>` whose server doesn't actually expose
+ *     `<name>` ({@link McpToolNotExposedError}).
+ *
+ * On any failure (including a later tool in the list) every MCP client this
+ * call opened is closed before the error propagates — resolution never
+ * leaks a connected client.
+ */
+export declare function resolveTools(agent: Agent, ctx?: ResolveToolsContext): Promise<ResolvedTools>;

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

@@ -0,0 +1,79 @@
+import { createLocalExecutionEnv } from "../exec/index.js";
+import { McpServerNotConfiguredError, McpToolNotExposedError, UnknownNativeToolError } from "./errors.js";
+import { connectMcpServer } from "./mcp.js";
+import { createDefaultNativeToolRegistry } from "./native.js";
+import { parseToolSource } from "./parse.js";
+/**
+ * Turns `agent.tools[]` into an AI SDK `ToolSet`, connecting whatever MCP
+ * servers the agent's tools declare and discovering their tools. This is
+ * the tool-level "second door" (mirroring the capability gate):
+ * every declared tool is resolved and validated *before* the loop executor
+ * ever runs a step, so a misconfigured or drifted tool fails loud at
+ * session start rather than surfacing as an opaque tool-call error mid-run.
+ *
+ * Fail-fast is two passes:
+ *  1. Before connecting anything: unknown `native` names
+ *     ({@link UnknownNativeToolError}) and MCP server ids with no entry in
+ *     `mcpServers` ({@link McpServerNotConfiguredError}).
+ *  2. After connecting + discovering each referenced server's tools: any
+ *     declared `mcp:<server>/<name>` whose server doesn't actually expose
+ *     `<name>` ({@link McpToolNotExposedError}).
+ *
+ * On any failure (including a later tool in the list) every MCP client this
+ * call opened is closed before the error propagates — resolution never
+ * leaks a connected client.
+ */
+export async function resolveTools(agent, ctx = {}) {
+    const executionEnv = ctx.executionEnv ?? createLocalExecutionEnv();
+    const enforcementPolicy = ctx.enforcementPolicy ?? { readOnly: false };
+    const nativeTools = ctx.nativeTools ?? createDefaultNativeToolRegistry(executionEnv, enforcementPolicy);
+    const mcpServers = ctx.mcpServers ?? {};
+    const specs = agent.tools.map((toolSpec) => ({
+        toolSpec,
+        source: parseToolSource(toolSpec.source),
+    }));
+    const serverIds = new Set();
+    for (const { toolSpec, source } of specs) {
+        if (source.kind === "native") {
+            if (!nativeTools.has(toolSpec.name)) {
+                throw new UnknownNativeToolError(toolSpec.name);
+            }
+        }
+        else if (!mcpServers[source.server]) {
+            throw new McpServerNotConfiguredError(source.server);
+        }
+        else {
+            serverIds.add(source.server);
+        }
+    }
+    const clients = new Map();
+    const discoveredByServer = new Map();
+    async function closeAll() {
+        await Promise.all([...clients.values()].map((client) => client.close().catch(() => undefined)));
+    }
+    try {
+        for (const serverId of serverIds) {
+            const client = await connectMcpServer(mcpServers[serverId]);
+            clients.set(serverId, client);
+            discoveredByServer.set(serverId, (await client.tools()));
+        }
+        const tools = {};
+        for (const { toolSpec, source } of specs) {
+            if (source.kind === "native") {
+                tools[toolSpec.name] = nativeTools.create(toolSpec.name);
+                continue;
+            }
+            const serverTools = discoveredByServer.get(source.server);
+            const discoveredTool = serverTools[source.toolName];
+            if (!discoveredTool) {
+                throw new McpToolNotExposedError(source.server, source.toolName);
+            }
+            tools[toolSpec.name] = discoveredTool;
+        }
+        return { tools, close: closeAll };
+    }
+    catch (error) {
+        await closeAll();
+        throw error;
+    }
+}

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

@@ -0,0 +1,84 @@
+import { type Tool } from "ai";
+import { z } from "zod";
+import type { ExecutionEnv, ExecutionPolicy } from "../exec/index.js";
+export declare const SETUP_EXECUTION_TOOL_NAME = "setup_execution";
+export interface SetupExecutionToolOptions {
+    /** Backend the tool's side effects route through — never a direct child_process/fs call. */
+    readonly env: ExecutionEnv;
+    readonly policy: ExecutionPolicy;
+    /**
+     * The setup workspace root — the default (and outer bound) for the `exec`
+     * action's subprocess `cwd`, and the `write` action's scope boundary.
+     * Always caller-supplied and fixed as the ceiling; the `exec` action MAY
+     * narrow its own cwd via an optional per-call `cwd` field (see
+     * `resolveExecCwd`), but that value is contained by the same two-phase
+     * check as the write path and can never resolve outside this root — a
+     * command/path can narrow its own working directory within the root, but
+     * never broaden either its cwd or its write scope beyond it.
+     */
+    readonly workspaceRoot: string;
+}
+/**
+ * A single flat top-level object, NOT a `z.discriminatedUnion` — a
+ * discriminated union serializes (via `z.toJSONSchema`) to a schema whose
+ * TOP level is `{"oneOf": [...]}` with no top-level `"type": "object"`, which
+ * both OpenAI's function-calling API and Anthropic's `input_schema` reject
+ * outright (confirmed against a real OpenAI `gpt-4.1` call; see
+ * `test/native-tool-schema-shape.test.ts` for the offline, no-API-key-spent
+ * regression coverage). `command`/`path`/`content` are therefore all
+ * optional here — the per-action required-field combination a discriminated
+ * union would enforce at the schema level is instead checked in
+ * `createSetupExecutionTool`'s `execute`, before any side effect.
+ *
+ * Flattening the schema drops the model-facing pairing a discriminated union
+ * used to encode for free (`exec` needs `command`; `write` needs `path` +
+ * `content`) — nothing about the field TYPES says which action requires
+ * which field. Since in-process has no turn budget (unlike dispatched's fixed
+ * `--max-turns` cap on setup), an under-described schema makes that pairing
+ * discoverable only by the model guessing wrong and reading a thrown
+ * `SetupExecutionInputError` back — unbounded trial-and-error on the user's
+ * own API spend. The `.describe()` calls below and the tool `description` in
+ * `createSetupExecutionTool` spell the pairing out explicitly so the model
+ * can satisfy it on the first call; the `execute`-time checks remain as the
+ * enforced (not just described) guarantee.
+ */
+export declare const setupExecutionInputSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        exec: "exec";
+        write: "write";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SetupExecutionInput = z.infer<typeof setupExecutionInputSchema>;
+export type SetupExecutionResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    notFound?: boolean;
+    timedOut?: boolean;
+    maxBufferExceeded?: boolean;
+} | {
+    written: true;
+    path: string;
+    bytes: number;
+};
+/**
+ * Builds the combined `setup_execution` tool: `action: "exec"` runs a shell
+ * command via `/bin/sh -c`, cwd defaulting to `workspaceRoot` but narrowable
+ * per-call via the optional `cwd` field (see {@link resolveExecCwd} — always
+ * contained within `workspaceRoot`, never able to escape it), broadened
+ * beyond a single fixed binary the way the dispatcher-side `setup_execution`
+ * guardrail broadens Bash — but still subject to the same denylist, checked
+ * first, never relaxed. `action: "write"` writes a file relative to the same
+ * optional cwd (workspaceRoot by default), scoped to `workspaceRoot` by the
+ * two-phase containment check above, then delegates the actual write to
+ * `env.writeFile` (which applies its OWN, nominal-only
+ * `policy.artifactWriteScope` check — this tool's pre-flight check is
+ * additional, not a replacement, since `env.writeFile` has no realpath
+ * re-check of its own; see `harness/exec/local.ts`).
+ */
+export declare function executeSetupExecution(input: SetupExecutionInput, options: SetupExecutionToolOptions): Promise<SetupExecutionResult>;
+export declare function createSetupExecutionTool(options: SetupExecutionToolOptions): Tool;