Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(cli): clarify telemetry identity and onboarding outcomes (#3064)

OwenKephart59ec96cc99f6
diff --git a/.changeset/track-init-telemetry-stages.md b/.changeset/track-init-telemetry-stages.md
new file mode 100644
index 000000000..ac9a24826
--- /dev/null
+++ b/.changeset/track-init-telemetry-stages.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add CLI telemetry for setup and onboarding flows.
diff --git a/docs/reference/telemetry.md b/docs/reference/telemetry.md
index 7d34d4b0d..a9b509742 100644
--- a/docs/reference/telemetry.md
+++ b/docs/reference/telemetry.md
@@ -12,9 +12,9 @@ eve collects usage data from its CLI to help improve its commands and developmen
eve sends the following information to Vercel:
- The eve version, operating system, CPU architecture, and whether stdin is a terminal.
-- The command you ran and whether it succeeded, had a usage error, or failed.
+- The command you ran, its outcome, and setup or onboarding steps when applicable.
- For `eve dev`, whether you connected to a local or remote agent and whether the UI was interactive or headless.
-- Random identifiers for the CLI session, your eve installation, and the project.
+- Random identifiers for the CLI session, installation, and project, plus whether the installation and project identifiers are ephemeral or persistent.
The project identifier lets eve group usage from the same project without sending its name or location. eve derives it from the Git remote when available, otherwise `REPOSITORY_URL` or the working directory, and transforms that value before sending it.
diff --git a/packages/eve/src/cli/commands/extension-init.ts b/packages/eve/src/cli/commands/extension-init.ts
index d6dbffce0..ffe077fd2 100644
--- a/packages/eve/src/cli/commands/extension-init.ts
+++ b/packages/eve/src/cli/commands/extension-init.ts
@@ -39,6 +39,13 @@ export interface ExtensionInitCliLogger {
log(message: string): void;
}
+export type ExtensionInitSetupStep =
+ | "resolve_target"
+ | "scaffold"
+ | "install_dependencies"
+ | "initialize_git"
+ | "handoff";
+
export interface ExtensionInitCommandDependencies {
detectInvokingPackageManager: typeof detectInvokingPackageManager;
detectPackageManager: typeof detectPackageManager;
@@ -221,7 +228,9 @@ export async function runExtensionInitCommand(
parentDirectory: string,
target: string | undefined,
dependencies: ExtensionInitCommandDependencies = defaultDependencies,
+ trackStep?: (step: ExtensionInitSetupStep) => void,
): Promise<void> {
+ trackStep?.("resolve_target");
// Coding agent with no target: print a setup guide, same gate as agent init.
if (target === undefined && (await dependencies.isCodingAgentLaunch())) {
logger.log(initExtensionInstructions());
@@ -256,6 +265,7 @@ export async function runExtensionInitCommand(
);
}
+ trackStep?.("scaffold");
progress.update("Creating extension");
initLog.debug("creating extension");
const agentStartedAt = dependencies.now();
@@ -279,6 +289,7 @@ export async function runExtensionInitCommand(
agentElapsedMs = dependencies.now() - agentStartedAt;
initLog.debug("creating extension done", { ms: agentElapsedMs });
+ trackStep?.("install_dependencies");
progress.update("Installing dependencies", `${packageManager} install`);
initLog.debug(`installing dependencies with ${packageManager}`);
const installStartedAt = dependencies.now();
@@ -316,6 +327,7 @@ export async function runExtensionInitCommand(
}
initLog.debug("dependencies installed", { ms: installElapsedMs });
+ trackStep?.("initialize_git");
progress.update("Initializing Git repository");
initLog.debug("initializing git repository");
gitResult = await dependencies.tryInitializeGit(projectPath);
@@ -323,6 +335,7 @@ export async function runExtensionInitCommand(
progress.stop();
}
+ trackStep?.("handoff");
logger.log(
`${pc.green("✓")} Created an ${EVE_WORDMARK} extension in ${pc.bold(projectPath!)} ${pc.dim(`in ${formatElapsed(agentElapsedMs!)}`)}`,
);
diff --git a/packages/eve/src/cli/commands/init.ts b/packages/eve/src/cli/commands/init.ts
index ec2da0eeb..bef13c2b0 100644
--- a/packages/eve/src/cli/commands/init.ts
+++ b/packages/eve/src/cli/commands/init.ts
@@ -5,6 +5,7 @@ import { performance } from "node:perf_hooks";
import pc from "#compiled/picocolors/index.js";
import { isCodingAgentLaunch } from "#cli/agent-detection.js";
+import type { EveCliSetupStep, EveCliSetupTerminalResult } from "#cli/telemetry/index.js";
import { EVE_WORDMARK } from "#cli/banner.js";
import { formatElapsed } from "#cli/format-elapsed.js";
import { startCliLiveRow } from "#cli/ui/live-row.js";
@@ -128,10 +129,6 @@ function formatWorkspaceRootMutationWarning(mutation: WorkspaceRootMutation): st
return `Updated workspace root ${target} at ${mutation.path}${suffix}`;
}
-/**
- * Adds the agent to an existing project and returns the
- * detected manager, which drives the install and dev handoff.
- */
async function addToExistingProject(
targetPath: string,
options: InitCommandOptions,
@@ -173,10 +170,6 @@ async function addToExistingProject(
};
}
-/**
- * The manager a fresh scaffold will be owned by: an existing ancestor project
- * manager first, then the package runner that launched the CLI, then pnpm.
- */
async function resolveScaffoldPackageManager(
projectPath: string,
dependencies: InitCommandDependencies,
@@ -360,8 +353,9 @@ async function runInitSteps(input: {
options: InitCommandOptions;
parentDirectory: string;
target: string | undefined;
+ trackStep?: (step: EveCliSetupStep) => void;
}): Promise<InitResult> {
- const { dependencies, logger, options, parentDirectory, target } = input;
+ const { dependencies, logger, options, parentDirectory, target, trackStep } = input;
const debug = isLogLevelEnabled("debug");
const agentLaunched = await dependencies.isCodingAgentLaunch();
const initTarget = await resolveInitTarget({ parentDirectory, target });
@@ -371,6 +365,7 @@ async function runInitSteps(input: {
progress.update("Preparing project");
try {
const scaffoldPhase = initTarget.kind === "fresh" ? "creating agent" : "adding agent";
+ trackStep?.("scaffold");
progress.update(initTarget.kind === "fresh" ? "Creating agent" : "Adding agent");
initLog.debug(scaffoldPhase);
const agentStartedAt = dependencies.now();
@@ -462,6 +457,7 @@ async function runInitSteps(input: {
progress = startCliLiveRow(logger);
}
+ trackStep?.("install_dependencies");
progress.update("Installing dependencies", `${project.packageManager} install`);
initLog.debug(`installing dependencies with ${project.packageManager}`);
const installStartedAt = dependencies.now();
@@ -532,6 +528,7 @@ async function runInitSteps(input: {
initLog.debug("dependencies installed", { ms: installElapsedMs });
if (project.kind === "created") {
+ trackStep?.("initialize_git");
progress.update("Initializing Git repository");
initLog.debug("initializing git repository");
return {
@@ -549,25 +546,16 @@ async function runInitSteps(input: {
}
}
-/**
- * Creates a new eve agent (`target` is a project name), or adds one to an
- * existing project (`target` is a directory), without external provisioning.
- * A fresh in-place scaffold asks whether to use the current directory or a new
- * subdirectory when the current directory is not empty. Coding-agent launches
- * must pass an explicit subdirectory instead.
- *
- * Runs launched by a coding agent get the dev command printed instead of
- * spawned after scaffolding, since the dev TUI would wedge the launching agent.
- *
- * For extension packages, use `eve extension init` instead.
- */
export async function runInitCommand(
logger: InitCliLogger,
parentDirectory: string,
target: string | undefined,
options: InitCommandOptions,
dependencies: InitCommandDependencies = defaultDependencies,
+ trackStep?: (step: EveCliSetupStep) => void,
+ trackTerminal?: (step: EveCliSetupStep, result: EveCliSetupTerminalResult) => void,
): Promise<void> {
+ trackStep?.("resolve_target");
if (
await addAgentsToWorkspace(
logger,
@@ -576,17 +564,31 @@ export async function runInitCommand(
options,
dependencies.validateModelSlug,
)
- )
+ ) {
+ trackStep?.("handoff");
+ trackTerminal?.("handoff", "completed");
return;
+ }
let result: InitResult;
try {
- result = await runInitSteps({ dependencies, logger, options, parentDirectory, target });
+ result = await runInitSteps({
+ dependencies,
+ logger,
+ options,
+ parentDirectory,
+ target,
+ trackStep,
+ });
} catch (error) {
- if (error instanceof WizardCancelledError) return;
+ if (error instanceof WizardCancelledError) {
+ trackTerminal?.("resolve_target", "cancelled");
+ return;
+ }
throw error;
}
+ trackStep?.("handoff");
if (result.kind === "created") {
logger.log(
`${pc.green("✓")} Created an ${EVE_WORDMARK} agent in ${pc.bold(result.projectPath)} ${pc.dim(`in ${formatElapsed(result.agentElapsedMs)}`)}`,
@@ -618,8 +620,6 @@ export async function runInitCommand(
}
}
- // A workspace has no implicit primary agent. Let `eve dev` ask the person
- // which member to run, rather than silently selecting the first --agents value.
const baseDevArguments = eveDevArguments(result.packageManager);
const agentDevCommand = [result.packageManager, ...baseDevArguments].join(" ");
const agentHandoff = initAgentDevHandoff({
diff --git a/packages/eve/src/cli/dev/run-interactive-ui.ts b/packages/eve/src/cli/dev/run-interactive-ui.ts
index b1c92d15e..bc35d269d 100644
--- a/packages/eve/src/cli/dev/run-interactive-ui.ts
+++ b/packages/eve/src/cli/dev/run-interactive-ui.ts
@@ -7,6 +7,8 @@ import {
suspendDevelopmentRuntimeArtifacts,
} from "#services/dev-client/runtime-artifacts.js";
+import type { EveCliSetupStepEvent, EveCliSetupTerminalEvent } from "#cli/telemetry/index.js";
+
import type { DevelopmentCliOptions } from "./command-options.js";
import { resolveTuiDisplayOptions } from "./ui-options.js";
import type { DevelopmentTuiStartup, RunDevelopmentTuiInput } from "./tui/tui.js";
@@ -22,6 +24,8 @@ export async function runInteractiveDevelopmentUi(input: {
readonly remoteTarget?: DevelopmentUrlTarget;
readonly report?: DevBootProgressReporter;
readonly runDevelopmentTui?: (input: RunDevelopmentTuiInput) => Promise<void>;
+ readonly onOnboardingStep?: (input: EveCliSetupStepEvent) => void;
+ readonly onOnboardingTerminal?: (input: EveCliSetupTerminalEvent) => void;
readonly server: { readonly appRoot?: string; readonly serverUrl: string };
readonly startup?: DevelopmentTuiStartup;
}): Promise<void> {
@@ -48,6 +52,8 @@ export async function runInteractiveDevelopmentUi(input: {
initialInput: input.options.input,
onboard: input.options.onboard,
onBootProgress: input.report,
+ onOnboardingStep: input.onOnboardingStep,
+ onOnboardingTerminal: input.onOnboardingTerminal,
lifecycle: input.lifecycle,
...display,
};
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 65298ddf3..18ca9fe91 100644
--- a/packages/eve/src/cli/dev/tui/prompt-command-handler.ts
+++ b/packages/eve/src/cli/dev/tui/prompt-command-handler.ts
@@ -127,6 +127,9 @@ export function createPromptCommandHandler(
if (context.registryPlannerContext !== undefined) {
commandInput.registryPlannerContext = context.registryPlannerContext;
}
+ if (context.onOnboardingScreen !== undefined) {
+ commandInput.onOnboardingScreen = context.onOnboardingScreen;
+ }
// `/add <item>` confirms and installs that address; bare `/add` opens the planner.
if (command.name === "add" && command.argument.length > 0) {
commandInput.initialRegistryAddress = command.argument;
diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.ts
index 0022cab84..6db81f1ab 100644
--- a/packages/eve/src/cli/dev/tui/runner.test.ts
+++ b/packages/eve/src/cli/dev/tui/runner.test.ts
@@ -3568,6 +3568,7 @@ describe("EveTUIRunner boot setup detection", () => {
it("runs initial onboarding as one-way model and registry phases", async () => {
const order: string[] = [];
const results: string[] = [];
+ const stages: string[] = [];
const handle = vi.fn(async (command: { name: string }) => {
order.push(command.name);
return command.name === "model"
@@ -3590,12 +3591,15 @@ describe("EveTUIRunner boot setup detection", () => {
appRoot: "/tmp/weather-agent",
onboard: true,
bootDetections: [],
+ onOnboardingStep: ({ step }) => stages.push(step),
+ onOnboardingTerminal: ({ step, result }) => stages.push(`${step}_${result}`),
promptCommandHandler: { handle },
});
await runner.run();
expect(order).toEqual(["model", "prompt"]);
+ expect(stages).toEqual(["model_provider", "model_provider_error"]);
expect(results).toContain("/model failed: provider unavailable");
expect(handle).toHaveBeenCalledWith(
{ type: "extension", name: "model", argument: "" },
@@ -3625,6 +3629,7 @@ describe("EveTUIRunner boot setup detection", () => {
it("moves from Model to Channels and preserves diagnostics after a failed registry phase", async () => {
const order: string[] = [];
+ const stages: string[] = [];
const end = vi.fn(() => order.push("end"));
const handle = vi.fn(async (command: { name: string }) => {
order.push(command.name);
@@ -3646,12 +3651,15 @@ describe("EveTUIRunner boot setup detection", () => {
appRoot: "/tmp/weather-agent",
onboard: true,
bootDetections: [],
+ onOnboardingStep: ({ step }) => stages.push(step),
+ onOnboardingTerminal: ({ step, result }) => stages.push(`${step}_${result}`),
promptCommandHandler: { handle },
});
await runner.run();
expect(order).toEqual(["model", "add", "end", "prompt"]);
+ expect(stages).toEqual(["model_provider", "registry_channels", "registry_channels_error"]);
expect(end).toHaveBeenCalledWith({ preserveDiagnostics: true });
expect(handle).toHaveBeenNthCalledWith(
2,
@@ -3675,6 +3683,7 @@ describe("EveTUIRunner boot setup detection", () => {
it("keeps the completed /add result after onboarding", async () => {
const renderCommandInvocation = vi.fn();
const renderCommandResult = vi.fn();
+ const stages: string[] = [];
const runner = new EveTUIRunner({
session: sessionYielding([]),
renderer: fakeRenderer({
@@ -3687,6 +3696,8 @@ describe("EveTUIRunner boot setup detection", () => {
appRoot: "/tmp/weather-agent",
onboard: true,
bootDetections: [],
+ onOnboardingStep: ({ step }) => stages.push(step),
+ onOnboardingTerminal: ({ step, result }) => stages.push(`${step}_${result}`),
promptCommandHandler: {
handle: async (command) =>
command.name === "model"
@@ -3697,12 +3708,14 @@ describe("EveTUIRunner boot setup detection", () => {
await runner.run();
+ expect(stages).toEqual(["model_provider", "registry_channels", "registry_channels_completed"]);
expect(renderCommandInvocation).toHaveBeenCalledWith("/add", undefined);
expect(renderCommandResult).toHaveBeenCalledWith("Added Web Chat", "success");
});
it("does not render a detached /add dismissed result when onboarding is cancelled", async () => {
const renderCommandResult = vi.fn();
+ const stages: string[] = [];
const renderer = fakeRenderer({
readPrompt: vi.fn(async () => undefined),
renderCommandResult,
@@ -3715,6 +3728,8 @@ describe("EveTUIRunner boot setup detection", () => {
appRoot: "/tmp/weather-agent",
onboard: true,
bootDetections: [],
+ onOnboardingStep: ({ step }) => stages.push(step),
+ onOnboardingTerminal: ({ step, result }) => stages.push(`${step}_${result}`),
getVercelAuthStatus: vi.fn(async () => "authenticated" as const),
promptCommandHandler: {
handle: async (command) =>
@@ -3726,6 +3741,7 @@ describe("EveTUIRunner boot setup detection", () => {
await runner.run();
+ expect(stages).toEqual(["model_provider", "registry_channels", "registry_channels_cancelled"]);
expect(renderCommandResult).not.toHaveBeenCalledWith("/add dismissed.", expect.anything());
});
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index 945d40fb6..8d3a79256 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -20,6 +20,12 @@ import {
ClientSession,
} from "#client/index.js";
import { renderApplicationInfo } from "#cli/commands/info.js";
+import type {
+ EveCliSetupStep,
+ EveCliSetupStepEvent,
+ EveCliSetupTerminalEvent,
+} from "#cli/telemetry/index.js";
+import type { OnboardingScreenEvent } from "./setup-commands.js";
import { loadDevelopmentEnvironmentFiles } from "#cli/dev/environment.js";
import { subscribeDevelopmentSandboxPrewarmLogs } from "#execution/sandbox/development-prewarm.js";
import { createEventDeduper } from "#protocol/event-dedupe.js";
@@ -376,6 +382,7 @@ export interface PromptCommandHandlerContext {
/** Provider entry authorized by confirmed boot-time model-access evidence. */
readonly initialModelStep?: "provider";
readonly registryPlannerContext?: RegistryPlannerContext;
+ readonly onOnboardingScreen?: (input: OnboardingScreenEvent) => void;
/** Overrides the standalone command title inside a composed setup journey. */
readonly setupFlowTitle?: string;
/** Progress owned by an enclosing journey while this command runs. */
@@ -451,6 +458,9 @@ export type EveTUIRunnerOptions = TuiDisplayOptions & {
initialInput?: string;
/** Explicit fresh-agent onboarding handoff from `eve init`. */
onboard?: boolean;
+ /** Reports timestamped steps and terminal result for fresh-agent onboarding. */
+ onOnboardingStep?: (input: EveCliSetupStepEvent) => void;
+ onOnboardingTerminal?: (input: EveCliSetupTerminalEvent) => void;
/** Handles non-core slash commands without adding feature branches to the runner. */
promptCommandHandler?: PromptCommandHandler;
/** Commands shown in discovery for this local or remote session. */
@@ -508,6 +518,8 @@ export class EveTUIRunner {
readonly #startup?: TuiStartup;
/** Explicit fresh-agent onboarding handoff from `eve init`. */
readonly #onboard: boolean;
+ readonly #onOnboardingStep?: EveTUIRunnerOptions["onOnboardingStep"];
+ readonly #onOnboardingTerminal?: EveTUIRunnerOptions["onOnboardingTerminal"];
#initialOnboardingActive = false;
readonly #promptCommandHandler?: PromptCommandHandler;
readonly #availablePromptCommands: readonly PromptCommandSpec[];
@@ -623,6 +635,8 @@ export class EveTUIRunner {
if (options.initialInput !== undefined) this.#initialInput = options.initialInput;
if (options.startup !== undefined) this.#startup = options.startup;
this.#onboard = options.onboard === true;
+ this.#onOnboardingStep = options.onOnboardingStep;
+ this.#onOnboardingTerminal = options.onOnboardingTerminal;
if (options.appRoot !== undefined) {
this.#appRoot = options.appRoot;
const trackerOptions: VercelStatusTrackerOptions = {
@@ -1749,6 +1763,7 @@ export class EveTUIRunner {
readonly trigger: "startup" | "command";
readonly initialModelStep?: "provider";
readonly registryPlannerContext?: RegistryPlannerContext;
+ readonly onOnboardingScreen?: PromptCommandHandlerContext["onOnboardingScreen"];
readonly setupFlowTitle?: string;
readonly setupFlowNavigation?: PlannerNavigation;
readonly keepSetupFlowOpen?: true;
@@ -1791,28 +1806,65 @@ export class EveTUIRunner {
trigger: "startup" as const,
};
- const modelOutcome = await this.#executeExtensionCommand(
- { type: "extension", name: "model", argument: "" },
- title,
- {
- ...journey,
- suppressSuccessfulTranscript: true,
- initialModelStep: "provider",
- setupFlowNavigation: this.#onboardingNavigation(0),
- },
- );
+ let activeStep: EveCliSetupStep = "model_provider";
+ const onOnboardingScreen: NonNullable<PromptCommandHandlerContext["onOnboardingScreen"]> = (
+ input,
+ ) => {
+ activeStep = input.screen;
+ this.#onOnboardingStep?.({
+ flow: "onboarding",
+ step: input.screen,
+ registrySelectedCount: input.registrySelectedCount,
+ });
+ };
+ onOnboardingScreen({ screen: "model_provider" });
+ let modelOutcome: PromptCommandOutcome | undefined;
+ try {
+ modelOutcome = await this.#executeExtensionCommand(
+ { type: "extension", name: "model", argument: "" },
+ title,
+ {
+ ...journey,
+ suppressSuccessfulTranscript: true,
+ initialModelStep: "provider",
+ setupFlowNavigation: this.#onboardingNavigation(0),
+ onOnboardingScreen,
+ },
+ );
+ } catch (error) {
+ this.#onOnboardingTerminal?.({ flow: "onboarding", step: activeStep, result: "error" });
+ throw error;
+ }
if (modelOutcome?.tone === "error" || modelOutcome?.cancelled === true) {
+ this.#onOnboardingTerminal?.({
+ flow: "onboarding",
+ step: activeStep,
+ result: modelOutcome.cancelled === true ? "cancelled" : "error",
+ });
this.#renderer.setupFlow?.end({ preserveDiagnostics: modelOutcome.tone === "error" });
return;
}
let addOutcome: PromptCommandOutcome | undefined;
+ activeStep = "registry_channels";
+ const onRegistryScreen: NonNullable<PromptCommandHandlerContext["onOnboardingScreen"]> = (
+ input,
+ ) => {
+ activeStep = input.screen;
+ this.#onOnboardingStep?.({
+ flow: "onboarding",
+ step: input.screen,
+ registrySelectedCount: input.registrySelectedCount,
+ });
+ };
try {
+ onRegistryScreen({ screen: "registry_channels" });
addOutcome = await this.#executeExtensionCommand(
{ type: "extension", name: "add", argument: "" },
title,
{
...journey,
+ onOnboardingScreen: onRegistryScreen,
registryPlannerContext: {
prefixSteps: [{ label: "Model", complete: true }],
reviewMessage: "Review your agent",
@@ -1821,7 +1873,22 @@ export class EveTUIRunner {
},
},
);
+ } catch (error) {
+ this.#onOnboardingTerminal?.({ flow: "onboarding", step: activeStep, result: "error" });
+ throw error;
} finally {
+ if (addOutcome !== undefined) {
+ this.#onOnboardingTerminal?.({
+ flow: "onboarding",
+ step: activeStep,
+ result:
+ addOutcome.cancelled === true
+ ? "cancelled"
+ : addOutcome.tone === "error"
+ ? "error"
+ : "completed",
+ });
+ }
// `/add` is the final onboarding phase. Release the shared panel so the
// ordinary chat prompt can own input, retaining deploy/setup evidence on failure.
this.#renderer.setupFlow?.end({ preserveDiagnostics: addOutcome?.tone === "error" });
diff --git a/packages/eve/src/cli/dev/tui/setup-commands.ts b/packages/eve/src/cli/dev/tui/setup-commands.ts
index f46d48d1b..385e1a4ea 100644
--- a/packages/eve/src/cli/dev/tui/setup-commands.ts
+++ b/packages/eve/src/cli/dev/tui/setup-commands.ts
@@ -41,7 +41,6 @@ export const SETUP_FLOW_CONFIG = {
deploy: { title: "Deploy to Vercel", indicator: "spinner" },
} satisfies Record<TuiSetupCommand, { title: string; indicator: SetupFlowIndicator }>;
-/** The prompter surface plus the working-state interrupt trap a command races against. */
export type TuiSetupCommandRenderer = TuiPrompterRenderer &
Pick<
SetupFlowRenderer,
@@ -51,6 +50,17 @@ export type TuiSetupCommandRenderer = TuiPrompterRenderer &
type MuteableSetupRenderer = TuiPrompterRenderer &
Pick<SetupFlowRenderer, "readProviderPicker" | "readModelEditor" | "setNavigation">;
+export type OnboardingScreenEvent = {
+ screen:
+ | "model_provider"
+ | "model_settings"
+ | "registry_channels"
+ | "registry_integrations"
+ | "registry_review"
+ | "registry_install";
+ registrySelectedCount?: number;
+};
+
export interface TuiSetupCommandInput {
command: TuiSetupCommand;
/** Project root for setup that changes shared dependencies, links, or environment files. */
@@ -65,17 +75,16 @@ export interface TuiSetupCommandInput {
initialRegistryAddress?: string;
/** Presentation and navigation supplied by an enclosing setup journey. */
registryPlannerContext?: RegistryPlannerContext;
+ onOnboardingScreen?: (input: OnboardingScreenEvent) => void;
/** Live ChatGPT identity shown only inside model configuration UI. */
chatGptAccountLabel?: string;
/** Suspends development runtime artifacts while registry installation and setup mutate them. */
withExclusiveTerminal?<T>(task: () => Promise<T>): Promise<T>;
- /** Test seam; defaults to the real TUI-native prompter over `renderer`. */
createPrompter?: (renderer: TuiPrompterRenderer) => Prompter;
/** Test seam; defaults to the real setup flows. */
flows?: Partial<TuiSetupFlows>;
}
-/** The flow entry points the commands dispatch to, injectable for tests. */
export interface TuiSetupFlows {
runInstallVercelCliFlow: typeof runInstallVercelCliFlow;
runLoginFlow: typeof runLoginFlow;
@@ -281,6 +290,9 @@ async function executeSetupCommand(
if (input.initialModelStep !== undefined) {
modelInput.initialStep = input.initialModelStep;
}
+ if (input.onOnboardingScreen !== undefined) {
+ modelInput.onScreen = (screen) => input.onOnboardingScreen?.({ screen });
+ }
modelInput.withExclusiveTerminal = (task) =>
renderer.withInheritedStdio(() => input.withExclusiveTerminal?.(task) ?? task());
const result = await flows.runModelFlow(modelInput);
@@ -320,6 +332,7 @@ async function executeSetupCommand(
signal,
initialAddress: input.initialRegistryAddress,
plannerContext: input.registryPlannerContext,
+ onScreen: input.onOnboardingScreen,
onItemStart: registryItemProgress(renderer),
runItem: runRegistryItem,
});
diff --git a/packages/eve/src/cli/dev/tui/tui.ts b/packages/eve/src/cli/dev/tui/tui.ts
index 44a413408..1854cfdfc 100644
--- a/packages/eve/src/cli/dev/tui/tui.ts
+++ b/packages/eve/src/cli/dev/tui/tui.ts
@@ -1,3 +1,4 @@
+import type { EveCliSetupStepEvent, EveCliSetupTerminalEvent } from "#cli/telemetry/index.js";
import { Client } from "#client/index.js";
import type { DevBootProgressReporter } from "#internal/dev-boot-progress.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
@@ -38,6 +39,9 @@ export interface RunDevelopmentTuiInput extends TuiDisplayOptions {
readonly initialInput?: string;
/** Explicit fresh-agent onboarding handoff from `eve init`. */
readonly onboard?: boolean;
+ /** Reports timestamped steps and terminal result for fresh-agent onboarding. */
+ readonly onOnboardingStep?: (input: EveCliSetupStepEvent) => void;
+ readonly onOnboardingTerminal?: (input: EveCliSetupTerminalEvent) => void;
/** Reports local CLI boot phases. Omitted for remote and programmatic TUI runs. */
readonly onBootProgress?: DevBootProgressReporter;
/** Gives setup subprocesses exclusive terminal and development-host ownership. */
@@ -141,6 +145,8 @@ export async function runDevelopmentTui(input: RunDevelopmentTuiInput): Promise<
headers,
initialInput,
onboard,
+ onOnboardingStep,
+ onOnboardingTerminal,
onBootProgress,
lifecycle,
startup,
@@ -189,6 +195,8 @@ export async function runDevelopmentTui(input: RunDevelopmentTuiInput): Promise<
options.startup = startup;
}
if (onboard !== undefined) options.onboard = onboard;
+ if (onOnboardingStep !== undefined) options.onOnboardingStep = onOnboardingStep;
+ if (onOnboardingTerminal !== undefined) options.onOnboardingTerminal = onOnboardingTerminal;
if (onBootProgress !== undefined) options.onBootProgress = onBootProgress;
if (lifecycle !== undefined) options.lifecycle = lifecycle;
if (withExclusiveTerminal !== undefined) options.withExclusiveTerminal = withExclusiveTerminal;
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index ceed53fb7..c847b31af 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -76,7 +76,7 @@ describe("CLI command registration", () => {
resolveAgent: async () => undefined as never,
root: process.cwd(),
},
- { trackDevContext: () => {} },
+ { trackDevContext: () => {}, trackSetupStep: () => {}, trackSetupTerminal: () => {} },
);
const paths: string[] = [];
const visit = (command: (typeof program.commands)[number], parentPath = ""): void => {
@@ -311,11 +311,20 @@ describe("bare eve command", () => {
await runCli([], logger, { findApplicationRoot });
expect(findApplicationRoot).toHaveBeenCalledWith(resolve(process.cwd()));
- expect(runInitCommand).toHaveBeenCalledWith(logger, resolve(process.cwd()), undefined, {
- channelWebNextjs: undefined,
- model: undefined,
- reasoning: undefined,
- });
+ expect(runInitCommand).toHaveBeenCalledWith(
+ logger,
+ resolve(process.cwd()),
+ undefined,
+ {
+ agents: undefined,
+ channelWebNextjs: undefined,
+ model: undefined,
+ reasoning: undefined,
+ },
+ undefined,
+ expect.any(Function),
+ expect.any(Function),
+ );
});
it("runs dev from the enclosing eve application", async () => {
@@ -384,11 +393,20 @@ describe("eve init compatibility flags", () => {
logger,
);
- expect(runInitCommand).toHaveBeenCalledWith(logger, resolve(process.cwd()), "my-agent", {
- channelWebNextjs: undefined,
- model: "openai/gpt-5.6-sol",
- reasoning: "high",
- });
+ expect(runInitCommand).toHaveBeenCalledWith(
+ logger,
+ resolve(process.cwd()),
+ "my-agent",
+ {
+ agents: undefined,
+ channelWebNextjs: undefined,
+ model: "openai/gpt-5.6-sol",
+ reasoning: "high",
+ },
+ undefined,
+ expect.any(Function),
+ expect.any(Function),
+ );
});
it("rejects unsupported reasoning before running the init command", async () => {
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 47243f9f8..b61c86f0b 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -137,7 +137,7 @@ export function createCliProgram(
logger: CliLogger,
runtime: CliRuntimeOverrides,
applicationContext: CliApplicationContext,
- telemetry: Pick<EveCliTelemetry, "trackDevContext">,
+ telemetry: Pick<EveCliTelemetry, "trackDevContext" | "trackSetupStep" | "trackSetupTerminal">,
): Command {
const packageVersion = resolveInstalledPackageInfo().version;
const program = new Command();
@@ -185,8 +185,6 @@ export function createCliProgram(
.description("Create and build reusable eve extension packages.");
extension
- // Optional: a missing target scaffolds the current directory, matching
- // `eve extension init .`.
.command("init [target]")
.description("Create a new eve extension package.")
.option("-y, --yes", "Accepted for compatibility; has no effect")
@@ -196,7 +194,9 @@ export function createCliProgram(
}
const { runExtensionInitCommand } = await import("#cli/commands/extension-init.js");
- await runExtensionInitCommand(logger, applicationContext.root, target);
+ await runExtensionInitCommand(logger, applicationContext.root, target, undefined, (step) => {
+ telemetry.trackSetupStep({ flow: "extension_init", step });
+ });
});
extension
@@ -213,8 +213,6 @@ export function createCliProgram(
registerRegistryCommands({ program, logger, applicationContext });
program
- // Optional: a missing target scaffolds or updates the current directory,
- // matching `eve init .`.
.command("init [target]")
.description("Create a new eve agent, or add one to an existing project directory.")
.option("--channel-web-nextjs", "Add the Web Chat application (Next.js)")
@@ -246,12 +244,24 @@ export function createCliProgram(
}
const { runInitCommand } = await import("#cli/commands/init.js");
- await runInitCommand(logger, applicationContext.root, target, {
- agents: options.agents,
- channelWebNextjs: options.channelWebNextjs,
- model: options.model,
- reasoning: options.reasoning,
- });
+ await runInitCommand(
+ logger,
+ applicationContext.root,
+ target,
+ {
+ agents: options.agents,
+ channelWebNextjs: options.channelWebNextjs,
+ model: options.model,
+ reasoning: options.reasoning,
+ },
+ undefined,
+ (step) => {
+ telemetry.trackSetupStep({ flow: "init", step });
+ },
+ (step, result) => {
+ telemetry.trackSetupTerminal({ flow: "init", step, result });
+ },
+ );
},
);
@@ -417,6 +427,8 @@ export function createCliProgram(
applicationRoot: applicationContext.root,
existingLocalServer: existingLocalDevelopmentServer,
lifecycle,
+ onOnboardingStep: telemetry.trackSetupStep,
+ onOnboardingTerminal: telemetry.trackSetupTerminal,
options,
remoteTarget,
runDevelopmentTui: runtime.runDevelopmentTui,
@@ -518,6 +530,8 @@ export function createCliProgram(
applicationRoot: applicationContext.root,
existingLocalServer: false,
lifecycle,
+ onOnboardingStep: telemetry.trackSetupStep,
+ onOnboardingTerminal: telemetry.trackSetupTerminal,
options,
report: onBootProgress,
runDevelopmentTui: runtime.runDevelopmentTui,
@@ -666,11 +680,7 @@ export async function runCli(
telemetry.trackOutcome(error instanceof CommanderError ? "usage_error" : "error");
if (error instanceof CommanderError) {
- // A coding agent that fumbles `eve init` can trip commander before the
- // init action runs, so the action's own agent detection never fires.
- // Commander has already written its usage error to stderr; add the setup
- // guide on stdout so the agent gets actionable next steps, but still fall
- // through to throw so the malformed invocation keeps its nonzero exit.
+ // Commander can reject `eve init` before its action detects the coding agent.
const detectCodingAgentLaunch = runtime.isCodingAgentLaunch ?? isCodingAgentLaunch;
const agentLaunched = await detectCodingAgentLaunch();
if (input[0] === "init" && agentLaunched) {
diff --git a/packages/eve/src/cli/telemetry/index.test.ts b/packages/eve/src/cli/telemetry/index.test.ts
index 25bd66c06..438fec754 100644
--- a/packages/eve/src/cli/telemetry/index.test.ts
+++ b/packages/eve/src/cli/telemetry/index.test.ts
@@ -134,6 +134,9 @@ describe("createEveCliTelemetry", () => {
}>;
expect(events).toContainEqual(expect.objectContaining({ key: "target", value: "remote" }));
expect(events).toContainEqual(expect.objectContaining({ key: "ui", value: "headless" }));
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "identity_kind", value: "persistent" }),
+ );
expect(events).toContainEqual(
expect.objectContaining({ key: "installation_id", value: "installation_123" }),
);
@@ -145,6 +148,50 @@ describe("createEveCliTelemetry", () => {
});
});
+ it("records the furthest init stage without error details", async () => {
+ vi.stubEnv("NODE_ENV", "production");
+ vi.stubEnv("EVE_TELEMETRY_DEBUG", "1");
+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+ const telemetry = createEveCliTelemetry("1.0.0");
+ telemetry.trackCommand("init");
+ telemetry.trackSetupStep({ flow: "init", step: "resolve_target" });
+ telemetry.trackSetupStep({ flow: "init", step: "install_dependencies" });
+
+ await telemetry.flush();
+
+ const events = JSON.parse(
+ String(write.mock.calls[0]?.[0]).replace("[eve telemetry] ", ""),
+ ) as Array<{ key: string; value: string }>;
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "setup_step", value: "install_dependencies" }),
+ );
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "setup_step", value: "resolve_target" }),
+ );
+ });
+
+ it("records the final onboarding stage without user selections", async () => {
+ vi.stubEnv("NODE_ENV", "production");
+ vi.stubEnv("EVE_TELEMETRY_DEBUG", "1");
+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+ const telemetry = createEveCliTelemetry("1.0.0");
+ telemetry.trackCommand("dev");
+ telemetry.trackSetupStep({ flow: "onboarding", step: "model_provider" });
+ telemetry.trackSetupTerminal({ flow: "onboarding", step: "registry_install", result: "error" });
+
+ await telemetry.flush();
+
+ const events = JSON.parse(
+ String(write.mock.calls[0]?.[0]).replace("[eve telemetry] ", ""),
+ ) as Array<{ key: string; value: string }>;
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "setup_terminal_step", value: "registry_install" }),
+ );
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "setup_step", value: "model_provider" }),
+ );
+ });
+
it("skips telemetry when identity initialization fails", async () => {
vi.stubEnv("NODE_ENV", "production");
vi.mocked(readOrCreateEveTelemetryIdentity).mockRejectedValue(new Error("read-only config"));
@@ -168,7 +215,15 @@ describe("createEveCliTelemetry", () => {
expect(readOrCreateEveTelemetryIdentity).not.toHaveBeenCalled();
expect(createEveTelemetryIdentity).toHaveBeenCalledOnce();
- expect(String(write.mock.calls[0]?.[0])).toContain("ephemeral_installation_123");
+ const events = JSON.parse(
+ String(write.mock.calls[0]?.[0]).replace("[eve telemetry] ", ""),
+ ) as Array<{ key: string; value: string }>;
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "identity_kind", value: "ephemeral" }),
+ );
+ expect(events).toContainEqual(
+ expect.objectContaining({ key: "installation_id", value: "ephemeral_installation_123" }),
+ );
});
it("flushes an allowlisted outcome through a telemetry-disabled child process", async () => {
diff --git a/packages/eve/src/cli/telemetry/index.ts b/packages/eve/src/cli/telemetry/index.ts
index 4f85d2a05..19f6a2b17 100644
--- a/packages/eve/src/cli/telemetry/index.ts
+++ b/packages/eve/src/cli/telemetry/index.ts
@@ -20,9 +20,38 @@ export type EveCliTelemetryEvent = {
readonly value: string;
};
+export type EveCliSetupFlow = "init" | "extension_init" | "onboarding";
+export type EveCliSetupStep =
+ | "resolve_target"
+ | "scaffold"
+ | "install_dependencies"
+ | "initialize_git"
+ | "handoff"
+ | "model_provider"
+ | "model_settings"
+ | "registry_channels"
+ | "registry_integrations"
+ | "registry_review"
+ | "registry_install";
+export type EveCliSetupTerminalResult = "completed" | "cancelled" | "error";
+
+export type EveCliSetupStepEvent = {
+ flow: EveCliSetupFlow;
+ step: EveCliSetupStep;
+ registrySelectedCount?: number;
+};
+
+export type EveCliSetupTerminalEvent = {
+ flow: EveCliSetupFlow;
+ step: EveCliSetupStep;
+ result: EveCliSetupTerminalResult;
+};
+
export type EveCliTelemetry = {
trackCommand(command: string): void;
trackDevContext(context: { target: "local" | "remote"; ui: "tui" | "headless" }): void;
+ trackSetupStep(input: EveCliSetupStepEvent): void;
+ trackSetupTerminal(input: EveCliSetupTerminalEvent): void;
trackOutcome(outcome: "success" | "usage_error" | "error"): void;
notify(logger: { error(message: string): void }): Promise<void>;
flush(): Promise<void>;
@@ -109,6 +138,9 @@ export function createEveCliTelemetry(version: string): EveCliTelemetry {
event("stdin_is_tty", process.stdin.isTTY ? "true" : "false"),
];
const sessionId = randomUUID();
+ const setupEvents: EveCliTelemetryEvent[] = [];
+ let activeSetup: { flow: EveCliSetupFlow; step: EveCliSetupStep } | undefined;
+ let setupTerminalRecorded = false;
return {
trackCommand(command) {
@@ -117,7 +149,28 @@ export function createEveCliTelemetry(version: string): EveCliTelemetry {
trackDevContext(context) {
events.push(event("target", context.target), event("ui", context.ui));
},
+ trackSetupStep(input) {
+ activeSetup = { flow: input.flow, step: input.step };
+ setupEvents.push(event("setup_flow", input.flow), event("setup_step", input.step));
+ if (input.registrySelectedCount !== undefined) {
+ setupEvents.push(event("registry_selected_count", String(input.registrySelectedCount)));
+ }
+ },
+ trackSetupTerminal(input) {
+ setupTerminalRecorded = true;
+ setupEvents.push(
+ event("setup_flow", input.flow),
+ event("setup_terminal_step", input.step),
+ event("setup_terminal_result", input.result),
+ );
+ },
trackOutcome(outcome) {
+ if (activeSetup !== undefined && !setupTerminalRecorded) {
+ this.trackSetupTerminal({
+ ...activeSetup,
+ result: outcome === "success" ? "completed" : "error",
+ });
+ }
events.push(event("outcome", outcome));
},
async notify(logger) {
@@ -145,13 +198,16 @@ export function createEveCliTelemetry(version: string): EveCliTelemetry {
async flush() {
if (!(await isEnabled()) || events.length === 0) return;
try {
- const identity = isEphemeralEveTelemetryEnvironment()
+ const ephemeralIdentity = isEphemeralEveTelemetryEnvironment();
+ const identity = ephemeralIdentity
? createEveTelemetryIdentity()
: await readOrCreateEveTelemetryIdentity();
events.push(
+ event("identity_kind", ephemeralIdentity ? "ephemeral" : "persistent"),
event("installation_id", identity.installationId),
event("project_id", await resolveEveTelemetryProjectId({ identity })),
);
+ events.push(...setupEvents);
} catch {
return;
}
diff --git a/packages/eve/src/setup/flows/model.ts b/packages/eve/src/setup/flows/model.ts
index 12c930c9d..f2a9e5463 100644
--- a/packages/eve/src/setup/flows/model.ts
+++ b/packages/eve/src/setup/flows/model.ts
@@ -289,6 +289,7 @@ export async function runModelFlow(input: {
prompter: Prompter;
/** Opens provider setup before the root menu when runtime evidence requires it. */
initialStep?: "provider";
+ onScreen?: (screen: "model_provider" | "model_settings") => void;
signal?: AbortSignal;
/** Gives ChatGPT sign-in exclusive terminal ownership. */
withExclusiveTerminal?: <T>(task: () => Promise<T>) => Promise<T>;
@@ -414,6 +415,7 @@ export async function runModelFlow(input: {
}
if (pick === "model") {
+ input.onScreen?.("model_settings");
const pickModelSettings = deps.pickModelSettings;
if (pickModelSettings === undefined) {
throw new Error("runModelFlow requires a pickModelSettings dep to open the model screen.");
@@ -460,6 +462,7 @@ export async function runModelFlow(input: {
continue;
}
+ input.onScreen?.("model_provider");
const result = await deps.runProviderFlow({
appRoot: environmentRoot,
prompter,
diff --git a/packages/eve/src/setup/flows/registry.test.ts b/packages/eve/src/setup/flows/registry.test.ts
index 9021f7853..17ab8e1a4 100644
--- a/packages/eve/src/setup/flows/registry.test.ts
+++ b/packages/eve/src/setup/flows/registry.test.ts
@@ -206,6 +206,7 @@ describe("runRegistryFlow", () => {
it("starts bare /add on channels and keeps empty Review open", async () => {
const prompts: unknown[] = [];
+ const screens: Array<{ screen: string; registrySelectedCount?: number }> = [];
const fake = createFakePrompter({
single: (options) => {
prompts.push(options);
@@ -220,9 +221,16 @@ describe("runRegistryFlow", () => {
await runRegistryFlow({
appRoot: APP_ROOT,
prompter: fake.prompter,
+ onScreen: (screen) => screens.push(screen),
deps: deps(),
});
+ expect(screens).toEqual([
+ { screen: "registry_channels" },
+ { screen: "registry_integrations" },
+ { screen: "registry_review", registrySelectedCount: 0 },
+ { screen: "registry_install" },
+ ]);
expect(prompts).toMatchObject([
{ message: "Where should people reach your agent?" },
{ message: "What should your agent be able to work with?" },
diff --git a/packages/eve/src/setup/flows/registry.ts b/packages/eve/src/setup/flows/registry.ts
index 00b9e62bb..f73b0ae1f 100644
--- a/packages/eve/src/setup/flows/registry.ts
+++ b/packages/eve/src/setup/flows/registry.ts
@@ -194,11 +194,18 @@ async function editPlan(input: {
selected: Set<string>;
notices?: readonly SelectNotice[];
plannerContext?: RegistryPlannerContext;
+ onScreen?: (input: {
+ screen: "registry_channels" | "registry_integrations" | "registry_review" | "registry_install";
+ registrySelectedCount?: number;
+ }) => void;
}): Promise<"install" | "cancelled"> {
let screen: PlannerScreen = "channels";
let notices = input.notices;
while (true) {
if (screen !== "review") {
+ input.onScreen?.({
+ screen: screen === "channels" ? "registry_channels" : "registry_integrations",
+ });
try {
const direction = await editSection({
...input,
@@ -219,6 +226,7 @@ async function editPlan(input: {
}
try {
+ input.onScreen?.({ screen: "registry_review", registrySelectedCount: input.selected.size });
const hasSelections = input.selected.size > 0;
const selectedItems = [...input.selected].map((address) => {
const item = input.itemsByAddress.get(address);
@@ -284,6 +292,10 @@ export async function runRegistryFlow(input: {
/** Registry item supplied by `/add <item>`, confirmed and installed directly. */
initialAddress?: string;
plannerContext?: RegistryPlannerContext;
+ onScreen?: (input: {
+ screen: "registry_channels" | "registry_integrations" | "registry_review" | "registry_install";
+ registrySelectedCount?: number;
+ }) => void;
onItemStart?: (item: Item, index: number, total: number) => void;
/** Gives each installation its own cancellation boundary without ending the batch. */
runItem?<T>(task: (signal?: AbortSignal) => Promise<T>): Promise<T>;
@@ -324,6 +336,7 @@ export async function runRegistryFlow(input: {
selected,
notices,
plannerContext: input.plannerContext,
+ onScreen: input.onScreen,
});
if (plan !== "install") return { kind: "cancelled" };
items = [...selected].map((address) => {
@@ -342,6 +355,7 @@ export async function runRegistryFlow(input: {
(await import("#setup/project-resolution.js")).detectDeployment;
const runDeployFlow = input.deps?.runDeployFlow ?? (await import("./deploy.js")).runDeployFlow;
session = createRegistrySession({ detectDeployment, runDeployFlow });
+ input.onScreen?.({ screen: "registry_install" });
const activeSession = session;
for (const [index, item] of items.entries()) {
input.signal?.throwIfAborted();