The Open Framework for Building Agents
refactor(eve): give the local trace spool one owner (#1463)
Chad Hietala731464f0feec
diff --git a/.changeset/trace-spool-single-owner.md b/.changeset/trace-spool-single-owner.mdnew file mode 100644index 000000000..cc77dbccc--- /dev/null+++ b/.changeset/trace-spool-single-owner.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Give the local trace spool's on-disk layout a single owner: the shared trace reader now exposes the listing and segment-read primitives that `eve traces` and the `/traces` viewer both use, and payload formatting is shared between the detail panel and the conversation view.diff --git a/packages/eve/src/cli/commands/trace.ts b/packages/eve/src/cli/commands/trace.tsindex b85484af7..55e9a5d72 100644--- a/packages/eve/src/cli/commands/trace.ts+++ b/packages/eve/src/cli/commands/trace.ts@@ -16,8 +16,6 @@ interface CliTraceLogger {log(message: string): void;}-export type { LocalTrace, LocalTraceSpan };-interface SpanExtent {readonly endTimeNs: bigint;readonly startTimeNs: bigint;diff --git a/packages/eve/src/cli/dev/tui/traces/trace-content.ts b/packages/eve/src/cli/dev/tui/traces/trace-content.tsindex 90e3c90df..520436410 100644--- a/packages/eve/src/cli/dev/tui/traces/trace-content.ts+++ b/packages/eve/src/cli/dev/tui/traces/trace-content.ts@@ -40,13 +40,26 @@ export function formatAttributeContent(const transcript = messageTranscript(value, theme, width);if (transcript !== undefined) return transcript;}- const parsed = parseJson(value);+ return formatPayloadContent(value, width);+}++/**+ * Wraps text to `width`, splitting on embedded newlines so a multi-line payload+ * keeps its shape, and stripping control bytes the frame must not carry.+ */+export function wrapPlainText(text: string, width: number): string[] {+ return splitEmbeddedNewlines([stripTerminalControls(text)]).flatMap((line) =>+ wrapVisibleLine(line, width),+ );+}++/** Formats a payload: JSON structure pretty-prints, anything else stays text. */+export function formatPayloadContent(text: string, width: number): string[] {+ const parsed = parseJson(text);if (parsed !== undefined && (Array.isArray(parsed) || isRecord(parsed))) {return prettyJson(parsed, width);}- return splitEmbeddedNewlines([stripTerminalControls(value)]).flatMap((line) =>- wrapVisibleLine(line, width),- );+ return wrapPlainText(text, width);}function messageTranscript(raw: string, theme: Theme, width: number): string[] | undefined {diff --git a/packages/eve/src/cli/dev/tui/traces/trace-conversation.ts b/packages/eve/src/cli/dev/tui/traces/trace-conversation.tsindex 41897adcc..d4f36bc72 100644--- a/packages/eve/src/cli/dev/tui/traces/trace-conversation.ts+++ b/packages/eve/src/cli/dev/tui/traces/trace-conversation.ts@@ -8,18 +8,13 @@*/import { formatElapsed } from "#cli/format-elapsed.js";-import {- clipVisible,- stripTerminalControls,- visibleLength,- wrapVisibleLine,-} from "#cli/ui/terminal-text.js";+import { clipVisible, stripTerminalControls, visibleLength } from "#cli/ui/terminal-text.js";import type { LocalTrace, LocalTraceSpan } from "#tracing/local-trace-reader.js";import { compareLocalTraceSpans } from "#tracing/local-trace-reader.js";import { formatCompactTokenCount } from "../stream-format.js";import type { Theme } from "../theme.js";-import { prettyJson, splitEmbeddedNewlines } from "./trace-content.js";+import { formatPayloadContent, wrapPlainText } from "./trace-content.js";export interface ConversationItem {readonly kind: "system" | "user" | "assistant" | "tool";@@ -242,8 +237,8 @@ export function renderConversationItem(const name = colors.bold(colors.white(item.name ?? "tool"));leftTitle = `${foldMarker(expanded, expandable, theme)}${name}`;rightTitle = item.durationMs > 0 ? colors.dim(formatElapsed(item.durationMs)) : "";- const argsLines = item.args === undefined ? [] : payloadJsonLines(item.args, inner);- const resultLines = item.result === undefined ? [] : payloadJsonLines(item.result, inner);+ const argsLines = item.args === undefined ? [] : formatPayloadContent(item.args, inner);+ const resultLines = item.result === undefined ? [] : formatPayloadContent(item.result, inner);const cappedArgs = expanded ? argsLines : capLines(argsLines, inner);const cappedResult = expanded ? resultLines : capLines(resultLines, inner);if (cappedArgs.length > 0) {@@ -255,7 +250,7 @@ export function renderConversationItem(} else if (item.kind === "system") {leftTitle = `${foldMarker(expanded, expandable, theme)}${colors.bold(colors.white("system"))}`;rightTitle = colors.dim(`~${formatCompactTokenCount(estimateTokens(item.text ?? ""))} tokens`);- const uncapped = wrapText(item.text ?? "", inner);+ const uncapped = wrapPlainText(item.text ?? "", inner);body.push(...(expanded ? uncapped : capLines(uncapped, inner)));} else if (item.kind === "assistant") {leftTitle = `${foldMarker(expanded, expandable, theme)}${colors.bold(colors.white("assistant"))}${@@ -265,11 +260,11 @@ export function renderConversationItem(const reasoningUncapped =item.reasoning === undefined || item.reasoning.trim().length === 0? []- : payloadLines(item.reasoning, inner);+ : wrapPlainText(item.reasoning, inner);const textUncapped =item.text === undefined || item.text.trim().length === 0? []- : payloadLines(item.text, inner);+ : wrapPlainText(item.text, inner);const reasoningLines = (expanded ? reasoningUncapped : capLines(reasoningUncapped, inner)).map((line) => colors.dim(line),);@@ -301,7 +296,7 @@ export function renderConversationItem(const textUncapped =item.text === undefined || item.text.trim().length === 0? []- : payloadLines(item.text, inner);+ : wrapPlainText(item.text, inner);body.push(...(expanded ? textUncapped : capLines(textUncapped, inner)));}// Delegated work is called out on every card of the subagent's turn so it@@ -433,27 +428,6 @@ function foldMarker(expanded: boolean, expandable: boolean, theme: Theme): strinreturn expandable ? `${theme.colors.dim("▸")} ` : "";}-function wrapText(text: string, width: number): string[] {- return splitEmbeddedNewlines([stripTerminalControls(text)]).flatMap((line) =>- wrapVisibleLine(line, width),- );-}--function payloadLines(text: string, width: number): string[] {- return wrapText(text, width);-}--/** Tool payloads pretty-print when they're JSON; text stays text. */-function payloadJsonLines(text: string, width: number): string[] {- try {- const parsed: unknown = JSON.parse(text);- if (typeof parsed === "object" && parsed !== null) return prettyJson(parsed, width);- } catch {- // Not JSON — fall through to plain text.- }- return payloadLines(text, width);-}-/** Caps payload lines — the standalone `…` + click hint marks the cut. */function capLines(lines: readonly string[], width: number): string[] {if (lines.length <= CARD_PAYLOAD_LINES) return [...lines];@@ -477,27 +451,29 @@ export function conversationItemLineCount(export function conversationItemExpandable(item: ConversationItem, width: number): boolean {const inner = Math.max(8, width - 8);if (item.kind === "tool") {- const args = item.args === undefined ? 0 : payloadJsonLines(item.args, inner - 2).length;- const result = item.result === undefined ? 0 : payloadJsonLines(item.result, inner - 2).length;+ const args = item.args === undefined ? 0 : formatPayloadContent(item.args, inner - 2).length;+ const result =+ item.result === undefined ? 0 : formatPayloadContent(item.result, inner - 2).length;return args > CARD_PAYLOAD_LINES || result > CARD_PAYLOAD_LINES;}- if (item.kind === "system") return wrapText(item.text ?? "", inner).length > CARD_PAYLOAD_LINES;+ if (item.kind === "system")+ return wrapPlainText(item.text ?? "", inner).length > CARD_PAYLOAD_LINES;if (item.kind === "user") {const text =item.text === undefined || item.text.trim().length === 0? 0- : payloadLines(item.text, inner).length;+ : wrapPlainText(item.text, inner).length;return text > CARD_PAYLOAD_LINES;}// assistantconst reasoning =item.reasoning === undefined || item.reasoning.trim().length === 0? 0- : payloadLines(item.reasoning, inner).length;+ : wrapPlainText(item.reasoning, inner).length;const text =item.text === undefined || item.text.trim().length === 0? 0- : payloadLines(item.text, inner).length;+ : wrapPlainText(item.text, inner).length;return reasoning > CARD_PAYLOAD_LINES || text > CARD_PAYLOAD_LINES;}diff --git a/packages/eve/src/cli/dev/tui/traces/trace-store.ts b/packages/eve/src/cli/dev/tui/traces/trace-store.tsindex f61c4ed91..0586e4e64 100644--- a/packages/eve/src/cli/dev/tui/traces/trace-store.ts+++ b/packages/eve/src/cli/dev/tui/traces/trace-store.ts@@ -7,19 +7,14 @@* of parsing spans, keeping a 1s poll cheap even with a large spool.*/-import { readdir, readFile, stat } from "node:fs/promises";-import { join } from "node:path";-import type { LocalTrace, LocalTraceSpan } from "#tracing/local-trace-reader.js";-import { assembleLocalTrace, parseLocalTraceSegment } from "#tracing/local-trace-reader.js";import {- resolveLocalTraceSchemaDirectory,- resolveLocalTraceSegmentsDirectory,-} from "#tracing/local-trace-span-processor.js";--const TRACE_ID_PATTERN = /^[0-9a-f]{32}$/u;-const SPAN_FILE_PATTERN = /^[0-9a-f]{16}\.otlp\.json$/u;-const MAX_SEGMENT_BYTES = 8 * 1024 * 1024;+ assembleLocalTrace,+ listLocalTraceIds,+ listLocalTraceSegments,+ readLocalTraceActivityMs,+ readLocalTraceSegment,+} from "#tracing/local-trace-reader.js";export interface TraceStoreEntry {readonly traceId: string;@@ -39,7 +34,6 @@ export interface TraceStore {}export function createTraceStore(options: { readonly appRoot: string }): TraceStore {- const schemaRoot = resolveLocalTraceSchemaDirectory(options.appRoot);const caches = new Map<string,{ seen: Set<string>; spans: Map<string, LocalTraceSpan>; assembled?: LocalTrace }@@ -47,24 +41,10 @@ export function createTraceStore(options: { readonly appRoot: string }): TraceStreturn {async list() {- let entries;- try {- entries = await readdir(schemaRoot, { withFileTypes: true });- } catch (error) {- if (isMissing(error)) return [];- throw error;- }const traces: TraceStoreEntry[] = [];- for (const entry of entries) {- if (!entry.isDirectory() || !TRACE_ID_PATTERN.test(entry.name)) continue;- try {- const segments = await stat(- resolveLocalTraceSegmentsDirectory(options.appRoot, entry.name),- );- traces.push({ traceId: entry.name, lastActivityMs: segments.mtimeMs });- } catch (error) {- if (!isMissing(error)) throw error;- }+ for (const traceId of await listLocalTraceIds(options.appRoot)) {+ const lastActivityMs = await readLocalTraceActivityMs(options.appRoot, traceId);+ if (lastActivityMs !== undefined) traces.push({ traceId, lastActivityMs });}return traces.sort((left, right) =>right.lastActivityMs === left.lastActivityMs@@ -74,16 +54,10 @@ export function createTraceStore(options: { readonly appRoot: string }): TraceSt},async read(traceId) {- const segmentsRoot = resolveLocalTraceSegmentsDirectory(options.appRoot, traceId);- let entries;- try {- entries = await readdir(segmentsRoot, { withFileTypes: true });- } catch (error) {- if (isMissing(error)) {- caches.delete(traceId);- return undefined;- }- throw error;+ const fileNames = await listLocalTraceSegments(options.appRoot, traceId);+ if (fileNames === undefined) {+ caches.delete(traceId);+ return undefined;}let cache = caches.get(traceId);@@ -92,19 +66,10 @@ export function createTraceStore(options: { readonly appRoot: string }): TraceStcaches.set(traceId, cache);}let changed = false;- for (const entry of entries) {- if (!entry.isFile() || !SPAN_FILE_PATTERN.test(entry.name)) continue;- if (cache.seen.has(entry.name)) continue;- cache.seen.add(entry.name);- let content: string;- try {- const path = join(segmentsRoot, entry.name);- if ((await stat(path)).size > MAX_SEGMENT_BYTES) continue;- content = await readFile(path, "utf8");- } catch {- continue;- }- for (const span of parseLocalTraceSegment(content, traceId)) {+ for (const fileName of fileNames) {+ if (cache.seen.has(fileName)) continue;+ cache.seen.add(fileName);+ for (const span of await readLocalTraceSegment(options.appRoot, traceId, fileName)) {if (!cache.spans.has(span.spanId)) {cache.spans.set(span.spanId, span);changed = true;@@ -119,7 +84,3 @@ export function createTraceStore(options: { readonly appRoot: string }): TraceSt},};}--function isMissing(error: unknown): boolean {- return (error as NodeJS.ErrnoException).code === "ENOENT";-}diff --git a/packages/eve/src/tracing/local-trace-reader.ts b/packages/eve/src/tracing/local-trace-reader.tsindex bfc775a7b..8dbcd8e4f 100644--- a/packages/eve/src/tracing/local-trace-reader.ts+++ b/packages/eve/src/tracing/local-trace-reader.ts@@ -11,10 +11,13 @@import { readdir, readFile, stat } from "node:fs/promises";import { join } from "node:path";-import { resolveLocalTraceSchemaDirectory } from "#tracing/local-trace-span-processor.js";+import {+ resolveLocalTraceSchemaDirectory,+ resolveLocalTraceSegmentsDirectory,+} from "#tracing/local-trace-span-processor.js";const TRACE_ID_PATTERN = /^[0-9a-f]{32}$/u;-const SPAN_FILE_PATTERN = /^([0-9a-f]{16})\.otlp\.json$/u;+const SPAN_FILE_PATTERN = /^[0-9a-f]{16}\.otlp\.json$/u;const MAX_SEGMENT_BYTES = 8 * 1024 * 1024;const MAX_UINT64 = 18_446_744_073_709_551_615n;@@ -49,21 +52,89 @@ export interface LocalTrace {readonly window?: number;}-/** Reads valid local traces, newest first, while ignoring malformed segments. */-export async function listLocalTraces(appRoot: string): Promise<LocalTrace[]> {- const root = resolveLocalTraceSchemaDirectory(appRoot);+/**+ * Trace ids held by the spool, unordered. Empty when nothing has been written+ * yet; any other read fault propagates.+ */+export async function listLocalTraceIds(appRoot: string): Promise<string[]> {let entries;try {- entries = await readdir(root, { withFileTypes: true });+ entries = await readdir(resolveLocalTraceSchemaDirectory(appRoot), { withFileTypes: true });} catch (error) {if (isMissing(error)) return [];throw error;}+ return entries+ .filter((entry) => entry.isDirectory() && TRACE_ID_PATTERN.test(entry.name))+ .map((entry) => entry.name);+}+/**+ * Instant one trace last received a span, or `undefined` once retention has+ * pruned it. Reads the segments directory's mtime, so it stays cheap enough to+ * poll a large spool without parsing any span.+ */+export async function readLocalTraceActivityMs(+ appRoot: string,+ traceId: string,+): Promise<number | undefined> {+ try {+ return (await stat(resolveLocalTraceSegmentsDirectory(appRoot, traceId))).mtimeMs;+ } catch (error) {+ if (isMissing(error)) return undefined;+ throw error;+ }+}++/**+ * Segment file names of one trace in read order, or `undefined` when the trace+ * is gone. Segments are immutable and named for their span, so the order is+ * stable across reads and a caller can treat names it has seen as parsed.+ */+export async function listLocalTraceSegments(+ appRoot: string,+ traceId: string,+): Promise<string[] | undefined> {+ let entries;+ try {+ entries = await readdir(resolveLocalTraceSegmentsDirectory(appRoot, traceId), {+ withFileTypes: true,+ });+ } catch (error) {+ if (isMissing(error)) return undefined;+ throw error;+ }+ return entries+ .filter((entry) => entry.isFile() && SPAN_FILE_PATTERN.test(entry.name))+ .map((entry) => entry.name)+ .sort((left, right) => left.localeCompare(right));+}++/**+ * Spans held by one segment file. An oversized, unreadable, or malformed+ * segment yields none, so a partial write never breaks a view.+ */+export async function readLocalTraceSegment(+ appRoot: string,+ traceId: string,+ fileName: string,+): Promise<LocalTraceSpan[]> {+ const path = join(resolveLocalTraceSegmentsDirectory(appRoot, traceId), fileName);+ let content: string;+ try {+ if ((await stat(path)).size > MAX_SEGMENT_BYTES) return [];+ content = await readFile(path, "utf8");+ } catch {+ return [];+ }+ return parseLocalTraceSegment(content, traceId);+}++/** Reads valid local traces, newest first, while ignoring malformed segments. */+export async function listLocalTraces(appRoot: string): Promise<LocalTrace[]> {const traces: LocalTrace[] = [];- for (const entry of entries) {- if (!entry.isDirectory() || !TRACE_ID_PATTERN.test(entry.name)) continue;- const trace = await readLocalTrace(root, entry.name).catch(() => undefined);+ for (const traceId of await listLocalTraceIds(appRoot)) {+ const trace = await readLocalTrace(appRoot, traceId).catch(() => undefined);if (trace !== undefined) traces.push(trace);}return traces.sort((left, right) =>@@ -76,33 +147,15 @@ export async function listLocalTraces(appRoot: string): Promise<LocalTrace[]> {}/**- * Reads one trace from its segments directory, or `undefined` when the trace- * has no valid spans. Spans come back ordered by start time.+ * Reads one whole trace, or `undefined` when it holds no valid spans. Spans+ * come back ordered by start time.*/-export async function readLocalTrace(- root: string,- traceId: string,-): Promise<LocalTrace | undefined> {- const segmentsRoot = join(root, traceId, "segments");- let entries;- try {- entries = await readdir(segmentsRoot, { withFileTypes: true });- } catch (error) {- if (isMissing(error)) return undefined;- throw error;- }+async function readLocalTrace(appRoot: string, traceId: string): Promise<LocalTrace | undefined> {+ const fileNames = await listLocalTraceSegments(appRoot, traceId);+ if (fileNames === undefined) return undefined;const spans = new Map<string, LocalTraceSpan>();- for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {- if (!entry.isFile() || !SPAN_FILE_PATTERN.test(entry.name)) continue;- let content: string;- try {- const path = join(segmentsRoot, entry.name);- if ((await stat(path)).size > MAX_SEGMENT_BYTES) continue;- content = await readFile(path, "utf8");- } catch {- continue;- }- for (const span of parseLocalTraceSegment(content, traceId)) {+ for (const fileName of fileNames) {+ for (const span of await readLocalTraceSegment(appRoot, traceId, fileName)) {if (!spans.has(span.spanId)) spans.set(span.spanId, span);}}