@unbrained/pm-cli 2026.6.12 → 2026.6.16

package/dist/core/telemetry/runtime.d.ts

@@ -3,12 +3,68 @@ import { type TelemetryErrorCategory } from "../shared/constants.js";
 import { type TelemetryCommandResolution, type TelemetryCommandTaxonomy, type TelemetryResolutionStage } from "./observability.js";
 export declare const TELEMETRY_SCHEMA_VERSION = 1;
 export declare const TELEMETRY_MAX_QUEUE_ENTRY_ATTEMPTS = 15;
-declare const PM_TELEMETRY_SOURCE_CONTEXT_VALUES: readonly ["user", "automation", "test", "dogfood", "audit_smoke"];
+export declare const PM_TELEMETRY_SOURCE_CONTEXT_VALUES: readonly ["user", "automation", "test", "dogfood", "audit_smoke"];
 /** Wait for the most recent background flush to settle. Test-only helper. */
 export declare function waitForPendingFlush(): Promise<void>;
+interface TelemetryEvent {
+    schema_version: number;
+    event_id: string;
+    event_type: "command_start" | "command_finish" | "command_error";
+    occurred_at: string;
+    installation_id: string;
+    session_id: string;
+    command: string;
+    payload: Record<string, unknown>;
+}
+interface QueuedTelemetryEvent {
+    client_schema_version?: number;
+    event: TelemetryEvent;
+    attempts: number;
+    last_attempt_at?: string;
+    next_attempt_after?: string;
+}
+interface TelemetryRuntimeState {
+    last_attempted_flush_at?: string;
+    last_successful_flush_at?: string;
+    last_failed_flush_at?: string;
+    last_failed_flush_error?: string;
+    endpoint?: string;
+    queue_entries?: number;
+    pending_otel_spans?: number;
+    last_otel_attempt_at?: string;
+    last_otel_success_at?: string;
+    last_otel_failure_at?: string;
+    last_otel_failure_error?: string;
+}
+/**
+ * A built OpenTelemetry span request awaiting export. Persisted to a small,
+ * bounded queue so the OTLP trace POST happens in the detached, unref'd flush
+ * worker instead of inline in the foreground command. This keeps the CLI process
+ * from staying alive while a connecting socket to an unreachable traces endpoint
+ * drains its 5s timeout (the GH-209 root cause). `payload` is the fully built
+ * OTLP resourceSpans body; `endpoint` is the per-span traces endpoint.
+ */
+interface PendingOtelSpan {
+    /**
+     * Stable id used to reconcile the queue after the network flush: the worker
+     * re-reads the file and removes/updates only the spans it processed, by id, so
+     * spans appended by a concurrent foreground process during the flush are never
+     * overwritten. Mirrors the event-queue's event_id-based reconciliation.
+     */
+    id: string;
+    endpoint: string;
+    payload: unknown;
+    enqueued_at: string;
+    attempts: number;
+    next_attempt_after?: string;
+}
 type TelemetryCaptureLevel = "minimal" | "redacted" | "max";
 type TelemetrySourceContext = (typeof PM_TELEMETRY_SOURCE_CONTEXT_VALUES)[number];
 type TelemetrySourceContextSource = "inferred" | "env_override";
+interface ResolvedTelemetrySourceContext {
+    source_context: TelemetrySourceContext;
+    source_context_source: TelemetrySourceContextSource;
+}
 export interface ActiveTelemetryCommand {
     started_at: string;
     started_at_ms: number;
@@ -60,16 +116,231 @@ export interface TelemetryErrorEventContext {
     command_resolution?: TelemetryCommandResolution;
     resolution_stage?: TelemetryResolutionStage;
 }
+declare function otelSpansQueuePath(globalPmRoot: string): string;
+declare function runtimeStatePath(globalPmRoot: string): string;
 declare function flushLockPath(globalPmRoot: string): string;
 declare function flushSpawnLockPath(globalPmRoot: string): string;
+declare function telemetryFlushRunnerPath(): string;
+declare function shouldFlushInline(): boolean;
+declare function readRuntimeState(globalPmRoot: string): Promise<TelemetryRuntimeState>;
+declare function writeRuntimeState(globalPmRoot: string, patch: TelemetryRuntimeState): Promise<void>;
+declare function isEmailLocalCharacter(character: string | undefined): boolean;
+declare function isEmailDomainCharacter(character: string | undefined): boolean;
+declare function looksLikeEmailToken(token: string): boolean;
+declare function sanitizeStringRedacted(input: string): string;
+declare function sanitizeStringMax(input: string): string;
+declare function sanitizeValue(value: unknown, keyHint?: string, captureLevel?: Exclude<TelemetryCaptureLevel, "minimal">, depth?: number): unknown;
+declare function sanitizeCommandArgs(args: string[], captureLevel?: Exclude<TelemetryCaptureLevel, "minimal">): string[];
+declare function normalizeCaptureLevel(value: string | undefined): TelemetryCaptureLevel;
+declare function parseBooleanTrueLike(value: string | undefined): boolean;
+declare function normalizePmVersion(value: string | undefined): string;
+declare function normalizeTelemetryErrorCode(value: string | undefined): string | undefined;
+declare function normalizeTelemetryExitCode(exitCode: number | undefined, ok: boolean): number;
+declare function normalizeTelemetryErrorCategory(params: {
+    ok: boolean;
+    errorCode?: string;
+    errorCategory?: TelemetryErrorCategory;
+}): TelemetryErrorCategory | undefined;
+declare function resolveTelemetrySourceContext(globalOptions: GlobalOptions): ResolvedTelemetrySourceContext;
+declare function normalizeForHash(value: unknown, depth?: number): unknown;
+declare function hashTelemetryValue(installationId: string, value: unknown): string;
+declare function hashTelemetryErrorFingerprint(installationId: string, command: string, errorCode: string | undefined, errorMessage: string | undefined): string;
+declare function resolveOtelTracesEndpoint(): string | null;
+/**
+ * Build the OTLP trace-export request for a finished command without performing
+ * any network I/O. Returns `null` when OTLP export is not configured (no traces
+ * endpoint / trace ids). The actual POST is deferred to the detached flush worker
+ * via {@link enqueuePendingOtelSpan} so the foreground command never blocks on a
+ * connecting socket (GH-209).
+ */
+declare function buildOtelSpanRequest(activeCommand: ActiveTelemetryCommand, outcome: {
+    ok: boolean;
+    error?: string;
+    exit_code?: number;
+    error_code?: string;
+    error_category?: TelemetryErrorCategory;
+}, finishedAtIso: string, durationMs: number): {
+    endpoint: string;
+    payload: unknown;
+} | null;
+declare function summarizeResult(result: unknown, captureLevel?: Exclude<TelemetryCaptureLevel, "minimal">): Record<string, unknown>;
+declare function buildCommandStartPayload(params: {
+    captureLevel: TelemetryCaptureLevel;
+    context: TelemetryCommandContext;
+    pmVersion: string;
+    sourceContext: ResolvedTelemetrySourceContext;
+    pmRootHash: string;
+    cwdHash: string;
+    installationId: string;
+}): Record<string, unknown>;
+declare function buildCommandFinishPayload(params: {
+    captureLevel: TelemetryCaptureLevel;
+    pmVersion: string;
+    sourceContext: ResolvedTelemetrySourceContext;
+    outcome: TelemetryCommandOutcome;
+    durationMs: number;
+    startedAt: string;
+    command: string;
+    installationId: string;
+    commandTaxonomy: TelemetryCommandTaxonomy;
+    exitCode: number;
+    errorCode?: string;
+    errorCategory?: TelemetryErrorCategory;
+    commandResolution: TelemetryCommandResolution;
+    resolutionStage: TelemetryResolutionStage;
+}): Record<string, unknown>;
+declare function buildCommandErrorPayload(params: {
+    captureLevel: TelemetryCaptureLevel;
+    pmVersion: string;
+    sourceContext: ResolvedTelemetrySourceContext;
+    command: string;
+    commandTaxonomy: TelemetryCommandTaxonomy;
+    commandResolution: TelemetryCommandResolution;
+    resolutionStage: TelemetryResolutionStage;
+    args: string[];
+    options: Record<string, unknown>;
+    pmRootHash: string;
+    cwdHash: string;
+    installationId: string;
+    errorCode: string;
+    errorMessage: string;
+    errorCategory: TelemetryErrorCategory;
+    exitCode: number;
+}): Record<string, unknown>;
+declare function enqueueTelemetryEvent(globalPmRoot: string, event: TelemetryEvent): Promise<void>;
+declare function parseQueueLines(raw: string): QueuedTelemetryEvent[];
+declare function isDueForRetryAt(nextAttemptAfter: string | undefined): boolean;
+declare function isDueForRetry(entry: QueuedTelemetryEvent): boolean;
+declare function retentionCutoffMs(retentionDays: number): number;
+declare function isExpiredQueueEntry(entry: QueuedTelemetryEvent, cutoffMs: number): boolean;
+declare function pruneExpiredQueueEntries(entries: QueuedTelemetryEvent[], retentionDays: number): {
+    entries: QueuedTelemetryEvent[];
+    prunedCount: number;
+};
+declare function rewriteQueue(globalPmRoot: string, entries: QueuedTelemetryEvent[]): Promise<void>;
+declare function isRetryableQueueRewriteError(error: unknown): boolean;
+declare function sleep(milliseconds: number): Promise<void>;
+/**
+ * Append a built OTLP span request to the bounded pending-spans queue. The
+ * detached flush worker drains and POSTs these so the foreground command never
+ * performs OTLP network I/O (GH-209). Best effort: a write failure never blocks
+ * the command, and the span is simply not exported.
+ */
+declare function enqueuePendingOtelSpan(globalPmRoot: string, request: {
+    endpoint: string;
+    payload: unknown;
+}): Promise<void>;
+declare function parsePendingOtelSpanLines(raw: string): PendingOtelSpan[];
+declare function isExpiredPendingOtelSpan(entry: PendingOtelSpan, cutoffMs: number): boolean;
+declare function prunePendingOtelSpans(entries: PendingOtelSpan[], retentionDays: number): {
+    entries: PendingOtelSpan[];
+    prunedCount: number;
+};
+declare function rewritePendingOtelSpans(globalPmRoot: string, entries: PendingOtelSpan[]): Promise<void>;
+/**
+ * Drain the pending OTLP span queue and POST due spans to their traces endpoint.
+ * Runs only inside the flush worker (detached child) or the inline test path, so
+ * the foreground command never makes OTLP network calls. Failures increment
+ * per-span attempts with backoff and are retried by a later flush; runtime state
+ * records OTLP export diagnostics for `pm health` (GH-205).
+ */
+/**
+ * Re-read the spans queue under the mutation serializer and rewrite it with the
+ * processed spans removed/updated by id, preserving any spans a concurrent
+ * foreground process appended during the (network) flush window. `succeededIds`
+ * are dropped; `failedUpdates` patch attempts/next_attempt_after by id; all other
+ * (incl. newly-appended) entries are retained, then pruned. Returns the count of
+ * spans left in the queue. Mirrors removeFlushedEntriesFromCurrentQueue.
+ */
+declare function reconcilePendingOtelSpansAfterFlush(globalPmRoot: string, retentionDays: number, succeededIds: ReadonlySet<string>, failedUpdates: ReadonlyMap<string, {
+    attempts: number;
+    next_attempt_after: string;
+}>): Promise<number>;
+declare function flushPendingOtelSpans(globalPmRoot: string, retentionDays: number): Promise<void>;
+/**
+ * Flush both telemetry artifacts under the same worker invocation: the event
+ * ingest queue and the pending OTLP span queue. Used by the detached flush
+ * worker and the inline (test) path so OTLP export always happens off the
+ * foreground command's critical path.
+ */
+declare function flushTelemetryArtifacts(globalPmRoot: string, endpoint: string, retentionDays: number): Promise<void>;
+declare function withQueueMutation<T>(operation: () => Promise<T>): Promise<T>;
+declare function readCurrentQueueEntries(globalPmRoot: string): Promise<QueuedTelemetryEvent[]>;
+declare function removeFlushedEntriesFromCurrentQueue(globalPmRoot: string, flushedIds: ReadonlySet<string>, retentionDays: number): Promise<QueuedTelemetryEvent[]>;
+declare function flushQueue(globalPmRoot: string, endpoint: string, retentionDays: number): Promise<void>;
+declare function acquireTelemetryFlushLock(globalPmRoot: string): Promise<boolean>;
+declare function isFreshDirectoryLock(lockPath: string, staleMs: number): boolean;
+declare function removeDirectoryLockBestEffort(lockPath: string): void;
+declare function errorCode(error: unknown): string | undefined;
+declare function createDirectoryLock(lockPath: string): boolean;
 declare function acquireTelemetryFlushSpawnGate(globalPmRoot: string): boolean;
 declare function releaseTelemetryFlushSpawnGate(globalPmRoot: string): void;
 export declare const _testOnly: {
     acquireTelemetryFlushSpawnGate: typeof acquireTelemetryFlushSpawnGate;
+    acquireTelemetryFlushLock: typeof acquireTelemetryFlushLock;
+    buildCommandErrorPayload: typeof buildCommandErrorPayload;
+    buildCommandFinishPayload: typeof buildCommandFinishPayload;
+    buildCommandStartPayload: typeof buildCommandStartPayload;
+    buildOtelSpanRequest: typeof buildOtelSpanRequest;
+    createDirectoryLock: typeof createDirectoryLock;
+    enqueuePendingOtelSpan: typeof enqueuePendingOtelSpan;
+    enqueueTelemetryEvent: typeof enqueueTelemetryEvent;
+    errorCode: typeof errorCode;
+    flushPendingOtelSpans: typeof flushPendingOtelSpans;
+    flushQueue: typeof flushQueue;
+    flushQueueWithProcessLock: typeof flushQueueWithProcessLock;
+    flushTelemetryArtifacts: typeof flushTelemetryArtifacts;
+    hashTelemetryErrorFingerprint: typeof hashTelemetryErrorFingerprint;
+    hashTelemetryValue: typeof hashTelemetryValue;
+    isEmailDomainCharacter: typeof isEmailDomainCharacter;
+    isEmailLocalCharacter: typeof isEmailLocalCharacter;
+    isExpiredPendingOtelSpan: typeof isExpiredPendingOtelSpan;
+    isExpiredQueueEntry: typeof isExpiredQueueEntry;
+    isFreshDirectoryLock: typeof isFreshDirectoryLock;
+    isDueForRetry: typeof isDueForRetry;
+    isDueForRetryAt: typeof isDueForRetryAt;
+    isRetryableQueueRewriteError: typeof isRetryableQueueRewriteError;
+    looksLikeEmailToken: typeof looksLikeEmailToken;
+    otelSpansQueuePath: typeof otelSpansQueuePath;
+    parseBooleanTrueLike: typeof parseBooleanTrueLike;
+    parsePendingOtelSpanLines: typeof parsePendingOtelSpanLines;
+    prunePendingOtelSpans: typeof prunePendingOtelSpans;
+    reconcilePendingOtelSpansAfterFlush: typeof reconcilePendingOtelSpansAfterFlush;
+    retentionCutoffMs: typeof retentionCutoffMs;
+    resolveOtelTracesEndpoint: typeof resolveOtelTracesEndpoint;
+    rewritePendingOtelSpans: typeof rewritePendingOtelSpans;
+    normalizeForHash: typeof normalizeForHash;
+    normalizeCaptureLevel: typeof normalizeCaptureLevel;
+    normalizePmVersion: typeof normalizePmVersion;
+    normalizeTelemetryErrorCategory: typeof normalizeTelemetryErrorCategory;
+    normalizeTelemetryErrorCode: typeof normalizeTelemetryErrorCode;
+    normalizeTelemetryExitCode: typeof normalizeTelemetryExitCode;
+    parseQueueLines: typeof parseQueueLines;
+    pruneExpiredQueueEntries: typeof pruneExpiredQueueEntries;
+    readRuntimeState: typeof readRuntimeState;
+    readCurrentQueueEntries: typeof readCurrentQueueEntries;
     releaseTelemetryFlushSpawnGate: typeof releaseTelemetryFlushSpawnGate;
+    removeFlushedEntriesFromCurrentQueue: typeof removeFlushedEntriesFromCurrentQueue;
+    removeDirectoryLockBestEffort: typeof removeDirectoryLockBestEffort;
+    resolveTelemetrySourceContext: typeof resolveTelemetrySourceContext;
+    rewriteQueue: typeof rewriteQueue;
+    sanitizeCommandArgs: typeof sanitizeCommandArgs;
+    sanitizeStringMax: typeof sanitizeStringMax;
+    sanitizeStringRedacted: typeof sanitizeStringRedacted;
+    sanitizeValue: typeof sanitizeValue;
+    scheduleTelemetryFlush: typeof scheduleTelemetryFlush;
+    shouldFlushInline: typeof shouldFlushInline;
+    sleep: typeof sleep;
+    summarizeResult: typeof summarizeResult;
+    telemetryFlushRunnerPath: typeof telemetryFlushRunnerPath;
+    withQueueMutation: typeof withQueueMutation;
     flushLockPath: typeof flushLockPath;
     flushSpawnLockPath: typeof flushSpawnLockPath;
+    runtimeStatePath: typeof runtimeStatePath;
+    writeRuntimeState: typeof writeRuntimeState;
 };
+declare function flushQueueWithProcessLock(globalPmRoot: string, endpoint: string, retentionDays: number): Promise<void>;
+declare function scheduleTelemetryFlush(globalPmRoot: string, endpoint: string, retentionDays: number): void;
 export declare function flushTelemetryQueueNow(globalPmRoot?: string): Promise<void>;
 export declare function startTelemetryCommand(context: TelemetryCommandContext): Promise<ActiveTelemetryCommand | null>;
 export declare function finishTelemetryCommand(activeCommand: ActiveTelemetryCommand | null, outcome: TelemetryCommandOutcome): Promise<void>;