@a5c-ai/agent-runtime 5.0.1-staging.04ca6ab00d21

package/dist/session/write.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Session state file writing utilities.
+ * Provides atomic writes for session state files.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeSessionState = serializeSessionState;
+exports.createSessionFileContent = createSessionFileContent;
+exports.writeSessionFile = writeSessionFile;
+exports.updateSessionState = updateSessionState;
+exports.addRunToSession = addRunToSession;
+exports.getSessionRuns = getSessionRuns;
+exports.getCurrentTimestamp = getCurrentTimestamp;
+exports.isoToEpochSeconds = isoToEpochSeconds;
+exports.updateIterationTimes = updateIterationTimes;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const types_1 = require("./types");
+/**
+ * Serialize session state to YAML frontmatter format.
+ */
+function serializeSessionState(state) {
+    const lines = [];
+    lines.push(`active: ${state.active}`);
+    lines.push(`iteration: ${state.iteration}`);
+    lines.push(`max_iterations: ${state.maxIterations}`);
+    lines.push(`run_id: "${state.runId}"`);
+    lines.push(`run_ids: ${state.runIds.join(',')}`);
+    lines.push(`started_at: "${state.startedAt}"`);
+    lines.push(`last_iteration_at: "${state.lastIterationAt}"`);
+    lines.push(`iteration_times: ${state.iterationTimes.join(',')}`);
+    for (const [key, value] of Object.entries(state.metadata ?? {})) {
+        lines.push(`metadata_${key}: "${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Create full session file content with YAML frontmatter and prompt.
+ */
+function createSessionFileContent(state, prompt) {
+    const frontmatter = serializeSessionState(state);
+    return `---\n${frontmatter}\n---\n\n${prompt}\n`;
+}
+/**
+ * Write session state file atomically.
+ * Uses temp file + rename pattern to ensure atomic writes.
+ */
+async function writeSessionFile(filePath, state, prompt) {
+    const content = createSessionFileContent(state, prompt);
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    try {
+        // Ensure directory exists
+        await node_fs_1.promises.mkdir(dir, { recursive: true });
+        // Write to temp file
+        await node_fs_1.promises.writeFile(tempPath, content, 'utf8');
+        // Atomic rename
+        await node_fs_1.promises.rename(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            await node_fs_1.promises.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        const err = error;
+        throw new types_1.SessionError(`Failed to write session state file: ${err.message}`, types_1.SessionErrorCode.FS_ERROR, { filePath, originalError: err.message });
+    }
+}
+/**
+ * Update specific fields in an existing session state file.
+ * Reads, modifies, and atomically writes the file.
+ */
+async function updateSessionState(filePath, updates, existingContent) {
+    let state;
+    let prompt;
+    if (existingContent) {
+        state = existingContent.state;
+        prompt = existingContent.prompt;
+    }
+    else {
+        // Read existing file
+        const { readSessionFile } = await Promise.resolve().then(() => __importStar(require('./parse')));
+        const file = await readSessionFile(filePath);
+        state = file.state;
+        prompt = file.prompt;
+    }
+    // Apply updates
+    const updatedState = {
+        ...state,
+        ...updates,
+    };
+    // Write updated file
+    await writeSessionFile(filePath, updatedState, prompt);
+    return updatedState;
+}
+/**
+ * Bind a new run to the session, retiring the previous active run to history.
+ *
+ * Invariant: only one run is active at a time (`runId`).
+ * The previous `runId` (if any) is pushed into `runIds` as audit history.
+ * Idempotent: re-binding the same runId is a no-op.
+ *
+ * Throws if the caller tries to bind a new run while `runId` is still set
+ * and `retirePrevious` is not explicitly true — this forces callers to
+ * acknowledge that the prior run is done.
+ */
+function addRunToSession(state, runId, options) {
+    // Idempotent: already bound to this run
+    if (state.runId === runId)
+        return state;
+    // Guard: refuse to silently overwrite an active run
+    if (state.runId && !options?.retirePrevious) {
+        throw new types_1.SessionError(`Session already bound to run ${state.runId}. ` +
+            `Pass { retirePrevious: true } to retire it and bind ${runId}.`, types_1.SessionErrorCode.RUN_ALREADY_ASSOCIATED, { currentRunId: state.runId, requestedRunId: runId });
+    }
+    // Retire the old runId into history (if not already there)
+    const runIds = [...state.runIds];
+    if (state.runId && !runIds.includes(state.runId)) {
+        runIds.push(state.runId);
+    }
+    // Add the new one to the audit trail too
+    if (!runIds.includes(runId)) {
+        runIds.push(runId);
+    }
+    return { ...state, runId, runIds };
+}
+/**
+ * Get the historical audit trail of all run IDs for this session (GAP-SESSION-001).
+ * Falls back to [runId] when runIds is empty for backward compatibility
+ * with sessions created before the runIds field existed.
+ */
+function getSessionRuns(state) {
+    if (state.runIds.length > 0)
+        return state.runIds;
+    return state.runId ? [state.runId] : [];
+}
+/**
+ * Get current ISO timestamp.
+ */
+function getCurrentTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Convert ISO timestamp to epoch seconds.
+ * Returns null if conversion fails.
+ */
+function isoToEpochSeconds(isoTimestamp) {
+    if (!isoTimestamp)
+        return null;
+    try {
+        const date = new Date(isoTimestamp);
+        if (Number.isNaN(date.getTime()))
+            return null;
+        return Math.floor(date.getTime() / 1000);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate iteration duration and update times array.
+ * Keeps only the last 10 durations for diagnostics.
+ */
+function updateIterationTimes(existingTimes, lastIterationAt, currentTime) {
+    const lastEpoch = isoToEpochSeconds(lastIterationAt);
+    const currentEpoch = isoToEpochSeconds(currentTime);
+    if (lastEpoch === null || currentEpoch === null) {
+        return existingTimes;
+    }
+    const duration = currentEpoch - lastEpoch;
+    if (duration <= 0) {
+        return existingTimes;
+    }
+    const newTimes = [...existingTimes, duration];
+    // Keep only last 10
+    return newTimes.slice(-10);
+}

package/dist/telemetry/audit-log.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AuditLog — append-only structured log for security-relevant and
+ * compliance-relevant actions within a babysitter agent runtime session.
+ *
+ * Each entry captures *who* did *what* to *which target*, with an optional
+ * telemetry span correlation. Entries are queryable by actor, action, and
+ * time range.
+ */
+/** A single audit log entry. */
+export interface AuditEntry {
+    /** Who performed the action (user id, agent name, system, etc.). */
+    readonly actor: string;
+    /** What action was performed. */
+    readonly action: string;
+    /** What the action was performed on (resource, span, task, etc.). */
+    readonly target: string;
+    /** Optional human-readable detail or serialized context. */
+    readonly detail?: string;
+    /** Optional telemetry span ID to correlate with the span tree. */
+    readonly spanId?: string;
+    /** ISO-8601 timestamp of when the entry was recorded. */
+    readonly timestamp: string;
+}
+/** Filter criteria for querying the audit log. */
+export interface AuditFilter {
+    /** Match entries from this actor. */
+    actor?: string;
+    /** Match entries with this action. */
+    action?: string;
+    /** Match entries recorded at or after this ISO-8601 timestamp. */
+    from?: string;
+    /** Match entries recorded at or before this ISO-8601 timestamp. */
+    to?: string;
+}
+/** Append-only in-memory audit log. */
+export declare class AuditLog {
+    private readonly entries;
+    /**
+     * Record a new audit entry.
+     *
+     * The timestamp is auto-populated to the current time.
+     */
+    record(entry: Omit<AuditEntry, "timestamp">): AuditEntry;
+    /**
+     * Query log entries with optional filters.
+     *
+     * All supplied filter fields are AND-ed together. Omitted fields match
+     * everything.
+     */
+    getEntries(filter?: AuditFilter): AuditEntry[];
+    /** Total number of entries in the log. */
+    get size(): number;
+    /** Clear all entries (useful in tests or session resets). */
+    clear(): void;
+}
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/telemetry/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../src/telemetry/audit-log.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAMD,uCAAuC;AACvC,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,UAAU;IAMxD;;;;;OAKG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,EAAE;IAc9C,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6DAA6D;IAC7D,KAAK,IAAI,IAAI;CAGd"}

package/dist/telemetry/audit-log.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * AuditLog — append-only structured log for security-relevant and
+ * compliance-relevant actions within a babysitter agent runtime session.
+ *
+ * Each entry captures *who* did *what* to *which target*, with an optional
+ * telemetry span correlation. Entries are queryable by actor, action, and
+ * time range.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLog = void 0;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/** Append-only in-memory audit log. */
+class AuditLog {
+    entries = [];
+    /**
+     * Record a new audit entry.
+     *
+     * The timestamp is auto-populated to the current time.
+     */
+    record(entry) {
+        const full = { ...entry, timestamp: new Date().toISOString() };
+        this.entries.push(full);
+        return full;
+    }
+    /**
+     * Query log entries with optional filters.
+     *
+     * All supplied filter fields are AND-ed together. Omitted fields match
+     * everything.
+     */
+    getEntries(filter) {
+        if (!filter) {
+            return [...this.entries];
+        }
+        return this.entries.filter((e) => {
+            if (filter.actor && e.actor !== filter.actor)
+                return false;
+            if (filter.action && e.action !== filter.action)
+                return false;
+            if (filter.from && e.timestamp < filter.from)
+                return false;
+            if (filter.to && e.timestamp > filter.to)
+                return false;
+            return true;
+        });
+    }
+    /** Total number of entries in the log. */
+    get size() {
+        return this.entries.length;
+    }
+    /** Clear all entries (useful in tests or session resets). */
+    clear() {
+        this.entries.length = 0;
+    }
+}
+exports.AuditLog = AuditLog;

package/dist/telemetry/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
+ * and in-memory implementations.
+ */
+export { TelemetrySpanStatus, type TelemetryEvent, type TelemetrySpan, type TelemetryProvider, type TelemetryConfig, } from "./types";
+export { InMemoryTelemetryProvider } from "./provider";
+export { AuditLog, type AuditEntry, type AuditFilter, } from "./audit-log";
+export { SpanTree, type SpanTreeNode, type SerializedSpanTreeNode, } from "./span-tree";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EACL,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanTree = exports.AuditLog = exports.InMemoryTelemetryProvider = exports.TelemetrySpanStatus = void 0;
+/**
+ * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
+ * and in-memory implementations.
+ */
+var types_1 = require("./types");
+Object.defineProperty(exports, "TelemetrySpanStatus", { enumerable: true, get: function () { return types_1.TelemetrySpanStatus; } });
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "InMemoryTelemetryProvider", { enumerable: true, get: function () { return provider_1.InMemoryTelemetryProvider; } });
+var audit_log_1 = require("./audit-log");
+Object.defineProperty(exports, "AuditLog", { enumerable: true, get: function () { return audit_log_1.AuditLog; } });
+var span_tree_1 = require("./span-tree");
+Object.defineProperty(exports, "SpanTree", { enumerable: true, get: function () { return span_tree_1.SpanTree; } });

package/dist/telemetry/provider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * InMemoryTelemetryProvider — in-process telemetry backend for development,
+ * testing, and single-process agent runtimes.
+ *
+ * Stores spans in memory and supports flush/drain for export pipelines.
+ */
+import type { TelemetryProvider, TelemetrySpan, TelemetryEvent } from "./types";
+import { TelemetrySpanStatus } from "./types";
+/**
+ * In-memory telemetry provider that satisfies the TelemetryProvider interface.
+ *
+ * - `startSpan` creates a new span and tracks it as active.
+ * - `endSpan` marks a span as completed and moves it to the completed set.
+ * - `recordEvent` appends a discrete event to an active span.
+ * - `flush` returns all completed spans and clears the completed buffer.
+ * - `getActiveSpans` returns all currently open (un-ended) spans.
+ */
+export declare class InMemoryTelemetryProvider implements TelemetryProvider {
+    /** Active (in-flight) spans keyed by spanId. */
+    private readonly active;
+    /** Completed spans awaiting flush. */
+    private readonly completed;
+    /** Maps spanId -> traceId so child spans inherit the parent's trace. */
+    private readonly traceIndex;
+    startSpan(name: string, parentSpanId?: string): Promise<TelemetrySpan>;
+    endSpan(spanId: string, status?: TelemetrySpanStatus): Promise<void>;
+    recordEvent(spanId: string, event: TelemetryEvent): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Drain completed spans — returns and clears the completed buffer.
+     *
+     * Unlike `flush()` (which satisfies the TelemetryProvider interface and
+     * returns void), this method hands the span data back to the caller.
+     */
+    drain(): Promise<TelemetrySpan[]>;
+    /** Return a snapshot of all currently open (un-ended) spans. */
+    getActiveSpans(): TelemetrySpan[];
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/telemetry/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/telemetry/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAwB9C;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAIlD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BtE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAMvC,gEAAgE;IAChE,cAAc,IAAI,aAAa,EAAE;CAGlC"}

package/dist/telemetry/provider.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * InMemoryTelemetryProvider — in-process telemetry backend for development,
+ * testing, and single-process agent runtimes.
+ *
+ * Stores spans in memory and supports flush/drain for export pipelines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryTelemetryProvider = void 0;
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("./types");
+function toReadonly(span) {
+    return { ...span, attributes: { ...span.attributes }, events: [...span.events] };
+}
+/**
+ * In-memory telemetry provider that satisfies the TelemetryProvider interface.
+ *
+ * - `startSpan` creates a new span and tracks it as active.
+ * - `endSpan` marks a span as completed and moves it to the completed set.
+ * - `recordEvent` appends a discrete event to an active span.
+ * - `flush` returns all completed spans and clears the completed buffer.
+ * - `getActiveSpans` returns all currently open (un-ended) spans.
+ */
+class InMemoryTelemetryProvider {
+    /** Active (in-flight) spans keyed by spanId. */
+    active = new Map();
+    /** Completed spans awaiting flush. */
+    completed = [];
+    /** Maps spanId -> traceId so child spans inherit the parent's trace. */
+    traceIndex = new Map();
+    // ---------- TelemetryProvider interface ----------
+    async startSpan(name, parentSpanId) {
+        const spanId = (0, node_crypto_1.randomUUID)();
+        let traceId;
+        if (parentSpanId) {
+            // Inherit traceId from the parent span.
+            traceId = this.traceIndex.get(parentSpanId) ?? (0, node_crypto_1.randomUUID)();
+        }
+        else {
+            traceId = (0, node_crypto_1.randomUUID)();
+        }
+        const span = {
+            name,
+            traceId,
+            spanId,
+            parentSpanId,
+            startTime: new Date().toISOString(),
+            status: types_1.TelemetrySpanStatus.Unset,
+            attributes: {},
+            events: [],
+        };
+        this.active.set(spanId, span);
+        this.traceIndex.set(spanId, traceId);
+        return toReadonly(span);
+    }
+    async endSpan(spanId, status) {
+        const span = this.active.get(spanId);
+        if (!span) {
+            return; // Silently ignore unknown/already-ended spans.
+        }
+        span.endTime = new Date().toISOString();
+        span.status = status ?? types_1.TelemetrySpanStatus.Ok;
+        this.active.delete(spanId);
+        this.completed.push(span);
+    }
+    async recordEvent(spanId, event) {
+        const span = this.active.get(spanId);
+        if (!span) {
+            return; // Silently ignore events on unknown/ended spans.
+        }
+        span.events.push(event);
+    }
+    async flush() {
+        this.completed.length = 0;
+    }
+    /**
+     * Drain completed spans — returns and clears the completed buffer.
+     *
+     * Unlike `flush()` (which satisfies the TelemetryProvider interface and
+     * returns void), this method hands the span data back to the caller.
+     */
+    async drain() {
+        return this.completed.splice(0).map(toReadonly);
+    }
+    // ---------- Extra helpers (not on interface) ----------
+    /** Return a snapshot of all currently open (un-ended) spans. */
+    getActiveSpans() {
+        return [...this.active.values()].map(toReadonly);
+    }
+}
+exports.InMemoryTelemetryProvider = InMemoryTelemetryProvider;

package/dist/telemetry/span-tree.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SpanTree — builds a parent/child tree from a flat list of TelemetrySpans.
+ *
+ * Useful for rendering trace waterfalls, computing subtree durations, and
+ * serializing trace hierarchies to JSON for the observer UI.
+ */
+import type { TelemetrySpan } from "./types";
+/** A tree node wrapping a span with its children. */
+export interface SpanTreeNode {
+    readonly span: TelemetrySpan;
+    readonly children: SpanTreeNode[];
+}
+/** Serializable representation of a SpanTreeNode. */
+export interface SerializedSpanTreeNode {
+    readonly spanId: string;
+    readonly name: string;
+    readonly traceId: string;
+    readonly parentSpanId?: string;
+    readonly startTime: string;
+    readonly endTime?: string;
+    readonly status: string;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly events: Array<{
+        readonly name: string;
+        readonly timestamp: string;
+        readonly attributes?: Record<string, string | number | boolean>;
+    }>;
+    readonly children: SerializedSpanTreeNode[];
+}
+/** Tree built from a flat span list. */
+export declare class SpanTree {
+    /** All nodes keyed by spanId for O(1) lookup. */
+    private readonly nodes;
+    /** Root node ids (spans with no parent or whose parent is unknown). */
+    private readonly rootIds;
+    /** Insert a span into the tree, linking it to its parent if present. */
+    addSpan(span: TelemetrySpan): void;
+    /** Get direct children of a span. */
+    getChildren(spanId: string): TelemetrySpan[];
+    /** Get top-level spans (those with no parent). */
+    getRoots(): TelemetrySpan[];
+    /** Serialize the full tree to a JSON-safe structure. */
+    toJSON(): SerializedSpanTreeNode[];
+    private serializeNode;
+}
+//# sourceMappingURL=span-tree.d.ts.map

package/dist/telemetry/span-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-tree.d.ts","sourceRoot":"","sources":["../../src/telemetry/span-tree.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACjE,CAAC,CAAC;IACH,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CAC7C;AAMD,wCAAwC;AACxC,qBAAa,QAAQ;IACnB,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,wEAAwE;IACxE,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAgClC,qCAAqC;IACrC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAM5C,kDAAkD;IAClD,QAAQ,IAAI,aAAa,EAAE;IAO3B,wDAAwD;IACxD,MAAM,IAAI,sBAAsB,EAAE;IAOlC,OAAO,CAAC,aAAa;CAmBtB"}

package/dist/telemetry/span-tree.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * SpanTree — builds a parent/child tree from a flat list of TelemetrySpans.
+ *
+ * Useful for rendering trace waterfalls, computing subtree durations, and
+ * serializing trace hierarchies to JSON for the observer UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanTree = void 0;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/** Tree built from a flat span list. */
+class SpanTree {
+    /** All nodes keyed by spanId for O(1) lookup. */
+    nodes = new Map();
+    /** Root node ids (spans with no parent or whose parent is unknown). */
+    rootIds = [];
+    /** Insert a span into the tree, linking it to its parent if present. */
+    addSpan(span) {
+        // Create or retrieve the node for this span.
+        let node = this.nodes.get(span.spanId);
+        if (node) {
+            // Node was pre-created as a placeholder by a child — update the span.
+            node.span = span;
+        }
+        else {
+            node = { span, children: [] };
+            this.nodes.set(span.spanId, node);
+        }
+        if (span.parentSpanId) {
+            let parentNode = this.nodes.get(span.parentSpanId);
+            if (!parentNode) {
+                // Parent hasn't been added yet — create a placeholder.
+                parentNode = {
+                    span: undefined,
+                    children: [],
+                };
+                this.nodes.set(span.parentSpanId, parentNode);
+            }
+            // Avoid duplicate children on re-add.
+            if (!parentNode.children.some((c) => c.span?.spanId === span.spanId)) {
+                parentNode.children.push(node);
+            }
+        }
+        else {
+            if (!this.rootIds.includes(span.spanId)) {
+                this.rootIds.push(span.spanId);
+            }
+        }
+    }
+    /** Get direct children of a span. */
+    getChildren(spanId) {
+        const node = this.nodes.get(spanId);
+        if (!node)
+            return [];
+        return node.children.map((c) => c.span);
+    }
+    /** Get top-level spans (those with no parent). */
+    getRoots() {
+        return this.rootIds
+            .map((id) => this.nodes.get(id))
+            .filter((n) => n != null && n.span != null)
+            .map((n) => n.span);
+    }
+    /** Serialize the full tree to a JSON-safe structure. */
+    toJSON() {
+        return this.getRoots()
+            .map((root) => this.nodes.get(root.spanId))
+            .filter((n) => n != null)
+            .map((n) => this.serializeNode(n));
+    }
+    serializeNode(node) {
+        const { span } = node;
+        return {
+            spanId: span.spanId,
+            name: span.name,
+            traceId: span.traceId,
+            parentSpanId: span.parentSpanId,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            status: span.status,
+            attributes: { ...span.attributes },
+            events: span.events.map((e) => ({
+                name: e.name,
+                timestamp: e.timestamp,
+                ...(e.attributes ? { attributes: { ...e.attributes } } : {}),
+            })),
+            children: node.children.map((c) => this.serializeNode(c)),
+        };
+    }
+}
+exports.SpanTree = SpanTree;