opensquid 0.5.395

package/dist/runtime/load_matchers.js

@@ -0,0 +1,190 @@
+/**
+ * `when_to_load` matcher evaluator.
+ *
+ * Skills declare load conditions as a list of matchers. The runtime walks the
+ * list per Event and asks: "does this skill want to activate now?" Matchers
+ * are pure predicates (no I/O, no side effects) so the evaluator can run on
+ * every PreToolUse / UserPromptSubmit / Stop / SessionEnd hook without
+ * starving the agent budget.
+ *
+ * Authoritative source: `docs/opensquid-real-design.md` §"Skill format" +
+ * §"Skill properties" + spec `docs/tasks/phase-3-dynamic-loading.md` task 3.1.
+ *
+ * Four matcher kinds (discriminated on `kind`):
+ *
+ *   tool_match       — exact tool name match on a `tool_call` event.
+ *   command_pattern  — regex against `tool_call.args.command` (Bash flavor).
+ *   file_glob        — minimatch glob against a file-path field on `tool_call`.
+ *   event_type       — match the event's own `kind` literal.
+ *
+ * Semantics are OR: a non-empty matcher list activates the skill if ANY
+ * matcher hits. An empty list never activates (a skill with empty
+ * `when_to_load` is either `load: preload` or intentionally inert).
+ *
+ * Shorthand surface — pack authors write the common case as a single-key
+ * object:
+ *
+ *   when_to_load:
+ *     - tool_match: Bash             # canonical: { kind: tool_match, tool: Bash }
+ *     - command_pattern: '^git'      # canonical: { kind: command_pattern, pattern: '^git' }
+ *     - file_glob: 'src/**\/*.ts'    # canonical: { kind: file_glob, glob: 'src/**\/*.ts' }
+ *     - event_type: prompt_submit    # canonical: { kind: event_type, type: prompt_submit }
+ *
+ * `normalizeMatcher` accepts either form. `Matcher` (the Zod schema) only
+ * accepts the canonical (discriminated) form so that everything past the YAML
+ * boundary is type-safe.
+ *
+ * File-glob field precedence on `tool_call` events: `file_path` → `path` →
+ * `notebook_path`. Multiple host conventions, picked in this order because
+ * Claude Code's Read/Edit/Write surface `file_path`, generic FS tools surface
+ * `path`, and notebook editors surface `notebook_path`. The first non-empty
+ * string wins.
+ *
+ * Imports from: zod, minimatch, ./types.
+ * Imported by: src/packs/schemas/skill.ts, src/runtime/index.ts.
+ */
+import { z } from 'zod';
+import { minimatch } from 'minimatch';
+import { EventKind } from './types.js';
+// ---------------------------------------------------------------------------
+// Matcher — canonical discriminated form. The shorthand pre-pass converts
+// single-key objects (`{tool_match: 'Bash'}`) to this shape before parsing.
+//
+// `event_type` accepts any of the eight `EventKind` literals (AUTO.1 widened
+// the union from 4 → 8). We re-export the runtime enum rather than redeclare
+// the four literals locally so a future variant lands in one place.
+// ---------------------------------------------------------------------------
+export const MatcherCanonical = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('tool_match'), tool: z.string().min(1) }),
+    z.object({ kind: z.literal('command_pattern'), pattern: z.string().min(1) }),
+    z.object({ kind: z.literal('file_glob'), glob: z.string().min(1) }),
+    z.object({ kind: z.literal('event_type'), type: EventKind }),
+]);
+// ---------------------------------------------------------------------------
+// Shorthand normalizer — collapses `{tool_match: 'Bash'}` to canonical form.
+//
+// We accept these exact single-key shapes (one key, value is a non-empty
+// string, key name matches a Matcher kind). Anything else passes through
+// unchanged so Zod can produce a precise error path. We deliberately do NOT
+// guess on multi-key objects (e.g. `{kind: 'tool_match', tool: 'Bash', x: 1}`)
+// — extra keys would silently be dropped by the discriminated union, so the
+// canonical form already self-validates.
+// ---------------------------------------------------------------------------
+const SHORTHAND_KEYS = ['tool_match', 'command_pattern', 'file_glob', 'event_type'];
+function isShorthandKey(k) {
+    return SHORTHAND_KEYS.includes(k);
+}
+export function normalizeMatcher(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return raw;
+    const obj = raw;
+    const keys = Object.keys(obj);
+    if (keys.length !== 1)
+        return raw;
+    const k = keys[0];
+    if (k === undefined || !isShorthandKey(k))
+        return raw;
+    const v = obj[k];
+    if (typeof v !== 'string')
+        return raw;
+    switch (k) {
+        case 'tool_match':
+            return { kind: 'tool_match', tool: v };
+        case 'command_pattern':
+            return { kind: 'command_pattern', pattern: v };
+        case 'file_glob':
+            return { kind: 'file_glob', glob: v };
+        case 'event_type':
+            return { kind: 'event_type', type: v };
+    }
+}
+// ---------------------------------------------------------------------------
+// Matcher — public schema used by `Skill.when_to_load`. Wraps the canonical
+// discriminated union with a `z.preprocess` that runs the shorthand pass.
+// ---------------------------------------------------------------------------
+export const Matcher = z.preprocess(normalizeMatcher, MatcherCanonical);
+// ---------------------------------------------------------------------------
+// Regex cache — `command_pattern` patterns recompile on every event without
+// this. Cache key is the pattern string itself; entries never expire (matchers
+// come from pack YAML, so the working set is bounded by pack count).
+//
+// `compileRegex` returns `null` on bad regex AND logs to stderr. The matcher
+// then treats that pattern as a non-match so a typoed regex degrades a single
+// skill, not the whole hook. Negative results are NOT cached — fixing a typo
+// at pack-edit time should take effect on next load.
+// ---------------------------------------------------------------------------
+const regexCache = new Map();
+function compileRegex(pattern) {
+    const cached = regexCache.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const r = new RegExp(pattern);
+        regexCache.set(pattern, r);
+        return r;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`[opensquid] when_to_load command_pattern bad regex: ${pattern} — ${msg}`);
+        return null;
+    }
+}
+/** Test-only: drop the regex cache so per-test mutations don't leak. */
+export function clearRegexCache() {
+    regexCache.clear();
+}
+// ---------------------------------------------------------------------------
+// Field precedence for `file_glob` — Claude Code's Read/Edit/Write use
+// `file_path`, generic FS tools use `path`, NotebookEdit uses `notebook_path`.
+// First non-empty wins. Returns empty string when none present so callers can
+// short-circuit cheaply.
+// ---------------------------------------------------------------------------
+function extractFilePath(args) {
+    const candidates = ['file_path', 'path', 'notebook_path'];
+    for (const key of candidates) {
+        const v = args[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// matchesEvent — OR-walk the matcher list. Returns true on first hit.
+//
+// Tool-call-only matchers (`tool_match`, `command_pattern`, `file_glob`)
+// short-circuit when the event isn't a tool_call. `event_type` works on every
+// kind. The function is pure — no state, no I/O, no throws.
+// ---------------------------------------------------------------------------
+export function matchesEvent(matchers, event) {
+    for (const m of matchers) {
+        if (m.kind === 'event_type') {
+            if (m.type === event.kind)
+                return true;
+            continue;
+        }
+        if (event.kind !== 'tool_call')
+            continue;
+        if (m.kind === 'tool_match') {
+            if (event.tool === m.tool)
+                return true;
+            continue;
+        }
+        if (m.kind === 'command_pattern') {
+            const cmd = event.args.command;
+            if (typeof cmd !== 'string')
+                continue;
+            const re = compileRegex(m.pattern);
+            if (re?.test(cmd) === true)
+                return true;
+            continue;
+        }
+        if (m.kind === 'file_glob') {
+            const path = extractFilePath(event.args);
+            if (path !== '' && minimatch(path, m.glob))
+                return true;
+            continue;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=load_matchers.js.map

package/dist/runtime/load_matchers.js.map

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

package/dist/runtime/observability/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Observability module barrel (OBSERVE.1).
+ *
+ * Public surface:
+ *
+ *   TraceReader      — libsql-backed reader over `checkpoints` +
+ *                      `run_manifests` + `terminal_markers`
+ *   TailOpts         — args for `TraceReader.tail`
+ *   ListRecentOpts   — args for `TraceReader.listRecent`
+ *   TraceEvent       — one primitive-call boundary
+ *   TraceTimeline    — one run's ordered timeline + manifest identity
+ *   TraceListEntry   — `listRecent` row (no per-step events)
+ *   TraceStatus      — completed | in_flight | errored | interrupted
+ *
+ * The reader does NOT introduce new tables. Every query hits DURABLE.1's
+ * `checkpoints` + DURABLE.4's `run_manifests` and `terminal_markers`.
+ * Single source of truth.
+ */
+export { TraceReader, type ListRecentOpts, type TailOpts } from './trace_reader.js';
+export type { TraceEvent, TraceListEntry, TraceStatus, TraceTimeline } from './trace_types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEpF,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/runtime/observability/index.js

@@ -0,0 +1,20 @@
+/**
+ * Observability module barrel (OBSERVE.1).
+ *
+ * Public surface:
+ *
+ *   TraceReader      — libsql-backed reader over `checkpoints` +
+ *                      `run_manifests` + `terminal_markers`
+ *   TailOpts         — args for `TraceReader.tail`
+ *   ListRecentOpts   — args for `TraceReader.listRecent`
+ *   TraceEvent       — one primitive-call boundary
+ *   TraceTimeline    — one run's ordered timeline + manifest identity
+ *   TraceListEntry   — `listRecent` row (no per-step events)
+ *   TraceStatus      — completed | in_flight | errored | interrupted
+ *
+ * The reader does NOT introduce new tables. Every query hits DURABLE.1's
+ * `checkpoints` + DURABLE.4's `run_manifests` and `terminal_markers`.
+ * Single source of truth.
+ */
+export { TraceReader } from './trace_reader.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAsC,MAAM,mBAAmB,CAAC"}

package/dist/runtime/observability/otel_export.d.ts

@@ -0,0 +1,58 @@
+/**
+ * OBSERVE.1 — OpenTelemetry OTLP/JSON export.
+ *
+ * Subset of the OTLP/JSON trace format (spec:
+ * https://opentelemetry.io/docs/specs/otel/protocol/otlp/#otlpjson) —
+ * enough for AgentOps / LangSmith / Jaeger to import a single run's
+ * timeline as a trace with one span per primitive call.
+ *
+ * ID derivation (locked):
+ *
+ *   trace_id  =  sha256(runId).slice(0, 32)              // 16 bytes / 32 hex
+ *   span_id   =  sha256(runId + ':' + stepIdx).slice(0, 16)  // 8 bytes / 16 hex
+ *
+ * Hex-string IDs satisfy the OTLP/JSON encoding spec (the binary protocol
+ * uses raw bytes; the JSON encoding uses hex strings).
+ *
+ * Imports from: node:crypto, ./trace_types.js.
+ * Imported by: ./trace_reader.ts.
+ */
+import type { TraceTimeline } from './trace_types.js';
+interface OtelAttrValue {
+    stringValue?: string;
+    intValue?: string;
+}
+interface OtelAttr {
+    key: string;
+    value: OtelAttrValue;
+}
+interface OtelSpan {
+    trace_id: string;
+    span_id: string;
+    name: string;
+    start_time_unix_nano: string;
+    end_time_unix_nano: string;
+    status: {
+        code: 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR';
+        message?: string;
+    };
+    attributes: OtelAttr[];
+}
+export interface OtelExport {
+    resourceSpans: {
+        resource: {
+            attributes: OtelAttr[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: OtelSpan[];
+        }[];
+    }[];
+}
+/** Convert a TraceTimeline to OTLP/JSON. trace_id = 32 hex; span_id = 16 hex. */
+export declare function toOtel(t: TraceTimeline): OtelExport;
+export {};
+//# sourceMappingURL=otel_export.d.ts.map

package/dist/runtime/observability/otel_export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel_export.d.ts","sourceRoot":"","sources":["../../../src/runtime/observability/otel_export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,UAAU,aAAa;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,QAAQ;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE;QAAE,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE;QACb,QAAQ,EAAE;YAAE,UAAU,EAAE,QAAQ,EAAE,CAAA;SAAE,CAAC;QACrC,UAAU,EAAE;YAAE,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;SAAE,EAAE,CAAC;KAC/E,EAAE,CAAC;CACL;AAED,iFAAiF;AACjF,wBAAgB,MAAM,CAAC,CAAC,EAAE,aAAa,GAAG,UAAU,CA6CnD"}

package/dist/runtime/observability/otel_export.js

@@ -0,0 +1,74 @@
+/**
+ * OBSERVE.1 — OpenTelemetry OTLP/JSON export.
+ *
+ * Subset of the OTLP/JSON trace format (spec:
+ * https://opentelemetry.io/docs/specs/otel/protocol/otlp/#otlpjson) —
+ * enough for AgentOps / LangSmith / Jaeger to import a single run's
+ * timeline as a trace with one span per primitive call.
+ *
+ * ID derivation (locked):
+ *
+ *   trace_id  =  sha256(runId).slice(0, 32)              // 16 bytes / 32 hex
+ *   span_id   =  sha256(runId + ':' + stepIdx).slice(0, 16)  // 8 bytes / 16 hex
+ *
+ * Hex-string IDs satisfy the OTLP/JSON encoding spec (the binary protocol
+ * uses raw bytes; the JSON encoding uses hex strings).
+ *
+ * Imports from: node:crypto, ./trace_types.js.
+ * Imported by: ./trace_reader.ts.
+ */
+import { createHash } from 'node:crypto';
+/** Convert a TraceTimeline to OTLP/JSON. trace_id = 32 hex; span_id = 16 hex. */
+export function toOtel(t) {
+    const traceId = sha256Hex(t.runId).slice(0, 32);
+    const spans = t.events.map((e) => {
+        const span = {
+            trace_id: traceId,
+            span_id: sha256Hex(`${t.runId}:${e.stepIdx}`).slice(0, 16),
+            name: e.fn,
+            start_time_unix_nano: msToUnixNanoString(e.startedAtMs),
+            end_time_unix_nano: msToUnixNanoString(e.completedAtMs),
+            status: e.status === 'completed'
+                ? { code: 'STATUS_CODE_OK' }
+                : { code: 'STATUS_CODE_ERROR', message: e.errorMessage ?? '' },
+            attributes: [
+                { key: 'opensquid.step_idx', value: { intValue: e.stepIdx.toString() } },
+                { key: 'opensquid.inputs_hash', value: { stringValue: e.inputsHash } },
+            ],
+        };
+        if (e.asBinding !== undefined) {
+            span.attributes.push({ key: 'opensquid.as', value: { stringValue: e.asBinding } });
+        }
+        if (e.outputsPreview !== undefined) {
+            span.attributes.push({
+                key: 'opensquid.outputs_preview',
+                value: { stringValue: e.outputsPreview },
+            });
+        }
+        return span;
+    });
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        { key: 'service.name', value: { stringValue: `opensquid/${t.packId}` } },
+                        { key: 'opensquid.skill', value: { stringValue: t.skill } },
+                        { key: 'opensquid.rule_id', value: { stringValue: t.ruleId } },
+                        { key: 'opensquid.event_kind', value: { stringValue: t.eventKind } },
+                        { key: 'opensquid.run_id', value: { stringValue: t.runId } },
+                    ],
+                },
+                scopeSpans: [{ scope: { name: 'opensquid.trace', version: '1' }, spans }],
+            },
+        ],
+    };
+}
+function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+function msToUnixNanoString(ms) {
+    // 1ms = 1_000_000ns. BigInt to avoid Number precision loss above 2^53ns.
+    return (BigInt(ms) * 1000000n).toString();
+}
+//# sourceMappingURL=otel_export.js.map

package/dist/runtime/observability/otel_export.js.map

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

package/dist/runtime/observability/trace_reader.d.ts

@@ -0,0 +1,104 @@
+/**
+ * OBSERVE.1 — trace timeline reader.
+ *
+ * Reads the existing DURABLE.1 + DURABLE.4 tables (`checkpoints` +
+ * `run_manifests` + `terminal_markers`) and renders them as a typed
+ * timeline. There is NO separate trace table — the checkpoint log IS
+ * the trace data. Every query in this module hits those three tables
+ * directly; nothing is duplicated, nothing is denormalized.
+ *
+ * Status inference (4 paths):
+ *
+ *   completed    — terminal_markers row exists AND no errored checkpoint
+ *   errored      — terminal_markers row exists AND ≥1 errored checkpoint
+ *   in_flight    — no terminal_markers row AND lastCompletedAtMs within
+ *                  RESUME_WINDOW_MS (60s, same as Resumer)
+ *   interrupted  — no terminal_markers row AND lastCompletedAtMs is older
+ *                  than RESUME_WINDOW_MS (the Resumer would skip these)
+ *
+ * OpenTelemetry export uses derived IDs:
+ *
+ *   trace_id  =  sha256(runId).slice(0, 32)              // 16 bytes / 32 hex
+ *   span_id   =  sha256(runId + ':' + stepIdx).slice(0, 16)  // 8 bytes / 16 hex
+ *
+ * Previews are truncated to 200 user-visible code points (UTF-8-safe via
+ * `Array.from`) and then passed through `stripSecrets` from
+ * `deliver_only.ts` — same regex pattern as the SCHED.2 deliver-only
+ * webhook path. Inputs only carry a content-addressed hash in the
+ * checkpoint, so `inputsPreview` is derived from the hash; outputs hold
+ * the canonical-JSON-revived value so `outputsPreview` is a JSON snippet.
+ *
+ * Tail polling defaults to 1000ms with a 100ms floor — libsql is
+ * resilient but hammering at 10ms doesn't reflect anything `tail`-shaped
+ * a user actually needs.
+ *
+ * Imports from: @libsql/client, node:crypto, ../deliver_only.js,
+ *               ../durable/canonical_json.js, ./trace_types.js.
+ * Imported by: OBSERVE.2 CLI, downstream consumers via barrel.
+ */
+import type { Client } from '@libsql/client';
+import type { TraceEvent, TraceListEntry, TraceStatus, TraceTimeline } from './trace_types.js';
+export interface TailOpts {
+    /** Earliest `completed_at_ms` to surface. Defaults to `Date.now()`. */
+    sinceMs?: number;
+    /** Optional pack filter. */
+    packId?: string;
+    /** Polling interval in ms; floored at 100ms; default 1000ms. */
+    intervalMs?: number;
+    /** AbortSignal to stop the polling loop cleanly. */
+    signal?: AbortSignal;
+}
+export interface ListRecentOpts {
+    limit?: number;
+    sinceMs?: number;
+    packId?: string;
+    skill?: string;
+    status?: TraceStatus;
+}
+export declare class TraceReader {
+    private readonly db;
+    private readonly nowMs;
+    constructor(db: Client, nowMs?: () => number);
+    /**
+     * Materialize a full timeline for `runId`. Joins one row from
+     * `run_manifests` with its ordered checkpoint rows, then derives status
+     * from the presence of a `terminal_markers` row + the age of the last
+     * completed step.
+     *
+     * Returns `null` when the manifest is missing — even if checkpoint rows
+     * exist, an orphan run can't be reconstructed without manifest identity
+     * (matches the Resumer's `manifest_missing` audit reason).
+     */
+    getTimeline(runId: string): Promise<TraceTimeline | null>;
+    /**
+     * Recent runs, filterable by pack/skill/status/window. Uses
+     * `idx_run_manifests_started_at` for the time-range scan, which keeps
+     * the query sub-100ms at 1M-row scale (validated via EXPLAIN — the
+     * index is hit before the LEFT JOIN against terminal_markers).
+     *
+     * Status filter is applied AFTER the SQL pass since `interrupted` vs
+     * `in_flight` is a time-based heuristic, not a column.
+     */
+    listRecent(opts?: ListRecentOpts): Promise<TraceListEntry[]>;
+    /**
+     * Polling tail. Returns an `AsyncIterable<TraceEvent>` that yields every
+     * checkpoint row whose `completed_at_ms` is `> cursor`, where `cursor`
+     * starts at `opts.sinceMs` and advances after every batch.
+     *
+     * Termination: caller passes an `AbortSignal`. When aborted, the
+     * generator returns cleanly (no thrown error, no leaked timer).
+     *
+     * libsql has no CDC; polling at 1s is fine for human-facing tail use
+     * cases. Higher-frequency consumers (CI dashboards) can drop to the
+     * 100ms floor.
+     */
+    tail(opts?: TailOpts): Promise<AsyncIterable<TraceEvent>>;
+    /**
+     * Serialize a timeline as JSON (pretty) or OTEL (subset of the OTLP
+     * trace JSON format — vendor-importable into AgentOps / LangSmith /
+     * Jaeger). Returns `''` for a nonexistent runId so callers don't have
+     * to disambiguate `null` vs serialization failure.
+     */
+    export(runId: string, format: 'json' | 'otel'): Promise<string>;
+}
+//# sourceMappingURL=trace_reader.d.ts.map

package/dist/runtime/observability/trace_reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace_reader.d.ts","sourceRoot":"","sources":["../../../src/runtime/observability/trace_reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAO7C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAa/F,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,MAAM,MAAiB;IAGjD;;;;;;;;;OASG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAwD/D;;;;;;;;OAQG;IACG,UAAU,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0DtE;;;;;;;;;;;OAWG;IAEG,IAAI,CAAC,IAAI,GAAE,QAAa,GAAG,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAyCnE;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAMtE"}