@wrenai/genbi 0.0.1

package/dist-server/harness/setup/runner.d.ts

@@ -0,0 +1,497 @@
+import type { AuthChoice } from "../auth/index.js";
+import { type AgentEvent } from "../events/index.js";
+import { StepBudgetExhaustedError } from "../loop/index.js";
+export { StepBudgetExhaustedError };
+import type { AdapterSpec } from "../providers/index.js";
+import type { ResolvedCli } from "../route/agent-sdk-cli.js";
+/** The warble component the setup wizard's connect step dispatches. */
+export declare const CONNECT_SOURCE_AGENT_ID = "connect_source";
+/** The Warble component the setup wizard's context step dispatches (`profiles/genbi-setup/components/build_context`). */
+export declare const BUILD_CONTEXT_AGENT_ID = "build_context";
+/**
+ * Default agent-loop budget for setup turns, forwarded as `warble-agent-sdk
+ * chat --max-turns`. Well above the dispatcher's own default (40) because
+ * `build_context` agentically generates an MDL — many read/introspect/write/
+ * build/validate tool calls — and routinely blows past 40, failing the turn
+ * with `error_max_turns`. Overridable via `DispatchedSetupRunnerOptions.maxTurns`
+ * (wired to `WREN_HARNESS_SETUP_MAX_TURNS` in `server/bin.ts`).
+ */
+export declare const DEFAULT_SETUP_MAX_TURNS = 120;
+export interface SetupStepRunOptions {
+    /** The composed single-line prompt (see `composeSetupPrompt`). */
+    readonly prompt: string;
+    /** The workspace root the initial connect turn scaffolds `<name>/` into. */
+    readonly workspaceRoot: string;
+    /**
+     * The persisted, validated single-segment project name. Required by the
+     * project-bound `connect_resume` and `context` turns; optional only so
+     * pre-existing initial-connect callers retain their workspace-root cwd.
+     */
+    readonly projectName?: string;
+    /**
+     * Step semantics for the dispatch cwd. Initial `connect` is intentionally
+     * workspace-bound so it can scaffold; later turns are project-bound.
+     */
+    readonly stepKey?: "connect" | "connect_resume" | "context";
+    readonly authChoice: AuthChoice;
+    /**
+     * Which warble component to dispatch — `CONNECT_SOURCE_AGENT_ID` for the
+     * `connect`/`connect_resume` steps, `BUILD_CONTEXT_AGENT_ID` for the
+     * `context` step. Optional and defaults to `CONNECT_SOURCE_AGENT_ID` so
+     * every pre-existing caller/test (all predating the `context` step) keeps
+     * dispatching exactly what it always has without passing this explicitly.
+     */
+    readonly agentId?: string;
+    /** Forwarded to the dispatched executor so the turn's worklog streams identically to an Ask turn. */
+    readonly onEvent?: (event: AgentEvent) => void;
+    /**
+     * Plan A session resume: an SDK session id captured from an earlier turn's `SetupStepRunResult`
+     * (success) or its thrown error (failure — see `DispatchedSessionError`, `../route/dispatched.js`). When
+     * set, forwarded to `DispatchedOptions.resumeSessionId` so this turn resumes the SAME agent-sdk
+     * conversation instead of starting a fresh one. Omitted (or a runner that doesn't support it)
+     * falls back to the pre-existing fresh-dispatch behavior.
+     */
+    readonly resumeSessionId?: string;
+}
+export interface SetupStepRunResult {
+    /** The dispatched turn's final answer text — callers parse this via `parseSetupTerminal`. */
+    readonly finalText: string;
+    /**
+     * The SDK session id this turn ran under, for resuming a LATER turn via
+     * `SetupStepRunOptions.resumeSessionId`. Optional so pre-existing stub runners in tests aren't
+     * forced to return it (mirrors `SetupStepRunner.effectiveMaxTurns`'s optionality above);
+     * callers that need it treat an absent field the same as `undefined` — no session captured.
+     * `null` means the dispatcher itself reported no session id at all.
+     */
+    readonly sessionId?: string | null;
+}
+/**
+ * Backend-abstract seam for dispatching one setup-wizard turn. Implementations
+ * own how the `connect_source` component actually runs (dispatched subprocess
+ * today; a future in-process variant could implement this same
+ * interface) and are responsible for forwarding `onEvent` so the caller's SSE
+ * worklog streaming is unaffected by which backend served the turn.
+ */
+export interface SetupStepRunner {
+    run(options: SetupStepRunOptions): Promise<SetupStepRunResult>;
+    /**
+     * The `--max-turns` budget this runner will actually dispatch a given
+     * `agentId` with — the same value `run()` computes internally. Callers that
+     * need to *describe* a future dispatch (e.g. the `max_turns_continue`
+     * decision's "Continue (+N turns)" label — see `server/turn.ts`) call this
+     * instead of duplicating the resolution logic, so the label can never drift
+     * from what `run()` actually applies. Optional so pre-existing stub runners
+     * in tests aren't forced to implement it; callers fall back to
+     * `DEFAULT_SETUP_MAX_TURNS` when it's absent.
+     */
+    effectiveMaxTurns?(agentId: string): number | undefined;
+}
+export interface SetupRunnerSet {
+    readonly claudeSubscription: SetupStepRunner;
+    readonly codexSubscription: SetupStepRunner;
+    readonly nonSubscription: SetupStepRunner;
+}
+/** Single provider-aware selection seam shared by boot wiring and tests. */
+export declare function selectSetupRunnerForAuth(authChoice: AuthChoice, runners: SetupRunnerSet): SetupStepRunner;
+export interface DispatchedSetupRunnerOptions {
+    /** Path to the committed genbi-setup IR (e.g. `profiles/genbi-setup/ir.golden.json`) — see `resolveSetupIrPath`. */
+    readonly irPath: string;
+    readonly warbleBin?: string;
+    readonly agentSdkBin?: string;
+    readonly outDir?: string;
+    readonly workDir?: string;
+    /** Live dispatcher config generated from the persisted runtime tier rows. */
+    readonly getModelsConfig?: () => string | undefined;
+    /** Agent-loop budget forwarded as `--max-turns`; defaults to `DEFAULT_SETUP_MAX_TURNS` when unset. */
+    readonly maxTurns?: number;
+}
+/**
+ * Dispatches a setup-wizard turn over dispatched, bypassing `route()` entirely
+ * (unlike the Ask turn path) so it can perform its own, setup-specific
+ * subscription-mode check with a clear, actionable error message rather than
+ * `route()`'s generic in-process/B branch. Uses `DispatchedOptions.irPath` to skip
+ * `compileProfile` — there is no bound wren project yet during setup, so
+ * there is nothing to compile a profile against; the setup dispatch always
+ * runs the same fixed, warble-committed IR regardless of which project is
+ * being onboarded.
+ */
+export declare class DispatchedSetupRunner implements SetupStepRunner {
+    private readonly options;
+    constructor(options: DispatchedSetupRunnerOptions);
+    effectiveMaxTurns(agentId: string): number | undefined;
+    run(runOptions: SetupStepRunOptions): Promise<SetupStepRunResult>;
+}
+export interface CodexSetupRunnerOptions {
+    readonly irPath: string;
+    readonly getStrongModel: () => string;
+    readonly codexLocalBin?: string;
+    /** Test/dev override for a command with required prefix args. */
+    readonly codexLocalCli?: ResolvedCli;
+    readonly codexBin?: string;
+    readonly mcpServer?: ResolvedCli;
+    readonly timeoutMs?: number;
+}
+/**
+ * Setup-only Codex subscription runner. It invokes the target's `dispatch`
+ * command directly against the committed setup IR and exposes exactly one
+ * guarded MCP tool. Normal Ask routing never calls this class.
+ */
+export declare class CodexSetupRunner implements SetupStepRunner {
+    private readonly options;
+    constructor(options: CodexSetupRunnerOptions);
+    run(runOptions: SetupStepRunOptions): Promise<SetupStepRunResult>;
+}
+/**
+ * This package's bundled setup capability-provider fragment
+ * (`providers/setup.provider.yaml`) — the default `--provider` for
+ * `InProcessSetupRunner`'s dispatch, mirroring `compileProfile`'s own
+ * `DEFAULT_WREN_PROVIDER_PATH` constant (`harness/compile/pipeline.ts`).
+ */
+export declare const DEFAULT_SETUP_PROVIDER_PATH: string;
+export interface InProcessSetupRunnerOptions {
+    /** Path to the committed genbi-setup IR (e.g. `profiles/genbi-setup/ir.golden.json`) — same contract as `DispatchedSetupRunnerOptions.irPath`. */
+    readonly irPath: string;
+    readonly warbleBin?: string;
+    /** Overrides the bundled `providers/setup.provider.yaml` fragment `warble dispatch --provider` uses. */
+    readonly providerPath?: string;
+    /** Scratch dir the dispatched vercel bundle is written into; a fresh `mkdtemp` per run when unset. */
+    readonly outDir?: string;
+    /** Forwarded to `deriveAdapterSpec` for `authChoice.mode === "local"` (see its own doc comment). */
+    readonly model?: string;
+    /** Live strong-tier adapter/model binding from persisted runtime settings. */
+    readonly getStrongAdapterSpec?: (authChoice: AuthChoice) => AdapterSpec;
+    /**
+     * Agent-loop step budget forwarded as `ExecuteAgentContext.maxSteps`;
+     * resolved the same way as `DispatchedSetupRunnerOptions.maxTurns` via the
+     * shared `resolveEffectiveMaxTurns` (only `build_context` gets the raised
+     * `DEFAULT_SETUP_MAX_TURNS` budget by default; `connect`/`connect_resume`
+     * fall back to `ToolLoopAgent`'s own SDK default of 20 steps unless this
+     * is set). Wired to the same `WREN_HARNESS_SETUP_MAX_TURNS` env var as
+     * `DispatchedSetupRunnerOptions.maxTurns` in `server/bin.ts`.
+     */
+    readonly maxTurns?: number;
+}
+/**
+ * Dispatches a setup-wizard turn over in-process: the in-process vercel loop
+ * (`harness/loop/executor.ts`'s `executeAgent`), instead of shelling a
+ * claude-agent-sdk subprocess. Mirrors `DispatchedSetupRunner`'s own shape
+ * (same `SetupStepRunner` interface, same "bypass the per-user compile
+ * pipeline and dispatch the fixed, warble-committed setup IR directly"
+ * design) but reuses the in-process building blocks `harness/route/in-process.ts`'s
+ * `runInProcessDefault` wires together, minus the two pieces that don't apply to
+ * setup:
+ *
+ *  - No `resolveWrenBinary()` preflight — the setup components' only tool
+ *    (`setup_execution`, see `harness/tools/setup-native.ts`) never shells
+ *    the `wren` CLI directly; it's a general scoped exec/write pair, not a
+ *    wren-specific one.
+ *  - No `deriveEnforcement(agent)` (`harness/guardrails/policy.ts`) — that
+ *    function maps `read_only`/`scoped_write`/threshold guardrails onto an
+ *    `EnforcementPolicy` and has no branch for the `setup_execution`
+ *    guardrail shape (`{name: "setup_execution", locked: true, scope: "."}`)
+ *    the two setup components declare. Rather than widen that shared module
+ *    for a guardrail only this path uses, this runner builds its own fixed
+ *    `ExecutionPolicy` below, matching what `setup_execution` actually grants
+ *    on the dispatched (claude-agent-sdk) side: unrestricted exec (subject only
+ *    to the native tool's own destructive/redirection denylist, never
+ *    `readOnly`-gated) and a write scope of the whole workspace root.
+ *
+ * Unlike `DispatchedSetupRunner`, which forwards its `--max-turns` budget to a
+ * subprocess CLI flag, this runner's turn budget is an in-process
+ * `ExecuteAgentContext.maxSteps` (an `isStepCount` stop condition on the
+ * step's underlying `ToolLoopAgent`) — see `effectiveMaxTurns()` below for
+ * how it's resolved, and `StepBudgetExhaustedError` (`harness/loop/errors.ts`)
+ * for how a turn that runs out of steps before finishing is reported.
+ *
+ * Also calls `executeAgent` directly rather than the higher-level
+ * `runAgent()` in-process's Ask-turn path uses: `runAgent` asserts every
+ * `agent.capabilities[]` entry against a `CapabilityRegistry`, but
+ * `connect_source`/`build_context` declare `source_connect`/`context_build`
+ * — capabilities outside the fixed `DEFAULT_CAPABILITIES` set a wren-project
+ * Ask turn resolves. `executeAgent` (confirmed via `ExecuteAgentContext`'s
+ * own shape) has no `capabilityRegistry` concept at all, so it runs the
+ * bundle's dataflow with no capability assertion — exactly what dispatching
+ * a setup-only capability needs, without inventing a parallel registry for
+ * two names nothing else provides.
+ */
+export declare class InProcessSetupRunner implements SetupStepRunner {
+    private readonly options;
+    constructor(options: InProcessSetupRunnerOptions);
+    /**
+     * The `ExecuteAgentContext.maxSteps` budget this runner will actually pass
+     * into `executeAgent` for a given `agentId` — the same value `run()`
+     * computes internally. This was previously documented as always
+     * `undefined` on the theory that "`executeAgent` has no turn-budget
+     * concept at all" — that was already false when it was written: every
+     * tools-bearing step ran as a `ToolLoopAgent` turn, and `ToolLoopAgent`
+     * itself silently defaults to a 20-step budget (`ai`'s
+     * `stopWhen: this.settings.stopWhen ?? isStepCount(20)`) whenever nothing
+     * overrides it. There was a real, unconfigurable ceiling the whole time;
+     * it just had no name and nothing here reported it. Now that `run()` below
+     * threads an explicit `maxSteps` through, this reports the real value —
+     * mirroring `DispatchedSetupRunner.effectiveMaxTurns` — via the same
+     * `resolveEffectiveMaxTurns` helper so the two can never disagree.
+     */
+    effectiveMaxTurns(agentId: string): number | undefined;
+    run(runOptions: SetupStepRunOptions): Promise<SetupStepRunResult>;
+}
+export type SetupTerminalStatus = "ok" | "needs_input" | "error";
+export interface SetupTerminalContext {
+    /** The workspace root the project was scaffolded under. */
+    readonly root: string;
+    /** The project name (the scaffolded directory is `<root>/<name>`). */
+    readonly name: string;
+    /**
+     * Which setup step this terminal check is verifying — a string, not
+     * `SetupStepKey`, so this module (`harness/`) never has to import the BFF layer
+     * (`server/compose.ts`); callers pass `turn.setupStepKey` straight through.
+     * Undefined (or any value other than `"connect_resume"`/`"context"`) is
+     * treated exactly like `"connect"`, matching every pre-existing caller/test
+     * that never set this field.
+     *
+     * Three distinct `ok` verifications exist, one per step — a plain boolean
+     * stopped being expressive enough once `context` joined `connect`/
+     * `connect_resume`:
+     *
+     *  - `"connect"` (default): `<root>/<name>/wren_project.yml` must exist —
+     *    the scaffold this step is supposed to have just written.
+     *  - `"connect_resume"`: by the time this step runs, `wren_project.yml`
+     *    already exists (written during `connect`), so re-checking it would be
+     *    vacuous — it would let a resume's claimed "ok" pass on pure agent
+     *    self-report, defeating the "don't trust the agent" design. Instead this
+     *    checks for a distinct `.wren-validated` sentinel file, which
+     *    `composeSetupPrompt`'s `connect_resume` branch instructs the agent to
+     *    create ONLY after a successful `wren profile add`/validate call. A
+     *    sentinel file is used (rather than inspecting wren's own profile
+     *    registry, e.g. `~/.wren/profiles.yml`) because that registry's exact
+     *    path/format is not something this BFF can reliably assume is stable
+     *    across wren CLI versions/environments; the sentinel is fully within our
+     *    own control and lives right next to `wren_project.yml`.
+     *  - `"context"`: checks `<root>/<name>/target/mdl.json` — the artifact
+     *    `wren context build` writes by default (confirmed via `wren context
+     *    build --help`: "Build into target/mdl.json for the engine" — and by
+     *    inspecting a real built fixture, whose top-level shape is
+     *    `{ catalog, schema, models: [...], relationships, views, cubes,
+     *    dataSource, layoutVersion }`). A missing file, invalid JSON, a
+     *    `models` array with zero entries, or (when a worklog is available) no
+     *    successfully completed recognized schema
+     *    discovery command all downgrade a claimed "ok" to "error" — an agent
+     *    that ran `wren context build` against an empty/unfinished MDL project
+     *    must not be trusted just because it self-reports success.
+     *
+     * `needs_input` gets an analogous check, but only for `"connect"`
+     * (undefined/default): `needs_input` IS `connect`'s designed success
+     * ending — its own prompt (`composeSetupPrompt`) promises a scaffolded
+     * project directory, a `wren_project.yml`, and an empty `.env` template
+     * before it stops to wait for the user. Without this check, an agent that
+     * burned its whole turn on the skill's Preflight and produced none of
+     * those files could still report `needs_input`, and the wizard would offer
+     * the "I've filled in .env" affordance for a project that was never
+     * created. `connect_resume` and `context` do NOT get this check: neither
+     * step's prompt promises a NEW on-disk artifact as part of a `needs_input`
+     * ending (e.g. `context`'s `needs_input` is "ambiguous relationship,
+     * please confirm" — there is nothing new on disk to verify), so there is
+     * no analogous claim to hold them to.
+     */
+    readonly stepKey?: string;
+    /**
+     * The data source the user actually selected for this project (e.g.
+     * `"duckdb"`), as already known to the BFF from the setup form — never
+     * re-derived from anything an agent turn wrote. Only consulted when
+     * `stepKey === "connect_resume"`; every other step (and every
+     * pre-existing caller/test that omits this field) is unaffected.
+     *
+     * This backs a SECOND, additive `ok` check for `connect_resume`, layered
+     * on top of the `.wren-validated` sentinel check above: sentinel presence
+     * only proves *some* profile validated successfully, not that it was the
+     * *right* one. Two deliberately-NOT-taken approaches, for the record:
+     *
+     *  - Reading the onboarding skill's scratch file (`conn.profile.yml`)
+     *    directly: rejected. The skill's own happy path deletes that file the
+     *    moment validation succeeds (see `skills_content/onboarding/SKILL.md`
+     *    step 3.5), so a post-turn check reading it would be a no-op on
+     *    exactly the success case it exists to guard. It would also hardcode
+     *    that scratch filename into this BFF layer, which a prior decision
+     *    deliberately undid (this module is meant to stay agnostic of the
+     *    skill's internal scratch-file naming).
+     *  - Reading `~/.wren/profiles.yml`: already rejected above for the
+     *    sentinel check, for the same environment/version-stability reason.
+     *
+     * Instead this reads `<root>/<name>/wren_project.yml` — an artifact this
+     * module already reads elsewhere in this same function — and checks two
+     * of its fields against ground truth the wren CLI itself is responsible
+     * for keeping consistent:
+     *
+     *  1. `profile:` must be non-empty. The CLI's own
+     *     `maybe_pin_new_profile_to_project` gate (in `core/wren/src/wren/
+     *     context.py`) refuses to pin a profile whose datasource conflicts
+     *     with an already-declared one, leaving `profile:` unset — so an
+     *     empty `profile:` here means the CLI itself never committed to a
+     *     pin, regardless of what the agent claims.
+     *  2. `data_source:` must match this field (case-insensitive, trimmed).
+     *     `pin_profile` always writes `profile:` and `data_source:` together
+     *     from the SAME profile, so this catches the case the gate above
+     *     can't: an agent that force-repins via `wren context set-profile
+     *     <project>` (which has no mismatch gate — it's an explicit override)
+     *     onto a profile for the wrong data source.
+     *
+     * A mismatch or missing pin downgrades a claimed "ok" to "error" with a
+     * message that names the profile fields, not `.env` — the wrong-datasource
+     * failure mode this exists to catch has nothing to do with `.env`'s
+     * contents.
+     */
+    readonly expectedSourceType?: string;
+    /**
+     * The turn's tool-call worklog (a `ToolStep[]`, defined in
+     * `server/wire-types.ts`), declared here as a narrow LOCAL structural type
+     * rather than imported — for the same one-way-dependency reason `stepKey`
+     * above is a bare `string`, not `SetupStepKey`: this module (`harness/`)
+     * must never import from `server/`. Optional and additive: every existing
+     * caller/test that omits it keeps the exact pre-existing behavior below.
+     *
+     * Consulted when `stepKey === "context"`: an `ok` must have successful
+     * discovery evidence as well as the structural MDL gate, while an `error`
+     * still uses it for the diagnostic attribution described by
+     * {@link firstFailedExec}.
+     */
+    readonly worklog?: readonly SetupWorklogEntry[];
+    /**
+     * A host-recorded, identity-bound completed prefix from earlier corrective
+     * context attempts. Agent prose never supplies this value. It is optional
+     * so callers that only have one worklog retain the original behavior.
+     */
+    readonly priorContextLifecycle?: ContextLifecyclePrefix;
+}
+/**
+ * The minimal structural shape of a `ToolStep` (`server/wire-types.ts`) that
+ * {@link firstFailedExec} needs. Declared locally rather than imported — see
+ * `SetupTerminalContext.worklog`'s doc comment.
+ *
+ * `state` mirrors `ToolStep.state` and is ALREADY populated correctly, today,
+ * for every mode: `LiveWorkLog.ingest` (`server/fold.ts`) sets it straight
+ * from the originating `AgentEvent`'s own structured `status`/`outcome`
+ * field, and `server/turn.ts` passes that raw, unsanitized snapshot into
+ * `parseSetupTerminal` — no plumbing change was needed to expose it here.
+ * See {@link execSucceeded} for why it is trustworthy for a dispatched (`Bash`)
+ * entry but NOT for a in-process / Codex local (`setup_execution`-shaped) one.
+ */
+export interface SetupWorklogEntry {
+    readonly label: string;
+    readonly input?: unknown;
+    readonly detail?: string;
+    readonly state?: "running" | "done" | "error";
+}
+/**
+ * A non-secret, host-derived identity for retained context lifecycle proof.
+ * It deliberately binds the canonical on-disk project, the BFF-selected
+ * source type, wren's project-level profile declaration, and a non-secret
+ * digest of the effective connection target. If any required filesystem fact
+ * cannot be read or is ambiguous, callers must fail closed and not reuse
+ * evidence from an earlier attempt.
+ */
+export declare function contextLifecycleIdentityFingerprint(root: string, name: string, selectedSourceType: string): string | undefined;
+export interface SetupTerminalResult {
+    readonly status: SetupTerminalStatus;
+    readonly message: string;
+    /**
+     * A host-owned rejection of an agent's claimed `SETUP_STATUS: ok`.
+     *
+     * This is deliberately structured rather than inferred from the display
+     * message: `server/turn.ts` uses it to decide whether the completed,
+     * resumable agent session gets one corrective continuation. Agent-declared
+     * errors, dispatcher failures, cancellation, and timeouts do not create
+     * this diagnostic and therefore cannot enter that recovery path.
+     */
+    readonly diagnostic?: HostContractDiagnostic;
+    /**
+     * A deterministic workflow outcome, deliberately separate from the
+     * human-facing message so callers never have to re-classify prose.
+     * Present when a context turn needs the BFF's explicit bounded
+     * missing-discovery correction.
+     */
+    readonly failureKind?: "no_successful_schema_discovery" | "missing_terminal_status";
+}
+export type HostContractCode = "connect_artifact_missing" | "connection_marker_missing" | "connection_profile_missing" | "connection_source_mismatch" | "context_schema_discovery_missing" | "context_schema_discovery_failed" | "context_validate_missing" | "context_build_missing" | "context_lifecycle_out_of_order" | "context_mdl_missing" | "context_mdl_empty";
+/** Non-secret, host-owned evidence returned when a claimed setup success fails its artifact gate. */
+export interface HostContractDiagnostic {
+    readonly kind: "host_contract";
+    readonly code: HostContractCode;
+    /** What the BFF observed. This must remain safe to return to the agent. */
+    readonly observed: string;
+    /** The concrete artifact/workflow conditions that must be true before another claimed success. */
+    readonly expectedArtifactContract: readonly string[];
+}
+export type RecordedSchemaDiscovery = {
+    readonly kind: "successful";
+    readonly command: string;
+} | {
+    readonly kind: "failed";
+    readonly command: string;
+    readonly exitCode?: number;
+} | {
+    readonly kind: "none";
+};
+/**
+ * The single setup-workflow contract for recognisable schema discovery. A
+ * matching command is evidence only after it completed successfully (see
+ * {@link execSucceeded} for what "successfully" means per mode); command
+ * text alone proves neither execution nor a readable schema. Callers use
+ * this for both terminal acceptance and the no-introspection diagnostic,
+ * rather than reimplementing the allowlist elsewhere.
+ */
+export declare function classifyRecordedSchemaDiscovery(worklog: readonly SetupWorklogEntry[]): RecordedSchemaDiscovery;
+/** Ordered, host-recorded progress; each value includes all preceding work. */
+export type ContextLifecyclePrefix = "none" | "discovery" | "validate" | "build";
+export type RecordedContextLifecycle = {
+    readonly kind: "successful";
+} | {
+    readonly kind: "missing_discovery";
+} | {
+    readonly kind: "validate_missing";
+    readonly observed: string;
+} | {
+    readonly kind: "build_missing";
+    readonly observed: string;
+} | {
+    readonly kind: "out_of_order";
+    readonly observed: string;
+};
+/**
+ * Returns the greatest ordered prefix proved by the supplied successful tool
+ * calls. This intentionally retains an earlier valid prefix even if a later
+ * call in the same attempt is out of order, so a corrective attempt can ask
+ * only for the unproven suffix.
+ */
+export declare function recordedContextLifecyclePrefix(worklog: readonly SetupWorklogEntry[], prior?: ContextLifecyclePrefix): ContextLifecyclePrefix;
+export declare function classifyRecordedContextLifecycle(worklog: readonly SetupWorklogEntry[], prior?: ContextLifecyclePrefix): RecordedContextLifecycle;
+/**
+ * Parses the LAST `SETUP_STATUS: ok|needs_input|error` line out of a setup
+ * turn's finalText (the terminal contract lives in the composed
+ * prompt, not warble — the agent is instructed to emit this line, and an
+ * agent narrating its plan mid-message could emit misleading earlier
+ * "SETUP_STATUS"-like text, so only the last line counts).
+ *
+ * For `ok`, independently verifies an on-disk artifact before trusting the
+ * agent's self-report, rather than blindly advancing the wizard — see
+ * `SetupTerminalContext.stepKey`'s doc comment for exactly which artifact each
+ * step checks (`wren_project.yml` / `.wren-validated` / `target/mdl.json`
+ * with at least one model).
+ *
+ * The `context` step's `ok` check also requires a successfully completed
+ * recognized schema-discovery command whenever a worklog is available. It
+ * does NOT try to infer fabrication from model names or columns. Two semantic
+ * heuristics were considered and rejected as unsafe:
+ *   - Flagging a model literally named "example": a real warehouse can
+ *     genuinely have a table named "example" (the composed `context` prompt
+ *     itself explicitly tolerates a pre-existing "example" placeholder
+ *     surviving on disk), so this would false-positive on a legitimate build.
+ *   - Flagging models with zero columns: a fabricating agent writes
+ *     plausible-looking column lists (that's what makes the fabrication
+ *     convincing), so this wouldn't even have caught the real incident —
+ *     it's a weak signal with no compensating safety benefit.
+ * No cheap structural signal reliably distinguishes fabricated MDL from a
+ * real one. The completed-discovery gate is therefore the deterministic
+ * provenance boundary here; the prompt still tells the agent to never
+ * fabricate and to report failed discovery honestly as additional guidance.
+ */
+export declare function parseSetupTerminal(finalText: string, context: SetupTerminalContext): SetupTerminalResult;