live-traces 0.1.0

package/react/store.ts

@@ -0,0 +1,357 @@
+/**
+ * Trace Store — Reactive store for live trace events.
+ *
+ * Reduces a stream of TraceEvents into a tree of SpanNodes per trace.
+ * Framework-agnostic core — uses useSyncExternalStore for React binding.
+ *
+ * No Effect dependency. Consumes plain TraceEvent JSON from any source.
+ */
+import type { TraceEvent, TraceStart, SpanStart, SpanEnd, SpanEvent, TraceEnd, TraceScope } from "../src/types.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TraceStatus = "running" | "completed" | "failed";
+
+export interface SpanEventEntry {
+    readonly name: string;
+    readonly level?: string;
+    readonly attributes?: Record<string, unknown>;
+    readonly timestamp: number;
+}
+
+export interface SpanNode {
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly name: string;
+    readonly status: "running" | "ok" | "error";
+    readonly attributes: Record<string, unknown>;
+    readonly events: SpanEventEntry[];
+    readonly children: SpanNode[];
+    readonly startedAt: number;
+    readonly durationMs?: number;
+    /** True if this span has ui.step attribute */
+    readonly isStep: boolean;
+}
+
+export interface TraceState {
+    readonly traceId: string;
+    readonly label: string;
+    readonly scope: TraceScope;
+    readonly status: TraceStatus;
+    readonly rootSpanId?: string;
+    readonly spans: Map<string, SpanNode>;
+    readonly startedAt: number;
+    readonly completedAt?: number;
+    readonly durationMs?: number;
+    readonly error?: string;
+    readonly updatedAt: number;
+}
+
+// ============================================================================
+// Store
+// ============================================================================
+
+/** TTL for completed traces before eviction (ms) */
+const COMPLETED_TTL_MS = 30_000;
+
+/** Maximum events per span */
+const MAX_SPAN_EVENTS = 50;
+
+/** Replay filter: skip events older than 30 minutes */
+const REPLAY_MAX_AGE_MS = 30 * 60 * 1000;
+
+type Listener = () => void;
+
+export class TraceStore {
+    private traces = new Map<string, TraceState>();
+    private listeners = new Set<Listener>();
+    private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+    constructor() {
+        this.cleanupTimer = setInterval(() => this.cleanup(), 5_000);
+    }
+
+    /** Subscribe to store changes (for useSyncExternalStore) */
+    subscribe = (listener: Listener): (() => void) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+
+    /** Get snapshot (for useSyncExternalStore) */
+    getSnapshot = (): Map<string, TraceState> => this.traces;
+
+    /** Dispatch a single trace event */
+    dispatch(event: TraceEvent): void {
+        // Skip ancient events on replay
+        if (Date.now() - event.timestamp > REPLAY_MAX_AGE_MS) return;
+
+        switch (event._tag) {
+            case "TraceStart":
+                this.handleTraceStart(event);
+                break;
+            case "SpanStart":
+                this.handleSpanStart(event);
+                break;
+            case "SpanEnd":
+                this.handleSpanEnd(event);
+                break;
+            case "SpanEvent":
+                this.handleSpanEvent(event);
+                break;
+            case "TraceEnd":
+                this.handleTraceEnd(event);
+                break;
+        }
+
+        this.notify();
+    }
+
+    /** Dispatch a batch of events */
+    dispatchBatch(events: TraceEvent[]): void {
+        for (const event of events) {
+            // Inline without notify per event
+            if (Date.now() - event.timestamp > REPLAY_MAX_AGE_MS) continue;
+            switch (event._tag) {
+                case "TraceStart":
+                    this.handleTraceStart(event);
+                    break;
+                case "SpanStart":
+                    this.handleSpanStart(event);
+                    break;
+                case "SpanEnd":
+                    this.handleSpanEnd(event);
+                    break;
+                case "SpanEvent":
+                    this.handleSpanEvent(event);
+                    break;
+                case "TraceEnd":
+                    this.handleTraceEnd(event);
+                    break;
+            }
+        }
+        this.notify();
+    }
+
+    /** Get a single trace */
+    getTrace(traceId: string): TraceState | undefined {
+        return this.traces.get(traceId);
+    }
+
+    /** Get all traces as array, sorted by startedAt descending */
+    getAllTraces(): TraceState[] {
+        return Array.from(this.traces.values()).toSorted((a, b) => b.startedAt - a.startedAt);
+    }
+
+    /** Get step spans (ui.step=true) for a trace, in order */
+    getSteps(traceId: string): SpanNode[] {
+        const trace = this.traces.get(traceId);
+        if (!trace) return [];
+        return Array.from(trace.spans.values())
+            .filter((s) => s.isStep)
+            .toSorted((a, b) => a.startedAt - b.startedAt);
+    }
+
+    /** Build the span tree for a trace */
+    getSpanTree(traceId: string): SpanNode | undefined {
+        const trace = this.traces.get(traceId);
+        if (!trace || !trace.rootSpanId) return undefined;
+        return trace.spans.get(trace.rootSpanId);
+    }
+
+    /** Destroy the store (stop cleanup timer) */
+    destroy(): void {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.listeners.clear();
+    }
+
+    // -- Event handlers --
+
+    private handleTraceStart(event: TraceStart): void {
+        const existing = this.traces.get(event.traceId);
+        if (existing) return; // idempotent
+
+        this.traces = new Map(this.traces);
+        this.traces.set(event.traceId, {
+            traceId: event.traceId,
+            label: event.label,
+            scope: event.scope,
+            status: "running",
+            spans: new Map(),
+            startedAt: event.timestamp,
+            updatedAt: event.timestamp,
+        });
+    }
+
+    private handleSpanStart(event: SpanStart): void {
+        const trace = this.traces.get(event.traceId);
+        if (!trace) return;
+
+        const span: SpanNode = {
+            spanId: event.spanId,
+            parentSpanId: event.parentSpanId,
+            name: event.name,
+            status: "running",
+            attributes: event.attributes,
+            events: [],
+            children: [],
+            startedAt: event.timestamp,
+            isStep: event.attributes["ui.step"] === true,
+        };
+
+        const newSpans = new Map(trace.spans);
+        newSpans.set(event.spanId, span);
+
+        // Add as child of parent span
+        if (event.parentSpanId) {
+            const parent = newSpans.get(event.parentSpanId);
+            if (parent) {
+                newSpans.set(event.parentSpanId, {
+                    ...parent,
+                    children: [...parent.children, span],
+                });
+            }
+        }
+
+        this.traces = new Map(this.traces);
+        this.traces.set(event.traceId, {
+            ...trace,
+            spans: newSpans,
+            rootSpanId: trace.rootSpanId ?? event.spanId,
+            updatedAt: event.timestamp,
+        });
+    }
+
+    private handleSpanEnd(event: SpanEnd): void {
+        const trace = this.traces.get(event.traceId);
+        if (!trace) return;
+
+        const span = trace.spans.get(event.spanId);
+        if (!span) return;
+
+        const newSpans = new Map(trace.spans);
+        const updatedSpan = {
+            ...span,
+            status: event.status as "ok" | "error",
+            durationMs: event.durationMs,
+        };
+        newSpans.set(event.spanId, updatedSpan);
+
+        // Update in parent's children array too
+        if (span.parentSpanId) {
+            const parent = newSpans.get(span.parentSpanId);
+            if (parent) {
+                newSpans.set(span.parentSpanId, {
+                    ...parent,
+                    children: parent.children.map((c) => (c.spanId === event.spanId ? updatedSpan : c)),
+                });
+            }
+        }
+
+        this.traces = new Map(this.traces);
+        this.traces.set(event.traceId, {
+            ...trace,
+            spans: newSpans,
+            updatedAt: event.timestamp,
+        });
+    }
+
+    private handleSpanEvent(event: SpanEvent): void {
+        const trace = this.traces.get(event.traceId);
+        if (!trace) return;
+
+        const span = trace.spans.get(event.spanId);
+        if (!span) return;
+
+        const entry: SpanEventEntry = {
+            name: event.name,
+            level: event.level,
+            attributes: event.attributes,
+            timestamp: event.timestamp,
+        };
+
+        const newEvents = span.events.length >= MAX_SPAN_EVENTS ? [...span.events.slice(-MAX_SPAN_EVENTS + 1), entry] : [...span.events, entry];
+
+        const newSpans = new Map(trace.spans);
+        newSpans.set(event.spanId, { ...span, events: newEvents });
+
+        this.traces = new Map(this.traces);
+        this.traces.set(event.traceId, {
+            ...trace,
+            spans: newSpans,
+            updatedAt: event.timestamp,
+        });
+    }
+
+    private handleTraceEnd(event: TraceEnd): void {
+        const trace = this.traces.get(event.traceId);
+        if (!trace) return;
+
+        // Close any still-running spans (handles lost SpanEnd events)
+        const finalStatus = event.status === "completed" ? ("ok" as const) : ("error" as const);
+        let newSpans = trace.spans;
+        let hasRunningSpans = false;
+        for (const span of trace.spans.values()) {
+            if (span.status === "running") {
+                hasRunningSpans = true;
+                break;
+            }
+        }
+        if (hasRunningSpans) {
+            newSpans = new Map(trace.spans);
+            for (const [id, span] of newSpans) {
+                if (span.status === "running") {
+                    newSpans.set(id, { ...span, status: finalStatus, durationMs: event.timestamp - span.startedAt });
+                }
+            }
+        }
+
+        this.traces = new Map(this.traces);
+        this.traces.set(event.traceId, {
+            ...trace,
+            spans: newSpans,
+            status: event.status === "completed" ? "completed" : "failed",
+            completedAt: event.timestamp,
+            durationMs: event.durationMs,
+            error: event.error,
+            updatedAt: event.timestamp,
+        });
+    }
+
+    private cleanup(): void {
+        const now = Date.now();
+        let changed = false;
+
+        for (const [traceId, trace] of this.traces) {
+            if (trace.completedAt && now - trace.completedAt > COMPLETED_TTL_MS) {
+                if (!changed) {
+                    this.traces = new Map(this.traces);
+                    changed = true;
+                }
+                this.traces.delete(traceId);
+            }
+        }
+
+        if (changed) this.notify();
+    }
+
+    private notify(): void {
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+}
+
+/** Singleton store instance */
+let _store: TraceStore | null = null;
+
+export function getTraceStore(): TraceStore {
+    if (!_store) {
+        _store = new TraceStore();
+    }
+    return _store;
+}

package/src/LiveTrace.ts

@@ -0,0 +1,99 @@
+import type { AnySpan } from "effect/Tracer";
+
+/**
+ * LiveTrace — User-facing API for starting traced scopes.
+ *
+ * Usage:
+ * ```ts
+ * yield* pipe(
+ *   myWorkflow,
+ *   LiveTrace.withTrace({
+ *     traceId: `doc:${documentId}`,
+ *     label: "Processing report.pdf",
+ *     scope: { type: "team", id: teamId },
+ *   }),
+ * )
+ * ```
+ *
+ * Inside the scope, all `Effect.withSpan` and `Effect.log` calls
+ * are automatically captured and streamed to the frontend.
+ */
+import * as Effect from "effect/Effect";
+import * as FiberRef from "effect/FiberRef";
+
+import {
+    LIVE_TRACE,
+    LIVE_TRACE_ID,
+    LIVE_TRACE_LABEL,
+    LIVE_TRACE_PROVIDER,
+    LIVE_TRACE_SCOPE_ID,
+    LIVE_TRACE_SCOPE_TYPE,
+    type TraceScope,
+    UI_STEP,
+} from "./types.js";
+
+export interface LiveTraceConfig {
+    /** Logical trace ID for stream routing (e.g., "doc:abc123") */
+    readonly traceId: string;
+    /** Human-readable label (e.g., filename) */
+    readonly label: string;
+    /** Stream routing scope */
+    readonly scope: TraceScope;
+    /** Optional provider key for source-page filtering (e.g. "notion", "google-drive") */
+    readonly provider?: string;
+}
+
+/**
+ * FiberRef that holds the current WrappedSpan (if inside a withTrace/step scope).
+ * Used by LiveTraceLogger to bridge Effect.log() → SpanEvent automatically.
+ * Inherited by child fibers so forked work stays attributed to the correct span.
+ */
+export const LiveSpanRef: FiberRef.FiberRef<AnySpan | null> = FiberRef.unsafeMake<AnySpan | null>(null);
+
+/**
+ * After Effect.withSpan creates the span, read it via Effect.currentSpan
+ * and store it in LiveSpanRef so the Logger can access it synchronously.
+ */
+const propagateSpan = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.gen(function* () {
+        const span = yield* Effect.currentSpan.pipe(Effect.orElseSucceed(() => null));
+        if (span) {
+            yield* FiberRef.set(LiveSpanRef, span);
+        }
+        return yield* effect;
+    }) as Effect.Effect<A, E, R>;
+
+/**
+ * Wrap an effect in a live-traced scope.
+ *
+ * All `Effect.withSpan` and `Effect.log` calls within this scope
+ * are captured by the LiveTraceLayer and streamed to the sink.
+ */
+export const withTrace =
+    (config: LiveTraceConfig) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+        Effect.withSpan(propagateSpan(effect), config.label, {
+            attributes: {
+                [LIVE_TRACE]: true,
+                [LIVE_TRACE_ID]: config.traceId,
+                [LIVE_TRACE_LABEL]: config.label,
+                [LIVE_TRACE_SCOPE_TYPE]: config.scope.type,
+                [LIVE_TRACE_SCOPE_ID]: config.scope.id,
+                ...(config.provider !== undefined ? { [LIVE_TRACE_PROVIDER]: config.provider } : {}),
+            },
+        });
+
+/**
+ * Create a traced step span. Shows as a top-level section in the UI.
+ *
+ * ```ts
+ * yield* LiveTrace.step("Parsing")(parseDocument(doc))
+ * yield* LiveTrace.step("Embedding")(embedChunks(chunks))
+ * ```
+ */
+export const step =
+    (name: string, attributes?: Record<string, unknown>) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+        Effect.withSpan(propagateSpan(effect), name, {
+            attributes: { [UI_STEP]: true, ...attributes },
+        });

package/src/Logger.ts

@@ -0,0 +1,33 @@
+/**
+ * LiveTraceLogger — Bridges Effect.log() → SpanEvent automatically.
+ *
+ * When inside a `withTrace()` or `step()` scope, this Logger reads
+ * the current WrappedSpan from LiveSpanRef and calls span.event()
+ * so the log message appears in the trace card's step event list.
+ *
+ * Outside a traced scope, this Logger is a no-op (other loggers
+ * like Logger.pretty still handle the log normally).
+ *
+ * Wire via `Logger.add(liveTraceLogger)` in the services layer.
+ */
+import * as FiberRefs from "effect/FiberRefs";
+import * as HashMap from "effect/HashMap";
+import * as Logger from "effect/Logger";
+
+import { LiveSpanRef } from "./LiveTrace.js";
+import { isWrappedSpan } from "./WrappedSpan.js";
+
+export const liveTraceLogger = Logger.make(({ message, logLevel, context: fiberRefs, annotations }) => {
+    const span = FiberRefs.getOrDefault(fiberRefs, LiveSpanRef);
+    if (!span || !isWrappedSpan(span)) return;
+
+    // Flatten message to string
+    const msg = Array.isArray(message) ? message.join(" ") : String(message);
+
+    const attrs: Record<string, unknown> = { "effect.logLevel": logLevel.label };
+    for (const [k, v] of HashMap.entries(annotations)) {
+        attrs[k] = v;
+    }
+
+    span.event(msg, BigInt(Date.now()) * 1_000_000n, attrs);
+});

package/src/Schema.ts

@@ -0,0 +1,70 @@
+/**
+ * Effect Schema wrappers for TraceEvent types.
+ *
+ * Used for runtime NDJSON validation. Optional — consumers
+ * can use plain types from "./types" if they don't need validation.
+ */
+import * as Schema from "effect/Schema";
+
+// ============================================================================
+// Scope
+// ============================================================================
+
+export const TraceScopeSchema = Schema.Struct({
+    type: Schema.Literal("team", "org", "user"),
+    id: Schema.String,
+});
+
+// ============================================================================
+// Events
+// ============================================================================
+
+export const TraceStartSchema = Schema.Struct({
+    _tag: Schema.Literal("TraceStart"),
+    traceId: Schema.String,
+    label: Schema.String,
+    scope: TraceScopeSchema,
+    timestamp: Schema.Number,
+});
+
+export const SpanStartSchema = Schema.Struct({
+    _tag: Schema.Literal("SpanStart"),
+    traceId: Schema.String,
+    spanId: Schema.String,
+    parentSpanId: Schema.optional(Schema.String),
+    name: Schema.String,
+    attributes: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+    timestamp: Schema.Number,
+});
+
+export const SpanEndSchema = Schema.Struct({
+    _tag: Schema.Literal("SpanEnd"),
+    traceId: Schema.String,
+    spanId: Schema.String,
+    status: Schema.Literal("ok", "error"),
+    durationMs: Schema.Number,
+    timestamp: Schema.Number,
+});
+
+export const SpanEventSchema = Schema.Struct({
+    _tag: Schema.Literal("SpanEvent"),
+    traceId: Schema.String,
+    spanId: Schema.String,
+    name: Schema.String,
+    level: Schema.optional(Schema.Literal("Debug", "Info", "Warning", "Error")),
+    attributes: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    timestamp: Schema.Number,
+});
+
+export const TraceEndSchema = Schema.Struct({
+    _tag: Schema.Literal("TraceEnd"),
+    traceId: Schema.String,
+    status: Schema.Literal("completed", "failed"),
+    durationMs: Schema.Number,
+    error: Schema.optional(Schema.String),
+    timestamp: Schema.Number,
+});
+
+export const TraceEventSchema = Schema.Union(TraceStartSchema, SpanStartSchema, SpanEndSchema, SpanEventSchema, TraceEndSchema);
+
+export type TraceEventEncoded = Schema.Schema.Encoded<typeof TraceEventSchema>;

package/src/Sink.ts

@@ -0,0 +1,108 @@
+/**
+ * TraceSink — Buffered event sink with pluggable transport.
+ *
+ * The sink has two parts:
+ * - TraceSinkHandle: synchronous emit() for use inside Tracer.span() (which is sync)
+ * - TraceSink: Effect service that manages the handle + flush daemon
+ *
+ * TraceTransport: pluggable backend (Durable Streams, SSE, WebSocket, console, etc.)
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
+
+import type { TraceEvent } from "./types.js";
+
+// ============================================================================
+// TraceTransport — pluggable destination
+// ============================================================================
+
+export interface TraceTransport {
+    /** Send a batch of events. Called periodically by the flush daemon. */
+    readonly send: (events: ReadonlyArray<TraceEvent>) => Effect.Effect<void>;
+}
+
+export class TraceTransportTag extends Context.Tag("@live-traces/TraceTransport")<TraceTransportTag, TraceTransport>() {}
+
+// ============================================================================
+// TraceSinkHandle — the synchronous interface used by WrappedSpan
+// ============================================================================
+
+export interface TraceSinkHandle {
+    /** Synchronous, non-blocking. Buffers internally. */
+    readonly emit: (event: TraceEvent) => void;
+}
+
+// ============================================================================
+// TraceSink — Effect service managing buffer + flush lifecycle
+// ============================================================================
+
+export class TraceSink extends Context.Tag("@live-traces/TraceSink")<TraceSink, TraceSinkHandle>() {}
+
+// ============================================================================
+// Layer — creates a TraceSink backed by a TraceTransport
+// ============================================================================
+
+export interface TraceSinkConfig {
+    /** Flush interval in milliseconds. Default: 200 */
+    readonly flushIntervalMs?: number;
+}
+
+export const TraceSinkLive = (config?: TraceSinkConfig): Layer.Layer<TraceSink, never, TraceTransportTag> =>
+    Layer.scoped(
+        TraceSink,
+        Effect.gen(function* () {
+            const transport = yield* TraceTransportTag;
+            const intervalMs = config?.flushIntervalMs ?? 200;
+
+            let buffer: TraceEvent[] = [];
+
+            const flush = Effect.suspend(() => {
+                if (buffer.length === 0) return Effect.void;
+                const batch = buffer;
+                buffer = [];
+                return transport.send(batch);
+            });
+
+            // Daemon fiber: flush every intervalMs
+            yield* flush.pipe(
+                Effect.schedule(Schedule.spaced(intervalMs)),
+                Effect.catchAllCause((cause) => Effect.logDebug("live-traces flush daemon error").pipe(Effect.annotateLogs("cause", String(cause)))),
+                Effect.forkScoped,
+            );
+
+            // Final flush on scope close
+            yield* Effect.addFinalizer(() =>
+                flush.pipe(
+                    Effect.catchAllCause((cause) =>
+                        Effect.logDebug("live-traces finalizer flush error").pipe(Effect.annotateLogs("cause", String(cause))),
+                    ),
+                ),
+            );
+
+            const handle: TraceSinkHandle = {
+                emit: (event) => {
+                    buffer.push(event);
+                },
+            };
+
+            return handle;
+        }),
+    );
+
+// ============================================================================
+// Console transport — for development/debugging
+// ============================================================================
+
+export const ConsoleTransport: TraceTransport = {
+    send: (events) =>
+        Effect.sync(() => {
+            for (const event of events) {
+                // eslint-disable-next-line no-console
+                console.log(`[live-trace] ${event._tag}`, JSON.stringify(event));
+            }
+        }),
+};
+
+export const ConsoleTransportLayer: Layer.Layer<TraceTransportTag> = Layer.succeed(TraceTransportTag, ConsoleTransport);