Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): guide fresh model onboarding (#349)

Ruiddda14ca6768
diff --git a/.changeset/fresh-model-onboarding.md b/.changeset/fresh-model-onboarding.md
new file mode 100644
index 000000000..cc5676437
--- /dev/null
+++ b/.changeset/fresh-model-onboarding.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Fresh agents now start model setup from their prefilled `/model` prompt, installing the Vercel CLI and logging in when those prerequisites are missing. Other `eve dev` sessions leave missing model setup as an attention prompt.
diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.md
index 6d5efb82b..b1b4b7a5e 100644
--- a/docs/guides/dev-tui.md
+++ b/docs/guides/dev-tui.md
@@ -16,7 +16,7 @@ On startup the TUI prints a brand line with your agent's name, plus a rotating t
Use /channels to add more ways to reach your agent.
```
-If agent discovery reported problems, an error and warning count renders between the two lines. Instructions, tools, skills, and subagents are one `eve info` away, and `/help` lists every command. The TUI also runs a startup check. When the runtime confirms that no model provider is configured, it opens the `/model` provider picker before the first prompt. Unknown or linked-but-incomplete credential states remain visible as an attention line, with each command's outcome hanging under it on a `⎿` connector.
+If agent discovery reported problems, an error and warning count renders between the two lines. Instructions, tools, skills, and subagents are one `eve info` away, and `/help` lists every command. The TUI also runs a startup check. A fresh `eve init` starts local `eve dev` with `/model` prefilled. That input starts onboarding: the flow installs the Vercel CLI if needed, asks you to log in if needed, then opens `/model` before the first prompt. Other `eve dev` sessions show missing setup as an attention line, with each command's outcome hanging under it on a `⎿` connector.
## Reading the transcript
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index c6e5c36ff..cf6478fea 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -100,7 +100,7 @@ Pass a bare URL as the only argument and the UI connects to that server instead
| `-u, --url <url>` | string | none | Connect to an existing server URL instead of starting one |
| `--no-ui` | flag | UI on | Start the server without an interactive UI |
| `--name <name>` | string | app folder name | Title shown in the terminal UI |
-| `--input <text>` | string | none | Pre-fill the prompt input after launching the UI (editable, not auto-submitted) |
+| `--input <text>` | string | none | Pre-fill the prompt input; bare local `/model` starts onboarding |
| `--tools <mode>` | enum | `auto-collapsed` | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
| `--reasoning <mode>` | enum | `full` | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
| `--subagents <mode>` | enum | `auto-collapsed` | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
@@ -109,6 +109,8 @@ Pass a bare URL as the only argument and the UI connects to that server instead
| `--context-size <tokens>` | number | none | Model context window size, shown as a usage percentage |
| `--logs <mode>` | enum | `stderr` | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none` |
+A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, then opens `/model`. Other input stays editable in the prompt.
+
Local dev records the last ready URL per resolved app root in `.eve/dev-server-state.v1.json`. A second interactive `eve dev` reconnects only when that URL is loopback and healthy; each terminal UI creates a fresh client session while sharing the server process. A stale or malformed record is replaced when eve starts a new server. Passing `--host`, `--port`, or a `PORT` environment value skips reconnection and reports a healthy recorded server instead.
Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight sessions hold a consistent code revision while new prompts pick up rebuilds. On startup, `eve dev` prunes stale runtime snapshots and old local sandbox templates in the background. For manual cleanup, stop `eve dev` and delete `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`.
diff --git a/packages/eve/src/cli/commands/init.integration.test.ts b/packages/eve/src/cli/commands/init.integration.test.ts
index c31105d49..1b9bf0cde 100644
--- a/packages/eve/src/cli/commands/init.integration.test.ts
+++ b/packages/eve/src/cli/commands/init.integration.test.ts
@@ -177,6 +177,8 @@ describe("runInitCommand", () => {
"exec",
"eve",
"dev",
+ "--input",
+ "/model",
]);
// Substring assertions keep the expectations color-agnostic; picocolors
// decides at import time whether the strings carry escape codes. The boot
@@ -294,6 +296,8 @@ describe("runInitCommand", () => {
"exec",
"eve",
"dev",
+ "--input",
+ "/model",
]);
expect(output.messages[1]).toContain("Created an eve agent in ");
expect(output.messages[1]).toContain(projectPath);
@@ -301,9 +305,9 @@ describe("runInitCommand", () => {
);
it.each([
- ["npm", ["exec", "--", "eve", "dev"]],
- ["yarn", ["eve", "dev"]],
- ["bun", ["x", "eve", "dev"]],
+ ["npm", ["exec", "--", "eve", "dev", "--input", "/model"]],
+ ["yarn", ["eve", "dev", "--input", "/model"]],
+ ["bun", ["x", "eve", "dev", "--input", "/model"]],
] as const)(
"scaffolds a fresh project owned by the invoking manager %s without pnpm policy",
async (kind, devArguments) => {
@@ -355,14 +359,20 @@ describe("runInitCommand", () => {
projectPath,
expect.anything(),
);
- expect(deps.spawnPackageManager).toHaveBeenCalledWith("bun", projectPath, ["x", "eve", "dev"]);
+ expect(deps.spawnPackageManager).toHaveBeenCalledWith("bun", projectPath, [
+ "x",
+ "eve",
+ "dev",
+ "--input",
+ "/model",
+ ]);
});
it.each([
- ["npm", "package-lock.json", "bun", ["exec", "--", "eve", "dev"]],
- ["yarn", "yarn.lock", "npm", ["eve", "dev"]],
- ["bun", "bun.lock", "npm", ["x", "eve", "dev"]],
- ["pnpm", "pnpm-lock.yaml", "npm", ["exec", "eve", "dev"]],
+ ["npm", "package-lock.json", "bun", ["exec", "--", "eve", "dev", "--input", "/model"]],
+ ["yarn", "yarn.lock", "npm", ["eve", "dev", "--input", "/model"]],
+ ["bun", "bun.lock", "npm", ["x", "eve", "dev", "--input", "/model"]],
+ ["pnpm", "pnpm-lock.yaml", "npm", ["exec", "eve", "dev", "--input", "/model"]],
] as const)(
"scaffolds a fresh named project with the ancestor %s lockfile before the launcher",
async (kind, lockfile, invokingManager, devArguments) => {
@@ -530,8 +540,8 @@ describe("runInitCommand", () => {
});
it.each([
- ["yarn", "yarn.lock", "resolutions", ["eve", "dev"]],
- ["bun", "bun.lock", "overrides", ["x", "eve", "dev"]],
+ ["yarn", "yarn.lock", "resolutions", ["eve", "dev", "--input", "/model"]],
+ ["bun", "bun.lock", "overrides", ["x", "eve", "dev", "--input", "/model"]],
] as const)(
"scaffolds a fresh %s workspace member without nested root-only package fields",
async (kind, lockfile, rootAiPinField, devArguments) => {
@@ -608,6 +618,8 @@ describe("runInitCommand", () => {
"--",
"eve",
"dev",
+ "--input",
+ "/model",
]);
});
@@ -622,7 +634,7 @@ describe("runInitCommand", () => {
expect(deps.spawnPackageManager).toHaveBeenCalledWith(
"pnpm",
join(parentDirectory, "my-agent"),
- ["exec", "eve", "dev"],
+ ["exec", "eve", "dev", "--input", "/model"],
);
});
@@ -653,6 +665,8 @@ describe("runInitCommand", () => {
"exec",
"eve",
"dev",
+ "--input",
+ "/model",
]);
});
diff --git a/packages/eve/src/cli/commands/init.ts b/packages/eve/src/cli/commands/init.ts
index 1d7bcaf22..82caca87a 100644
--- a/packages/eve/src/cli/commands/init.ts
+++ b/packages/eve/src/cli/commands/init.ts
@@ -534,8 +534,11 @@ export async function runInitCommand(
// Strictly the eve binary, never the project's dev script, which in an
// existing app may start unrelated processes. Exec-style runs do not echo
// the command the way run-scripts do, so the handoff line is printed here.
- const devArguments = eveDevArguments(result.packageManager);
- logger.log(pc.dim("$ eve dev"));
+ const freshScaffold = result.kind === "created";
+ const devArguments = freshScaffold
+ ? [...eveDevArguments(result.packageManager), "--input", "/model"]
+ : eveDevArguments(result.packageManager);
+ logger.log(pc.dim(freshScaffold ? "$ eve dev --input /model" : "$ eve dev"));
if (
!(await dependencies.spawnPackageManager(
result.packageManager,
diff --git a/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts b/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts
index 1e0696d84..23feff703 100644
--- a/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts
+++ b/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts
@@ -162,6 +162,35 @@ describe("createPromptCommandHandler", () => {
}
});
+ it("keeps the setup panel open for an immediate onboarding handoff", async () => {
+ const runTuiSetupCommand = vi.fn(async () => ({
+ message: "Vercel CLI installed.",
+ preserveFlowDiagnostics: false,
+ }));
+ vi.doMock("./setup-commands.js", () => ({
+ SETUP_FLOW_CONFIG: {
+ "vc:install": { title: "Install the Vercel CLI", indicator: "pulse" },
+ },
+ runTuiSetupCommand,
+ }));
+
+ try {
+ const setupFlow = setupFlowRenderer();
+ const handler = createPromptCommandHandler({ target: LOCAL_TARGET });
+ const handoffContext = Object.assign(context({ setupFlow }), {
+ keepSetupFlowOpen: true,
+ });
+
+ await handler.handle({ type: "extension", name: "vc:install", argument: "" }, handoffContext);
+
+ expect(setupFlow.begin).toHaveBeenCalledWith("Install the Vercel CLI", "pulse");
+ expect(setupFlow.end).not.toHaveBeenCalled();
+ } finally {
+ vi.doUnmock("./setup-commands.js");
+ vi.resetModules();
+ }
+ });
+
it("reports a login that completed before remote authentication was cancelled", async () => {
const setupFlow = setupFlowRenderer();
const runLoginFlow = vi.fn(async () => ({ kind: "cancelled" as const }));
diff --git a/packages/eve/src/cli/dev/tui/prompt-command-handler.ts b/packages/eve/src/cli/dev/tui/prompt-command-handler.ts
index bff856897..d3c33d9c6 100644
--- a/packages/eve/src/cli/dev/tui/prompt-command-handler.ts
+++ b/packages/eve/src/cli/dev/tui/prompt-command-handler.ts
@@ -129,7 +129,9 @@ export function createPromptCommandHandler(
if (result.effect !== undefined) outcome.effect = result.effect;
return outcome;
} finally {
- flow.end({ preserveDiagnostics: preserveFlowDiagnostics });
+ if (context.keepSetupFlowOpen !== true) {
+ flow.end({ preserveDiagnostics: preserveFlowDiagnostics });
+ }
}
},
};
diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.ts
index 3a1de2de7..8d8abbf69 100644
--- a/packages/eve/src/cli/dev/tui/runner.test.ts
+++ b/packages/eve/src/cli/dev/tui/runner.test.ts
@@ -1909,12 +1909,13 @@ describe("EveTUIRunner boot setup detection", () => {
serverUrl: "http://localhost:3000",
name: "Weather Agent",
appRoot: "/tmp/weather-agent",
+ initialInput: "/model",
bootDetections: input.bootDetections ?? [
{
id: "test",
detect: () => [
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: "model provider not linked",
command: "/model",
},
@@ -1944,16 +1945,21 @@ describe("EveTUIRunner boot setup detection", () => {
expect(warnings).toEqual(["1 setup issue: AI Gateway credentials · /model"]);
});
- it("opens /model before the first prompt when the provider is unset", async () => {
+ it("runs the initial model onboarding prerequisites before opening /model", async () => {
const order: string[] = [];
- const handle = vi.fn(async () => {
- order.push("model");
+ const authStatuses: Array<"cli-missing" | "logged-out" | "authenticated"> = [
+ "cli-missing",
+ "logged-out",
+ "authenticated",
+ ];
+ const handle = vi.fn(async (command: { name: string }) => {
+ order.push(command.name);
return { message: "/model cancelled." };
});
const renderer = fakeRenderer({
readPrompt: vi.fn(async (options?: AgentTUISessionOptions) => {
order.push("prompt");
- expect(options?.initialDraft).toBe("draft me");
+ expect(options?.initialDraft).toBeUndefined();
return undefined;
}),
setupFlow: createFakeSetupFlowRenderer(),
@@ -1963,31 +1969,126 @@ describe("EveTUIRunner boot setup detection", () => {
renderer,
name: "Weather Agent",
appRoot: "/tmp/weather-agent",
- initialInput: "draft me",
+ initialInput: "/model",
bootDetections: [
{
id: "test",
detect: () => [
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: "model provider not linked",
command: "/model",
},
],
},
],
+ getVercelAuthStatus: vi.fn(async () => authStatuses.shift() ?? "authenticated"),
promptCommandHandler: { handle },
});
await runner.run();
- expect(order).toEqual(["model", "prompt"]);
+ expect(order).toEqual(["vc:install", "vc:login", "model", "prompt"]);
+ expect(handle).toHaveBeenNthCalledWith(
+ 1,
+ { type: "extension", name: "vc:install", argument: "" },
+ expect.objectContaining({ keepSetupFlowOpen: true }),
+ );
+ expect(handle).toHaveBeenNthCalledWith(
+ 2,
+ { type: "extension", name: "vc:login", argument: "" },
+ expect.objectContaining({ keepSetupFlowOpen: true }),
+ );
expect(handle).toHaveBeenCalledWith(
{ type: "extension", name: "model", argument: "" },
{ renderer, title: "Weather Agent", initialModelStep: "provider" },
);
});
+ it("stops onboarding when Vercel CLI installation leaves the CLI unavailable", async () => {
+ const order: string[] = [];
+ const authStatuses: Array<"cli-missing"> = ["cli-missing", "cli-missing"];
+ const end = vi.fn();
+ const setupFlow = createFakeSetupFlowRenderer({ end });
+ const runner = new EveTUIRunner({
+ session: sessionYielding([]),
+ renderer: fakeRenderer({ setupFlow }),
+ name: "Weather Agent",
+ appRoot: "/tmp/weather-agent",
+ initialInput: "/model",
+ bootDetections: [
+ {
+ id: "test",
+ detect: () => [
+ {
+ kind: "attention",
+ label: "model provider not linked",
+ command: "/model",
+ },
+ ],
+ },
+ ],
+ getVercelAuthStatus: vi.fn(async () => authStatuses.shift() ?? "cli-missing"),
+ promptCommandHandler: {
+ handle: async (command) => {
+ order.push(command.name);
+ return { message: "/vc:install cancelled." };
+ },
+ },
+ });
+
+ await runner.run();
+
+ expect(order).toEqual(["vc:install"]);
+ expect(end).toHaveBeenCalledOnce();
+ });
+
+ it("does not auto-open /model outside the prefilled onboarding launch", async () => {
+ const handle = vi.fn(async () => ({ message: "/model cancelled." }));
+ const runner = new EveTUIRunner({
+ session: sessionYielding([]),
+ renderer: fakeRenderer({ setupFlow: createFakeSetupFlowRenderer() }),
+ name: "Weather Agent",
+ appRoot: "/tmp/weather-agent",
+ bootDetections: [
+ {
+ id: "test",
+ detect: () => [
+ {
+ kind: "attention",
+ label: "model provider not linked",
+ command: "/model",
+ },
+ ],
+ },
+ ],
+ promptCommandHandler: { handle },
+ });
+
+ await runner.run();
+
+ expect(handle).not.toHaveBeenCalled();
+ });
+
+ it("keeps a prefilled /model editable without a local app root", async () => {
+ const handle = vi.fn(async () => ({ message: "/model cancelled." }));
+ const readPrompt = vi.fn(async (options?: AgentTUISessionOptions) => {
+ expect(options?.initialDraft).toBe("/model");
+ return undefined;
+ });
+ const runner = new EveTUIRunner({
+ session: sessionYielding([]),
+ renderer: fakeRenderer({ readPrompt, setupFlow: createFakeSetupFlowRenderer() }),
+ name: "Weather Agent",
+ initialInput: "/model",
+ promptCommandHandler: { handle },
+ });
+
+ await runner.run();
+
+ expect(handle).not.toHaveBeenCalled();
+ });
+
it("normalizes a committed local key after automatic provider setup", async () => {
const clearSetupWarning = vi.fn();
const headers: AgentTUIAgentHeader[] = [];
@@ -1995,7 +2096,7 @@ describe("EveTUIRunner boot setup detection", () => {
info?.agent.model.endpoint?.kind === "gateway" && !info.agent.model.endpoint.connected
? [
{
- kind: "model-provider-unconfigured" as const,
+ kind: "attention" as const,
label: "model provider not linked",
command: "/model" as const,
},
@@ -2036,7 +2137,7 @@ describe("EveTUIRunner boot setup detection", () => {
info?.agent.model.endpoint?.kind === "gateway" && !info.agent.model.endpoint.connected
? [
{
- kind: "model-provider-unconfigured" as const,
+ kind: "attention" as const,
label: "model provider not linked",
command: "/model" as const,
},
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index 4ca89f07c..9fb46dceb 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -59,7 +59,6 @@ import type { DevelopmentCredentialGate } from "#services/dev-client/credential-
import {
BOOT_DETECTIONS,
CLI_MISSING_SETUP_ISSUE,
- automaticSetupCommand,
detectSetupIssues,
formatSetupIssuesLine,
LOGIN_SETUP_ISSUE,
@@ -297,6 +296,11 @@ export interface PromptCommandHandlerContext {
readonly title: string;
/** Provider entry authorized by confirmed boot-time model-access evidence. */
readonly initialModelStep?: "provider";
+ /**
+ * Leaves the current setup panel mounted for the next automatic onboarding
+ * command. The runner closes it if no next command can proceed.
+ */
+ readonly keepSetupFlowOpen?: true;
readonly remoteConnection?: RemoteConnectionController;
}
@@ -346,8 +350,8 @@ export type EveTUIRunnerOptions = TuiDisplayOptions & {
/** Absolute local application root; omitted for remote `--url` sessions. */
appRoot?: string;
/**
- * Seeds the editable prompt buffer for the first prompt only. The text is
- * not auto-submitted — the user can edit it and presses Enter to send.
+ * Seeds the editable prompt buffer for the first prompt. A bare local
+ * `/model` starts initial model onboarding.
*/
initialInput?: string;
/** Handles non-core slash commands without adding feature branches to the runner. */
@@ -393,7 +397,10 @@ export class EveTUIRunner {
readonly #runtimeArtifacts?: DevelopmentRuntimeArtifactSessionRefresher;
readonly #serverUrl?: string;
readonly #appRoot?: string;
- /** Seeds the first prompt's editable buffer; consumed once in {@link #run}. */
+ /**
+ * Seeds the first prompt's editable buffer. A bare local `/model` starts
+ * fresh-agent onboarding.
+ */
readonly #initialInput?: string;
readonly #promptCommandHandler?: PromptCommandHandler;
readonly #availablePromptCommands: readonly PromptCommandSpec[];
@@ -602,7 +609,6 @@ export class EveTUIRunner {
async #run() {
const title = this.#name;
let prompt: string | undefined;
- let automaticSetup: ReturnType<typeof automaticSetupCommand> = undefined;
let pendingInputResponses: readonly InputResponse[] | undefined;
let hasRunTurn = false;
let streamWithoutPrompt = false;
@@ -615,7 +621,7 @@ export class EveTUIRunner {
await this.#executeExtensionCommand(
{ type: "extension", name: "vc:login", argument: "" },
title,
- "startup",
+ { trigger: "startup" },
);
}
this.#subscribeDevelopmentSandboxLogs();
@@ -623,9 +629,18 @@ export class EveTUIRunner {
// first prompt must not wait on it. The segment appears when it lands.
this.#vercelStatus?.refreshIdentity();
- if (this.#promptCommandHandler !== undefined && this.#renderer.setupFlow !== undefined) {
- automaticSetup = automaticSetupCommand(this.#bootIssues);
- prompt = automaticSetup?.prompt;
+ const initialCommand =
+ this.#initialInput === undefined ? undefined : parsePromptCommand(this.#initialInput);
+ const initialModelOnboarding =
+ initialCommand?.type === "extension" &&
+ initialCommand.name === "model" &&
+ initialCommand.argument === "" &&
+ this.#appRoot !== undefined &&
+ this.#promptCommandHandler !== undefined &&
+ this.#renderer.setupFlow !== undefined;
+ if (initialModelOnboarding) {
+ initialDraft = undefined;
+ await this.#runInitialModelOnboarding(title);
}
while (true) {
@@ -699,10 +714,7 @@ export class EveTUIRunner {
if (command?.type === "extension") {
try {
- const initialModelStep =
- command.name === "model" ? automaticSetup?.initialModelStep : undefined;
- automaticSetup = undefined;
- await this.#executeExtensionCommand(command, title, "command", initialModelStep);
+ await this.#executeExtensionCommand(command, title, { trigger: "command" });
} catch (error) {
if (isInterruptedError(error)) return;
throw error;
@@ -1105,18 +1117,22 @@ export class EveTUIRunner {
async #handleExtensionCommand(
command: Extract<PromptCommand, { type: "extension" }>,
- input: Pick<PromptCommandHandlerContext, "initialModelStep" | "title">,
+ input: Pick<PromptCommandHandlerContext, "initialModelStep" | "keepSetupFlowOpen" | "title">,
): Promise<PromptCommandOutcome | undefined> {
const handler = this.#promptCommandHandler;
if (handler === undefined)
return { message: `/${command.name} is not available in this session.` };
- return await handler.handle(command, {
+ const context: PromptCommandHandlerContext = {
renderer: this.#renderer,
title: input.title,
initialModelStep: input.initialModelStep,
remoteConnection: this.#remoteConnection,
- });
+ };
+ if (input.keepSetupFlowOpen === true) {
+ return await handler.handle(command, { ...context, keepSetupFlowOpen: true });
+ }
+ return await handler.handle(command, context);
}
#renderStartupCommandInvocation(
@@ -1167,16 +1183,75 @@ export class EveTUIRunner {
async #executeExtensionCommand(
command: Extract<PromptCommand, { type: "extension" }>,
title: string,
- trigger: "startup" | "command",
- initialModelStep?: "provider",
+ input: {
+ readonly trigger: "startup" | "command";
+ readonly initialModelStep?: "provider";
+ readonly keepSetupFlowOpen?: true;
+ },
): Promise<void> {
- const outcome = await this.#handleExtensionCommand(command, { initialModelStep, title });
- this.#renderStartupCommandInvocation(command, trigger);
+ const outcome = await this.#handleExtensionCommand(command, {
+ initialModelStep: input.initialModelStep,
+ keepSetupFlowOpen: input.keepSetupFlowOpen,
+ title,
+ });
+ this.#renderStartupCommandInvocation(command, input.trigger);
this.#renderCommandOutcome(outcome?.message);
await this.#applyCommandEffect(outcome?.effect);
this.#refreshHeaderFromRemoteConnection();
}
+ /**
+ * Fresh `eve init` launches the TUI with `/model` prefilled. Project-backed
+ * model access depends on the Vercel CLI and a Vercel session, so resolve
+ * only those missing prerequisites before entering the model picker. A probe
+ * failure still opens `/model`: its own-key and external-provider paths do
+ * not require Vercel.
+ */
+ async #runInitialModelOnboarding(title: string): Promise<void> {
+ const appRoot = this.#appRoot;
+ if (appRoot === undefined) return;
+
+ const authStatus = async (): Promise<VercelAuthStatus | undefined> => {
+ try {
+ return await this.#getVercelAuthStatus(appRoot, { signal: this.#authProbeAbort.signal });
+ } catch {
+ return undefined;
+ }
+ };
+
+ let status = await authStatus();
+ if (status === "cli-missing") {
+ await this.#executeExtensionCommand(
+ { type: "extension", name: "vc:install", argument: "" },
+ title,
+ { trigger: "startup", keepSetupFlowOpen: true },
+ );
+ status = await authStatus();
+ if (status === "cli-missing") {
+ this.#renderer.setupFlow?.end();
+ return;
+ }
+ }
+
+ if (status === "logged-out") {
+ await this.#executeExtensionCommand(
+ { type: "extension", name: "vc:login", argument: "" },
+ title,
+ { trigger: "startup", keepSetupFlowOpen: true },
+ );
+ status = await authStatus();
+ if (status === "cli-missing" || status === "logged-out") {
+ this.#renderer.setupFlow?.end();
+ return;
+ }
+ }
+
+ await this.#executeExtensionCommand({ type: "extension", name: "model", argument: "" }, title, {
+ trigger: "startup",
+ initialModelStep: "provider",
+ });
+ }
+
#refreshHeaderFromRemoteConnection(): void {
const connection = this.#remoteConnection?.current().connection;
if (connection?.state !== "ready" || connection.info === this.#agentInfo) return;
diff --git a/packages/eve/src/cli/dev/tui/setup-issues.integration.test.ts b/packages/eve/src/cli/dev/tui/setup-issues.integration.test.ts
index 4778410dd..494810e49 100644
--- a/packages/eve/src/cli/dev/tui/setup-issues.integration.test.ts
+++ b/packages/eve/src/cli/dev/tui/setup-issues.integration.test.ts
@@ -7,7 +7,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import { Client, type AgentInfoResult } from "#client/index.js";
import { EveTUIRunner, type AgentTUIRenderer } from "./runner.js";
-import { automaticSetupCommand, detectSetupIssues } from "./setup-issues.js";
+import { detectSetupIssues } from "./setup-issues.js";
import { createFakeSetupFlowRenderer } from "./test/fake-setup-flow-renderer.js";
afterEach(() => {
@@ -76,7 +76,7 @@ describe("BOOT_DETECTIONS against a real directory", () => {
]);
});
- it("authorizes model setup when the runtime confirms a linked project is disconnected", async () => {
+ it("diagnoses a linked project with disconnected model access", async () => {
const appRoot = await linkedAppRoot();
const issues = await detectSetupIssues({
appRoot,
@@ -86,21 +86,17 @@ describe("BOOT_DETECTIONS against a real directory", () => {
expect(issues).toEqual([
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: "AI Gateway credentials missing",
command: "/model",
},
]);
- expect(automaticSetupCommand(issues)).toEqual({
- prompt: "/model",
- initialModelStep: "provider",
- });
});
- it("opens model setup from the default detection before the first prompt", async () => {
+ it("opens model setup from the prefilled onboarding prompt when inspection is unavailable", async () => {
const appRoot = await linkedAppRoot();
const client = new Client({ host: "http://localhost:3000" });
- vi.spyOn(client, "info").mockResolvedValue(DISCONNECTED_GATEWAY_INFO);
+ vi.spyOn(client, "info").mockRejectedValue(new Error("inspection unavailable"));
vi.stubGlobal(
"fetch",
vi.fn(async () => Response.json({ revision: "snapshot-a" })),
@@ -128,6 +124,7 @@ describe("BOOT_DETECTIONS against a real directory", () => {
renderer,
serverUrl: "http://localhost:3000",
session: client.session(),
+ initialInput: "/model",
});
await runner.run();
diff --git a/packages/eve/src/cli/dev/tui/setup-issues.test.ts b/packages/eve/src/cli/dev/tui/setup-issues.test.ts
index 6072c4fc7..aa44a99bb 100644
--- a/packages/eve/src/cli/dev/tui/setup-issues.test.ts
+++ b/packages/eve/src/cli/dev/tui/setup-issues.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
import {
BOOT_DETECTIONS,
CLI_MISSING_SETUP_ISSUE,
- automaticSetupCommand,
detectSetupIssues,
formatSetupIssuesLine,
LOGIN_SETUP_ISSUE,
@@ -65,10 +64,9 @@ describe("BOOT_DETECTIONS", () => {
expect(issues).toEqual([
{ kind: "attention", label: "model provider not linked", command: "/model" },
]);
- expect(automaticSetupCommand(issues)).toBeUndefined();
});
- it("opens model setup only when the runtime confirms the gateway is disconnected", async () => {
+ it("diagnoses a disconnected gateway", async () => {
const info = infoWithRouting(
{ kind: "gateway", target: "openai" },
{ kind: "gateway", connected: false },
@@ -77,15 +75,11 @@ describe("BOOT_DETECTIONS", () => {
const issues = await detectSetupIssues(context({ info }));
expect(issues).toEqual([
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: "model provider not linked",
command: "/model",
},
]);
- expect(automaticSetupCommand(issues)).toEqual({
- prompt: "/model",
- initialModelStep: "provider",
- });
});
it.each([
@@ -198,7 +192,7 @@ describe("formatSetupIssuesLine", () => {
describe("orderedSetupIssues", () => {
it("puts the auth prerequisite before the boot detections", () => {
const modelIssue = {
- kind: "model-provider-unconfigured" as const,
+ kind: "attention" as const,
label: "model provider not linked",
command: "/model" as const,
};
diff --git a/packages/eve/src/cli/dev/tui/setup-issues.ts b/packages/eve/src/cli/dev/tui/setup-issues.ts
index dc183a668..ca69b51c6 100644
--- a/packages/eve/src/cli/dev/tui/setup-issues.ts
+++ b/packages/eve/src/cli/dev/tui/setup-issues.ts
@@ -4,21 +4,14 @@ import type { AgentInfoResult } from "#client/index.js";
import { pathExists } from "#setup/path-exists.js";
/** One boot-time setup problem the TUI can point at a fixing command. */
-export type SetupIssue =
- | {
- /** Diagnostics never authorize a command by themselves. */
- kind: "attention";
- /** Short category label, e.g. "AI Gateway credentials". */
- label: string;
- /** The slash command that fixes it, e.g. "/model". */
- command: string;
- }
- | {
- /** Positive runtime evidence that no model provider is configured. */
- kind: "model-provider-unconfigured";
- label: string;
- command: "/model";
- };
+export interface SetupIssue {
+ /** Diagnostics never authorize a command by themselves. */
+ kind: "attention";
+ /** Short category label, e.g. "AI Gateway credentials". */
+ label: string;
+ /** The slash command that fixes it, e.g. "/model". */
+ command: string;
+}
/** What a boot detection may inspect. */
export interface BootDetectionContext {
@@ -124,9 +117,8 @@ function modelProviderAccess(
* gateway model it reports only the most-root cause; an unlinked directory
* implies missing OIDC, so listing both would double-count what /model's
* provider step fixes in one pass. The header and detection receive the same
- * local-credential-normalized endpoint snapshot. Their absence remains
- * unknown and cannot launch setup. A hint, not an error: the model call stays
- * the source of truth.
+ * local-credential-normalized endpoint snapshot. A hint, not an error: the
+ * model call stays the source of truth.
*/
const modelProvider: BootDetection = {
id: "model-provider",
@@ -140,7 +132,7 @@ const modelProvider: BootDetection = {
const linked = await pathExists(join(appRoot, ".vercel", "project.json"));
return [
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: linked ? "AI Gateway credentials missing" : "model provider not linked",
command: "/model",
},
@@ -213,21 +205,6 @@ export function orderedSetupIssues(
return authIssue === undefined ? [...bootIssues] : [authIssue, ...bootIssues];
}
-/** The command and entry step authorized by positive setup evidence. */
-export interface AutomaticSetupCommand {
- prompt: "/model";
- initialModelStep: "provider";
-}
-
-/** Returns the only command authorized to run from positive setup evidence. */
-export function automaticSetupCommand(
- issues: readonly SetupIssue[],
-): AutomaticSetupCommand | undefined {
- return issues.some((issue) => issue.kind === "model-provider-unconfigured")
- ? { prompt: "/model", initialModelStep: "provider" }
- : undefined;
-}
-
/**
* The attention line's body, mirroring Claude Code's
* `1 setup issue: MCP · /doctor` shape; the renderer prefixes the warning
diff --git a/packages/eve/src/cli/dev/tui/tui.ts b/packages/eve/src/cli/dev/tui/tui.ts
index ff0dd595f..d6337ca52 100644
--- a/packages/eve/src/cli/dev/tui/tui.ts
+++ b/packages/eve/src/cli/dev/tui/tui.ts
@@ -26,9 +26,8 @@ export interface RunDevelopmentTuiInput extends TuiDisplayOptions {
/** The local server or remote URL used by this TUI session. */
readonly target: DevelopmentTuiTarget;
/**
- * Text to seed the prompt input with after the UI launches. The buffer is
- * editable and is not auto-submitted — the user presses Enter to send it.
- * Applies to the first prompt only.
+ * Text to seed the prompt input with after the UI launches. A bare local
+ * `/model` starts fresh-agent onboarding. Applies to the first prompt only.
*/
readonly initialInput?: string;
/** Reports local CLI boot phases. Omitted for remote and programmatic TUI runs. */
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index dd4e0ddd7..bd96c477c 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -413,7 +413,7 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
.option("-u, --url <url>", "Connect to an existing server URL", parseDevelopmentServerUrl)
.option("--no-ui", "Start the server without an interactive UI")
.option("--name <name>", "Title shown in the terminal UI (defaults to the app folder name)")
- .option("--input <text>", "Pre-fill the prompt input after launching the UI")
+ .option("--input <text>", "Pre-fill the prompt input, or start onboarding with /model")
.option(
"--tools <mode>",
"How tool calls render: full | collapsed | auto-collapsed | hidden",
diff --git a/packages/eve/test/scenarios/eve-init.scenario.test.ts b/packages/eve/test/scenarios/eve-init.scenario.test.ts
index 1bc9a1540..8b75bdba7 100644
--- a/packages/eve/test/scenarios/eve-init.scenario.test.ts
+++ b/packages/eve/test/scenarios/eve-init.scenario.test.ts
@@ -189,7 +189,7 @@ describe("eve init smoke", () => {
cwd: canonicalProjectDir,
},
{
- args: ["--dir", canonicalProjectDir, "exec", "eve", "dev"],
+ args: ["--dir", canonicalProjectDir, "exec", "eve", "dev", "--input", "/model"],
cwd: canonicalProjectDir,
},
]);
@@ -232,7 +232,7 @@ describe("eve init smoke", () => {
"--no-frozen-lockfile",
"--config.minimum-release-age=0",
]);
- expect(devCall?.args.slice(-3)).toEqual(["exec", "eve", "dev"]);
+ expect(devCall?.args.slice(-5)).toEqual(["exec", "eve", "dev", "--input", "/model"]);
});
it("adds Web Chat through npm without writing pnpm configuration", async () => {
@@ -257,7 +257,7 @@ describe("eve init smoke", () => {
cwd: canonicalProjectDir,
},
{
- args: ["exec", "--", "eve", "dev"],
+ args: ["exec", "--", "eve", "dev", "--input", "/model"],
cwd: canonicalProjectDir,
},
]);
@@ -358,7 +358,7 @@ describe("eve init smoke", () => {
cwd: canonicalProjectDir,
},
{
- args: ["--dir", canonicalProjectDir, "exec", "eve", "dev"],
+ args: ["--dir", canonicalProjectDir, "exec", "eve", "dev", "--input", "/model"],
cwd: canonicalProjectDir,
},
]);
diff --git a/packages/eve/test/tui-client/tui-packed-install-model.ts b/packages/eve/test/tui-client/tui-packed-install-model.ts
index 42739ceb5..8bb2a6ebf 100644
--- a/packages/eve/test/tui-client/tui-packed-install-model.ts
+++ b/packages/eve/test/tui-client/tui-packed-install-model.ts
@@ -7,15 +7,15 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import { theme } from "./lib/theme.ts";
/**
- * End-to-end proof that the *packed* eve artifact can auto-open `/model` after
- * a consumer-shaped install.
+ * End-to-end proof that the *packed* eve artifact can open onboarding `/model`
+ * after a consumer-shaped install.
*
* Every other smoke test resolves eve's modules inside the workspace, where
* devDependencies are installed — so a runtime import of an undeclared
* dependency still resolves and the bug ships. This test packs the built
* package (`pnpm pack`), installs the tarball into an empty project with npm
* (which installs only declared dependencies, exactly like a user install),
- * and drives the installed TUI through automatic provider setup.
+ * and drives the installed TUI through the prefilled onboarding provider setup.
*
* Regression: eve 0.6.x–0.7.0 imported `oxc-parser` from the `/model` flow
* while declaring it only as a devDependency. In a scaffolded project the
@@ -107,6 +107,8 @@ void (async () => {
userInput: input,
name: "Packed install model command",
appRoot: consumerRoot,
+ initialInput: "/model",
+ getVercelAuthStatus: async () => "authenticated",
promptCommandHandler: createPromptCommandHandler({
target: {
kind: "local",
@@ -116,10 +118,10 @@ void (async () => {
}),
bootDetections: [
{
- id: "test-unconfigured-provider",
+ id: "test-model-setup-attention",
detect: () => [
{
- kind: "model-provider-unconfigured",
+ kind: "attention",
label: "model provider not linked",
command: "/model",
},
@@ -130,12 +132,12 @@ void (async () => {
const runPromise = runner.run();
try {
- // The provider picker paints before the first prompt only when boot
- // detection launched the installed `/model` flow and its module graph
- // loaded — the exact surface the oxc-parser regression crashed.
+ // The provider picker paints before the first prompt only when the
+ // prefilled onboarding `/model` flow and its module graph load — the
+ // exact surface the oxc-parser regression crashed.
await screen.waitForText("Configure the agent model", 15_000);
await screen.waitForText("Which model provider do you want to use?", 15_000);
- console.log(theme.muted("[tui-packed-install] /model auto-opened provider setup"));
+ console.log(theme.muted("[tui-packed-install] /model opened provider setup"));
input.send("\x1b");
await screen.waitForText("Change model", 5_000);