@pellux/goodvibes-sdk 0.18.3 → 0.18.12

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

@@ -0,0 +1,67 @@
+/**
+ * LLM provider call span helpers.
+ *
+ * Creates child spans under a turn span to track provider API calls.
+ * These spans capture model, token usage, latency, and error context.
+ */
+import type { Span } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting an LLM span. */
+export interface LlmSpanContext {
+    /** Turn ID this LLM call belongs to. */
+    readonly turnId: string;
+    /** Provider name (e.g. 'anthropic', 'openai'). */
+    readonly provider: string;
+    /** Model ID (e.g. 'claude-sonnet-4-6'). */
+    readonly model: string;
+    /** Trace ID from the parent turn span. */
+    readonly traceId: string;
+    /** Parent span ID (the turn span's spanId). */
+    readonly parentSpanId: string;
+    /** Whether this is a streaming call. */
+    readonly streaming?: boolean;
+    /** Number of messages in the request context. */
+    readonly messageCount?: number;
+}
+/** Token usage recorded when ending an LLM span. */
+export interface LlmTokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+/** Result context supplied when ending an LLM span. */
+export interface LlmSpanEndContext {
+    /** Whether the call succeeded. */
+    readonly success: boolean;
+    /** Stop reason from the provider (e.g. 'end_turn', 'tool_use', 'max_tokens'). */
+    readonly stopReason?: string;
+    /** Token usage if available. */
+    readonly tokens?: LlmTokenUsage;
+    /** Error message if success is false. */
+    readonly error?: string;
+    /** HTTP status code if available (for remote provider calls). */
+    readonly httpStatus?: number;
+}
+/**
+ * Start an LLM provider call span as a child of the turn span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - LLM span context.
+ */
+export declare function startLlmSpan(tracer: RuntimeTracer, ctx: LlmSpanContext): Span;
+/**
+ * Record that the LLM stream has started (first token received).
+ *
+ * @param span - The active LLM span.
+ * @param firstTokenMs - Epoch ms when the first token arrived (optional override).
+ */
+export declare function recordLlmStreamStart(span: Span, firstTokenMs?: number): void;
+/**
+ * End an LLM provider call span.
+ *
+ * @param span - The span returned by `startLlmSpan`.
+ * @param ctx - LLM end context.
+ */
+export declare function endLlmSpan(span: Span, ctx: LlmSpanEndContext): void;
+//# sourceMappingURL=llm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/llm.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAmB7E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CA+BnE"}

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

@@ -0,0 +1,73 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start an LLM provider call span as a child of the turn span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - LLM span context.
+ */
+export function startLlmSpan(tracer, ctx) {
+    const attrs = {
+        'llm.provider': ctx.provider,
+        'llm.model': ctx.model,
+        'turn.id': ctx.turnId,
+        'llm.streaming': ctx.streaming ?? false,
+    };
+    if (ctx.messageCount !== undefined) {
+        attrs['llm.message_count'] = ctx.messageCount;
+    }
+    return tracer.startSpan('llm.call', {
+        traceId: ctx.traceId,
+        parentSpanId: ctx.parentSpanId,
+        // LLM calls are modelled as CLIENT spans (calling an external service)
+        kind: SpanKind.CLIENT,
+        attributes: attrs,
+    });
+}
+/**
+ * Record that the LLM stream has started (first token received).
+ *
+ * @param span - The active LLM span.
+ * @param firstTokenMs - Epoch ms when the first token arrived (optional override).
+ */
+export function recordLlmStreamStart(span, firstTokenMs) {
+    if (span.ended)
+        return;
+    span.addEvent('llm.stream_start', {
+        'llm.time_to_first_token_ms': firstTokenMs ?? Date.now(),
+    });
+}
+/**
+ * End an LLM provider call span.
+ *
+ * @param span - The span returned by `startLlmSpan`.
+ * @param ctx - LLM end context.
+ */
+export function endLlmSpan(span, ctx) {
+    if (span.ended)
+        return;
+    if (ctx.stopReason) {
+        span.setAttribute('llm.stop_reason', ctx.stopReason);
+    }
+    if (ctx.httpStatus !== undefined) {
+        span.setAttribute('llm.http_status', ctx.httpStatus);
+    }
+    if (ctx.tokens) {
+        span.setAttributes({
+            'llm.tokens.input': ctx.tokens.inputTokens,
+            'llm.tokens.output': ctx.tokens.outputTokens,
+            'llm.tokens.cache_read': ctx.tokens.cacheReadTokens ?? 0,
+            'llm.tokens.cache_write': ctx.tokens.cacheWriteTokens ?? 0,
+        });
+    }
+    if (ctx.success) {
+        span.setStatus({ code: SpanStatusCode.OK });
+        span.addEvent('llm.call_completed');
+    }
+    else {
+        const msg = ctx.error ?? 'LLM call failed';
+        span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+        span.setAttribute('llm.error', msg);
+        span.addEvent('llm.call_failed', { 'llm.error': msg });
+    }
+    span.end();
+}

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

@@ -0,0 +1,60 @@
+/**
+ * MCP server lifecycle span helpers.
+ *
+ * Tracks the full MCP server state machine:
+ * MCP_CONFIGURED → MCP_CONNECTING → MCP_CONNECTED → MCP_DEGRADED
+ * Terminal states: MCP_DISCONNECTED | MCP_AUTH_REQUIRED (when not reconnecting)
+ *
+ * One span per MCP server connection lifecycle.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting an MCP server lifecycle span. */
+export interface McpSpanContext {
+    /** MCP server ID. */
+    readonly serverId: string;
+    /** Transport type (e.g. 'stdio', 'sse', 'websocket'). */
+    readonly transport: string;
+    /** Optional server URL for network transports. */
+    readonly url?: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+}
+/** Phase transitions that can be recorded on an MCP lifecycle span. */
+export type McpPhase = 'connecting' | 'connected' | 'degraded' | 'auth_required' | 'reconnecting';
+/** Result context supplied when ending an MCP lifecycle span. */
+export interface McpSpanEndContext {
+    /** Final outcome of the MCP server connection. */
+    readonly outcome: 'connected' | 'disconnected' | 'auth_failed';
+    /** Reason for disconnection if known. */
+    readonly reason?: string;
+    /** Whether a reconnect will be attempted. */
+    readonly willRetry?: boolean;
+    /** Number of tools available when connected. */
+    readonly toolCount?: number;
+    /** Number of resources available when connected. */
+    readonly resourceCount?: number;
+}
+/**
+ * Start an MCP server lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from MCP_CONFIGURED event.
+ */
+export declare function startMcpSpan(tracer: RuntimeTracer, ctx: McpSpanContext): Span;
+/**
+ * Record an MCP server phase transition event.
+ *
+ * @param span - The active MCP lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordMcpPhase(span: Span, phase: McpPhase, attrs?: SpanAttributes): void;
+/**
+ * End an MCP server lifecycle span.
+ *
+ * @param span - The span returned by `startMcpSpan`.
+ * @param ctx - MCP lifecycle end context.
+ */
+export declare function endMcpSpan(span: Span, ctx: McpSpanEndContext): void;
+//# sourceMappingURL=mcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,GAAG,cAAc,CAAC;AAElG,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,GAAG,aAAa,CAAC;IAC/D,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAe7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,QAAQ,EACf,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CA6BnE"}

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

@@ -0,0 +1,67 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start an MCP server lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from MCP_CONFIGURED event.
+ */
+export function startMcpSpan(tracer, ctx) {
+    const attrs = {
+        'mcp.server_id': ctx.serverId,
+        'mcp.transport': ctx.transport,
+    };
+    if (ctx.url !== undefined) {
+        attrs['mcp.url'] = ctx.url;
+    }
+    return tracer.startSpan('mcp.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.CLIENT,
+        attributes: attrs,
+    });
+}
+/**
+ * Record an MCP server phase transition event.
+ *
+ * @param span - The active MCP lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordMcpPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`mcp.${phase}`, attrs);
+}
+/**
+ * End an MCP server lifecycle span.
+ *
+ * @param span - The span returned by `startMcpSpan`.
+ * @param ctx - MCP lifecycle end context.
+ */
+export function endMcpSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttribute('mcp.outcome', ctx.outcome);
+    if (ctx.toolCount !== undefined) {
+        span.setAttribute('mcp.tool_count', ctx.toolCount);
+    }
+    if (ctx.resourceCount !== undefined) {
+        span.setAttribute('mcp.resource_count', ctx.resourceCount);
+    }
+    if (ctx.willRetry !== undefined) {
+        span.setAttribute('mcp.will_retry', ctx.willRetry);
+    }
+    span.addEvent(`mcp.${ctx.outcome}`);
+    if (ctx.outcome === 'auth_failed') {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: 'MCP authentication failed' });
+    }
+    else if (ctx.outcome === 'disconnected' && !ctx.willRetry) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.reason ?? 'MCP disconnected' });
+        if (ctx.reason) {
+            span.setAttribute('mcp.disconnect_reason', ctx.reason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Permission decision span helpers.
+ *
+ * Tracks the full permission evaluation pipeline:
+ * PERMISSION_REQUESTED → RULES_COLLECTED → INPUT_NORMALIZED
+ * → POLICY_EVALUATED → MODE_EVALUATED → SESSION_OVERRIDE_EVALUATED
+ * → SAFETY_CHECKED → DECISION_EMITTED
+ *
+ * One span per permission decision. Child of the active tool span
+ * when a parentSpanId is supplied.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a permission decision span. */
+export interface PermissionSpanContext {
+    /** Tool call ID this permission decision covers. */
+    readonly callId: string;
+    /** Tool name being evaluated. */
+    readonly tool: string;
+    /** Permission category (e.g. 'filesystem', 'network'). */
+    readonly category: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+    /**
+     * Optional parent span ID for nesting under a tool span.
+     * When provided, this permission span becomes a child of the tool span.
+     */
+    readonly parentSpanId?: string;
+}
+/** Phase transitions recordable on a permission decision span. */
+export type PermissionPhase = 'rules_collected' | 'input_normalized' | 'policy_evaluated' | 'mode_evaluated' | 'session_override_evaluated' | 'safety_checked';
+/** Result context supplied when ending a permission decision span. */
+export interface PermissionSpanEndContext {
+    /** Whether the tool call was approved. */
+    readonly approved: boolean;
+    /** Decision source (e.g. 'policy', 'mode', 'session_override', 'safety'). */
+    readonly source: string;
+    /** Whether the input was deemed safe. */
+    readonly safe?: boolean;
+    /** Safety warnings if any were raised. */
+    readonly warnings?: string[];
+}
+/**
+ * Start a permission decision span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from PERMISSION_REQUESTED event.
+ */
+export declare function startPermissionSpan(tracer: RuntimeTracer, ctx: PermissionSpanContext): Span;
+/**
+ * Record a permission evaluation phase transition.
+ *
+ * @param span - The active permission decision span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordPermissionPhase(span: Span, phase: PermissionPhase, attrs?: SpanAttributes): void;
+/**
+ * End a permission decision span.
+ *
+ * @param span - The span returned by `startPermissionSpan`.
+ * @param ctx - Permission decision end context.
+ */
+export declare function endPermissionSpan(span: Span, ctx: PermissionSpanEndContext): void;
+//# sourceMappingURL=permission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/permission.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,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,4BAA4B,GAC5B,gBAAgB,CAAC;AAErB,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,qBAAqB,GAAG,IAAI,CAa3F;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,CA4BjF"}

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

@@ -0,0 +1,63 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a permission decision span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from PERMISSION_REQUESTED event.
+ */
+export function startPermissionSpan(tracer, ctx) {
+    const attrs = {
+        'permission.call_id': ctx.callId,
+        'permission.tool': ctx.tool,
+        'permission.category': ctx.category,
+    };
+    return tracer.startSpan('permission.decision', {
+        traceId: ctx.traceId,
+        parentSpanId: ctx.parentSpanId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a permission evaluation phase transition.
+ *
+ * @param span - The active permission decision span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordPermissionPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`permission.${phase}`, attrs);
+}
+/**
+ * End a permission decision span.
+ *
+ * @param span - The span returned by `startPermissionSpan`.
+ * @param ctx - Permission decision end context.
+ */
+export function endPermissionSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttributes({
+        'permission.approved': ctx.approved,
+        'permission.source': ctx.source,
+    });
+    if (ctx.safe !== undefined) {
+        span.setAttribute('permission.safe', ctx.safe);
+    }
+    if (ctx.warnings !== undefined && ctx.warnings.length > 0) {
+        span.setAttribute('permission.warning_count', ctx.warnings.length);
+    }
+    span.addEvent(ctx.approved ? 'permission.approved' : 'permission.denied');
+    if (!ctx.approved) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: `Permission denied by ${ctx.source}`,
+        });
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Plugin lifecycle span helpers.
+ *
+ * Tracks the full plugin state machine:
+ * PLUGIN_DISCOVERED → PLUGIN_LOADING → PLUGIN_LOADED → PLUGIN_ACTIVE
+ * Terminal states: PLUGIN_ERROR | PLUGIN_UNLOADING → PLUGIN_DISABLED
+ *
+ * One span per plugin lifecycle: starts on PLUGIN_DISCOVERED, ends on terminal state.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a plugin lifecycle span. */
+export interface PluginSpanContext {
+    /** Plugin ID (unique identifier). */
+    readonly pluginId: string;
+    /** File system path to the plugin. */
+    readonly path: string;
+    /** Plugin version string. */
+    readonly version: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+}
+/** Phase transitions that can be recorded on a plugin lifecycle span. */
+export type PluginPhase = 'loading' | 'loaded' | 'active' | 'degraded' | 'unloading';
+/** Result context supplied when ending a plugin lifecycle span. */
+export interface PluginSpanEndContext {
+    /** Final outcome of the plugin lifecycle. */
+    readonly outcome: 'active' | 'error' | 'disabled';
+    /** Error description when outcome is 'error'. */
+    readonly error?: string;
+    /** Reason for disabling when outcome is 'disabled'. */
+    readonly reason?: string;
+    /** Capabilities registered by the plugin (populated on 'active'). */
+    readonly capabilities?: string[];
+}
+/**
+ * Start a plugin lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from PLUGIN_DISCOVERED event.
+ */
+export declare function startPluginSpan(tracer: RuntimeTracer, ctx: PluginSpanContext): Span;
+/**
+ * Record a plugin phase transition event on the active span.
+ *
+ * @param span - The active plugin lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes for this phase.
+ */
+export declare function recordPluginPhase(span: Span, phase: PluginPhase, attrs?: SpanAttributes): void;
+/**
+ * End a plugin lifecycle span.
+ *
+ * @param span - The span returned by `startPluginSpan`.
+ * @param ctx - Plugin lifecycle end context.
+ */
+export declare function endPluginSpan(span: Span, ctx: PluginSpanEndContext): void;
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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,iBAAiB;IAChC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAErF,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;IAClD,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAYnF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,WAAW,EAClB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAwBzE"}

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

@@ -0,0 +1,60 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a plugin lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from PLUGIN_DISCOVERED event.
+ */
+export function startPluginSpan(tracer, ctx) {
+    const attrs = {
+        'plugin.id': ctx.pluginId,
+        'plugin.path': ctx.path,
+        'plugin.version': ctx.version,
+    };
+    return tracer.startSpan('plugin.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a plugin phase transition event on the active span.
+ *
+ * @param span - The active plugin lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes for this phase.
+ */
+export function recordPluginPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`plugin.${phase}`, attrs);
+}
+/**
+ * End a plugin lifecycle span.
+ *
+ * @param span - The span returned by `startPluginSpan`.
+ * @param ctx - Plugin lifecycle end context.
+ */
+export function endPluginSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttribute('plugin.outcome', ctx.outcome);
+    if (ctx.capabilities !== undefined) {
+        span.setAttribute('plugin.capability_count', ctx.capabilities.length);
+    }
+    span.addEvent(`plugin.${ctx.outcome}`);
+    if (ctx.outcome === 'error' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('plugin.error', ctx.error);
+    }
+    else if (ctx.outcome === 'disabled') {
+        span.setStatus({ code: SpanStatusCode.OK });
+        if (ctx.reason) {
+            span.setAttribute('plugin.disable_reason', ctx.reason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Session recovery span helpers.
+ *
+ * Tracks the full session lifecycle:
+ * SESSION_STARTED | SESSION_LOADING → SESSION_RESUMED | SESSION_REPAIRING
+ * → SESSION_RECONCILING → SESSION_READY
+ * Terminal error state: SESSION_RECOVERY_FAILED
+ *
+ * One span per session initialisation / recovery attempt.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a session lifecycle span. */
+export interface SessionSpanContext {
+    /** Session ID. */
+    readonly sessionId: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+    /** Profile ID used for this session (present on new sessions). */
+    readonly profileId?: string;
+    /** Working directory for this session (present on new sessions). */
+    readonly workingDir?: string;
+    /** Path to the saved session file (present on resumed sessions). */
+    readonly path?: string;
+}
+/** Phase transitions recordable on a session lifecycle span. */
+export type SessionPhase = 'loading' | 'resumed' | 'repairing' | 'reconciling';
+/** Result context supplied when ending a session lifecycle span. */
+export interface SessionSpanEndContext {
+    /** Final outcome of the session initialisation. */
+    readonly outcome: 'ready' | 'recovery_failed';
+    /** Error description when outcome is 'recovery_failed'. */
+    readonly error?: string;
+    /** Number of turns loaded on resume (if applicable). */
+    readonly turnCount?: number;
+    /** Number of messages reconciled (if applicable). */
+    readonly messageCount?: number;
+}
+/**
+ * Start a session lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from SESSION_STARTED or SESSION_LOADING event.
+ */
+export declare function startSessionSpan(tracer: RuntimeTracer, ctx: SessionSpanContext): Span;
+/**
+ * Record a session lifecycle phase transition.
+ *
+ * @param span - The active session lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordSessionPhase(span: Span, phase: SessionPhase, attrs?: SpanAttributes): void;
+/**
+ * End a session lifecycle span.
+ *
+ * @param span - The span returned by `startSessionSpan`.
+ * @param ctx - Session lifecycle end context.
+ */
+export declare function endSessionSpan(span: Span, ctx: SessionSpanEndContext): void;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/telemetry/spans/session.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,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,kBAAkB;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,WAAW,GACX,aAAa,CAAC;AAElB,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAoBrF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,qBAAqB,GAAG,IAAI,CAsB3E"}

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

@@ -0,0 +1,64 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a session lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from SESSION_STARTED or SESSION_LOADING event.
+ */
+export function startSessionSpan(tracer, ctx) {
+    const attrs = {
+        'session.id': ctx.sessionId,
+    };
+    if (ctx.profileId !== undefined) {
+        attrs['session.profile_id'] = ctx.profileId;
+    }
+    if (ctx.workingDir !== undefined) {
+        attrs['session.working_dir'] = ctx.workingDir;
+    }
+    if (ctx.path !== undefined) {
+        attrs['session.path'] = ctx.path;
+    }
+    return tracer.startSpan('session.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a session lifecycle phase transition.
+ *
+ * @param span - The active session lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordSessionPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`session.${phase}`, attrs);
+}
+/**
+ * End a session lifecycle span.
+ *
+ * @param span - The span returned by `startSessionSpan`.
+ * @param ctx - Session lifecycle end context.
+ */
+export function endSessionSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttribute('session.outcome', ctx.outcome);
+    if (ctx.turnCount !== undefined) {
+        span.setAttribute('session.turn_count', ctx.turnCount);
+    }
+    if (ctx.messageCount !== undefined) {
+        span.setAttribute('session.message_count', ctx.messageCount);
+    }
+    span.addEvent(`session.${ctx.outcome}`);
+    if (ctx.outcome === 'recovery_failed' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('session.error', ctx.error);
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}