The Open Framework for Building Agents
feat(eve): rename eve trace to eve traces (#1413)
Chad Hietala38cdff84a153
diff --git a/.changeset/trace-cli-plural.md b/.changeset/trace-cli-plural.mdnew file mode 100644index 000000000..cbdb38add--- /dev/null+++ b/.changeset/trace-cli-plural.md@@ -0,0 +1,5 @@+---+"eve": minor+---++Renames the `eve trace` CLI command to `eve traces` so it matches the `/traces` TUI command and the plural `eve logs` command. `eve traces ls` and `eve traces <trace>` work as before; the old singular form is removed.diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex c01ece21d..39acdf485 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -13,7 +13,7 @@ When no authored `instrumentation.ts` exists, `eve dev` records agent, AI SDK, aThe directory is an immutable OTLP/JSON spool and remains available after `eve dev` exits, subject to the [retention policy](#local-trace-retention) below. Inspection tools may build a query index from these segments, but the index is derived and can be rebuilt without changing the captured trace data.-Use `eve trace ls` to list captured traces and `eve trace <trace>` to inspect a session's span tree.+Use `eve traces ls` to list captured traces and `eve traces <trace>` to inspect a session's span tree.When a model call is served by Vercel AI Gateway, its `agent.step` span also carries the cost the gateway reported: `gen_ai.usage.cost` (raw inference, USD), `gen_ai.usage.gateway_cost` (with the gateway surcharge), `gen_ai.usage.input_cost` / `gen_ai.usage.output_cost` (the split), and `gen_ai.generation.id` for reconciliation with the gateway dashboard. These attributes only exist for gateway-served calls — other providers emit nothing. Cost per turn is the sum across the turn's step spans.diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex f99ca05e9..fecb19244 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -17,8 +17,8 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l| `eve dev <url>` | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server || `eve logs [logid]` | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted) || `eve logs ls` | List `eve dev` diagnostic logs, most recent first |-| `eve trace ls` | List locally captured agent traces, most recent first |-| `eve trace [trace]` | Show a local span tree (the most recent when omitted) |+| `eve traces ls` | List locally captured agent traces, most recent first |+| `eve traces [trace]` | Show a local span tree (the most recent when omitted) || `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials || `eve deploy` | Deploy the agent to Vercel production (links first if needed) || `eve eval` | Run evals against the local app or a remote target |@@ -244,16 +244,16 @@ A log id is the file name without `.log` (for example `dev-2026-07-15T12-00-00.0Each log has a same-named `.dump` sibling holding environment diagnostics and session stats as one JSON document. `eve logs --dump` (with or without a log id) prepends that document to the JSONL log body; the combined output is a valid JSON value stream (`eve logs --dump | jq -c .`), one self-contained report to attach to an issue. When a log has no dump, the flag is silently a no-op.-## `eve trace`+## `eve traces````bash-eve trace ls # list traces, most recent first-eve trace ls --json # emit machine-readable trace summaries-eve trace # show the most recent span tree-eve trace <trace> # show one span tree+eve traces ls # list traces, most recent first+eve traces ls --json # emit machine-readable trace summaries+eve traces # show the most recent span tree+eve traces <trace> # show one span tree```-`eve trace ls` reads the immutable OTLP/JSON segments captured under `.eve/traces/v1`; `eve dev` does not need to be running. `eve trace` accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed or incomplete segments are skipped without hiding valid spans from the same trace.+`eve traces ls` reads the immutable OTLP/JSON segments captured under `.eve/traces/v1`; `eve dev` does not need to be running. `eve traces` accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed or incomplete segments are skipped without hiding valid spans from the same trace.## `eve link`diff --git a/packages/eve/src/cli/commands/trace.integration.test.ts b/packages/eve/src/cli/commands/trace.integration.test.tsindex 19f57c016..92f7f0791 100644--- a/packages/eve/src/cli/commands/trace.integration.test.ts+++ b/packages/eve/src/cli/commands/trace.integration.test.ts@@ -14,7 +14,7 @@ import {const TRACE_ONE = "1".repeat(32);const TRACE_TWO = "2".repeat(32);-describe("eve trace", () => {+describe("eve traces", () => {const roots: string[] = [];afterEach(async () => {diff --git a/packages/eve/src/cli/commands/trace.ts b/packages/eve/src/cli/commands/trace.tsindex 3c5a4de6b..f77f6eee3 100644--- a/packages/eve/src/cli/commands/trace.ts+++ b/packages/eve/src/cli/commands/trace.ts@@ -84,7 +84,7 @@ export function resolveLocalTrace(traces: readonly LocalTrace[], reference: striif (matches.length === 1) return matches[0]!;if (matches.length === 0) {throw new Error(- `No local trace matches "${sanitizeForTerminal(reference)}". Run \`eve trace ls\` to list traces.`,+ `No local trace matches "${sanitizeForTerminal(reference)}". Run \`eve traces ls\` to list traces.`,);}throw ambiguousTraceError(matches, reference);diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.tsindex 0433cc7eb..9bc5162d8 100644--- a/packages/eve/src/cli/run.test.ts+++ b/packages/eve/src/cli/run.test.ts@@ -114,10 +114,10 @@ describe("CLI command registration", () => {log: (message: string) => output.push(message),};- await runCli(["trace", "--help"], logger).catch(() => {});+ await runCli(["traces", "--help"], logger).catch(() => {});const help = output.join("\n");- expect(help).toContain("Usage: eve trace [options] [trace]");+ expect(help).toContain("Usage: eve traces [options] [trace]");expect(help).not.toContain("show <trace>");expect(help).toContain("ls");});diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.tsindex 6985dddae..7d3292930 100644--- a/packages/eve/src/cli/run.ts+++ b/packages/eve/src/cli/run.ts@@ -606,8 +606,8 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm});const traces = program- .command("trace [trace]")- .usage("[options] [trace]\n eve trace ls [options]")+ .command("traces [trace]")+ .usage("[options] [trace]\n eve traces ls [options]").description("Show a local `eve dev` trace (the most recent when trace is omitted).").action(async (reference: string | undefined) => {const { runTraceShowCommand } = await import("#cli/commands/trace.js");diff --git a/research/provider-neutral-local-observability.md b/research/provider-neutral-local-observability.mdindex a373ff515..8f597c2f0 100644--- a/research/provider-neutral-local-observability.md+++ b/research/provider-neutral-local-observability.md@@ -197,7 +197,7 @@ local-tracing work.convention and proves the trace tree in memory. Production remains unchanged.4. **Persistence.** Write session traces as OTLP/JSON, restore provider-owned session context acrossdev worker restarts, and apply payload capture policy. No browser UI.-5. **Inspection.** Add minimal `eve trace ls` and `eve trace [trace]` commands. A graphical viewer is a+5. **Inspection.** Add minimal `eve traces ls` and `eve traces [trace]` commands. A graphical viewer is aseparate design after the trace model stabilizes.6. **Public providers.** Promote the proven lifecycle contract into public hooks and migrate OTel,Vercel, Braintrust, and custom instrumentation onto it.