@mono-agent/observability 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @mono-agent/observability
+
+## Category
+
+Category: `observability`
+
+## Responsibility
+
+Local JSONL run observability and host trace source discovery. It records runtime events and compact summaries, redacts sensitive payload fields by default, lists recorded runs, reads selected run detail for local operator surfaces, and lets running agent processes register their artifact directories in a file-backed trace registry.
+
+## Install / Usage
+
+```bash
+pnpm --filter @mono-agent/observability run build
+```
+
+```ts
+import {
+  createJsonlRunRecorder,
+  registerTraceSource,
+  combineRecordedRunEvents,
+  listRecordedRuns,
+  listTraceRuns,
+  readRecordedRun,
+} from "@mono-agent/observability";
+```
+
+## Public API
+
+- `createJsonlRunRecorder`, `JsonlRunRecorder`
+- `listRecordedRuns`, `readRecordedRun`, `classifyRecordedRunEvent`
+- `combineRecordedRunEvents`
+- `registerTraceSource`, `listTraceSources`, `listTraceRuns`, `readTraceRun`
+- `redactJsonValue`
+- `ObservabilityError`, `ObservabilityReadError`
+- Recorder, summary, list, detail, event, trace source, and trace run types
+
+## Timeline Display
+
+Raw `.events.jsonl` artifacts stay append-only and one event per line. UI surfaces that need readable timelines can call `combineRecordedRunEvents()` to collapse adjacent assistant `thinking` or visible `text` stream chunks into bounded display rows while preserving raw source index ranges and event counts. Browser bundles can import the helper from `@mono-agent/observability/event-timeline` without pulling in the Node-backed artifact readers.
+
+## Trace Registry
+
+The trace registry is a directory of `agent-runtime.trace-source.v1` manifest JSON files. A running host registers one source with a stable `sourceId`, label, artifact directory, process id, status, and heartbeat timestamp. The registry only discovers agents and their artifact locations; run summaries and event JSONL files remain in each source's artifact directory.
+
+Running sources become `stale` when their heartbeat is older than the configured stale interval. Stopped and failed sources remain listed so the dashboard can distinguish a clean shutdown from a crashed or misconfigured host. The registry reader validates source/run ids against path traversal, ignores malformed manifests with warnings, and reuses the recorded-run reader's redaction and bounded-read limits.
+
+## Dependency Boundary
+
+This package writes and reads local artifact and registry files only. It has no runtime, adapter, UI, database, queue, or network dependency.
+
+## What This Package Does Not Own
+
+It does not provide a hosted trace backend, metrics service, durable database, UI, LangSmith export, OpenTelemetry exporter, or model-specific telemetry collector.
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/observability run build
+pnpm --filter @mono-agent/observability run typecheck
+pnpm --filter @mono-agent/observability run test
+```

package/dist/artifact-fs.d.ts

@@ -0,0 +1,50 @@
+import { mkdir } from "node:fs/promises";
+/**
+ * Shared, security-critical filesystem and validation helpers for the
+ * observability artifact store. These guards are duplicated nowhere else;
+ * every recorder/reader/registry module imports from here so the traversal
+ * defenses stay identical.
+ */
+export declare const DEFAULT_MAX_RUNS = 50;
+export declare const DEFAULT_MAX_EVENTS_PER_RUN = 500;
+export declare const DEFAULT_MAX_STRING_BYTES = 4096;
+/** Thrown to abort with a caller-supplied, code-tagged error. */
+export type Raise = (message: string) => never;
+/** Variant that also forwards the offending field name into the error details. */
+export type RaiseField = (message: string, field: string) => never;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isErrno(error: unknown, code: string): boolean;
+export declare function errorMessage(error: unknown): string;
+export declare function stringField(record: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Collapse a candidate identifier into a path-safe artifact base name. Any
+ * character outside `[a-z0-9._-]` is replaced so the result can never contain a
+ * path separator; `safeJoin` still enforces containment as a second layer.
+ */
+export declare function safeArtifactName(value: string): string;
+/**
+ * Reject a run id that could traverse outside the artifact directory. Empty/
+ * non-string ids raise via `raiseEmpty`; traversal-shaped ids raise via
+ * `raiseTraversal`. The two callbacks let each package keep its distinct error
+ * code/message surface (recorded-runs and trace-sources historically differed
+ * on the empty-id code), while the guard logic stays identical.
+ */
+export declare function normalizeRunId(runId: string, raiseTraversal: Raise, raiseEmpty?: Raise): string;
+/**
+ * Resolve `fileName` under `root` and fail closed if the result escapes the
+ * (normalized, separator-terminated) root. `raise` carries the package-specific
+ * escape message ("escapes artifactDir" vs "escapes registryDir").
+ */
+export declare function safeJoin(root: string, fileName: string, raise: Raise): string;
+export declare function positiveInteger(value: number | undefined, fallback: number, field: string, raise: RaiseField): number;
+export declare function minInteger(value: number | undefined, fallback: number, min: number, field: string, raise: RaiseField): number;
+/**
+ * Write a serialized artifact atomically via a temp file + rename, so readers
+ * (list/read) never observe a half-written file. The registry already did this;
+ * the recorder now shares the same primitive for its summary + events files.
+ * The temp name carries a per-process sequence (not a timestamp) so concurrent
+ * writers in the same millisecond never collide on the temp path.
+ */
+export declare function writeJsonAtomic(filePath: string, contents: string): Promise<void>;
+export { mkdir };
+//# sourceMappingURL=artifact-fs.d.ts.map

package/dist/artifact-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-fs.d.ts","sourceRoot":"","sources":["../src/artifact-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,kBAAkB,CAAC;AAG5D;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,iEAAiE;AACjE,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;AAE/C,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC;AAEnE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG5F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAE,KAAsB,GAAG,MAAM,CAS/G;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAQ7E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAQrH;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAQ7H;AAID;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/artifact-fs.js

@@ -0,0 +1,97 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { join, normalize, resolve, sep } from "node:path";
+/**
+ * Shared, security-critical filesystem and validation helpers for the
+ * observability artifact store. These guards are duplicated nowhere else;
+ * every recorder/reader/registry module imports from here so the traversal
+ * defenses stay identical.
+ */
+export const DEFAULT_MAX_RUNS = 50;
+export const DEFAULT_MAX_EVENTS_PER_RUN = 500;
+export const DEFAULT_MAX_STRING_BYTES = 4_096;
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isErrno(error, code) {
+    return isRecord(error) && error.code === code;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function stringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * Collapse a candidate identifier into a path-safe artifact base name. Any
+ * character outside `[a-z0-9._-]` is replaced so the result can never contain a
+ * path separator; `safeJoin` still enforces containment as a second layer.
+ */
+export function safeArtifactName(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "") || "run";
+}
+/**
+ * Reject a run id that could traverse outside the artifact directory. Empty/
+ * non-string ids raise via `raiseEmpty`; traversal-shaped ids raise via
+ * `raiseTraversal`. The two callbacks let each package keep its distinct error
+ * code/message surface (recorded-runs and trace-sources historically differed
+ * on the empty-id code), while the guard logic stays identical.
+ */
+export function normalizeRunId(runId, raiseTraversal, raiseEmpty = raiseTraversal) {
+    if (typeof runId !== "string" || runId.trim().length === 0) {
+        raiseEmpty("runId must be a non-empty string.");
+    }
+    const trimmed = runId.trim();
+    if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("..")) {
+        raiseTraversal("runId cannot contain path separators or '..'.");
+    }
+    return trimmed;
+}
+/**
+ * Resolve `fileName` under `root` and fail closed if the result escapes the
+ * (normalized, separator-terminated) root. `raise` carries the package-specific
+ * escape message ("escapes artifactDir" vs "escapes registryDir").
+ */
+export function safeJoin(root, fileName, raise) {
+    const normalizedRoot = normalize(resolve(root));
+    const resolved = normalize(join(normalizedRoot, fileName));
+    const safeRoot = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+    if (!resolved.startsWith(safeRoot)) {
+        raise("escape");
+    }
+    return resolved;
+}
+export function positiveInteger(value, fallback, field, raise) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        raise(`${field} must be a positive integer.`, field);
+    }
+    return value;
+}
+export function minInteger(value, fallback, min, field, raise) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!Number.isInteger(value) || value < min) {
+        raise(`${field} must be an integer of at least ${min}.`, field);
+    }
+    return value;
+}
+let atomicWriteSequence = 0;
+/**
+ * Write a serialized artifact atomically via a temp file + rename, so readers
+ * (list/read) never observe a half-written file. The registry already did this;
+ * the recorder now shares the same primitive for its summary + events files.
+ * The temp name carries a per-process sequence (not a timestamp) so concurrent
+ * writers in the same millisecond never collide on the temp path.
+ */
+export async function writeJsonAtomic(filePath, contents) {
+    atomicWriteSequence += 1;
+    const tempPath = `${filePath}.${process.pid}.${atomicWriteSequence}.tmp`;
+    await writeFile(tempPath, contents, "utf8");
+    await rename(tempPath, filePath);
+}
+export { mkdir };
+//# sourceMappingURL=artifact-fs.js.map

package/dist/artifact-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-fs.js","sourceRoot":"","sources":["../src/artifact-fs.ts"],"names":[],"mappings":"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"}

package/dist/content.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared content-shaping helpers for run-event summaries. Both the recorded-run
+ * reader and the timeline combiner classify the same assistant message blocks
+ * and compact the same way, so the kind-walk and the truncation live here once.
+ */
+export declare const SUMMARY_MAX_CHARS = 220;
+export type AssistantContentKind = "thinking" | "text";
+export interface AssistantContentWalk {
+    readonly kind: AssistantContentKind;
+    /** Concatenated block text, when any block carried text; otherwise undefined. */
+    readonly text: string | undefined;
+}
+/** Collapse whitespace and bound a summary string to {@link SUMMARY_MAX_CHARS} characters. */
+export declare function compactString(value: string, maxChars?: number): string;
+/**
+ * Walk an assistant `message` object's content blocks and report a single
+ * content kind, or `undefined` when the content is empty, mixed
+ * (thinking + text), or contains any non-text/thinking block. The walk also
+ * collects block text so streaming callers can join adjacent chunks.
+ */
+export declare function classifyAssistantContent(message: unknown): AssistantContentWalk | undefined;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAoB,GAAG,MAAM,CAMjF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CAgC3F"}

package/dist/content.js

@@ -0,0 +1,66 @@
+import { isRecord } from "./artifact-fs.js";
+/**
+ * Shared content-shaping helpers for run-event summaries. Both the recorded-run
+ * reader and the timeline combiner classify the same assistant message blocks
+ * and compact the same way, so the kind-walk and the truncation live here once.
+ */
+export const SUMMARY_MAX_CHARS = 220;
+/** Collapse whitespace and bound a summary string to {@link SUMMARY_MAX_CHARS} characters. */
+export function compactString(value, maxChars = SUMMARY_MAX_CHARS) {
+    const compact = value.replace(/\s+/gu, " ").trim();
+    if (compact.length <= maxChars) {
+        return compact;
+    }
+    return `${compact.slice(0, maxChars)}…`;
+}
+/**
+ * Walk an assistant `message` object's content blocks and report a single
+ * content kind, or `undefined` when the content is empty, mixed
+ * (thinking + text), or contains any non-text/thinking block. The walk also
+ * collects block text so streaming callers can join adjacent chunks.
+ */
+export function classifyAssistantContent(message) {
+    if (!isRecord(message)) {
+        return undefined;
+    }
+    const content = message.content;
+    if (!Array.isArray(content) || content.length === 0) {
+        return undefined;
+    }
+    let kind;
+    const texts = [];
+    for (const block of content) {
+        if (!isRecord(block) || (block.type !== "thinking" && block.type !== "text")) {
+            return undefined;
+        }
+        if (kind === undefined) {
+            kind = block.type;
+        }
+        else if (kind !== block.type) {
+            return undefined;
+        }
+        const text = blockText(block, block.type);
+        if (text !== undefined) {
+            texts.push(text);
+        }
+    }
+    if (kind === undefined) {
+        return undefined;
+    }
+    return {
+        kind,
+        text: texts.length > 0 ? texts.join("") : undefined,
+    };
+}
+function blockText(block, kind) {
+    const value = kind === "thinking"
+        ? rawStringField(block, "thinking") ?? rawStringField(block, "text") ?? rawStringField(block, "content")
+        : rawStringField(block, "text") ?? rawStringField(block, "content");
+    return value;
+}
+/** String field accessor that preserves empty/whitespace strings (unlike the trimmed-non-empty variant). */
+function rawStringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;GAIG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAUrC,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,QAAQ,GAAG,iBAAiB;IACvE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAgB;IACvD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,IAAsC,CAAC;IAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;YAC7E,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;KACpD,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAA8B,EAAE,IAA0B;IAC3E,MAAM,KAAK,GAAG,IAAI,KAAK,UAAU;QAC/B,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC;QACxG,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACtE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4GAA4G;AAC5G,SAAS,cAAc,CAAC,MAA+B,EAAE,GAAW;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC"}

package/dist/event-timeline.d.ts

@@ -0,0 +1,3 @@
+import type { RecordedRunEvent, RecordedRunTimelineItem } from "./types.js";
+export declare function combineRecordedRunEvents(events: readonly RecordedRunEvent[]): readonly RecordedRunTimelineItem[];
+//# sourceMappingURL=event-timeline.d.ts.map

package/dist/event-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-timeline.d.ts","sourceRoot":"","sources":["../src/event-timeline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,uBAAuB,EAAE,CAiChH"}

package/dist/event-timeline.js

@@ -0,0 +1,78 @@
+import { isRecord } from "./artifact-fs.js";
+import { classifyAssistantContent, compactString } from "./content.js";
+export function combineRecordedRunEvents(events) {
+    const timeline = [];
+    let index = 0;
+    while (index < events.length) {
+        const current = events[index];
+        if (current === undefined) {
+            break;
+        }
+        const currentChunk = assistantStreamChunk(current);
+        if (currentChunk === undefined) {
+            timeline.push(singleEventItem(current));
+            index += 1;
+            continue;
+        }
+        const group = [current];
+        const chunks = [currentChunk];
+        let nextIndex = index + 1;
+        while (nextIndex < events.length) {
+            const next = events[nextIndex];
+            const nextChunk = next === undefined ? undefined : assistantStreamChunk(next);
+            if (next === undefined || nextChunk === undefined || nextChunk.kind !== currentChunk.kind) {
+                break;
+            }
+            group.push(next);
+            chunks.push(nextChunk);
+            nextIndex += 1;
+        }
+        timeline.push(group.length === 1 ? singleEventItem(current) : combinedEventItem(group, chunks));
+        index = nextIndex;
+    }
+    return timeline;
+}
+function singleEventItem(event) {
+    return {
+        ...event,
+        sourceEventCount: 1,
+        sourceEventStartIndex: event.index,
+        sourceEventEndIndex: event.index,
+    };
+}
+function combinedEventItem(events, chunks) {
+    const first = events[0];
+    const firstChunk = chunks[0];
+    if (first === undefined || firstChunk === undefined) {
+        throw new Error("combinedEventItem requires at least one source event");
+    }
+    const last = events[events.length - 1] ?? first;
+    const kind = firstChunk.kind;
+    const summary = compactString(chunks.map((chunk) => chunk.text ?? "").join("") || events.map((event) => event.summary).join(" "));
+    return {
+        index: first.index,
+        ...(first.type === undefined ? {} : { type: first.type }),
+        category: kind === "thinking" ? "thinking" : "message",
+        ...(first.timestamp === undefined ? {} : { timestamp: first.timestamp }),
+        label: kind === "thinking" ? "Assistant thoughts" : "Assistant message",
+        summary,
+        payload: {
+            type: "assistant.timeline.combined",
+            contentKind: kind,
+            sourceEventCount: events.length,
+            sourceEventStartIndex: first.index,
+            sourceEventEndIndex: last.index,
+            preview: summary,
+        },
+        sourceEventCount: events.length,
+        sourceEventStartIndex: first.index,
+        sourceEventEndIndex: last.index,
+    };
+}
+function assistantStreamChunk(event) {
+    if (event.type !== "assistant" || !isRecord(event.payload)) {
+        return undefined;
+    }
+    return classifyAssistantContent(event.payload.message);
+}
+//# sourceMappingURL=event-timeline.js.map

package/dist/event-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-timeline.js","sourceRoot":"","sources":["../src/event-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AASvE,MAAM,UAAU,wBAAwB,CAAC,MAAmC;IAC1E,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM;QACR,CAAC;QACD,MAAM,YAAY,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;YACxC,KAAK,IAAI,CAAC,CAAC;YACX,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAC;QAC9B,IAAI,SAAS,GAAG,KAAK,GAAG,CAAC,CAAC;QAC1B,OAAO,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;YAC9E,IAAI,IAAI,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,YAAY,CAAC,IAAI,EAAE,CAAC;gBAC1F,MAAM;YACR,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvB,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;QAED,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAChG,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,eAAe,CAAC,KAAuB;IAC9C,OAAO;QACL,GAAG,KAAK;QACR,gBAAgB,EAAE,CAAC;QACnB,qBAAqB,EAAE,KAAK,CAAC,KAAK;QAClC,mBAAmB,EAAE,KAAK,CAAC,KAAK;KACjC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,MAAmC,EACnC,MAAuC;IAEvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC;IAChD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;IAC7B,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClI,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACzD,QAAQ,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACtD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACxE,KAAK,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,mBAAmB;QACvE,OAAO;QACP,OAAO,EAAE;YACP,IAAI,EAAE,6BAA6B;YACnC,WAAW,EAAE,IAAI;YACjB,gBAAgB,EAAE,MAAM,CAAC,MAAM;YAC/B,qBAAqB,EAAE,KAAK,CAAC,KAAK;YAClC,mBAAmB,EAAE,IAAI,CAAC,KAAK;YAC/B,OAAO,EAAE,OAAO;SACjB;QACD,gBAAgB,EAAE,MAAM,CAAC,MAAM;QAC/B,qBAAqB,EAAE,KAAK,CAAC,KAAK;QAClC,mBAAmB,EAAE,IAAI,CAAC,KAAK;KAChC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAuB;IACnD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,wBAAwB,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createJsonlRunRecorder, ObservabilityError, } from "./recorder.js";
+export type { ObservabilityErrorCode, ObservabilityErrorDetails, } from "./recorder.js";
+export { combineRecordedRunEvents, } from "./event-timeline.js";
+export { listRecordedRuns, ObservabilityReadError, readRecordedRun, } from "./recorded-runs.js";
+export type { ObservabilityReadErrorCode, ObservabilityReadErrorDetails, } from "./recorded-runs.js";
+export { listTraceRuns, listTraceSources, readTraceRun, registerTraceSource, TraceSourceRegistryError, } from "./trace-sources.js";
+export type { TraceSourceRegistryErrorCode, TraceSourceRegistryErrorDetails, } from "./trace-sources.js";
+export type { JsonlRunReaderOptions, JsonlRunRecorderOptions, RecordedRunDetail, RecordedRunEvent, RecordedRunEventCategory, RecordedRunListItem, RecordedRunListResult, RecordedRunTimelineItem, RunRecorder, RunSummary, RunSummaryStatus, RuntimeEventLike, RuntimeResultLike, RegisterTraceSourceOptions, TraceRunDetail, TraceRunListItem, TraceRunListOptions, TraceRunListResult, TraceSourceHandle, TraceSourceHealth, TraceSourceListItem, TraceSourceListResult, TraceSourceManifest, TraceSourceRegistryOptions, TraceSourceStatus, UpdateTraceSourceOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,0BAA0B,EAC1B,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createJsonlRunRecorder, ObservabilityError, } from "./recorder.js";
+export { combineRecordedRunEvents, } from "./event-timeline.js";
+export { listRecordedRuns, ObservabilityReadError, readRecordedRun, } from "./recorded-runs.js";
+export { listTraceRuns, listTraceSources, readTraceRun, registerTraceSource, TraceSourceRegistryError, } from "./trace-sources.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/recorded-runs.d.ts

@@ -0,0 +1,14 @@
+import type { JsonlRunReaderOptions, RecordedRunDetail, RecordedRunEventCategory, RecordedRunListResult } from "./types.js";
+export type ObservabilityReadErrorCode = "invalid_reader_options" | "invalid_run_id";
+export type ObservabilityReadErrorDetails = Record<string, unknown> & {
+    readonly code: ObservabilityReadErrorCode;
+};
+export declare class ObservabilityReadError extends Error {
+    readonly code: ObservabilityReadErrorCode;
+    readonly details: ObservabilityReadErrorDetails;
+    constructor(code: ObservabilityReadErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function listRecordedRuns(options: JsonlRunReaderOptions): Promise<RecordedRunListResult>;
+export declare function readRecordedRun(options: JsonlRunReaderOptions, runId: string): Promise<RecordedRunDetail | undefined>;
+export declare function classifyRecordedRunEvent(event: unknown): RecordedRunEventCategory;
+//# sourceMappingURL=recorded-runs.d.ts.map

package/dist/recorded-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorded-runs.d.ts","sourceRoot":"","sources":["../src/recorded-runs.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EAEjB,wBAAwB,EAExB,qBAAqB,EAGtB,MAAM,YAAY,CAAC;AAmBpB,MAAM,MAAM,0BAA0B,GAAG,wBAAwB,GAAG,gBAAgB,CAAC;AACrF,MAAM,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAEpH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;gBAEpC,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAMrG;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAUrG;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoBxC;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAiCjF"}