@ashlr/hub 2.2.0

package/dist/core/observability/telemetry-sink.js

@@ -0,0 +1,350 @@
+/**
+ * core/observability/telemetry-sink.ts — M19 telemetry sink seam.
+ *
+ * Two implementations:
+ *   LocalFileSink  — default (no endpoint / no PAT). Appends spans as JSONL
+ *                    to a daily file under ~/.ashlr/telemetry/. What `ashlr
+ *                    pulse` already aggregates locally.
+ *   OtlpHttpSink   — opt-in, only when cfg.telemetry.pulse AND a PAT are
+ *                    both present. Builds an OTLP/HTTP-JSON trace and POSTs
+ *                    it to the configured endpoint. Fire-and-forget, bounded
+ *                    timeout, never throws/blocks.
+ *
+ * GUARDRAILS:
+ *   - PRIVACY: JSONL records and span attributes are METADATA ONLY (model,
+ *     token counts, cost, ids, provider, tier, status, duration). NEVER
+ *     prompt/response text, tool args, file contents, or secrets.
+ *   - PAT/SECRET SAFETY: PAT lives ONLY in the Authorization header. It is
+ *     NEVER logged, printed, returned, placed in span attrs or `detail`, or
+ *     committed. Source: phantom (preferred) or ASHLR_PULSE_TOKEN env var.
+ *   - All emits are best-effort: ok:false is logged to stderr only and NEVER
+ *     blocks or propagates out of a run/swarm.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, appendFileSync } from 'node:fs';
+import { spawnSync, spawn } from 'node:child_process';
+import { buildGenAiTrace } from './otlp.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const PHANTOM_BIN = 'phantom';
+const PHANTOM_TIMEOUT_MS = 5_000;
+/**
+ * Fetch timeout for OTLP POST — bounded, never blocks a run. Kept short
+ * (this is a fire-and-forget metadata POST); a dead/slow-but-reachable
+ * endpoint must not add meaningful wall-clock latency to run/swarm completion.
+ */
+const OTLP_FETCH_TIMEOUT_MS = 3_000;
+/**
+ * Bounded budget for resolving the PAT via phantom on the emit hot path.
+ * Uses async spawn (NOT spawnSync) so the Node event loop is never frozen.
+ */
+const PHANTOM_RESOLVE_TIMEOUT_MS = 3_000;
+/** Secret name phantom stores for the Pulse PAT. */
+const PHANTOM_PAT_KEY = 'ASHLR_PULSE_TOKEN';
+// ---------------------------------------------------------------------------
+// Public: localTelemetryDir
+// ---------------------------------------------------------------------------
+/**
+ * Returns the absolute path to the local telemetry directory:
+ * ~/.ashlr/telemetry
+ *
+ * Re-resolves homedir() at call time so a relocated HOME in tests is honored.
+ */
+export function localTelemetryDir() {
+    return join(homedir(), '.ashlr', 'telemetry');
+}
+// ---------------------------------------------------------------------------
+// Public: patAvailable
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when a Pulse PAT is discoverable — either via the
+ * ASHLR_PULSE_TOKEN environment variable or via phantom (when installed,
+ * initialized, and the key is present in the vault).
+ *
+ * NEVER reads, returns, or logs the PAT value — boolean only.
+ *
+ * `allowPhantomProbe` (default true) controls the blocking spawnSync phantom
+ * probe. The doctor / `ashlr telemetry status` callers want the full probe
+ * (they are NOT on a run's completion path). The emit hot path
+ * (getSink -> patAvailable) MUST pass `false`: the spawnSync probe freezes the
+ * event loop for up to ~10s (2x5s) and is redundant there — OtlpHttpSink.emit
+ * resolves the PAT itself via the async, bounded resolvePatAsync. With the
+ * probe off, patAvailable is a pure env-var check (no blocking).
+ */
+export function patAvailable(cfg, allowPhantomProbe = true) {
+    // 1. Env var check — existence only, never the value.
+    if (process.env['ASHLR_PULSE_TOKEN'] !== undefined && process.env['ASHLR_PULSE_TOKEN'] !== '') {
+        return true;
+    }
+    // 2. Phantom check — only when phantom integration is enabled in cfg AND the
+    //    caller opted into the blocking probe (never on the emit hot path).
+    if (!allowPhantomProbe)
+        return false;
+    if (!cfg.phantom?.enabled)
+        return false;
+    try {
+        // Quick binary check.
+        const versionResult = spawnSync(PHANTOM_BIN, ['--version'], {
+            encoding: 'utf8',
+            timeout: PHANTOM_TIMEOUT_MS,
+            env: { ...process.env, PHANTOM_NO_UPDATE_CHECK: '1' },
+        });
+        if (versionResult.error || versionResult.status !== 0)
+            return false;
+        // List secret names only — never values.
+        const listResult = spawnSync(PHANTOM_BIN, ['list', '--json'], {
+            encoding: 'utf8',
+            timeout: PHANTOM_TIMEOUT_MS,
+            env: { ...process.env, PHANTOM_NO_UPDATE_CHECK: '1' },
+        });
+        if (listResult.error || listResult.status !== 0)
+            return false;
+        const raw = (listResult.stdout ?? '').trim();
+        if (!raw)
+            return false;
+        // Parse names only — same conservative extraction as phantom.ts.
+        const names = extractSecretNames(raw);
+        return names.includes(PHANTOM_PAT_KEY);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public: getSink
+// ---------------------------------------------------------------------------
+/**
+ * Returns the appropriate TelemetrySink for the given config:
+ *   - OtlpHttpSink when cfg.telemetry.pulse is set AND a PAT is available.
+ *   - LocalFileSink (default, 100% local) otherwise.
+ *
+ * `allowPhantomProbe` (default true) is forwarded to patAvailable. On the
+ * emit hot path (orchestrator/swarm completion) callers MUST pass `false` so
+ * the selection never runs a blocking spawnSync phantom probe: when an
+ * endpoint is configured we hand off to OtlpHttpSink, which resolves the PAT
+ * asynchronously with a bounded timeout (and degrades to a logged
+ * 'PAT unavailable' no-op if none is found) — never freezing the event loop.
+ * The CLI (`telemetry test`/`status`) keeps the default probe.
+ */
+export function getSink(cfg, allowPhantomProbe = true) {
+    if (cfg.telemetry?.pulse) {
+        // On the emit path (probe off): select OTLP whenever an endpoint is set and
+        // let OtlpHttpSink resolve the PAT async; if none, emit() is a logged no-op.
+        if (!allowPhantomProbe)
+            return new OtlpHttpSink(cfg);
+        // CLI path: keep the synchronous PAT availability probe for accurate routing.
+        if (patAvailable(cfg, true))
+            return new OtlpHttpSink(cfg);
+    }
+    return new LocalFileSink();
+}
+// ---------------------------------------------------------------------------
+// LocalFileSink — default, 100% local
+// ---------------------------------------------------------------------------
+/**
+ * Appends spans as JSONL to a daily file under ~/.ashlr/telemetry/.
+ * File name: telemetry-YYYY-MM-DD.jsonl
+ * Each line is a single JSON object containing one span (metadata only).
+ * What `ashlr pulse` already aggregates locally.
+ */
+class LocalFileSink {
+    async emit(spans) {
+        if (spans.length === 0) {
+            return { sink: 'local', ok: true, detail: 'no spans' };
+        }
+        try {
+            const dir = localTelemetryDir();
+            mkdirSync(dir, { recursive: true });
+            const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+            const filePath = join(dir, `telemetry-${date}.jsonl`);
+            const lines = spans.map((span) => JSON.stringify(span)).join('\n') + '\n';
+            appendFileSync(filePath, lines, 'utf8');
+            return { sink: 'local', ok: true, detail: `appended ${spans.length} span(s) to ${filePath}` };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[ashlr telemetry] LocalFileSink error: ${detail}\n`);
+            return { sink: 'local', ok: false, detail };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// OtlpHttpSink — opt-in, endpoint + PAT required
+// ---------------------------------------------------------------------------
+/**
+ * Builds an OTLP/HTTP-JSON trace payload from the spans and POSTs it to
+ * cfg.telemetry.pulse. Uses a bounded fetch timeout (fire-and-forget).
+ * PAT sourced from phantom (preferred) or ASHLR_PULSE_TOKEN env — placed
+ * ONLY in the Authorization header, never logged or returned.
+ */
+class OtlpHttpSink {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async emit(spans) {
+        const endpoint = this.cfg.telemetry?.pulse;
+        if (!endpoint) {
+            return { sink: 'otlp', ok: false, detail: 'no endpoint configured' };
+        }
+        // Retrieve PAT asynchronously — value used only in the Authorization
+        // header, never stored. Async + bounded so we never freeze the event loop
+        // (the spawnSync variant could block for up to 5s; resolvePatAsync uses
+        // spawn + a Promise.race timeout instead).
+        const pat = await resolvePatAsync(this.cfg);
+        if (!pat) {
+            return { sink: 'otlp', ok: false, detail: 'PAT unavailable' };
+        }
+        if (spans.length === 0) {
+            return { sink: 'otlp', ok: true, detail: 'no spans' };
+        }
+        try {
+            const body = JSON.stringify(buildGenAiTrace(spans));
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), OTLP_FETCH_TIMEOUT_MS);
+            let res;
+            try {
+                res = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        // PAT only in the Authorization header — never logged, never in detail.
+                        Authorization: `Bearer ${pat}`,
+                    },
+                    body,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (res.ok) {
+                return { sink: 'otlp', ok: true, detail: `HTTP ${res.status}` };
+            }
+            const detail = `HTTP ${res.status}`;
+            process.stderr.write(`[ashlr telemetry] OtlpHttpSink: ${detail}\n`);
+            return { sink: 'otlp', ok: false, detail };
+        }
+        catch (err) {
+            const isAbort = err instanceof Error && err.name === 'AbortError';
+            const detail = isAbort ? 'request timed out' : err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[ashlr telemetry] OtlpHttpSink error: ${detail}\n`);
+            return { sink: 'otlp', ok: false, detail };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the PAT value for use ONLY in the Authorization header — ASYNC and
+ * bounded so it is safe on a run/swarm completion path. The previous spawnSync
+ * implementation froze the Node event loop for up to PHANTOM_TIMEOUT_MS; this
+ * uses node:child_process.spawn wrapped in a Promise.race against a short
+ * timeout, so a hung phantom can never block the run.
+ *
+ * Sources (in order):
+ *   1. ASHLR_PULSE_TOKEN env var (direct, no spawn).
+ *   2. phantom exec — injects vault secrets as env vars into a subprocess;
+ *      we spawn `node -e 'process.stdout.write(process.env.ASHLR_PULSE_TOKEN||"")'`
+ *      under phantom exec so the value flows only into the header.
+ *
+ * Resolves to the PAT string, or null when unavailable.
+ * NEVER logs, prints, stores, or returns via any other path. The subprocess
+ * stdout is PAT-bearing — it is consumed locally and must never be logged.
+ */
+async function resolvePatAsync(cfg) {
+    // 1. Env var — fastest path, no subprocess.
+    const envPat = process.env['ASHLR_PULSE_TOKEN'];
+    if (envPat)
+        return envPat;
+    // 2. Phantom exec — only when integration enabled.
+    if (!cfg.phantom?.enabled)
+        return null;
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child.kill();
+            }
+            catch { /* already exited */ }
+            resolve(value);
+        };
+        // Bounded budget — a hung phantom never blocks the run.
+        const timer = setTimeout(() => done(null), PHANTOM_RESOLVE_TIMEOUT_MS);
+        let child;
+        try {
+            child = spawn(PHANTOM_BIN, ['exec', '--', 'node', '-e', `process.stdout.write(process.env['${PHANTOM_PAT_KEY}']||'')`], { env: { ...process.env, PHANTOM_NO_UPDATE_CHECK: '1' }, stdio: ['ignore', 'pipe', 'ignore'] });
+        }
+        catch {
+            done(null);
+            return;
+        }
+        // out is PAT-bearing — consumed locally, never logged.
+        let out = '';
+        child.stdout?.on('data', (chunk) => { out += chunk.toString('utf8'); });
+        child.on('error', () => done(null));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                done(null);
+                return;
+            }
+            const value = out.trim();
+            done(value || null);
+        });
+    });
+}
+/**
+ * Extract ONLY secret names from `phantom list --json` output.
+ * Conservative — returns [] on any parse failure to avoid leaking values.
+ * Mirrors the extraction logic in core/phantom.ts.
+ */
+function extractSecretNames(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            const names = [];
+            for (const item of parsed) {
+                if (item !== null && typeof item === 'object') {
+                    const obj = item;
+                    if (typeof obj['name'] === 'string')
+                        names.push(obj['name']);
+                    else if (typeof obj['key'] === 'string')
+                        names.push(obj['key']);
+                }
+                else if (typeof item === 'string') {
+                    names.push(item);
+                }
+            }
+            return names;
+        }
+        if (parsed !== null && typeof parsed === 'object') {
+            const obj = parsed;
+            for (const key of ['secrets', 'keys', 'names']) {
+                if (Array.isArray(obj[key])) {
+                    return extractSecretNames(JSON.stringify(obj[key]));
+                }
+            }
+        }
+        return [];
+    }
+    catch {
+        // Line-based fallback — env-var name pattern only, no values.
+        const ENV_VAR_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
+        const names = [];
+        for (const line of (raw ?? '').split('\n')) {
+            const token = line.trim().split(/\s+/)[0];
+            if (token && ENV_VAR_RE.test(token) && token !== 'NAME' && token !== 'KEY') {
+                names.push(token);
+            }
+        }
+        return names;
+    }
+}
+//# sourceMappingURL=telemetry-sink.js.map

package/dist/core/observability/telemetry-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-sink.js","sourceRoot":"","sources":["../../../src/core/observability/telemetry-sink.ts"],"names":[],"mappings":"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"}

package/dist/core/observability/usage-source.d.ts

@@ -0,0 +1,60 @@
+/**
+ * usage-source.ts — local-first UsageEvent collector (M5 observability).
+ *
+ * PRIVACY GUARDRAILS: reads ONLY token counts, model id, timestamp, and the
+ * project path (decoded from the encoded dir name). Never reads or retains
+ * message content, tool args/results, prompts, or completions.
+ *
+ * PERFORMANCE: streams line-by-line; skips files whose mtime is older than
+ * sinceMs; tolerates malformed lines; never throws.
+ */
+import type { UsageEvent } from "../types.js";
+/** Absolute path to ~/.claude/projects (honors $HOME). */
+export declare function claudeProjectsDir(): string;
+/**
+ * Decode an encoded Claude Code project dir name back to an absolute path.
+ *
+ * Claude encodes the absolute path by replacing the leading `/` with a `-`
+ * and then replacing every subsequent `/` with `-`. For example:
+ *   '-Users-you-Desktop-foo' -> '/Users/you/Desktop/foo'
+ *
+ * This is lossy for path segments that naturally contain `-`, but we do
+ * the best-effort reconstruction by:
+ *   1. Stripping the leading `-`
+ *   2. Re-prefixing with `/`
+ *   3. Replacing remaining `-` with `/`
+ *
+ * The result is a plausible absolute path suitable for display/grouping.
+ */
+export declare function decodeProjectPath(dirName: string): string;
+/**
+ * Collapse a real absolute path to the dash-normalized form Claude uses to
+ * encode project dir names: every `/` AND every `-` becomes `-`.
+ *
+ * Both the real path '/Users/x/dev-tools/ashlr-hub' and its lossy decode
+ * '/Users/x/dev/tools/ashlr/hub' normalize to the SAME string
+ * '-Users-x-dev-tools-ashlr-hub'. That makes dashNormalize a reliable join key
+ * between the index's REAL paths and the transcript's MANGLED decoded paths,
+ * which recovers correct grouping/labels for any repo whose name has a dash.
+ */
+export declare function dashNormalize(absPath: string): string;
+/**
+ * Resolve a (possibly mangled) decoded project path against known real paths
+ * from the index. Returns the matching real path when the dash-normalized
+ * forms agree, otherwise returns the input unchanged (best-effort decode).
+ *
+ * `realByNorm` maps dashNormalize(realPath) -> realPath and is built once by
+ * the caller so this stays O(1) per event.
+ */
+export declare function reconcileProjectPath(decodedPath: string, realByNorm: Map<string, string>): string;
+/**
+ * Collect normalized UsageEvents from all local sources with ts >= sinceMs.
+ *
+ * Sources:
+ *   (a) ~/.claude/projects/<encoded-dir>/*.jsonl  — METADATA ONLY
+ *   (b) ~/.ashlr/runs/*.json  — M4 RunState records
+ *
+ * Streams line-by-line; skips files older than sinceMs by mtime; tolerates
+ * malformed lines; never reads message content. Never throws.
+ */
+export declare function collectUsageEvents(sinceMs: number): UsageEvent[];