@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/telemetry/exporters/types.js

@@ -0,0 +1,19 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/** Default retry configuration. */
+export const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 100,
+    backoffFactor: 2,
+    maxDelayMs: 5000,
+};
+/** Default export queue configuration. */
+export const DEFAULT_QUEUE_CONFIG = {
+    maxSize: 128,
+    retry: DEFAULT_RETRY_CONFIG,
+    drainTimeoutMs: 5000,
+};
+/** Default OTLP exporter configuration. */
+export const DEFAULT_OTLP_CONFIG = {
+    batchSize: 512,
+    timeoutMs: 10000,
+};

package/dist/_internal/platform/runtime/telemetry/meter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * RuntimeMeter — lightweight OTel-compatible metric instruments.
+ *
+ * Provides Counter, Histogram, and Gauge instruments without depending
+ * on the @opentelemetry/* packages.
+ *
+ * All operations are synchronous and allocation-light. Label sets are
+ * serialised to a stable string key for Map lookups.
+ */
+import type { Counter, Gauge, Histogram, MeterConfig } from './types.js';
+/**
+ * RuntimeMeter — creates and caches named metric instruments.
+ *
+ * Usage:
+ * ```ts
+ * const turns = meter.counter('turn.completed');
+ * turns.add(1, { provider: 'anthropic' });
+ *
+ * const latency = meter.histogram('llm.latency.ms');
+ * latency.record(342, { model: 'claude-3-5-sonnet' });
+ *
+ * const activeConns = meter.gauge('mcp.connections.active');
+ * activeConns.set(3);
+ * ```
+ */
+export declare class RuntimeMeter {
+    private readonly config;
+    private readonly _counters;
+    private readonly _histograms;
+    private readonly _gauges;
+    constructor(config: MeterConfig);
+    /** Return the meter's instrumentation scope name. */
+    get scope(): string;
+    /**
+     * Get or create a named counter (monotonically increasing).
+     * Repeated calls with the same name return the same instrument.
+     */
+    counter(name: string): Counter;
+    /**
+     * Get or create a named histogram (distribution of values).
+     * Repeated calls with the same name return the same instrument.
+     */
+    histogram(name: string): Histogram;
+    /**
+     * Get or create a named gauge (point-in-time value).
+     * Repeated calls with the same name return the same instrument.
+     */
+    gauge(name: string): Gauge;
+}
+//# sourceMappingURL=meter.d.ts.map

package/dist/_internal/platform/runtime/telemetry/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/telemetry/meter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,SAAS,EAET,WAAW,EAEZ,MAAM,YAAY,CAAC;AAwFpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,MAAM,EAAE,WAAW;IAI/B,qDAAqD;IACrD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAS9B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IASlC;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;CAQ3B"}

package/dist/_internal/platform/runtime/telemetry/meter.js

@@ -0,0 +1,132 @@
+// ── Label key serialisation ─────────────────────────────────────────────────────
+/**
+ * Serialise a label set to a stable, deterministic string key.
+ * Sorts keys to ensure `{a:1,b:2}` and `{b:2,a:1}` produce the same key.
+ */
+function labelKey(labels) {
+    if (!labels || Object.keys(labels).length === 0)
+        return '__default__';
+    return Object.keys(labels)
+        .sort()
+        .map((k) => `${k}=${labels[k]}`)
+        .join(',');
+}
+// ── CounterImpl ──────────────────────────────────────────────────────────────────
+class CounterImpl {
+    _values = new Map();
+    add(delta = 1, labels) {
+        if (delta < 0)
+            return; // Counters are monotonically increasing
+        const key = labelKey(labels);
+        this._values.set(key, (this._values.get(key) ?? 0) + delta);
+    }
+    value(labels) {
+        return this._values.get(labelKey(labels)) ?? 0;
+    }
+}
+class HistogramImpl {
+    _accumulators = new Map();
+    record(value, labels) {
+        const key = labelKey(labels);
+        const acc = this._accumulators.get(key);
+        if (acc === undefined) {
+            this._accumulators.set(key, { count: 1, sum: value, min: value, max: value });
+        }
+        else {
+            acc.count += 1;
+            acc.sum += value;
+            if (value < acc.min)
+                acc.min = value;
+            if (value > acc.max)
+                acc.max = value;
+        }
+    }
+    snapshot(labels) {
+        const acc = this._accumulators.get(labelKey(labels));
+        if (!acc) {
+            return { count: 0, sum: 0, min: 0, max: 0, mean: 0 };
+        }
+        return {
+            count: acc.count,
+            sum: acc.sum,
+            min: acc.min,
+            max: acc.max,
+            mean: acc.count > 0 ? acc.sum / acc.count : 0,
+        };
+    }
+}
+// ── GaugeImpl ───────────────────────────────────────────────────────────────────
+class GaugeImpl {
+    _values = new Map();
+    set(value, labels) {
+        this._values.set(labelKey(labels), value);
+    }
+    value(labels) {
+        return this._values.get(labelKey(labels)) ?? 0;
+    }
+}
+// ── RuntimeMeter ────────────────────────────────────────────────────────────
+/**
+ * RuntimeMeter — creates and caches named metric instruments.
+ *
+ * Usage:
+ * ```ts
+ * const turns = meter.counter('turn.completed');
+ * turns.add(1, { provider: 'anthropic' });
+ *
+ * const latency = meter.histogram('llm.latency.ms');
+ * latency.record(342, { model: 'claude-3-5-sonnet' });
+ *
+ * const activeConns = meter.gauge('mcp.connections.active');
+ * activeConns.set(3);
+ * ```
+ */
+export class RuntimeMeter {
+    config;
+    _counters = new Map();
+    _histograms = new Map();
+    _gauges = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    /** Return the meter's instrumentation scope name. */
+    get scope() {
+        return this.config.scope;
+    }
+    /**
+     * Get or create a named counter (monotonically increasing).
+     * Repeated calls with the same name return the same instrument.
+     */
+    counter(name) {
+        let c = this._counters.get(name);
+        if (!c) {
+            c = new CounterImpl();
+            this._counters.set(name, c);
+        }
+        return c;
+    }
+    /**
+     * Get or create a named histogram (distribution of values).
+     * Repeated calls with the same name return the same instrument.
+     */
+    histogram(name) {
+        let h = this._histograms.get(name);
+        if (!h) {
+            h = new HistogramImpl();
+            this._histograms.set(name, h);
+        }
+        return h;
+    }
+    /**
+     * Get or create a named gauge (point-in-time value).
+     * Repeated calls with the same name return the same instrument.
+     */
+    gauge(name) {
+        let g = this._gauges.get(name);
+        if (!g) {
+            g = new GaugeImpl();
+            this._gauges.set(name, g);
+        }
+        return g;
+    }
+}

package/dist/_internal/platform/runtime/telemetry/spans/agent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent lifecycle span helpers.
+ *
+ * Tracks the full agent state machine:
+ * AGENT_SPAWNING → AGENT_RUNNING → AGENT_AWAITING_MESSAGE → AGENT_AWAITING_TOOL
+ * → AGENT_FINALIZING
+ * Terminal states: AGENT_COMPLETED | AGENT_FAILED | AGENT_CANCELLED
+ *
+ * Agent spans are root spans (new trace per agent) or child of a turn span
+ * when the agent was spawned within an interactive turn.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting an agent lifecycle span. */
+export interface AgentSpanContext {
+    /** Agent ID (unique per spawn). */
+    readonly agentId: string;
+    /** Task ID this agent is executing (if any). */
+    readonly taskId?: string;
+    /** Human-readable description of the agent task. */
+    readonly task: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+    /**
+     * Optional parent span ID for nesting under a turn span.
+     * When provided, this agent span becomes a child of the parent.
+     */
+    readonly parentSpanId?: string;
+}
+/** Phase transitions recordable on an agent lifecycle span. */
+export type AgentPhase = 'running' | 'awaiting_message' | 'awaiting_tool' | 'finalizing';
+/** Result context supplied when ending an agent lifecycle span. */
+export interface AgentSpanEndContext {
+    /** Final outcome of the agent. */
+    readonly outcome: 'completed' | 'failed' | 'cancelled';
+    /** Duration of the agent run in milliseconds. */
+    readonly durationMs: number;
+    /** Error description when outcome is 'failed'. */
+    readonly error?: string;
+    /** Cancel reason when outcome is 'cancelled'. */
+    readonly reason?: string;
+}
+/**
+ * Start an agent lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from AGENT_SPAWNING event.
+ */
+export declare function startAgentSpan(tracer: RuntimeTracer, ctx: AgentSpanContext): Span;
+/**
+ * Record an agent phase transition event.
+ *
+ * @param span - The active agent lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordAgentPhase(span: Span, phase: AgentPhase, attrs?: SpanAttributes): void;
+/**
+ * End an agent lifecycle span.
+ *
+ * @param span - The span returned by `startAgentSpan`.
+ * @param ctx - Agent lifecycle end context.
+ */
+export declare function endAgentSpan(span: Span, ctx: AgentSpanEndContext): void;
+//# sourceMappingURL=agent.d.ts.map

package/dist/_internal/platform/runtime/telemetry/spans/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,kBAAkB,GAClB,eAAe,GACf,YAAY,CAAC;AAEjB,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvD,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAgBjF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,UAAU,EACjB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAuBvE"}

package/dist/_internal/platform/runtime/telemetry/spans/agent.js

@@ -0,0 +1,63 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start an agent lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from AGENT_SPAWNING event.
+ */
+export function startAgentSpan(tracer, ctx) {
+    const attrs = {
+        'agent.id': ctx.agentId,
+        'agent.task': ctx.task.length > 256 ? ctx.task.slice(0, 256) + '...' : ctx.task,
+    };
+    if (ctx.taskId !== undefined) {
+        attrs['task.id'] = ctx.taskId;
+    }
+    return tracer.startSpan('agent.lifecycle', {
+        traceId: ctx.traceId,
+        parentSpanId: ctx.parentSpanId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record an agent phase transition event.
+ *
+ * @param span - The active agent lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordAgentPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`agent.${phase}`, attrs);
+}
+/**
+ * End an agent lifecycle span.
+ *
+ * @param span - The span returned by `startAgentSpan`.
+ * @param ctx - Agent lifecycle end context.
+ */
+export function endAgentSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttributes({
+        'agent.outcome': ctx.outcome,
+        'agent.duration_ms': ctx.durationMs,
+    });
+    span.addEvent(`agent.${ctx.outcome}`);
+    if (ctx.outcome === 'failed' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('agent.error', ctx.error);
+    }
+    else if (ctx.outcome === 'cancelled') {
+        span.setStatus({ code: SpanStatusCode.OK });
+        if (ctx.reason) {
+            span.setAttribute('agent.cancel_reason', ctx.reason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

package/dist/_internal/platform/runtime/telemetry/spans/compaction.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Compaction lifecycle span helpers.
+ *
+ * Tracks the full context compaction state machine:
+ * COMPACTION_CHECK | COMPACTION_AUTOCOMPACT | COMPACTION_REACTIVE
+ * → COMPACTION_MICROCOMPACT | COMPACTION_COLLAPSE | COMPACTION_BOUNDARY_COMMIT
+ * Terminal states: COMPACTION_DONE | COMPACTION_FAILED
+ *
+ * One span per compaction cycle. Captures token deltas and strategy.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a compaction lifecycle span. */
+export interface CompactionSpanContext {
+    /** Session ID this compaction is running for. */
+    readonly sessionId: string;
+    /** Compaction strategy (e.g. 'microcompact', 'collapse', 'auto'). */
+    readonly strategy: string;
+    /** Token count at the time compaction was triggered. */
+    readonly tokenCount: number;
+    /** Token threshold that triggered compaction (if applicable). */
+    readonly threshold?: number;
+    /** Context limit that triggered reactive compaction (if applicable). */
+    readonly limit?: number;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+}
+/** Phase transitions recordable on a compaction lifecycle span. */
+export type CompactionPhase = 'microcompact' | 'collapse' | 'boundary_commit';
+/** Result context supplied when ending a compaction lifecycle span. */
+export interface CompactionSpanEndContext {
+    /** Final outcome of the compaction cycle. */
+    readonly outcome: 'done' | 'failed';
+    /** Token count before compaction. */
+    readonly tokensBefore: number;
+    /** Token count after compaction (only set when outcome is 'done'). */
+    readonly tokensAfter?: number;
+    /** Duration of the compaction in milliseconds (only set when outcome is 'done'). */
+    readonly durationMs?: number;
+    /** Error description when outcome is 'failed'. */
+    readonly error?: string;
+    /** ID of the compaction checkpoint committed (when applicable). */
+    readonly checkpointId?: string;
+}
+/**
+ * Start a compaction lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from COMPACTION_CHECK, COMPACTION_AUTOCOMPACT, or COMPACTION_REACTIVE.
+ */
+export declare function startCompactionSpan(tracer: RuntimeTracer, ctx: CompactionSpanContext): Span;
+/**
+ * Record a compaction phase transition event.
+ *
+ * @param span - The active compaction lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordCompactionPhase(span: Span, phase: CompactionPhase, attrs?: SpanAttributes): void;
+/**
+ * End a compaction lifecycle span.
+ *
+ * @param span - The span returned by `startCompactionSpan`.
+ * @param ctx - Compaction lifecycle end context.
+ */
+export declare function endCompactionSpan(span: Span, ctx: CompactionSpanEndContext): void;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/_internal/platform/runtime/telemetry/spans/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,UAAU,GACV,iBAAiB,CAAC;AAEtB,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,qCAAqC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,qBAAqB,GAAG,IAAI,CAmB3F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,eAAe,EACtB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAkCjF"}

package/dist/_internal/platform/runtime/telemetry/spans/compaction.js

@@ -0,0 +1,70 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a compaction lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from COMPACTION_CHECK, COMPACTION_AUTOCOMPACT, or COMPACTION_REACTIVE.
+ */
+export function startCompactionSpan(tracer, ctx) {
+    const attrs = {
+        'compaction.session_id': ctx.sessionId,
+        'compaction.strategy': ctx.strategy,
+        'compaction.tokens_before': ctx.tokenCount,
+    };
+    if (ctx.threshold !== undefined) {
+        attrs['compaction.threshold'] = ctx.threshold;
+    }
+    if (ctx.limit !== undefined) {
+        attrs['compaction.limit'] = ctx.limit;
+    }
+    return tracer.startSpan('compaction.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a compaction phase transition event.
+ *
+ * @param span - The active compaction lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordCompactionPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`compaction.${phase}`, attrs);
+}
+/**
+ * End a compaction lifecycle span.
+ *
+ * @param span - The span returned by `startCompactionSpan`.
+ * @param ctx - Compaction lifecycle end context.
+ */
+export function endCompactionSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttributes({
+        'compaction.outcome': ctx.outcome,
+        'compaction.tokens_before': ctx.tokensBefore,
+    });
+    if (ctx.tokensAfter !== undefined) {
+        span.setAttribute('compaction.tokens_after', ctx.tokensAfter);
+        span.setAttribute('compaction.tokens_saved', ctx.tokensBefore - ctx.tokensAfter);
+    }
+    if (ctx.durationMs !== undefined) {
+        span.setAttribute('compaction.duration_ms', ctx.durationMs);
+    }
+    if (ctx.checkpointId !== undefined) {
+        span.setAttribute('compaction.checkpoint_id', ctx.checkpointId);
+    }
+    span.addEvent(`compaction.${ctx.outcome}`);
+    if (ctx.outcome === 'failed' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('compaction.error', ctx.error);
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

package/dist/_internal/platform/runtime/telemetry/spans/health.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Health cascade span helpers.
+ *
+ * Creates point-in-time spans for each CASCADE_APPLIED event from the
+ * health cascade engine. These are not lifecycle spans but event spans —
+ * they start and end immediately to record the cascade effect in the trace.
+ *
+ * Health cascade spans are always root spans (no parent) since they are
+ * cross-domain events that may span multiple domain lifecycles.
+ */
+import type { Span } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+import type { CascadeAppliedEvent } from '../../health/types.js';
+/** Context supplied when recording a health cascade span. */
+export interface HealthCascadeSpanContext {
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+    /** Optional parent span ID if the cascade is causally linked to a specific operation. */
+    readonly parentSpanId?: string;
+}
+/**
+ * Record a health cascade as a point-in-time span.
+ *
+ * Starts and immediately ends the span since the cascade is an instantaneous
+ * event rather than an ongoing lifecycle. The span captures rule, source,
+ * target, and effect details.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param event - The CASCADE_APPLIED event from the health engine.
+ * @param ctx - Optional trace context for correlation.
+ */
+export declare function recordHealthCascadeSpan(tracer: RuntimeTracer, event: CascadeAppliedEvent, ctx?: HealthCascadeSpanContext): Span;
+//# sourceMappingURL=health.d.ts.map

package/dist/_internal/platform/runtime/telemetry/spans/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,uBAAuB,CAAC;AAEhF,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,mBAAmB,EAC1B,GAAG,CAAC,EAAE,wBAAwB,GAC7B,IAAI,CA2CN"}

package/dist/_internal/platform/runtime/telemetry/spans/health.js

@@ -0,0 +1,81 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Record a health cascade as a point-in-time span.
+ *
+ * Starts and immediately ends the span since the cascade is an instantaneous
+ * event rather than an ongoing lifecycle. The span captures rule, source,
+ * target, and effect details.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param event - The CASCADE_APPLIED event from the health engine.
+ * @param ctx - Optional trace context for correlation.
+ */
+export function recordHealthCascadeSpan(tracer, event, ctx) {
+    const effectAttrs = extractEffectAttributes(event.effect);
+    const attrs = {
+        'health.cascade.rule_id': event.ruleId,
+        'health.cascade.source': event.source,
+        'health.cascade.target': event.target,
+        'health.cascade.effect_type': event.effect.type,
+        'health.cascade.recovery_exhausted': event.recoveryExhausted,
+        ...effectAttrs,
+    };
+    if (event.sourceContext !== undefined) {
+        for (const [k, v] of Object.entries(event.sourceContext)) {
+            attrs[`health.cascade.source_ctx.${k}`] = v;
+        }
+    }
+    const span = tracer.startSpan('health.cascade', {
+        traceId: ctx?.traceId,
+        parentSpanId: ctx?.parentSpanId,
+        kind: SpanKind.INTERNAL,
+        startTimeMs: event.timestamp,
+        attributes: attrs,
+    });
+    span.addEvent('health.cascade_applied', {
+        'health.cascade.rule_id': event.ruleId,
+        'health.cascade.effect_type': event.effect.type,
+    });
+    // Cascade is treated as an error signal when recovery was exhausted
+    if (event.recoveryExhausted) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: `Cascade after recovery exhausted: ${event.ruleId}`,
+        });
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end(event.timestamp);
+    return span;
+}
+/** Extract flat SpanAttributes from a CascadeEffect variant. */
+function extractEffectAttributes(effect) {
+    switch (effect.type) {
+        case 'CANCEL_INFLIGHT':
+            return { 'health.cascade.effect.scope': effect.scope };
+        case 'BLOCK_DISPATCH':
+            return {
+                'health.cascade.effect.scope': effect.scope,
+                'health.cascade.effect.queueable': effect.queueable,
+            };
+        case 'MARK_CHILDREN':
+            return {
+                'health.cascade.effect.status': effect.status,
+                'health.cascade.effect.notify_parent': effect.notifyParent,
+            };
+        case 'DEREGISTER_TOOLS':
+            return effect.pluginId !== undefined
+                ? { 'health.cascade.effect.plugin_id': effect.pluginId }
+                : {};
+        case 'EMIT_EVENT':
+            return { 'health.cascade.effect.event_type': effect.eventType };
+        case 'BLOCK_NEW':
+            return { 'health.cascade.effect.scope': effect.scope };
+        default: {
+            // Exhaustive check — TypeScript will error if a new variant is added without handling it
+            const _exhaustive = effect;
+            return {};
+        }
+    }
+}

package/dist/_internal/platform/runtime/telemetry/spans/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Barrel export for span helpers.
+ */
+export type { TurnSpanContext, TurnSpanEndContext } from './turn.js';
+export { startTurnSpan, endTurnSpan } from './turn.js';
+export type { ToolSpanContext, ToolSpanEndContext, ToolPhase } from './tool.js';
+export { startToolSpan, recordToolPhase, endToolSpan } from './tool.js';
+export type { LlmSpanContext, LlmSpanEndContext, LlmTokenUsage, } from './llm.js';
+export { startLlmSpan, recordLlmStreamStart, endLlmSpan } from './llm.js';
+export type { PluginSpanContext, PluginSpanEndContext, PluginPhase } from './plugin.js';
+export { startPluginSpan, recordPluginPhase, endPluginSpan } from './plugin.js';
+export type { McpSpanContext, McpSpanEndContext, McpPhase } from './mcp.js';
+export { startMcpSpan, recordMcpPhase, endMcpSpan } from './mcp.js';
+export type { TransportSpanContext, TransportSpanEndContext, TransportPhase } from './transport.js';
+export { startTransportSpan, recordTransportPhase, endTransportSpan } from './transport.js';
+export type { TaskSpanContext, TaskSpanEndContext, TaskPhase } from './task.js';
+export { startTaskSpan, recordTaskPhase, endTaskSpan } from './task.js';
+export type { AgentSpanContext, AgentSpanEndContext, AgentPhase } from './agent.js';
+export { startAgentSpan, recordAgentPhase, endAgentSpan } from './agent.js';
+export type { PermissionSpanContext, PermissionSpanEndContext, PermissionPhase } from './permission.js';
+export { startPermissionSpan, recordPermissionPhase, endPermissionSpan } from './permission.js';
+export type { SessionSpanContext, SessionSpanEndContext, SessionPhase } from './session.js';
+export { startSessionSpan, recordSessionPhase, endSessionSpan } from './session.js';
+export type { CompactionSpanContext, CompactionSpanEndContext, CompactionPhase } from './compaction.js';
+export { startCompactionSpan, recordCompactionPhase, endCompactionSpan } from './compaction.js';
+export type { HealthCascadeSpanContext } from './health.js';
+export { recordHealthCascadeSpan } from './health.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/telemetry/spans/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvD,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExE,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE1E,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhF,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEpE,YAAY,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE5F,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEpF,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/_internal/platform/runtime/telemetry/spans/index.js

@@ -0,0 +1,12 @@
+export { startTurnSpan, endTurnSpan } from './turn.js';
+export { startToolSpan, recordToolPhase, endToolSpan } from './tool.js';
+export { startLlmSpan, recordLlmStreamStart, endLlmSpan } from './llm.js';
+export { startPluginSpan, recordPluginPhase, endPluginSpan } from './plugin.js';
+export { startMcpSpan, recordMcpPhase, endMcpSpan } from './mcp.js';
+export { startTransportSpan, recordTransportPhase, endTransportSpan } from './transport.js';
+export { startTaskSpan, recordTaskPhase, endTaskSpan } from './task.js';
+export { startAgentSpan, recordAgentPhase, endAgentSpan } from './agent.js';
+export { startPermissionSpan, recordPermissionPhase, endPermissionSpan } from './permission.js';
+export { startSessionSpan, recordSessionPhase, endSessionSpan } from './session.js';
+export { startCompactionSpan, recordCompactionPhase, endCompactionSpan } from './compaction.js';
+export { recordHealthCascadeSpan } from './health.js';