@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/telemetry/spans/task.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Task lifecycle span helpers.
+ *
+ * Tracks the full task state machine:
+ * TASK_CREATED → TASK_STARTED → TASK_BLOCKED → TASK_PROGRESS
+ * Terminal states: TASK_COMPLETED | TASK_FAILED | TASK_CANCELLED
+ *
+ * One span per task. Optionally parented to an agent span.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a task lifecycle span. */
+export interface TaskSpanContext {
+    /** Task ID (unique). */
+    readonly taskId: string;
+    /** Optional agent ID that owns this task. */
+    readonly agentId?: string;
+    /** Human-readable task description. */
+    readonly description: string;
+    /** Task scheduling priority. */
+    readonly priority: number;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+    /**
+     * Optional parent span ID for nesting under an agent span.
+     * When provided, this task span becomes a child of the agent span.
+     */
+    readonly parentSpanId?: string;
+}
+/** Phase transitions recordable on a task lifecycle span. */
+export type TaskPhase = 'started' | 'blocked' | 'progress';
+/** Result context supplied when ending a task lifecycle span. */
+export interface TaskSpanEndContext {
+    /** Final outcome of the task. */
+    readonly outcome: 'completed' | 'failed' | 'cancelled';
+    /** Duration of the task in milliseconds. */
+    readonly durationMs: number;
+    /** Error description when outcome is 'failed'. */
+    readonly error?: string;
+    /** Cancel reason when outcome is 'cancelled'. */
+    readonly reason?: string;
+}
+/**
+ * Start a task lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from TASK_CREATED event.
+ */
+export declare function startTaskSpan(tracer: RuntimeTracer, ctx: TaskSpanContext): Span;
+/**
+ * Record a task phase transition event.
+ *
+ * @param span - The active task lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordTaskPhase(span: Span, phase: TaskPhase, attrs?: SpanAttributes): void;
+/**
+ * End a task lifecycle span.
+ *
+ * @param span - The span returned by `startTaskSpan`.
+ * @param ctx - Task lifecycle end context.
+ */
+export declare function endTaskSpan(span: Span, ctx: TaskSpanEndContext): void;
+//# sourceMappingURL=task.d.ts.map

package/dist/platform/runtime/telemetry/spans/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/telemetry/spans/task.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,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gCAAgC;IAChC,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,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3D,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvD,4CAA4C;IAC5C,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,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAmB/E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAuBrE"}

package/dist/platform/runtime/telemetry/spans/task.js

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

package/dist/platform/runtime/telemetry/spans/tool.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool execution span helpers.
+ *
+ * Creates child spans under a turn span to track the full tool execution
+ * pipeline: TOOL_RECEIVED → TOOL_VALIDATED → TOOL_PREHOOKED →
+ * TOOL_PERMISSIONED → TOOL_EXECUTING → TOOL_SUCCEEDED | TOOL_FAILED | TOOL_CANCELLED
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a tool span. */
+export interface ToolSpanContext {
+    /** Tool call ID (unique per call). */
+    readonly callId: string;
+    /** Turn ID this tool call belongs to. */
+    readonly turnId: string;
+    /** Tool name (e.g. 'precision_read'). */
+    readonly tool: string;
+    /** Trace ID from the parent turn span. */
+    readonly traceId: string;
+    /** Parent span ID (the turn span's spanId). */
+    readonly parentSpanId: string;
+    /** Tool call arguments (stored as JSON string, truncated). */
+    readonly args?: Record<string, unknown>;
+}
+/** Phase transition events that can be recorded on a tool span. */
+export type ToolPhase = 'validated' | 'prehooked' | 'permissioned' | 'executing' | 'mapped' | 'posthooked';
+/** Result context supplied when ending a tool span. */
+export interface ToolSpanEndContext {
+    /** Final outcome. */
+    readonly outcome: 'succeeded' | 'failed' | 'cancelled';
+    /** Duration in ms. */
+    readonly durationMs: number;
+    /** Error message if outcome is 'failed'. */
+    readonly error?: string;
+    /** Cancel reason if outcome is 'cancelled'. */
+    readonly cancelReason?: string;
+    /** Whether the tool call was approved by permissions. */
+    readonly approved?: boolean;
+}
+/**
+ * Start a tool execution span as a child of the turn span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Tool span context from TOOL_RECEIVED event.
+ */
+export declare function startToolSpan(tracer: RuntimeTracer, ctx: ToolSpanContext): Span;
+/**
+ * Record a phase transition event on a tool span.
+ *
+ * @param span - The active tool span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes for this phase.
+ */
+export declare function recordToolPhase(span: Span, phase: ToolPhase, attrs?: SpanAttributes): void;
+/**
+ * End a tool execution span.
+ *
+ * @param span - The span returned by `startToolSpan`.
+ * @param ctx - Tool end context.
+ */
+export declare function endToolSpan(span: Span, ctx: ToolSpanEndContext): void;
+//# sourceMappingURL=tool.d.ts.map

package/dist/platform/runtime/telemetry/spans/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/telemetry/spans/tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,mEAAmE;AACnE,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,WAAW,GACX,cAAc,GACd,WAAW,GACX,QAAQ,GACR,YAAY,CAAC;AAEjB,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvD,sBAAsB;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAqB/E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,CA2BrE"}

package/dist/platform/runtime/telemetry/spans/tool.js

@@ -0,0 +1,71 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a tool execution span as a child of the turn span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Tool span context from TOOL_RECEIVED event.
+ */
+export function startToolSpan(tracer, ctx) {
+    const argsJson = ctx.args
+        ? (() => {
+            const raw = JSON.stringify(ctx.args);
+            return raw.length > 512 ? raw.slice(0, 512) + '...' : raw;
+        })()
+        : '';
+    const attrs = {
+        'tool.name': ctx.tool,
+        'tool.call_id': ctx.callId,
+        'turn.id': ctx.turnId,
+        'tool.args': argsJson,
+    };
+    return tracer.startSpan('tool.execute', {
+        traceId: ctx.traceId,
+        parentSpanId: ctx.parentSpanId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a phase transition event on a tool span.
+ *
+ * @param span - The active tool span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes for this phase.
+ */
+export function recordToolPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`tool.${phase}`, attrs);
+}
+/**
+ * End a tool execution span.
+ *
+ * @param span - The span returned by `startToolSpan`.
+ * @param ctx - Tool end context.
+ */
+export function endToolSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttributes({
+        'tool.outcome': ctx.outcome,
+        'tool.duration_ms': ctx.durationMs,
+    });
+    if (ctx.approved !== undefined) {
+        span.setAttribute('tool.approved', ctx.approved);
+    }
+    span.addEvent(`tool.${ctx.outcome}`);
+    if (ctx.outcome === 'failed' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('tool.error', ctx.error);
+    }
+    else if (ctx.outcome === 'cancelled') {
+        span.setStatus({ code: SpanStatusCode.OK });
+        if (ctx.cancelReason) {
+            span.setAttribute('tool.cancel_reason', ctx.cancelReason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

package/dist/platform/runtime/telemetry/spans/transport.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Transport lifecycle span helpers.
+ *
+ * Tracks the full transport state machine:
+ * TRANSPORT_INITIALIZING → TRANSPORT_AUTHENTICATING → TRANSPORT_CONNECTED
+ * → TRANSPORT_SYNCING → TRANSPORT_DEGRADED → TRANSPORT_RECONNECTING
+ * Terminal states: TRANSPORT_DISCONNECTED | TRANSPORT_TERMINAL_FAILURE
+ *
+ * One span per transport connection session.
+ */
+import type { Span, SpanAttributes } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a transport lifecycle span. */
+export interface TransportSpanContext {
+    /** Transport ID. */
+    readonly transportId: string;
+    /** Protocol name (e.g. 'websocket', 'stdio', 'http'). */
+    readonly protocol: string;
+    /** Trace ID for cross-span correlation. */
+    readonly traceId: string;
+}
+/** Phase transitions recordable on a transport lifecycle span. */
+export type TransportPhase = 'authenticating' | 'connected' | 'syncing' | 'degraded' | 'reconnecting';
+/** Result context supplied when ending a transport lifecycle span. */
+export interface TransportSpanEndContext {
+    /** Final outcome of the transport lifecycle. */
+    readonly outcome: 'connected' | 'disconnected' | 'terminal_failure';
+    /** Disconnect or failure reason if applicable. */
+    readonly reason?: string;
+    /** Whether a reconnect will be attempted. */
+    readonly willRetry?: boolean;
+    /** Remote endpoint address when outcome is 'connected'. */
+    readonly endpoint?: string;
+}
+/**
+ * Start a transport lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from TRANSPORT_INITIALIZING event.
+ */
+export declare function startTransportSpan(tracer: RuntimeTracer, ctx: TransportSpanContext): Span;
+/**
+ * Record a transport phase transition event.
+ *
+ * @param span - The active transport lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export declare function recordTransportPhase(span: Span, phase: TransportPhase, attrs?: SpanAttributes): void;
+/**
+ * End a transport lifecycle span.
+ *
+ * @param span - The span returned by `startTransportSpan`.
+ * @param ctx - Transport lifecycle end context.
+ */
+export declare function endTransportSpan(span: Span, ctx: TransportSpanEndContext): void;
+//# sourceMappingURL=transport.d.ts.map

package/dist/platform/runtime/telemetry/spans/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/telemetry/spans/transport.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,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kEAAkE;AAClE,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,WAAW,GACX,SAAS,GACT,UAAU,GACV,cAAc,CAAC;AAEnB,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,GAAG,kBAAkB,CAAC;IACpE,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAWzF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,cAAc,EACrB,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,uBAAuB,GAAG,IAAI,CA4B/E"}

package/dist/platform/runtime/telemetry/spans/transport.js

@@ -0,0 +1,63 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a transport lifecycle span.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Context from TRANSPORT_INITIALIZING event.
+ */
+export function startTransportSpan(tracer, ctx) {
+    const attrs = {
+        'transport.id': ctx.transportId,
+        'transport.protocol': ctx.protocol,
+    };
+    return tracer.startSpan('transport.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.CLIENT,
+        attributes: attrs,
+    });
+}
+/**
+ * Record a transport phase transition event.
+ *
+ * @param span - The active transport lifecycle span.
+ * @param phase - The phase reached.
+ * @param attrs - Optional additional attributes.
+ */
+export function recordTransportPhase(span, phase, attrs) {
+    if (span.ended)
+        return;
+    span.addEvent(`transport.${phase}`, attrs);
+}
+/**
+ * End a transport lifecycle span.
+ *
+ * @param span - The span returned by `startTransportSpan`.
+ * @param ctx - Transport lifecycle end context.
+ */
+export function endTransportSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.setAttribute('transport.outcome', ctx.outcome);
+    if (ctx.endpoint !== undefined) {
+        span.setAttribute('transport.endpoint', ctx.endpoint);
+    }
+    if (ctx.willRetry !== undefined) {
+        span.setAttribute('transport.will_retry', ctx.willRetry);
+    }
+    span.addEvent(`transport.${ctx.outcome}`);
+    if (ctx.outcome === 'terminal_failure') {
+        const msg = ctx.reason ?? 'Transport terminal failure';
+        span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+        span.setAttribute('transport.error', msg);
+    }
+    else if (ctx.outcome === 'disconnected' && !ctx.willRetry) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.reason ?? 'Transport disconnected' });
+        if (ctx.reason) {
+            span.setAttribute('transport.disconnect_reason', ctx.reason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

package/dist/platform/runtime/telemetry/spans/turn.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Turn lifecycle span helpers.
+ *
+ * Creates and manages spans that track the full turn lifecycle:
+ * TURN_SUBMITTED → TURN_COMPLETED | TURN_ERROR | TURN_CANCEL
+ *
+ * The turn span is the root span for a conversation turn. Tool and LLM
+ * spans are created as children of the turn span.
+ */
+import type { Span } from '../types.js';
+import type { RuntimeTracer } from '../tracer.js';
+/** Context supplied when starting a turn span. */
+export interface TurnSpanContext {
+    /** Turn ID from the event envelope. */
+    readonly turnId: string;
+    /** Session-level trace ID for correlation. */
+    readonly traceId: string;
+    /** Session ID. */
+    readonly sessionId: string;
+    /** User prompt (truncated to 256 chars for the attribute). */
+    readonly prompt: string;
+}
+/** Result context supplied when ending a turn span. */
+export interface TurnSpanEndContext {
+    /** Final outcome of the turn. */
+    readonly outcome: 'completed' | 'error' | 'cancelled';
+    /** Error message if outcome is 'error'. */
+    readonly error?: string;
+    /** Cancel reason if outcome is 'cancelled'. */
+    readonly cancelReason?: string;
+    /** Token usage if available. */
+    readonly tokens?: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead?: number;
+    };
+}
+/**
+ * Start a turn lifecycle span.
+ *
+ * The returned Span should be stored and ended when the turn resolves
+ * via `endTurnSpan`.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Turn context from TURN_SUBMITTED event.
+ */
+export declare function startTurnSpan(tracer: RuntimeTracer, ctx: TurnSpanContext): Span;
+/**
+ * End a turn lifecycle span with outcome context.
+ *
+ * @param span - The span returned by `startTurnSpan`.
+ * @param ctx - Turn end context.
+ */
+export declare function endTurnSpan(span: Span, ctx: TurnSpanEndContext): void;
+//# sourceMappingURL=turn.d.ts.map

package/dist/platform/runtime/telemetry/spans/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/telemetry/spans/turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;IACtD,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAa/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,CA2BrE"}

package/dist/platform/runtime/telemetry/spans/turn.js

@@ -0,0 +1,56 @@
+import { SpanKind, SpanStatusCode } from '../types.js';
+/**
+ * Start a turn lifecycle span.
+ *
+ * The returned Span should be stored and ended when the turn resolves
+ * via `endTurnSpan`.
+ *
+ * @param tracer - RuntimeTracer instance.
+ * @param ctx - Turn context from TURN_SUBMITTED event.
+ */
+export function startTurnSpan(tracer, ctx) {
+    const attrs = {
+        'turn.id': ctx.turnId,
+        'session.id': ctx.sessionId,
+        // Truncate prompt to avoid large attribute values
+        'turn.prompt': ctx.prompt.length > 256 ? ctx.prompt.slice(0, 256) + '...' : ctx.prompt,
+    };
+    return tracer.startSpan('turn.lifecycle', {
+        traceId: ctx.traceId,
+        kind: SpanKind.INTERNAL,
+        attributes: attrs,
+    });
+}
+/**
+ * End a turn lifecycle span with outcome context.
+ *
+ * @param span - The span returned by `startTurnSpan`.
+ * @param ctx - Turn end context.
+ */
+export function endTurnSpan(span, ctx) {
+    if (span.ended)
+        return;
+    span.addEvent(`turn.${ctx.outcome}`);
+    span.setAttribute('turn.outcome', ctx.outcome);
+    if (ctx.tokens) {
+        span.setAttributes({
+            'turn.tokens.input': ctx.tokens.input,
+            'turn.tokens.output': ctx.tokens.output,
+            'turn.tokens.cache_read': ctx.tokens.cacheRead ?? 0,
+        });
+    }
+    if (ctx.outcome === 'error' && ctx.error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: ctx.error });
+        span.setAttribute('turn.error', ctx.error);
+    }
+    else if (ctx.outcome === 'cancelled') {
+        span.setStatus({ code: SpanStatusCode.OK });
+        if (ctx.cancelReason) {
+            span.setAttribute('turn.cancel_reason', ctx.cancelReason);
+        }
+    }
+    else {
+        span.setStatus({ code: SpanStatusCode.OK });
+    }
+    span.end();
+}

package/dist/platform/runtime/telemetry/tracer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * RuntimeTracer — lightweight OTel-compatible span factory.
+ *
+ * Implements span creation, parent/child relationships, attributes, events,
+ * and export without depending on the @opentelemetry/* packages.
+ *
+ * Design principles:
+ * - All public methods are synchronous; export is async fire-and-forget
+ * - End-after-end is a no-op (spans are immutable once ended)
+ * - Export failures are caught and logged; they never block the runtime
+ */
+import type { Span, SpanAttributes, TracerConfig } from './types.js';
+import { SpanKind } from './types.js';
+/**
+ * RuntimeTracer — creates spans and routes completed spans to exporters.
+ *
+ * Usage:
+ * ```ts
+ * const span = tracer.startSpan('turn.lifecycle', { traceId, parentSpanId });
+ * span.setAttribute('turn.id', turnId);
+ * span.end();
+ * ```
+ */
+export declare class RuntimeTracer {
+    private readonly config;
+    constructor(config: TracerConfig);
+    /**
+     * Start a new span.
+     *
+     * @param name - Human-readable span name.
+     * @param opts - Optional trace/parent context and kind.
+     */
+    startSpan(name: string, opts?: {
+        /** Existing trace ID to join. If omitted, a new trace is started. */
+        traceId?: string;
+        /** Parent span ID. Makes this span a child of the parent. */
+        parentSpanId?: string;
+        /** Span kind (defaults to INTERNAL). */
+        kind?: SpanKind;
+        /** Override start time in epoch ms (defaults to Date.now()). */
+        startTimeMs?: number;
+        /** Initial attributes. */
+        attributes?: SpanAttributes;
+    }): Span;
+    /**
+     * Flush all exporters. Call during graceful shutdown.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down all exporters.
+     */
+    shutdown(): Promise<void>;
+    /** Fire-and-forget export to all registered exporters. */
+    private _export;
+}
+//# sourceMappingURL=tracer.d.ts.map

package/dist/platform/runtime/telemetry/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/telemetry/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,cAAc,EAMd,YAAY,EAEb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAkB,MAAM,YAAY,CAAC;AAwItD;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,YAAY;IAIhC;;;;;OAKG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACL,qEAAqE;QACrE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,6DAA6D;QAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,wCAAwC;QACxC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,gEAAgE;QAChE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,0BAA0B;QAC1B,UAAU,CAAC,EAAE,cAAc,CAAC;KAC7B,GACA,IAAI;IAwBP;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,0DAA0D;IAC1D,OAAO,CAAC,OAAO;CAQhB"}