@wrenai/genbi 0.0.1

package/dist-server/harness/guardrails/policy.js

@@ -0,0 +1,57 @@
+const READ_ONLY_ENFORCEMENT = "read_only";
+const SCOPED_WRITE_ENFORCEMENT = "scoped_write";
+const ROW_LIMIT_GUARDRAIL = "row_limit";
+const STATEMENT_TIMEOUT_GUARDRAIL = "statement_timeout";
+const DRILL_DEPTH_LIMIT_GUARDRAIL = "drill_depth_limit";
+/**
+ * Maps an agent's `guardrails` to the harness's enforcement seams: a locked
+ * `read_only` guardrail sets `readOnly`; a locked `scoped_write` guardrail
+ * (with a `scope`) sets `artifactWriteScope`; `threshold_limit` / `generic`
+ * guardrails are matched by guardrail *key* (not just `enforcement`, since
+ * `row_limit` and `drill_depth_limit` share the `threshold_limit`
+ * enforcement kind) onto named numeric limits.
+ *
+ * `read_only_execution` and a locked `scoped_write` guardrail coexisting
+ * (`generate_dashboard`, `explain_change` in the golden bundle) is not a
+ * contradiction: the former restricts *data access* (no write-capable
+ * SQL/tool becomes active), the latter grants a narrow, separate permission
+ * to write the rendered *output artifact* inside `scope`. This is exactly
+ * why the two fields are independent here rather than one overriding the
+ * other — `LocalExecutionEnv.writeFile` (`harness/exec/local.ts`) reflects this
+ * directly, consulting only `artifactWriteScope`, never `readOnly`.
+ */
+export function deriveEnforcement(agent) {
+    let readOnly = false;
+    let artifactWriteScope;
+    let rowLimit;
+    let statementTimeoutSec;
+    let drillDepthLimit;
+    for (const [key, guardrail] of Object.entries(agent.guardrails)) {
+        if (guardrail.enforcement === READ_ONLY_ENFORCEMENT && guardrail.locked) {
+            readOnly = true;
+            continue;
+        }
+        if (guardrail.enforcement === SCOPED_WRITE_ENFORCEMENT && guardrail.locked && guardrail.scope !== undefined) {
+            artifactWriteScope = guardrail.scope;
+            continue;
+        }
+        if (guardrail.threshold === undefined)
+            continue;
+        if (key === ROW_LIMIT_GUARDRAIL) {
+            rowLimit = guardrail.threshold;
+        }
+        else if (key === STATEMENT_TIMEOUT_GUARDRAIL) {
+            statementTimeoutSec = guardrail.threshold;
+        }
+        else if (key === DRILL_DEPTH_LIMIT_GUARDRAIL) {
+            drillDepthLimit = guardrail.threshold;
+        }
+    }
+    return {
+        readOnly,
+        ...(artifactWriteScope !== undefined ? { artifactWriteScope } : {}),
+        ...(rowLimit !== undefined ? { rowLimit } : {}),
+        ...(statementTimeoutSec !== undefined ? { statementTimeoutSec } : {}),
+        ...(drillDepthLimit !== undefined ? { drillDepthLimit } : {}),
+    };
+}

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

@@ -0,0 +1,37 @@
+export { loadBundle, loadBundleWithProvenance, BundleValidationError } from "./bundle/loader.js";
+export type { BundleProvenance } from "./bundle/loader.js";
+export { bundleFormatVersion } from "./bundle/schema.js";
+export { assertCompat, BundleCompatError, HARNESS_SUPPORT } from "./bundle/version.js";
+export type { HarnessSupport } from "./bundle/version.js";
+export type { Agent, Bundle, Capability, Guardrail, OutputSchema, Step, StepGuard, StepRealization, Tool, } from "./bundle/schema.js";
+export { createDefaultCapabilityRegistry, createRegistry, DEFAULT_CAPABILITIES, } from "./capability/registry.js";
+export type { CapabilityRegistry } from "./capability/registry.js";
+export { assertCapabilities, CapabilityGateError } from "./capability/gate.js";
+export { ANTHROPIC_ADAPTER_ID, createAnthropicAdapter, createDefaultProviderRegistry, createMockAdapter, createOpenAICompatibleAdapter, createProviderRegistry, MOCK_ADAPTER_ID, OPENAI_COMPATIBLE_ADAPTER_ID, resolveStepModel, resolveTierModel, UnknownAdapterError, UnknownTierError, } from "./providers/index.js";
+export type { AdapterFactory, AdapterSpec, AnthropicAdapterConfig, MockAdapterConfig, OpenAICompatibleAdapterConfig, ProviderRegistry, TierBinding, } from "./providers/index.js";
+export { AgentScopeError, executeAgent, InvalidRepairFoldError, passthroughGuardEvaluator, RepairExhaustedError, } from "./loop/index.js";
+export type { DataflowArtifacts, ExecuteAgentContext, GuardEvaluator, StepGuardContext, ToolCallOutcome, ToolCallOutcomeListener, } from "./loop/index.js";
+export { createAgentEventEmitter, MalformedSseFrameError, parseAgentEvent, serializeAgentEvent, } from "./events/index.js";
+export type { AgentEvent, AgentEventBase, AgentEventEmitter, AgentEventInput, AgentEventKind, AnswerAgentEvent, ArtifactAgentEvent, ArtifactKind, ErrorAgentEvent, RefusalAgentEvent, RunFinishEvent, RunStartEvent, StepFinishEvent, StepStartEvent, StepTrace, TokenEvent, ToolCallEvent, ToolResultEvent, TraceStep, } from "./events/index.js";
+export { BUILD_DASHBOARD_TOOL_NAME, connectMcpServer, createDefaultNativeToolRegistry, createNativeToolRegistry, createWrenNativeToolRegistry, createWrenQueryTool, createWriteArtifactTool, McpServerNotConfiguredError, McpToolNotExposedError, parseToolSource, resolveTools, UnknownNativeToolError, UnsupportedToolSourceError, withResolvedTools, WREN_QUERY_TOOL_NAME, WrenQueryExecutionError, WRITE_ARTIFACT_TOOL_NAME, } from "./tools/index.js";
+export type { McpServerConfig, McpServerConfigMap, NativeToolFactory, NativeToolRegistry, ParsedToolSource, ResolvedTools, ResolveToolsContext, WrenNativeToolOptions, WrenQueryResult, WrenQueryToolOptions, } from "./tools/index.js";
+export { deriveEnforcement } from "./guardrails/index.js";
+export type { EnforcementPolicy } from "./guardrails/index.js";
+export { EgressNotAllowedError, PathTraversalError, ReadOnlyViolationError, WriteScopeNotGrantedError, createLocalExecutionEnv, } from "./exec/index.js";
+export type { ExecCommand, ExecMode, ExecResult, ExecutionEnv, ExecutionPolicy, FetchRequest, FetchResponse, LocalExecutionEnvOptions, } from "./exec/index.js";
+export { collectJsonSchemaErrors, EnvelopeParseError, EnvelopeSchemaError, extractEnvelopeFromText, NoRenderTierError, renderEnvelope, } from "./render/index.js";
+export type { JsonSchemaDocument, RenderEnvelope, RenderEnvelopeContext } from "./render/index.js";
+export { findLockedGatedCheck, runAgent, UnknownAgentError } from "./session/index.js";
+export type { AnswerResult, RefusalResult, RunAgentContext, RunAgentResult } from "./session/index.js";
+export { createDefaultLoginProbe, detectAndPick, toAuthChoice } from "./auth/index.js";
+export type { ApiKeyAuthChoice, AuthChoice, AuthOption, GatewayAuthChoice, LocalAuthChoice, LoginProbe, SubscriptionAuthChoice, } from "./auth/index.js";
+export { compileProfile, compileRawProfile, composeUserProfile, createFileSystemCompileCache, createInMemoryCompileCache, extractContextBindingPath, hashDirectory, InvalidProfileShapeError, resolveHubDir, resolveWarbleBinary, runWarble, rewriteContextBindingProject, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./compile/index.js";
+export type { CompileCache, CompileCacheEntry, CompileCacheKey, CompileMode, CompileProfileOptions, CompileProfileResult, CompileRawProfileOptions, } from "./compile/index.js";
+export { AgentSdkCliNotFoundError, buildAgentSdkChatArgs, buildAgentSdkManifestArgs, buildCodexAskArgs, buildHybridTierBinding, buildUniformTierBinding, DEFAULT_LOCAL_ENDPOINT, DEFAULT_LOCAL_MODEL, deriveAdapterSpec, describeBundle, DispatchedSessionError, resolveAgentSdkCli, resolveArtifactContent, resolveArtifactsDir, resolveDefaultEnrichIrPath, resolveDefaultProfileSource, resolveDefaultSetupIrPath, route, runAgentSdkManifest, runInProcessDefault, runDispatchedDefault, runCodexAskDefault, } from "./route/index.js";
+export type { AgentSdkChatCommand, AgentSdkManifestCommand, ArtifactContentDto, ArtifactContentUnavailableReason, BuildAgentSdkChatArgsOptions, BuildAgentSdkManifestArgsOptions, DeriveAdapterSpecOptions, DescribeBundleOptions, InProcessExecutor, InProcessOptions, CodexAskExecutor, CodexAskOptions, CodexAskResult, DispatchedExecutor, DispatchedOptions, DispatchedResult, ResolvedCli, RouteOptions, RouteResult, } from "./route/index.js";
+export { ComplianceError, enforceCompliance, SUBSCRIPTION_TOS_WARNING } from "./compliance/index.js";
+export { BUILD_CONTEXT_AGENT_ID, CONNECT_SOURCE_AGENT_ID, DEFAULT_SETUP_MAX_TURNS, CodexSetupRunner, contextLifecycleIdentityFingerprint, InProcessSetupRunner, DispatchedSetupRunner, parseSetupTerminal, recordedContextLifecyclePrefix, selectSetupRunnerForAuth, } from "./setup/runner.js";
+export type { CodexSetupRunnerOptions, InProcessSetupRunnerOptions, DispatchedSetupRunnerOptions, SetupStepRunner, SetupRunnerSet, SetupStepRunOptions, SetupStepRunResult, SetupTerminalContext, SetupTerminalResult, SetupTerminalStatus, ContextLifecyclePrefix, } from "./setup/runner.js";
+export type { ComplianceResult, Deployment } from "./compliance/index.js";
+export { NATIVE_PRODUCER_VERSION, createNativeProducerCassette, createRouteNativeProducer, nativeProducerCassetteKey, produceNoninteractiveNative, replayNoninteractiveNative, } from "./native-producer/index.js";
+export type { NativeProducerArtifactReference, NativeProducerCassette, NativeProducerDispatch, NativeProducerDispatchInput, NativeProducerDispatchResult, NativeProducerErrorCode, NativeProducerFailure, NativeProducerHostFence, NativeProducerLifecycle, NativeProducerLifecycleState, NativeProducerOptions, NativeProducerRequest, NativeProducerResponse, NativeProducerScope, NativeProducerSuccess, NativeProducerVendor, } from "./native-producer/index.js";

package/dist-server/harness/index.js

@@ -0,0 +1,19 @@
+export { loadBundle, loadBundleWithProvenance, BundleValidationError } from "./bundle/loader.js";
+export { bundleFormatVersion } from "./bundle/schema.js";
+export { assertCompat, BundleCompatError, HARNESS_SUPPORT } from "./bundle/version.js";
+export { createDefaultCapabilityRegistry, createRegistry, DEFAULT_CAPABILITIES, } from "./capability/registry.js";
+export { assertCapabilities, CapabilityGateError } from "./capability/gate.js";
+export { ANTHROPIC_ADAPTER_ID, createAnthropicAdapter, createDefaultProviderRegistry, createMockAdapter, createOpenAICompatibleAdapter, createProviderRegistry, MOCK_ADAPTER_ID, OPENAI_COMPATIBLE_ADAPTER_ID, resolveStepModel, resolveTierModel, UnknownAdapterError, UnknownTierError, } from "./providers/index.js";
+export { AgentScopeError, executeAgent, InvalidRepairFoldError, passthroughGuardEvaluator, RepairExhaustedError, } from "./loop/index.js";
+export { createAgentEventEmitter, MalformedSseFrameError, parseAgentEvent, serializeAgentEvent, } from "./events/index.js";
+export { BUILD_DASHBOARD_TOOL_NAME, connectMcpServer, createDefaultNativeToolRegistry, createNativeToolRegistry, createWrenNativeToolRegistry, createWrenQueryTool, createWriteArtifactTool, McpServerNotConfiguredError, McpToolNotExposedError, parseToolSource, resolveTools, UnknownNativeToolError, UnsupportedToolSourceError, withResolvedTools, WREN_QUERY_TOOL_NAME, WrenQueryExecutionError, WRITE_ARTIFACT_TOOL_NAME, } from "./tools/index.js";
+export { deriveEnforcement } from "./guardrails/index.js";
+export { EgressNotAllowedError, PathTraversalError, ReadOnlyViolationError, WriteScopeNotGrantedError, createLocalExecutionEnv, } from "./exec/index.js";
+export { collectJsonSchemaErrors, EnvelopeParseError, EnvelopeSchemaError, extractEnvelopeFromText, NoRenderTierError, renderEnvelope, } from "./render/index.js";
+export { findLockedGatedCheck, runAgent, UnknownAgentError } from "./session/index.js";
+export { createDefaultLoginProbe, detectAndPick, toAuthChoice } from "./auth/index.js";
+export { compileProfile, compileRawProfile, composeUserProfile, createFileSystemCompileCache, createInMemoryCompileCache, extractContextBindingPath, hashDirectory, InvalidProfileShapeError, resolveHubDir, resolveWarbleBinary, runWarble, rewriteContextBindingProject, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./compile/index.js";
+export { AgentSdkCliNotFoundError, buildAgentSdkChatArgs, buildAgentSdkManifestArgs, buildCodexAskArgs, buildHybridTierBinding, buildUniformTierBinding, DEFAULT_LOCAL_ENDPOINT, DEFAULT_LOCAL_MODEL, deriveAdapterSpec, describeBundle, DispatchedSessionError, resolveAgentSdkCli, resolveArtifactContent, resolveArtifactsDir, resolveDefaultEnrichIrPath, resolveDefaultProfileSource, resolveDefaultSetupIrPath, route, runAgentSdkManifest, runInProcessDefault, runDispatchedDefault, runCodexAskDefault, } from "./route/index.js";
+export { ComplianceError, enforceCompliance, SUBSCRIPTION_TOS_WARNING } from "./compliance/index.js";
+export { BUILD_CONTEXT_AGENT_ID, CONNECT_SOURCE_AGENT_ID, DEFAULT_SETUP_MAX_TURNS, CodexSetupRunner, contextLifecycleIdentityFingerprint, InProcessSetupRunner, DispatchedSetupRunner, parseSetupTerminal, recordedContextLifecyclePrefix, selectSetupRunnerForAuth, } from "./setup/runner.js";
+export { NATIVE_PRODUCER_VERSION, createNativeProducerCassette, createRouteNativeProducer, nativeProducerCassetteKey, produceNoninteractiveNative, replayNoninteractiveNative, } from "./native-producer/index.js";

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

@@ -0,0 +1,53 @@
+/**
+ * Thrown when an agent falls outside the v1 execution scope. v1 only
+ * executes `analytical` / `one_shot` / `none` agents — anything else
+ * (mutating components, scheduled/event triggers, assertion/mutation
+ * outcomes) is a later milestone's concern, not this executor's.
+ */
+export declare class AgentScopeError extends Error {
+    constructor(agentId: string, componentType: string, trigger: string, outcome: string);
+}
+/**
+ * Thrown when a `repair_fold` step's shape doesn't match the fold-into-loop
+ * error-recovery mechanism's closed contract: its `when` guard must be
+ * `on_failure` targeting the same step named by `realization.fold_into`,
+ * that target must exist among the agent's other steps, at most one
+ * repair_fold may bind to a given target, and the target must itself be a
+ * tools-bearing step (this mechanism only ever detects failure via a tool-error content
+ * part, so a fold onto a no-tools step can never fire).
+ */
+export declare class InvalidRepairFoldError extends Error {
+    constructor(stepName: string, reason: string);
+}
+/**
+ * Thrown when a repair_fold's `max_attempts` budget is exhausted and the
+ * folded-into step's tool loop is still seeing a tool-execution error. The
+ * fold-into-loop mechanism never retries silently or infinitely (it is bounded,
+ * with a hard exhaustion guarantee) — exhaustion is a loud failure, since the golden
+ * `answer_query` shape declares no `fallback`.
+ */
+export declare class RepairExhaustedError extends Error {
+    constructor(targetStep: string, repairStep: string, maxAttempts: number);
+}
+/**
+ * Thrown when a step's `ToolLoopAgent` turn is cut off by its configured step
+ * budget (`ExecuteAgentContext.maxSteps`) before the model finished on its
+ * own. `ToolLoopAgent` itself does not throw in this case — hitting its
+ * `stopWhen` condition (`isStepCount(maxSteps)`) makes `generate()` return
+ * normally with whatever partial text/tool results happened to exist at that
+ * point, indistinguishable at the SDK layer from a clean finish unless the
+ * caller checks `finishReason` itself. This executor treats that silent
+ * cutoff as a loud, distinguishable failure instead of quietly storing the
+ * partial text as if the step had completed normally — mirroring
+ * {@link RepairExhaustedError}'s "exhaustion is never a silent swallow" stance.
+ *
+ * Only ever thrown when `maxSteps` was explicitly configured (never for a
+ * caller that leaves it unset, e.g. the Ask path) — see
+ * `ExecuteAgentContext.maxSteps`'s own doc comment.
+ */
+export declare class StepBudgetExhaustedError extends Error {
+    readonly stepId: string;
+    readonly maxSteps: number;
+    readonly stepsCompleted: number;
+    constructor(stepId: string, maxSteps: number, stepsCompleted: number);
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Thrown when an agent falls outside the v1 execution scope. v1 only
+ * executes `analytical` / `one_shot` / `none` agents — anything else
+ * (mutating components, scheduled/event triggers, assertion/mutation
+ * outcomes) is a later milestone's concern, not this executor's.
+ */
+export class AgentScopeError extends Error {
+    constructor(agentId, componentType, trigger, outcome) {
+        super(`agent "${agentId}" is out of v1 scope for executeAgent: ` +
+            `component_type="${componentType}", trigger="${trigger}", outcome="${outcome}" ` +
+            `(v1 only supports component_type="analytical", trigger="one_shot", outcome="none")`);
+        this.name = "AgentScopeError";
+    }
+}
+/**
+ * Thrown when a `repair_fold` step's shape doesn't match the fold-into-loop
+ * error-recovery mechanism's closed contract: its `when` guard must be
+ * `on_failure` targeting the same step named by `realization.fold_into`,
+ * that target must exist among the agent's other steps, at most one
+ * repair_fold may bind to a given target, and the target must itself be a
+ * tools-bearing step (this mechanism only ever detects failure via a tool-error content
+ * part, so a fold onto a no-tools step can never fire).
+ */
+export class InvalidRepairFoldError extends Error {
+    constructor(stepName, reason) {
+        super(`repair_fold step "${stepName}" is not a valid repair fold: ${reason}`);
+        this.name = "InvalidRepairFoldError";
+    }
+}
+/**
+ * Thrown when a repair_fold's `max_attempts` budget is exhausted and the
+ * folded-into step's tool loop is still seeing a tool-execution error. The
+ * fold-into-loop mechanism never retries silently or infinitely (it is bounded,
+ * with a hard exhaustion guarantee) — exhaustion is a loud failure, since the golden
+ * `answer_query` shape declares no `fallback`.
+ */
+export class RepairExhaustedError extends Error {
+    constructor(targetStep, repairStep, maxAttempts) {
+        super(`step "${targetStep}" exhausted its repair budget: repair_fold step "${repairStep}" ` +
+            `allows at most ${maxAttempts} attempt(s), but a tool call still failed after that many repair turns`);
+        this.name = "RepairExhaustedError";
+    }
+}
+/**
+ * Thrown when a step's `ToolLoopAgent` turn is cut off by its configured step
+ * budget (`ExecuteAgentContext.maxSteps`) before the model finished on its
+ * own. `ToolLoopAgent` itself does not throw in this case — hitting its
+ * `stopWhen` condition (`isStepCount(maxSteps)`) makes `generate()` return
+ * normally with whatever partial text/tool results happened to exist at that
+ * point, indistinguishable at the SDK layer from a clean finish unless the
+ * caller checks `finishReason` itself. This executor treats that silent
+ * cutoff as a loud, distinguishable failure instead of quietly storing the
+ * partial text as if the step had completed normally — mirroring
+ * {@link RepairExhaustedError}'s "exhaustion is never a silent swallow" stance.
+ *
+ * Only ever thrown when `maxSteps` was explicitly configured (never for a
+ * caller that leaves it unset, e.g. the Ask path) — see
+ * `ExecuteAgentContext.maxSteps`'s own doc comment.
+ */
+export class StepBudgetExhaustedError extends Error {
+    stepId;
+    maxSteps;
+    stepsCompleted;
+    constructor(stepId, maxSteps, stepsCompleted) {
+        super(`step "${stepId}" exhausted its step budget (${maxSteps} tool-loop steps) before finishing — ` +
+            `${stepsCompleted} other step(s) had already produced their artifact`);
+        this.stepId = stepId;
+        this.maxSteps = maxSteps;
+        this.stepsCompleted = stepsCompleted;
+        this.name = "StepBudgetExhaustedError";
+    }
+}

package/dist-server/harness/loop/executor.d.ts

@@ -0,0 +1,123 @@
+import { type ToolSet } from "ai";
+import type { Agent } from "../bundle/schema.js";
+import type { AgentEventInput } from "../events/index.js";
+import type { ProviderRegistry, TierBinding } from "../providers/index.js";
+import { type GuardEvaluator } from "./guard.js";
+/** Dataflow artifact state: artifact name -> the value its producing step returned. */
+export type DataflowArtifacts = ReadonlyMap<string, unknown>;
+/**
+ * This tool-call-outcome observer seam, widened for the live-event layer: fired for every tool call that
+ * completes inside a `ToolLoopAgent` turn (`runToolLoopStep`/
+ * `runToolLoopStepWithRepair`), once per `tool-result` (`"success"`) or
+ * `tool-error` (`"error"`) content part across every step of the turn.
+ * `input`/`callId` are sourced straight off that content part (both AI SDK
+ * v7 `tool-result` and `tool-error` parts already carry `input` themselves
+ * — no cross-referencing a separate `tool-call` part is needed).
+ * `runAgent`'s deterministic `gated_check` gate (`harness/session/run.ts`)
+ * consumes `tool`/`outcome` to track whether a data-access tool call ever
+ * genuinely succeeded, independent of the model's own self-attested
+ * `verified` claim; the same firings also feed the FLOOR `StepTrace`.
+ */
+export interface ToolCallOutcome {
+    readonly tool: string;
+    readonly outcome: "success" | "error";
+    readonly callId?: string;
+    readonly input?: unknown;
+    /**
+     * The tool's structured return value (AI SDK v7 `tool-result` part's
+     * `output`), present only on `"success"`. Carried so a consumer can build
+     * a deterministic render envelope straight from a data-access tool's real
+     * result (e.g. the `query` tool's `{columns, rows}`) instead of relying on
+     * the step model to re-emit that structure as text — see `runAgent`.
+     */
+    readonly output?: unknown;
+    /**
+     * The tool-error part's derived human message ({@link describeError}),
+     * present only on `"error"`. Carried so a consumer (e.g. `runAgent`'s
+     * `TraceStep` enrichment) can surface *why* a failed tool call failed —
+     * e.g. the SQL-repair retry's `query` steps — without re-deriving it from
+     * a raw `unknown` error value itself.
+     */
+    readonly error?: string;
+}
+export type ToolCallOutcomeListener = (outcome: ToolCallOutcome) => void;
+export interface ExecuteAgentContext {
+    /** Tier -> adapter binding; resolves each step's model. */
+    readonly binding: TierBinding;
+    readonly registry: ProviderRegistry;
+    /**
+     * Tool set injected by the caller. This executor does not resolve `agent.tools[]`
+     * from the bundle itself (that native + `mcp:wren/*` resolution happens earlier) — the caller
+     * hands the executor an already-realized AI SDK tool set (or `{}` for a
+     * no-tools run).
+     */
+    readonly tools: ToolSet;
+    /** The user's question, threaded into every step's rendered prompt. */
+    readonly userInput: string;
+    /** Guard-eval seam for step-level repair/guard behavior. Defaults to an always-true pass-through. */
+    readonly evaluateGuard?: GuardEvaluator;
+    /**
+     * Per-step `ToolLoopAgent` step budget (an `isStepCount(maxSteps)` stop
+     * condition). Optional and unset by default, in which case every
+     * tools-bearing step falls back to `ToolLoopAgent`'s own SDK default of 20
+     * steps (`ai`'s `ToolLoopAgent.prepareCall()`: `stopWhen: this.settings.stopWhen
+     * ?? isStepCount(20)`) — that default applied silently to every caller of
+     * this executor even before this field existed; it just had no name. Only
+     * `InProcessSetupRunner` sets this today (to `DEFAULT_SETUP_MAX_TURNS`,
+     * `harness/setup/runner.ts`) — `runAgent`'s Ask-turn path
+     * (`harness/session/run.ts`) never sets it, so its behavior (the SDK's own
+     * 20-step default) is unchanged by this field's existence. When a
+     * tools-bearing step's turn is cut off by this budget before the model
+     * finished on its own, `executeAgent` throws {@link StepBudgetExhaustedError}
+     * instead of silently storing the turn's partial text as if it had
+     * completed normally — see that error's own doc comment.
+     */
+    readonly maxSteps?: number;
+    /** Optional observer for every tool call's success/error outcome. See {@link ToolCallOutcomeListener}. */
+    readonly onToolCallOutcome?: ToolCallOutcomeListener;
+    /**
+     * Live-event layer: optional sink for `step.*`/`tool.*`/`artifact`
+     * events as `executeAgent` produces them. Typed as `AgentEventInput`
+     * (no `runId`/`seq`) rather than the contract's literal `(e: AgentEvent)
+     * => void` — `runAgent` is the natural single owner of that run-level
+     * bookkeeping (via `createAgentEventEmitter`); `executeAgent`'s job is
+     * only to describe *what happened* at step/tool granularity. `runAgent`
+     * passes its emitter's `emit` method down as this field's value. Emitted
+     * events always carry `depth: 0` and no `parent` — in-process (this
+     * executor) has no sub-agent/Task mechanism, so nesting is structurally
+     * unavailable here.
+     */
+    readonly onEvent?: (event: AgentEventInput) => void;
+}
+/**
+ * Runs an agent's `steps[]` over a dataflow artifact state (option (b)):
+ * a step becomes runnable once every artifact it `consumes` is present, and
+ * on completion it stores its `produces` artifact. Step order is *derived*
+ * from consumes/produces satisfaction, not from the array's emergent index.
+ *
+ * Tool granularity is agent-level in the bundle, not per-step: if the agent
+ * declares `tools`, every (non-repair_fold) step runs as a `ToolLoopAgent`
+ * turn with the injected tool set (tool calls are emergent — a given step
+ * may make zero); otherwise every step is a single `generateText` call.
+ * A future milestone may refine this to scope tools per step.
+ *
+ * `realization.kind: "repair_fold"` steps are recognized but never run as
+ * independent top-level steps — instead each one folds into its
+ * `fold_into` target's tool-loop as a bounded error-recovery turn: when the
+ * target step's most recent turn surfaces a tool-execution error, the next
+ * turn's model and instructions swap to the repair step's, bounded by
+ * `max_attempts`. The DAG stays acyclic — this is a loop-internal retry, not
+ * a dataflow back-edge — and exhaustion is a loud failure
+ * ({@link RepairExhaustedError}), never a silent swallow or infinite retry.
+ *
+ * Returns the final dataflow artifact state — not a render envelope
+ * (the two-stage structured-output envelope is built in `harness/render/`).
+ */
+export declare function executeAgent(agent: Agent, ctx: ExecuteAgentContext): Promise<DataflowArtifacts>;
+/**
+ * Best-effort, bounded-length human summary of a tool's `output`, for
+ * `ToolResultEvent.summary`. Exported so `harness/session/run.ts` can build a
+ * `TraceStep.detail` for a successful outcome from the same seam, without
+ * duplicating the truncation logic.
+ */
+export declare function summarizeToolOutput(output: unknown): string | undefined;