@yagni-app/code 1.0.6 → 1.0.8

package/dist/extension/telemetry/sdk.d.ts

@@ -0,0 +1,63 @@
+/**
+ * OpenTelemetry SDK bootstrap for one YAGNI Code process: a tracer, meter,
+ * and logger provider, each with the OTLP exporter the config picked
+ * (gRPC, http/protobuf, or http/json), plus a diag hook that turns export
+ * failures into ONE in-session notice instead of silence.
+ *
+ * Deliberately built from the signal SDKs (`sdk-trace`, `sdk-metrics`,
+ * `sdk-logs`) rather than `sdk-node`: no auto-instrumentation, no Prometheus
+ * server, no propagators — this is a client-only process that pushes its own
+ * spans. Providers are process-global (the OTel API allows one of each), so
+ * the extension initializes once per process even though pi fires
+ * session_start again on /new, /resume, and /fork.
+ *
+ * Everything is fail-soft. Telemetry must never block a launch or a prompt:
+ * a bad exporter config degrades to "not exporting", reported through the
+ * status callback, never a throw into pi.
+ */
+import { type Resource } from "@opentelemetry/resources";
+import { LoggerProvider, type LogRecordExporter } from "@opentelemetry/sdk-logs";
+import { MeterProvider, type PushMetricExporter } from "@opentelemetry/sdk-metrics";
+import { TracerProvider, type SpanExporter } from "@opentelemetry/sdk-trace";
+import type { SignalConfig, TelemetryConfig } from "./config.js";
+export interface TelemetryExporters {
+    traces?: SpanExporter;
+    metrics?: PushMetricExporter;
+    logs?: LogRecordExporter;
+}
+export interface TelemetrySdkOptions {
+    /** Injected exporters (tests use the SDKs' in-memory ones). */
+    exporters?: TelemetryExporters;
+    /** Simple (synchronous) processors instead of batching — tests + the doctor probe. */
+    simpleProcessors?: boolean;
+    /** Called on the first export failure with a one-line, human-readable reason. */
+    onExportError?: (message: string) => void;
+}
+export interface TelemetrySdk {
+    tracerProvider: TracerProvider;
+    meterProvider: MeterProvider;
+    loggerProvider: LoggerProvider;
+    resource: Resource;
+    /** Flush every processor (bounded), then shut the providers down. */
+    shutdown(): Promise<void>;
+    /** Flush without shutting down (used between /go stages). */
+    forceFlush(): Promise<void>;
+}
+/** Build the trace exporter for a signal config. */
+export declare function makeTraceExporter(cfg: SignalConfig): SpanExporter;
+export declare function makeMetricExporter(cfg: SignalConfig, temporality: TelemetryConfig["metricsTemporality"]): PushMetricExporter;
+export declare function makeLogExporter(cfg: SignalConfig): LogRecordExporter;
+/**
+ * Create and register the providers. Returns null (and reports) when the
+ * config produced no exporter — never throws.
+ */
+export declare function createTelemetrySdk(config: TelemetryConfig, opts?: TelemetrySdkOptions): TelemetrySdk;
+/**
+ * Shutdown/flush bound. A blackholing collector (a corp collector with the
+ * VPN down) must not hold quit for long: the batch processors already flush
+ * every few seconds, so at most one interval of records is at risk.
+ */
+export declare const FLUSH_TIMEOUT_MS = 1500;
+/** Let a timeout never keep the process alive on its own (Node timers only). */
+export declare function unrefTimer(timer: unknown): void;
+//# sourceMappingURL=sdk.d.ts.map

package/dist/extension/telemetry/sdk.js

@@ -0,0 +1,207 @@
+/**
+ * OpenTelemetry SDK bootstrap for one YAGNI Code process: a tracer, meter,
+ * and logger provider, each with the OTLP exporter the config picked
+ * (gRPC, http/protobuf, or http/json), plus a diag hook that turns export
+ * failures into ONE in-session notice instead of silence.
+ *
+ * Deliberately built from the signal SDKs (`sdk-trace`, `sdk-metrics`,
+ * `sdk-logs`) rather than `sdk-node`: no auto-instrumentation, no Prometheus
+ * server, no propagators — this is a client-only process that pushes its own
+ * spans. Providers are process-global (the OTel API allows one of each), so
+ * the extension initializes once per process even though pi fires
+ * session_start again on /new, /resume, and /fork.
+ *
+ * Everything is fail-soft. Telemetry must never block a launch or a prompt:
+ * a bad exporter config degrades to "not exporting", reported through the
+ * status callback, never a throw into pi.
+ */
+import { Metadata } from "@grpc/grpc-js";
+import { diag, DiagLogLevel, metrics, trace } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { OTLPLogExporter as LogGrpcExporter } from "@opentelemetry/exporter-logs-otlp-grpc";
+import { OTLPLogExporter as LogHttpExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPLogExporter as LogProtoExporter } from "@opentelemetry/exporter-logs-otlp-proto";
+import { OTLPMetricExporter as MetricGrpcExporter } from "@opentelemetry/exporter-metrics-otlp-grpc";
+import { AggregationTemporalityPreference, OTLPMetricExporter as MetricHttpExporter, } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPMetricExporter as MetricProtoExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
+import { OTLPTraceExporter as TraceGrpcExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { OTLPTraceExporter as TraceHttpExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPTraceExporter as TraceProtoExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor, } from "@opentelemetry/sdk-logs";
+import { MeterProvider, PeriodicExportingMetricReader, } from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor, SimpleSpanProcessor, TracerProvider, } from "@opentelemetry/sdk-trace";
+import { logEvent } from "../errorSink.js";
+/**
+ * gRPC exporters take headers as grpc `Metadata`, not a record. Built from the
+ * resolved config rather than left to the exporter's own `process.env` read,
+ * so the doctor probe (which runs in-process with a synthetic env) and a
+ * session see the same headers.
+ */
+function toMetadata(headers) {
+    const md = new Metadata();
+    for (const [k, v] of Object.entries(headers))
+        md.set(k, v);
+    return md;
+}
+/** Build the trace exporter for a signal config. */
+export function makeTraceExporter(cfg) {
+    return pick(cfg.protocol, {
+        grpc: () => new TraceGrpcExporter({ url: cfg.url, metadata: toMetadata(cfg.headers) }),
+        proto: () => new TraceProtoExporter({ url: cfg.url, headers: cfg.headers }),
+        json: () => new TraceHttpExporter({ url: cfg.url, headers: cfg.headers }),
+    });
+}
+export function makeMetricExporter(cfg, temporality) {
+    const temporalityPreference = temporality === "cumulative" ? AggregationTemporalityPreference.CUMULATIVE : AggregationTemporalityPreference.DELTA;
+    return pick(cfg.protocol, {
+        grpc: () => new MetricGrpcExporter({ url: cfg.url, metadata: toMetadata(cfg.headers), temporalityPreference }),
+        proto: () => new MetricProtoExporter({ url: cfg.url, headers: cfg.headers, temporalityPreference }),
+        json: () => new MetricHttpExporter({ url: cfg.url, headers: cfg.headers, temporalityPreference }),
+    });
+}
+export function makeLogExporter(cfg) {
+    return pick(cfg.protocol, {
+        grpc: () => new LogGrpcExporter({ url: cfg.url, metadata: toMetadata(cfg.headers) }),
+        proto: () => new LogProtoExporter({ url: cfg.url, headers: cfg.headers }),
+        json: () => new LogHttpExporter({ url: cfg.url, headers: cfg.headers }),
+    });
+}
+function pick(protocol, ctors) {
+    if (protocol === "http/protobuf")
+        return ctors.proto();
+    if (protocol === "http/json")
+        return ctors.json();
+    return ctors.grpc();
+}
+/**
+ * A diag logger for exporter failures. OTel routes them — a 403 from a bad
+ * API key, ECONNREFUSED, a 404 on the wrong path — through `diag.error` via
+ * the global error handler, so this is the only place they surface. The
+ * FIRST one is forwarded to the session as a notice (one, never a stream);
+ * EVERY one is written to the local error sink (~/.yagni-code error log),
+ * so a later "why is nothing in Datadog" investigation has the full trail.
+ */
+function makeDiagLogger(onExportError) {
+    let reported = false;
+    const noop = () => { };
+    return {
+        verbose: noop,
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: (message, ...args) => {
+            const text = [message, ...args]
+                .map((a) => (a instanceof Error ? a.message : typeof a === "string" ? a : safeJson(a)))
+                .filter(Boolean)
+                .join(" ")
+                .slice(0, 500);
+            logEvent({ source: "telemetry", level: "warn", event: "export_error", fields: { error: text } });
+            if (reported || !onExportError)
+                return;
+            reported = true;
+            try {
+                onExportError(text);
+            }
+            catch {
+                // A failing notice must not take the session down.
+            }
+        },
+    };
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v) ?? "";
+    }
+    catch {
+        return String(v);
+    }
+}
+function buildResource(config) {
+    return resourceFromAttributes({
+        ...config.resourceAttributes,
+        "service.name": config.serviceName,
+        ...(config.serviceVersion ? { "service.version": config.serviceVersion } : {}),
+    });
+}
+/**
+ * Create and register the providers. Returns null (and reports) when the
+ * config produced no exporter — never throws.
+ */
+export function createTelemetrySdk(config, opts = {}) {
+    diag.setLogger(makeDiagLogger(opts.onExportError), { logLevel: DiagLogLevel.ERROR, suppressOverrideMessage: true });
+    const resource = buildResource(config);
+    const traceExporter = config.traces.enabled ? (opts.exporters?.traces ?? makeTraceExporter(config.traces)) : undefined;
+    const metricExporter = config.metrics.enabled
+        ? (opts.exporters?.metrics ?? makeMetricExporter(config.metrics, config.metricsTemporality))
+        : undefined;
+    const logExporter = config.logs.enabled ? (opts.exporters?.logs ?? makeLogExporter(config.logs)) : undefined;
+    const tracerProvider = new TracerProvider({
+        resource,
+        spanProcessors: traceExporter
+            ? [
+                opts.simpleProcessors
+                    ? new SimpleSpanProcessor({ exporter: traceExporter })
+                    : new BatchSpanProcessor({ exporter: traceExporter, scheduledDelayMillis: config.traces.exportIntervalMs }),
+            ]
+            : [],
+    });
+    const meterProvider = new MeterProvider({
+        resource,
+        readers: metricExporter
+            ? [
+                new PeriodicExportingMetricReader({
+                    exporter: metricExporter,
+                    exportIntervalMillis: config.metrics.exportIntervalMs,
+                }),
+            ]
+            : [],
+    });
+    const loggerProvider = new LoggerProvider({
+        resource,
+        processors: logExporter
+            ? [
+                opts.simpleProcessors
+                    ? new SimpleLogRecordProcessor({ exporter: logExporter })
+                    : new BatchLogRecordProcessor({ exporter: logExporter, scheduledDelayMillis: config.logs.exportIntervalMs }),
+            ]
+            : [],
+    });
+    // Register globally so any OTel-aware code in the process (an MCP client,
+    // a future hook) parents into the same providers. The API refuses a second
+    // registration and returns false; that is fine — a re-init keeps the first.
+    trace.setGlobalTracerProvider(tracerProvider);
+    metrics.setGlobalMeterProvider(meterProvider);
+    logs.setGlobalLoggerProvider(loggerProvider);
+    const bounded = (p, ms) => Promise.race([p, new Promise((resolve) => unrefTimer(setTimeout(resolve, ms)))]);
+    return {
+        tracerProvider,
+        meterProvider,
+        loggerProvider,
+        resource,
+        async forceFlush() {
+            await bounded(Promise.allSettled([tracerProvider.forceFlush(), meterProvider.forceFlush(), loggerProvider.forceFlush()]), FLUSH_TIMEOUT_MS);
+        },
+        async shutdown() {
+            // Unregister the globals FIRST, synchronously: a session that replaces
+            // this one (/new, /resume) can then register its own providers without
+            // waiting on a collector that may be blackholing the final flush.
+            trace.disable();
+            metrics.disable();
+            logs.disable();
+            diag.disable();
+            await bounded(Promise.allSettled([tracerProvider.shutdown(), meterProvider.shutdown(), loggerProvider.shutdown()]), FLUSH_TIMEOUT_MS);
+        },
+    };
+}
+/**
+ * Shutdown/flush bound. A blackholing collector (a corp collector with the
+ * VPN down) must not hold quit for long: the batch processors already flush
+ * every few seconds, so at most one interval of records is at risk.
+ */
+export const FLUSH_TIMEOUT_MS = 1_500;
+/** Let a timeout never keep the process alive on its own (Node timers only). */
+export function unrefTimer(timer) {
+    timer?.unref?.();
+}
+//# sourceMappingURL=sdk.js.map

package/dist/extension/telemetry/tracker.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Session telemetry tracker: turns pi's lifecycle into spans, metrics, and
+ * log events. Pure with respect to pi — `register.ts` feeds it events, tests
+ * feed it directly — and it only ever talks to the OTel API (tracer, meter,
+ * logger), never to exporters.
+ *
+ * Shape (Claude Code parity, prefix `yagni_code`):
+ *
+ *   spans    yagni_code.interaction ─┬─ yagni_code.turn ─┬─ yagni_code.llm_request
+ *                                    │                   └─ yagni_code.tool
+ *   metrics  session.count, token.usage, cost.usage, lines_of_code.count,
+ *            commit.count, pull_request.count, code_edit_tool.decision,
+ *            active_time.total
+ *   events   user_prompt, assistant_response, api_request, api_error,
+ *            tool_result, tool_decision, permission_mode_changed
+ *
+ * Metadata only. Prompt text, model output, tool arguments, and tool results
+ * never become attributes — only their lengths.
+ */
+import { type Attributes, type Meter, type Tracer } from "@opentelemetry/api";
+import { type Logger } from "@opentelemetry/api-logs";
+import { type Decision, type DecisionSource } from "./attrs.js";
+import type { TelemetryConfig } from "./config.js";
+/** pi's assistant-message usage block (loose: providers differ in what they fill). */
+export interface UsageLike {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cost?: number | {
+        total?: number;
+    };
+}
+export interface AssistantMessageLike {
+    model?: string;
+    responseModel?: string;
+    responseId?: string;
+    usage?: UsageLike;
+    stopReason?: string;
+    errorMessage?: string;
+    content?: unknown;
+}
+export interface ToolDecisionInput {
+    toolName: string;
+    toolCallId?: string;
+    decision: Decision;
+    source: DecisionSource;
+    /** For edit/write tools: the target path, so `language` can be derived. */
+    filePath?: string;
+}
+export interface TrackerDeps {
+    tracer: Tracer;
+    meter: Meter;
+    logger: Logger;
+    config: TelemetryConfig;
+    now?: () => number;
+}
+/** Idle cutoff for user active time: gaps longer than this are not "active". */
+export declare const USER_ACTIVE_IDLE_CUTOFF_MS: number;
+export declare class SessionTelemetry {
+    private readonly tracer;
+    private readonly meter;
+    private readonly logger;
+    private readonly config;
+    private readonly now;
+    private sessionId;
+    private sessionCounted;
+    private eventSequence;
+    private interactionSequence;
+    private interaction;
+    private turn;
+    private llm;
+    private readonly tools;
+    /** Decision recorded per tool call before it executes (feeds tool_result). */
+    private readonly decisions;
+    /** When the agent last went idle — the start of the user's active window. */
+    private idleSince;
+    private readonly counters;
+    constructor(deps: TrackerDeps);
+    /** Attributes every metric and event carries (Claude Code's standard set). */
+    standardAttributes(): Attributes;
+    /** Attributes every span carries: session identity in both vocabularies. */
+    private spanAttributes;
+    private counter;
+    private add;
+    emitEvent(name: string, attrs: Attributes): void;
+    sessionStart(sessionId: string | undefined): void;
+    getSessionId(): string | undefined;
+    interactionStart(prompt: string | undefined): void;
+    interactionEnd(): void;
+    turnStart(turnIndex: number | undefined): void;
+    turnEnd(): void;
+    private parentCtx;
+    llmStart(model: string | undefined): void;
+    llmResponseHeaders(status: number | undefined, headers: Record<string, string> | undefined): void;
+    /**
+     * The assistant message ended: attach usage, emit api_request / api_error
+     * plus the token and cost counters, and close the LLM span. Opens a span
+     * first when pi delivered the message without a before_provider_request
+     * (e.g. a replayed or synthetic message) so nothing is lost.
+     */
+    assistantMessageEnd(message: AssistantMessageLike): void;
+    llmEnd(error: Error | undefined): void;
+    toolDecision(input: ToolDecisionInput): void;
+    toolStart(toolCallId: string, toolName: string, args: unknown): void;
+    toolEnd(toolCallId: string, outcome: {
+        isError: boolean;
+        resultBytes: number;
+        errorType?: string;
+    }): void;
+    /** Lines added/removed by an edit or write, from pi's tool_result details. */
+    linesOfCode(added: number, removed: number): void;
+    /** A successful bash command: count commits and PR creations. */
+    bashSucceeded(command: string | undefined): void;
+    permissionModeChanged(fromMode: string, toMode: string): void;
+    /** Close everything still open so no span is lost at exit. */
+    close(): void;
+}
+/** Cap on the exported error excerpt (characters, one line). */
+export declare const ERROR_EXCERPT_CHARS = 120;
+/** First line of a provider error, capped, never the full body. */
+export declare function errorExcerpt(message: string | undefined): string;
+export declare function byteLength(v: unknown): number;
+/** Count +/- lines in a unified patch, ignoring file headers. */
+export declare function countPatchLines(patch: string | undefined): {
+    added: number;
+    removed: number;
+};
+/** Line count of freshly written content (a write tool call). */
+export declare function countContentLines(content: unknown): number;
+//# sourceMappingURL=tracker.d.ts.map