eve 0.5.4 → 0.6.0-beta.10

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# eve
+
+## 0.6.0-beta.10
+
+### Minor Changes
+
+- 24c4b85: Dissolves the scaffold engine's step flows into the setup boxes. `eve channels add` now runs the same channel boxes as onboarding through the shared runner: the picker enforces the existing-registration conflict checks directly, the slackbot question moves ahead of any file write, and prompts can never interleave with side effects.
+
+  Removes the `eve/setup/scaffold/cli` and `eve/setup/scaffold/primitives` subpath exports. The terminal prompt adapters and process primitives now live in the setup island (`src/setup/cli/`, `src/setup/primitives/`), and the names `create-eve` consumes (`createPromptCommandOutput`, `detectDeployment`, `runPnpmInstall`, `spawnPnpm`, `runVercel`) are exported from `eve/setup` instead. The `eve/setup/scaffold` barrel is unchanged.
+
+- 24c4b85: Route setup questions through a single ask channel. Setup boxes now ask keyed question values through one injected `Asker` whose decorator stack (interactive base, headless base, pre-supplied answers, detected/recommended policies) decides how each question resolves; the select-model, select-chat, select-channels, and resolve-target boxes migrate onto the unified single-gather contract. The channel gains a paired `askMany` method for multi-select questions (whose `T[]` answers cannot ride `ask<T>`), with option-level `locked`/`disabled` row semantics enforced both by the interactive picker and by pre-supplied answer validation. A headless run that reaches a required question without an answer now fails with a structured `InteractionRequired` error naming the question key instead of a `HeadlessPromptError`.
+
+  The Vercel provisioning, channel-scaffold, connection, and deploy boxes now flow through that same channel: the provisioning deploy tree (deploy gate, new/link project, credential wiring, and the AI Gateway key as a sensitive text question rendered through the masked prompt), the slackbot create confirm, and the connection picker plus its custom MCP/OpenAPI sub-prompts are all keyed questions on the asker; the deploy box collapses its two constant gather faces into one. A headless run missing any required provisioning decision now refuses with `InteractionRequired` rather than `HeadlessPromptError`.
+
+  The remaining no-prompt boxes (preflight, scaffold, detect-ai-gateway, link-project, apply-ai-gateway-credential) collapse their dual gather faces into one. Boxes whose two faces differed by mode (preflight derives a model to validate only on a headless `--model`; scaffold skips the write on a headless re-run over an existing Eve project) take a `headless` factory option fixed at the composition site, mirroring the deploy box. With every box migrated, the `SetupBox` contract is now unified-gather only: the `SetupBox` type is the single unified interface and the `LegacySetupBox`/`UnifiedSetupBox` union, the `isUnifiedSetupBox` guard, and the `InteractiveOutcome` type are gone. Both runners call `box.gather` directly; cancel is signaled solely by a thrown `WizardCancelledError`.
+
+- 455866d: Slack authorization prompts are now visible only to the triggering user. The default `authorization.required` handler sends the sign-in link and device code as an ephemeral message, and falls back to a public link-free status only when it has no user to target. Breaking: an `events["authorization.required"]` override now receives a private-delivery context (`postEphemeral`, `postDirectMessage`, `state`) instead of the full event context, so it can change the message but not the audience. Adds `SlackThread.postDirectMessage`, which DMs a user via `conversations.open` and requires the `im:write` scope.
+
+## 0.6.0-beta.9
+
+### Minor Changes
+
+- 1cf3593: Evals gain hard assertions and CI-grade pass/fail. Suites and cases accept a `checks` array (built-ins on `eve/evals/checks`: `Checks.completed`, `Checks.didNotFail`, `Checks.toolCalled` with input/output matchers, `Checks.toolOrder`, `Checks.subagentCalled`, and more); any failed check fails the case and the `eve eval` exit code, while scores stay soft unless `--strict`. Derived facts are now typed records — `toolCalls`/`subagentCalls` carry inputs, outputs, and error state (breaking: previously `string[]`), plus new `inputRequests` and `parked` fields, and `Run.didNotFail` no longer passes runs parked on HITL input. The CLI takes positional suite ids (replacing `--suite`; `--all` is removed) and adds `--tag`, `--case`, `--strict`, and `--list`. Suite `model` is now optional and only required when a model-backed scorer needs it.
+- a648895: Make `agent.ts` optional. Agents without an `agent.ts` now default to
+  `anthropic/claude-sonnet-4.6`; when `agent.ts` is present, `model` remains required.
+
+### Patch Changes
+
+- 74cd2e5: Store local just-bash sandbox templates and sessions as normal on-disk directories instead of JSON filesystem snapshots, and prune stale `eve dev` runtime snapshots and local sandbox templates in the background.
+
+## 0.6.0-beta.8
+
+### Patch Changes
+
+- 02d5272: Discover Markdown-authored agent sources case-insensitively, including instructions, schedules, and packaged skills, while keeping module and directory names case-sensitive.
+- 8aeba87: Expand the deterministic authored-model mock so smoke fixtures can exercise ask-question, bash command, loaded-skill, and subagent-token flows without live model variance.
+- 8d087ff: Run the development server and terminal UI when `eve` is invoked without a command. Use `eve info` explicitly to inspect the resolved application.
+- abaca02: Recover from empty model responses instead of silently ending the turn. When a model call completes with no content (finishReason 'other', e.g. an AI Gateway 200 with an empty stream), the harness reissues the call once within the same step. If the reissue also comes back empty, conversations end with a recoverable, channel-visible failure and task runs end with a failed task result rather than nothing.
+
+## 0.6.0-beta.7
+
+### Minor Changes
+
+- edf9f1a: Redesign the `eve dev` terminal UI and add `Client.info()`.
+
+  The TUI now streams its transcript into the terminal's native scrollback instead of a bordered alt-screen, so scrolling, copy/paste, and the transcript all survive after you exit. The visual language follows the Vercel / Next.js CLI: a monochrome base with the `▲` brand mark, colored gutter glyphs per speaker, the `dots` spinner, and status icons (`✓` done, `⨯` error). Tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`) that expands under `--tools full`, subagent work is indented beneath a `◆` header, and a startup header prints the connected agent's model, instructions, tools, skills, and subagents. Subagents now default to `auto-collapsed`.
+
+  The prompt input gains shell-style editing: `↑`/`↓` cycle through your previously sent messages, `←`/`→`/Home/End/`Ctrl+A`/`Ctrl+E` move the caret, and `Ctrl+U`/`Ctrl+K`/`Ctrl+W` kill the line/word. Escape sequences that arrive split across reads (common with PTYs) are reassembled, and pasted text is sanitized of stray control bytes.
+
+  Failures read more cleanly: a terminal `session.failed` (or a dead-socket transport error) no longer leaves you stuck — the TUI starts a fresh session before the next prompt and notes it inline, so you can keep going. A failure cascade (`step.failed` → `turn.failed` → `session.failed`) renders one error block instead of three, and code bugs escaping user code show their stack trace dim beneath the headline (capped to a dozen lines; recognized provider/config failures keep their curated one-line summary). Error blocks no longer double-print a `Code: Code:` prefix and render docs links in cyan, and denied tool approvals settle to a `→ denied` line instead of a frozen `?`.
+
+  Captured server `stdout`/`stderr` renders as quiet, indented log runs: consecutive lines from the same source coalesce behind one `stdout ·` / `stderr ·` label with a hanging indent, runs get a blank line of breathing room on both sides, and nothing is ever truncated — a transcript can't be clicked open, so the full output is always shown.
+
+  `Client.info()` fetches the agent inspection payload (`GET /eve/v1/info`) — model id, instructions source, tools, skills, subagents, schedules, and sandbox — for both local and remote targets, returning the new `AgentInfoResult` type.
+
+## 0.6.0-beta.6
+
+### Minor Changes
+
+- ed176f9: Adds `eve setup`: in a fresh directory it runs the same guided onboarding as `create-eve` (name, Vercel project, model, channels, deploy); inside an existing agent it runs in-project setup. The onboarding flow now lives in the eve package as reusable setup boxes with split interactive/headless faces, and `create-eve` drives that shared flow, so the wizard behaves identically from either entry point.
+
+### Patch Changes
+
+- 5e87d70: Per-tool interactive authorization never leaks a raw `Required` error into
+  the model. When a tool's `auth` strategy is interactive but no callback URL
+  can be minted for the run, the tool now fails with a classified
+  `ConnectionAuthorizationFailedError` (`reason: "authorization_callback_unavailable"`,
+  non-retryable) instead of rethrowing the raw authorization error — which the
+  model would otherwise surface as a sign-in URL and loop on. Non-interactive
+  strategies still rethrow their original error, since they have no consent
+  flow to park on.
+
+## 0.6.0-beta.5
+
+### Patch Changes
+
+- ca1ca18: Per-tool authorization now evicts the rejected bearer from its per-step cache before re-running the consent flow, so a tool that re-reports `Required` (e.g. after a downstream `401`/`requireAuth()`) re-resolves a fresh token instead of re-reading the rejected one. This mirrors the MCP client's behavior. Documented the recommended pattern: map a provider `401` inside a tool's `execute` to `ctx.requireAuth()` so Eve re-challenges.
+
+## 0.6.0-beta.4
+
+### Patch Changes
+
+- 2aec0cf: Raise the derived `$eve.title` cap (`EVE_SESSION_TITLE_MAX_CHARS`) from 80 to 125 code points so Agent Runs titles keep more of the original prompt.
+- 5b69978: Fix `eve dev` source snapshots so monorepo-relative config paths and local workspace package links keep resolving from immutable dev-runtime snapshots.
+
+## 0.6.0-beta.3
+
+### Patch Changes
+
+- 3f71a5c: Add `repository`, `homepage`, and `bugs` metadata to published packages, ship the Apache-2.0 NOTICE file in npm tarballs, and add an `exports` map and `sideEffects: false` to `create-eve`.
+
+## 0.6.0-beta.2
+
+### Patch Changes
+
+- 3af511f: Bump `@workflow/core` to `5.0.0-beta.13`.
+- 5923ebc: fix(eve): prevent provider-executed tool calls from being emitted as client actions
+- beddb37: Prepare packages for open source: remove the internal `eve/dev-tui-test` subpath export, point the deployed home page and headless onboarding hints at the public docs site, add a README and packed CHANGELOG for `create-eve`, and remove internal doc references from runtime error messages.

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2013 Adobe Systems Incorporated
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+eve
+Copyright 2026 Vercel, Inc. and contributors
+
+This product includes software developed at Vercel, Inc.
+(https://vercel.com/).

package/README.md

@@ -1,146 +1,158 @@
 # Eve
 
-Tiny event helping JavaScript library.
-
-## eve(name, scope, varargs)
-Fires event with given `name`, given scope and other parameters.
-
-### Parameters
-- _name_  **string**
-    name of the _event_, dot (`.`) or slash (`/`) separated
-- _scope_  **object**
-    context for the event handlers
-- _varargs_  **...**
-    the rest of arguments will be sent to event handlers
+Eve is a filesystem-first framework for durable backend agents on Vercel.
+
+You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.
+
+The framework is called Eve. The published npm package is `eve`. The CLI binary is `eve`.
+
+## What Eve Prioritizes
+
+- Markdown-first authoring for instructions and procedures
+- TypeScript where typed runtime behavior matters
+- Durable message runs and follow-up turns
+- Inspectable compiled artifacts under `.eve/`
+- Per-agent sandbox with optional authored overrides
+- A stable HTTP protocol with explicit `continuationToken` and `sessionId` contracts
+- A runtime model that keeps channels, harnesses, and workflow execution separate
+
+## Authored Directory
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+└── agent/
+    ├── agent.ts           # additive runtime config (model, name, build, compaction, …)
+    ├── instructions.md    # always-on instructions prompt
+    ├── tools/             # typed executable integrations
+    ├── skills/            # optional named procedures the model can load on demand
+    ├── hooks/             # lifecycle and stream-event subscribers
+    ├── channels/          # message ingress and delivery (HTTP, Slack, …)
+    ├── connections/       # external MCP server connections
+    ├── sandbox/           # the agent's single sandbox (optional override)
+    ├── workspace/         # files seeded into the sandbox on each session
+    ├── subagents/         # specialist child agents (reuse `defineAgent`)
+    ├── schedules/         # recurring jobs
+    └── lib/               # shared authored code imported by other files
+```
 
-**Returns:**  **object** array of returned values from the listeners. Array has two methods `.firstDefined()` and `.lastDefined()` to get first or last not `undefined` value.
+## Authoring Helpers
 
-## eve.listeners(name)
-Internal method which gives you array of all event handlers that will be triggered by the given `name`.
+Every authored directory has a typed helper. Import each from the matching subpath:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated
+| Helper                                                                                                              | Subpath                               | Authored Location                                |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------ |
+| `defineAgent(...)`                                                                                                  | `eve`                                 | `agent.ts`, `subagents/<id>/agent.ts`            |
+| `defineInstructions(...)`                                                                                           | `eve/instructions`                    | `instructions.ts` (or `instructions.md`)         |
+| `defineTool(...)`, `defineBeveTool(...)`, `defineReadFileTool(...)`, `defineWriteFileTool(...)`, `disableTool(...)` | `eve/tools`                           | `tools/<name>.ts`                                |
+| `defineSkill(...)`, `getSkill(...)`                                                                                 | `eve/skills`                          | `skills/<name>.ts` (or `skills/<name>.md`)       |
+| `defineHook(...)`                                                                                                   | `eve/hooks`                           | `hooks/<slug>.ts`                                |
+| `defineChannel(...)`, `POST`, `GET`                                                                                 | `eve/channels`                        | `channels/<name>.ts`                             |
+| `eveChannel(...)`, `slackChannel(...)`, `vercelOidc(...)`                                                           | `eve/channels/eve`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
+| `defineSandbox(...)`                                                                                                | `eve/sandbox`                         | `sandbox.ts` (or `sandbox/sandbox.ts`)           |
+| `defineSchedule(...)`                                                                                               | `eve/schedules`                       | `schedules/<name>.ts` (or `schedules/<name>.md`) |
+| `defineEvalSuite(...)`                                                                                              | `eve/evals`                           | `evals/<name>.eval.ts`                           |
 
-**Returns:**  **array** array of event handlers
+Runtime accessors live on the subpath that owns the concern:
 
-## eve.separator(separator)
-If for some reasons you don’t like default separators (`.` or `/`) you can specify yours
-here. Be aware that if you pass a string longer than one character it will be treated as
-a list of characters.
+- `getSession()` — current session, turn, auth, parent lineage (`eve/context`)
+- `getSandbox()` — live sandbox handle for the current agent (`eve/sandbox`)
+- `getSkill(identifier)` — handle for a named skill visible to the current agent (`eve/skills`)
+- `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`eve/context`)
 
-### Parameters
-- _separator_  **string**
-    new separator. Empty string resets to default: `.` or `/`.
+The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/reference/typescript-api.md`](./dist/docs/public/reference/typescript-api.md).
 
+## Tiny Example
 
-## eve.on(name, f, name, f)
-Binds given event handler with a given name. You can use wildcards “`*`” for the names:
+`agent/instructions.md`
 
-```js
-eve.on("*.under.*", f);
-eve("mouse.under.floor"); // triggers f
+```md
+You are a weather-focused assistant. Be concise, accurate, and explicit when you use a tool.
 ```
-Use <a href="#eve" class="dr-link">eve</a> to trigger the listener.
-
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
-- _name_  **array**
-    if you don’t want to use separators, you can use array of strings
-- _f_  **function**
-    event handler function
-
-**Returns:**  **function** returned function accepts a single numeric parameter that represents z-index of the handler. It is an optional feature and only used when you need to ensure that some subset of handlers will be invoked in a given order, despite of the order of assignment.
-
-### Example:
-```js
-eve.on("mouse", eatIt)(2);
-eve.on("mouse", scream);
-eve.on("mouse", catchIt)(1);
-```
-This will ensure that `catchIt` function will be called before `eatIt`.
 
-If you want to put your handler before non-indexed handlers, specify a negative value.
-Note: I assume most of the time you don’t need to worry about z-index, but it’s nice to have this feature “just in case”.
+`agent/tools/get_weather.ts`
+
+```ts
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  async execute(input) {
+    return {
+      city: input.city,
+      condition: "Sunny",
+      temperatureF: 72,
+    };
+  },
+});
+```
 
+`agent/agent.ts`
 
-## eve.f(event, varargs)
-Returns function that will fire given event with optional arguments.
-Arguments that will be passed to the result function will be also
-concated to the list of final arguments.
+```ts
+import { defineAgent } from "eve";
 
-```js
-el.onclick = eve.f("click", 1, 2);
-eve.on("click", function (a, b, c) {
-    console.log(a, b, c); // 1, 2, [event object]
+export default defineAgent({
+  model: "openai/gpt-5.4-mini",
 });
 ```
-### Parameters
-- _event_  **string**
-    event name
-- _varargs_  **…**
-    and any other arguments
-
-**Returns:**  **function** possible event handler function
 
-## eve.stop()
-Is used inside an event handler to stop the event, preventing any subsequent listeners from firing.
+## Quick Start
 
+```bash
+pnpm create eve@beta
+cd my-agent
+pnpm dev
+```
 
-## eve.nt([subname])
-Could be used inside event handler to figure out actual name of the event.
+The wizard scaffolds the project, picks a model, and (for the REPL channel) installs dependencies and starts the dev server for you. To scaffold into the current empty directory, run `pnpm create eve@beta .`.
 
-### Parameters
-- _subname_  **string**
-    subname of the event
+CLI commands:
 
-**Returns:**  **string** name of the event, if `subname` is not specified
-or
+- `eve info` — discovery results and compiled artifacts
+- `eve build` — compile `.eve/` and build the host output
+- `eve start` — serve the built `.output/` app
+- `eve dev` — start the local runtime and REPL
 
-**Returns:**  **boolean** `true`, if current event’s name contains `subname`
+## Deploying
 
-## eve.nts()
-Could be used inside event handler to figure out actual name of the event.
+Eve is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/advanced/deployment.md`](./dist/docs/public/advanced/deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
 
-**Returns:**  **array** names of the event
+## Read Next
 
-## eve.off(name, f)
-Removes given function from the list of event listeners assigned to given name.
-If no arguments specified all the events will be cleared.
+These files ship inside the installed package at `node_modules/eve/dist/docs/public/`:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
+- [Full docs index](./dist/docs/public/README.md) — recommended entry point
+- [Getting Started](./dist/docs/public/getting-started.mdx) — install, scaffold, and run locally
+- [Project Layout](./dist/docs/public/reference/project-layout.md) — every authored directory in depth
+- [`agent.ts`](./dist/docs/public/agent-config.md) — agent config reference
+- [TypeScript API](./dist/docs/public/reference/typescript-api.md) — complete `define*` and runtime helper reference
+- [Vercel Deployment](./dist/docs/public/advanced/deployment.md) — deploy to production
 
+By authoring concern: [Tools](./dist/docs/public/tools.mdx) · [Channels](./dist/docs/public/channels/overview.mdx) · [Hooks](./dist/docs/public/advanced/hooks.md) · [Skills](./dist/docs/public/skills.mdx) · [Sandbox](./dist/docs/public/sandbox.mdx) · [Connections](./dist/docs/public/connections.mdx) · [Subagents](./dist/docs/public/subagents.mdx) · [Schedules](./dist/docs/public/schedules.mdx) · [Evals](./dist/docs/public/advanced/evals.md)
 
-## eve.unbind()
-See <a href="#eve.off" class="dr-link">eve.off</a>
+By runtime concern: [Sessions and Streaming](./dist/docs/public/advanced/sessions-runs-and-streaming.md) · [Session Context](./dist/docs/public/advanced/session-context.md) · [Context Control](./dist/docs/public/advanced/context-control.md) · [Auth and Route Protection](./dist/docs/public/advanced/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/reference/cli.md) · [Instrumentation](./dist/docs/public/advanced/instrumentation.md)
 
+## Architecture (Internals)
 
-## eve.once(name, f)
-Binds given event handler with a given name to only run once then unbind itself.
+You do not need this section to author an Eve agent — it documents the public HTTP protocol contracts so Eve composes predictably with other systems.
 
-```js
-eve.once("login", f);
-eve("login"); // triggers f
-eve("login"); // no listeners
-```
-Use <a href="#eve" class="dr-link">eve</a> to trigger the listener.
+Eve's internal split is:
 
-### Parameters
-- _name_  **string**
-    name of the event, dot (`.`) or slash (`/`) separated, with optional wildcards
-- _f_  **function**
-    event handler function
+- the **channel** normalizes inbound transport, applies auth and delivery policy, and owns `continuationToken`
+- the **harness** does one unit of AI work and returns `{ session, next }`
+- the **runtime** persists state, follows `next`, streams events, and owns workflow primitives (`start()`, `resumeHook()`, `createHook()`, `getWritable()`)
 
-**Returns:**  **function** same return function as <a href="#eve.on" class="dr-link">eve.on</a>
+That split is why the public HTTP protocol separates two distinct identifiers:
 
-## eve.version()
-Current version of the library.
+- `continuationToken` — channel-owned handle the caller uses to start the next user turn
+- `sessionId` — runtime-owned handle for streaming and inspection
 
+## Changelog
 
+See [`./CHANGELOG.md`](./CHANGELOG.md) for the release history. The changelog ships inside the published package so agents can read it directly from `node_modules/eve/CHANGELOG.md` to evaluate upgrades.

package/bin/eve.d.ts

@@ -0,0 +1,66 @@
+export interface BootstrapOptions {
+  /**
+   * Absolute path to the compiled CLI module.
+   */
+  cliEntrypointPath?: string;
+
+  /**
+   * Absolute path to the eve package root.
+   */
+  packageRoot?: string;
+
+  /**
+   * Absolute paths to scripts that run after workspace bootstrap compilation.
+   */
+  postBuildScriptPaths?: readonly string[];
+
+  /**
+   * Absolute path to the tsgo CLI entrypoint used for bootstrap builds.
+   */
+  tsgoCliPath?: string;
+}
+
+export interface BootstrapCommandOptions {
+  cwd: string;
+}
+
+export interface BootstrapBuildDependencies {
+  exists?: (path: string) => Promise<boolean>;
+  getLatestBuildInputMtimeMs?: (input: { packageRoot: string }) => Promise<number>;
+  getPathMtimeMs?: (path: string) => Promise<number | undefined>;
+  runCommand?: (
+    command: string,
+    args: readonly string[],
+    options: BootstrapCommandOptions,
+  ) => Promise<void>;
+}
+
+export interface BootstrapCliModule {
+  runCli(argv?: string[]): Promise<void>;
+}
+
+export interface BootstrapDependencies extends BootstrapBuildDependencies {
+  importModule?: (specifier: string) => Promise<BootstrapCliModule>;
+
+  /**
+   * Node.js version string used by tests to exercise the bin version guard.
+   */
+  nodeVersion?: string;
+}
+
+/**
+ * Ensures the compiled CLI entrypoint exists before the workspace bin is executed.
+ */
+export function ensureBuiltCli(
+  overrides?: BootstrapOptions,
+  dependencies?: BootstrapBuildDependencies,
+): Promise<string>;
+
+/**
+ * Runs the compiled Eve CLI, building the workspace package on demand when needed.
+ */
+export function runEveCli(
+  argv?: string[],
+  overrides?: BootstrapOptions,
+  dependencies?: BootstrapDependencies,
+): Promise<void>;