@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/telemetry/state.js

@@ -0,0 +1,195 @@
+/**
+ * The locally persisted telemetry plan cache.
+ *
+ * The client decides whether to report from two inputs, neither of which is a live network call at
+ * send time: the last confirmed plan tier and the saved preference. The tier is bound to the
+ * account that confirmed it, locally, by a SHA-256 hash of the auth subject — a value that never
+ * leaves the machine.
+ *
+ * One entry would lose an earlier user's answer: if A opts out and B then signs in, A's return
+ * during an outage would find B's entry and start reporting. A few entries mean a previously
+ * opted-out subject finds its own answer again while the map stays bounded. Opt-out entries are
+ * evicted last, because evicting the one paid user who turned reporting off is exactly the mistake
+ * the cache exists to prevent.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { telemetryDirectory, withTelemetryLock } from './identity.js';
+export const TELEMETRY_STATE_VERSION = 1;
+/** Answered plans kept for signed-in subjects. */
+export const PLAN_CACHE_LIVE_LIMIT = 8;
+/** Opt-out entries are protected up to this total. */
+export const PLAN_CACHE_TOTAL_LIMIT = 64;
+const SUBJECT_HASH = /^[a-f0-9]{64}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const TIERS = ['free', 'legacy', 'paid', 'unknown'];
+export function statePath(directory) { return join(directory, 'state.json'); }
+/** A local, one-way identifier for the account, so the cache can be bound without storing the subject. */
+export function subjectHash(subject) {
+    return createHash('sha256').update(subject).digest('hex');
+}
+/** Ignore a cache entry this build cannot read rather than dropping the whole file. */
+function validEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return TIERS.includes(entry.tier)
+        && (entry.preference === 'on' || entry.preference === 'off')
+        && typeof entry.confirmedAt === 'string' && ISO.test(entry.confirmedAt);
+}
+/**
+ * Read the cache.
+ *
+ * A missing file is an empty cache. A file this build cannot parse is also empty: the cache is
+ * derived state, and collecting again is always safe, while failing a run over it is not.
+ */
+export async function readTelemetryState(directory = telemetryDirectory()) {
+    let stored;
+    try {
+        stored = await readFile(statePath(directory), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { version: 1, plans: {} };
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(stored);
+        if (parsed.version !== TELEMETRY_STATE_VERSION || !parsed.plans || typeof parsed.plans !== 'object' || Array.isArray(parsed.plans)) {
+            return { version: 1, plans: {} };
+        }
+        const plans = {};
+        for (const [key, entry] of Object.entries(parsed.plans)) {
+            if (SUBJECT_HASH.test(key) && validEntry(entry))
+                plans[key] = { tier: entry.tier, preference: entry.preference, confirmedAt: entry.confirmedAt };
+        }
+        return { version: 1, plans };
+    }
+    catch {
+        return { version: 1, plans: {} };
+    }
+}
+async function writeState(directory, state) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.state.${randomUUID()}.tmp`);
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(state, null, 2) + '\n', 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, statePath(directory));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Bound the cache.
+ *
+ * Non-opt-out entries are trimmed to the live limit first, then the whole map to the total limit,
+ * evicting older non-opt-out entries before any opt-out. Only when every entry is an opt-out does
+ * the oldest opt-out go.
+ */
+export function prunePlanCache(plans, now = Date.now()) {
+    const entries = Object.entries(plans).sort((a, b) => Date.parse(a[1].confirmedAt) - Date.parse(b[1].confirmedAt));
+    const remove = new Set();
+    const live = () => entries.filter(([key]) => !remove.has(key) && plans[key].preference === 'on');
+    for (const [key] of live())
+        if (live().length > PLAN_CACHE_LIVE_LIMIT)
+            remove.add(key);
+    for (;;) {
+        const remaining = entries.filter(([key]) => !remove.has(key));
+        if (remaining.length <= PLAN_CACHE_TOTAL_LIMIT)
+            break;
+        const evictable = remaining.find(([key]) => plans[key].preference === 'on') ?? remaining[0];
+        remove.add(evictable[0]);
+    }
+    const pruned = {};
+    for (const [key, entry] of entries)
+        if (!remove.has(key))
+            pruned[key] = entry;
+    return pruned;
+}
+/**
+ * Record a plan the account service named.
+ *
+ * Called from the membership client on every successful `/me`; a signed-out or unavailable answer
+ * never calls it, so a confirmed opt-out survives an outage.
+ */
+export async function recordConfirmedPlan(input) {
+    const directory = input.directory ?? telemetryDirectory();
+    const key = subjectHash(input.subject);
+    await withTelemetryLock(directory, async () => {
+        const state = await readTelemetryState(directory);
+        // A `/me` answer can be in flight while `/feedback off` saves the configuration and updates
+        // this cache. The confirmation then carries the preference as it stood before that change, so
+        // an entry written after the answer was observed keeps its own preference.
+        const observedAt = input.observedAt === undefined ? Number.NaN : Date.parse(input.observedAt);
+        const existing = state.plans[key];
+        const preference = existing !== undefined && existing.preference !== input.preference
+            && Number.isFinite(observedAt) && Date.parse(existing.confirmedAt) > observedAt
+            ? existing.preference : input.preference;
+        const entry = { tier: input.tier, preference, confirmedAt: new Date().toISOString() };
+        // A repeated confirmation always refreshes the timestamp, even when nothing changed: signed-out
+        // operation selects the newest entry, and the account actively using the installation is the
+        // one that must win — skipping the write let another account's older confirmation stay newest
+        // and silently override the active account's opt-out.
+        state.plans[key] = entry;
+        state.plans = prunePlanCache(state.plans);
+        await writeState(directory, state);
+    });
+}
+/**
+ * Update the cached entry a preference change belongs to.
+ *
+ * The entry's `preference` is what marks an opt-out for eviction protection: an account whose
+ * template still says `on` is an ordinary live entry, and eight newer confirmations can push it
+ * out. The Paid user who later returns while `/me` is unavailable would then be `unknown` and start
+ * reporting again. Signed out, the newest entry is the one the gate consults, so that is the one
+ * updated.
+ */
+export async function recordPreference(input) {
+    const directory = input.directory ?? telemetryDirectory();
+    await withTelemetryLock(directory, async () => {
+        const state = await readTelemetryState(directory);
+        const key = input.subject
+            ? subjectHash(input.subject)
+            : Object.entries(state.plans).sort((a, b) => Date.parse(b[1].confirmedAt) - Date.parse(a[1].confirmedAt))[0]?.[0];
+        if (key === undefined || state.plans[key] === undefined)
+            return;
+        if (state.plans[key].preference === input.preference)
+            return;
+        // The refresh matters after a sign-out: selection then takes the newest entry, and an account
+        // that just changed its preference is the one currently using the installation.
+        state.plans[key] = { ...state.plans[key], preference: input.preference, confirmedAt: new Date().toISOString() };
+        state.plans = prunePlanCache(state.plans);
+        await writeState(directory, state);
+    });
+}
+/**
+ * The last confirmed plan for the account operating this installation.
+ *
+ * A signed-in subject that matches an entry gets that entry. A signed-in subject with no entry is
+ * `undefined` — `unknown` — until `/me` answers, so a shared installation cannot hand one user's
+ * plan or opt-out to another. Signed out, the most recently confirmed entry still applies, which is
+ * the case the outage rule protects.
+ */
+export async function cachedPlan(directory, subject) {
+    const state = await readTelemetryState(directory);
+    if (subject) {
+        const entry = state.plans[subjectHash(subject)];
+        return entry ? { entry, matched: true } : undefined;
+    }
+    const newest = Object.values(state.plans).sort((a, b) => Date.parse(b.confirmedAt) - Date.parse(a.confirmedAt))[0];
+    return newest ? { entry: newest, matched: false } : undefined;
+}
+/** Drop every cached plan; used by tests and by a settings reset. */
+export async function clearPlanCache(directory = telemetryDirectory()) {
+    await withTelemetryLock(directory, () => writeState(directory, { version: 1, plans: {} }));
+}

package/dist/src/telemetry/surface.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The per-surface glue between a run's lifecycle and the emitter.
+ *
+ * Each surface already knows its graph, permission mode, JEV configuration and result; this module
+ * only names them in one place so three surfaces cannot report different dimensions for the same
+ * run. It also owns the process's spool identity, which must be stable for the process's lifetime
+ * and distinct between concurrent engines.
+ */
+import { type Config } from '../config.js';
+import { telemetryHome, type RunDimensions, type TelemetryContext } from './emitter.js';
+import type { Graph } from '../graphs.js';
+import type { RunTelemetry } from './capture.js';
+import type { ClassifiableStatus } from './classify.js';
+/** What a graph contributes to the run's dimensions: its size, and whether it can delegate. */
+export declare function graphShape(graph: Graph): {
+    nodes: number;
+    subagents: boolean;
+};
+export interface RunTelemetryHandle {
+    /** The random telemetry id, not the persisted run id. */
+    runId: string;
+    startedAt: string;
+    dimensions: RunDimensions;
+    /** The workspace root, when the surface has one. */
+    workspace?: string;
+    /** Whether the start reached the spool; `undefined` until the start has been attempted. */
+    started?: boolean;
+    /**
+     * The preference generation the start was queued under. The finish is only paired with it while
+     * that generation is current: an opt-out purges the outbox, so the start it would join is gone.
+     */
+    generation?: number;
+}
+/**
+ * This process's engine id.
+ *
+ * Stable per surface for the process lifetime, so every event a process writes lands in the same
+ * spool and the process that owns that spool can drain it.
+ */
+export declare function engineId(surface: string): string;
+/** The surface a relayed or embedded engine should report. */
+export declare function configuredSurface(fallback: 'cli' | 'desktop' | 'remote' | 'subagent'): 'cli' | 'desktop' | 'remote' | 'subagent';
+export interface SurfaceInput {
+    home?: string;
+    config?: Config;
+    subject?: string;
+    surface: 'cli' | 'desktop' | 'remote' | 'subagent';
+}
+export declare function contextFor(input: SurfaceInput): TelemetryContext;
+/** A handle allocated before the run starts; its id is written into the open record. */
+export declare function createRunHandle(runId: string, startedAt: string, dimensions: RunDimensions, workspace?: string): RunTelemetryHandle;
+export declare function reportRunStarted(input: SurfaceInput, handle: RunTelemetryHandle): Promise<void>;
+export declare function reportRunFinished(input: SurfaceInput, handle: RunTelemetryHandle, finish: {
+    status: ClassifiableStatus;
+    reason?: string;
+    providerRequestFailed?: boolean;
+    providerOverflow?: boolean;
+    telemetry?: RunTelemetry;
+    toolCalls?: number;
+    toolFailures?: number;
+    attempts?: number;
+    retries?: number;
+}): Promise<void>;
+/** Enqueue the `interrupted` finish for every run recovery marked. Idempotent by the telemetry id. */
+export declare function reportInterruptedRuns(input: SurfaceInput, records: Record<string, unknown>[]): Promise<void>;
+export declare function reportSessionStarted(input: SurfaceInput & {
+    workspace?: string;
+}): Promise<void>;
+/**
+ * Deliver queued events before the process exits.
+ *
+ * A no-op while no endpoint is configured, and when a Paid account has opted out. Nothing here
+ * throws: a run that already succeeded must not fail on a network error.
+ */
+export declare function drainTelemetry(input: SurfaceInput, signal?: AbortSignal): Promise<void>;
+export { telemetryHome };

package/dist/src/telemetry/surface.js

@@ -0,0 +1,116 @@
+/**
+ * The per-surface glue between a run's lifecycle and the emitter.
+ *
+ * Each surface already knows its graph, permission mode, JEV configuration and result; this module
+ * only names them in one place so three surfaces cannot report different dimensions for the same
+ * run. It also owns the process's spool identity, which must be stable for the process's lifetime
+ * and distinct between concurrent engines.
+ */
+import { configDirectory, loadConfig } from '../config.js';
+import { drainOutbox } from './uploader.js';
+import { emitInterruptedRun, emitRunFinished, emitRunStarted, emitSessionStarted, telemetryHome, } from './emitter.js';
+import { telemetryDirectory } from './identity.js';
+import { telemetryGate } from './gate.js';
+import { clearInterruptedTelemetry } from '../run-records.js';
+/** What a graph contributes to the run's dimensions: its size, and whether it can delegate. */
+export function graphShape(graph) {
+    return {
+        nodes: Object.keys(graph.nodes).length,
+        subagents: Object.values(graph.nodes).some(node => node.subagents?.enabled === true),
+    };
+}
+const engines = new Map();
+/**
+ * This process's engine id.
+ *
+ * Stable per surface for the process lifetime, so every event a process writes lands in the same
+ * spool and the process that owns that spool can drain it.
+ */
+export function engineId(surface) {
+    let id = engines.get(surface);
+    if (!id) {
+        id = `${surface}-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+        engines.set(surface, id);
+    }
+    return id;
+}
+/** The surface a relayed or embedded engine should report. */
+export function configuredSurface(fallback) {
+    const value = process.env.ANDORRA_SURFACE;
+    return value === 'cli' || value === 'desktop' || value === 'remote' || value === 'subagent' ? value : fallback;
+}
+export function contextFor(input) {
+    return { home: input.home, config: input.config, subject: input.subject, surface: input.surface, engineId: engineId(input.surface) };
+}
+/** A handle allocated before the run starts; its id is written into the open record. */
+export function createRunHandle(runId, startedAt, dimensions, workspace) {
+    return { runId, startedAt, dimensions, workspace };
+}
+export async function reportRunStarted(input, handle) {
+    const generation = await emitRunStarted(contextFor(input), { ...handle.dimensions, runId: handle.runId });
+    handle.started = generation !== undefined;
+    handle.generation = generation;
+}
+export async function reportRunFinished(input, handle, finish) {
+    // A run whose start never went out keeps silent: a finish alone would inflate completed runs
+    // against started ones. A run whose start did go out always finishes, even if another process
+    // changed the preference in between.
+    if (handle.started === false)
+        return;
+    await emitRunFinished({ ...contextFor(input), ...handle.dimensions }, {
+        ...contextFor(input),
+        ...handle.dimensions,
+        ...(handle.started === true ? { paired: true, ...(handle.generation === undefined ? {} : { startGeneration: handle.generation }) } : {}),
+        runId: handle.runId, startedAt: handle.startedAt,
+        workspace: handle.workspace,
+        ...finish,
+    });
+}
+/** Enqueue the `interrupted` finish for every run recovery marked. Idempotent by the telemetry id. */
+export async function reportInterruptedRuns(input, records) {
+    const context = contextFor(input);
+    const reported = [];
+    for (const record of records) {
+        // Each record names the account it ran under. A shared installation otherwise resolves the
+        // newest cached plan, which can belong to another account and carry a different opt-out.
+        const subject = typeof record.accountSubject === 'string' ? record.accountSubject : input.subject;
+        // The producing surface travels with the record: a crashed CLI run recovered by a desktop
+        // app-server must still report `cli`, or the joined pair disagrees and the interrupted outcome
+        // lands in the wrong surface bucket.
+        const surface = record.surface === 'cli' || record.surface === 'desktop' || record.surface === 'remote' || record.surface === 'subagent'
+            ? record.surface : context.surface;
+        const queued = await emitInterruptedRun({ ...context, surface, subject }, record);
+        if (queued && typeof record.id === 'string')
+            reported.push(record.id);
+    }
+    // The marker is cleared only after the finish is on the spool. A process that dies before this
+    // leaves the record reported again on the next pass, under the same derived event id.
+    if (reported.length)
+        await clearInterruptedTelemetry(input.home ?? configDirectory(), reported).catch(() => { });
+}
+export async function reportSessionStarted(input) {
+    await emitSessionStarted({ ...contextFor(input), workspace: input.workspace });
+}
+/**
+ * Deliver queued events before the process exits.
+ *
+ * A no-op while no endpoint is configured, and when a Paid account has opted out. Nothing here
+ * throws: a run that already succeeded must not fail on a network error.
+ */
+export async function drainTelemetry(input, signal) {
+    try {
+        // Read fresh, for the same reason the emitter does: the generation and preference this drain
+        // compares against must be the ones on disk now, not the ones this process started with.
+        const config = await loadConfig(input.home ?? configDirectory());
+        const gate = await telemetryGate({ home: input.home, config, subject: input.subject });
+        // A drain can outlast the snapshot it started with, and another engine may opt out meanwhile:
+        // the preference is re-read between posts rather than trusted for the whole spool.
+        const reporting = async () => {
+            const current = await loadConfig(input.home ?? configDirectory());
+            return (await telemetryGate({ home: input.home, config: current, subject: input.subject })).report;
+        };
+        await drainOutbox(telemetryDirectory(input.home ?? configDirectory()), gate.generation, { report: gate.report, signal, reporting });
+    }
+    catch { /* Telemetry is optional. */ }
+}
+export { telemetryHome };

package/dist/src/telemetry/uploader.d.ts

@@ -0,0 +1,29 @@
+import { type TelemetryEvent } from './schema.js';
+/** The configured ingest endpoint, or `undefined` while the deployment does not name one. */
+export declare function telemetryEndpoint(): string | undefined;
+export interface UploadDependencies {
+    /** Whether reporting is still allowed; asked before each post so a mid-drain opt-out is obeyed. */
+    reporting?: () => Promise<boolean>;
+    fetch?: typeof globalThis.fetch;
+    baseUrl?: string;
+    /** The caller's abort signal, so an opt-out cancels an upload already in flight. */
+    signal?: AbortSignal;
+}
+export interface DrainResult {
+    sent: number;
+    dropped: number;
+    remaining: number;
+    skipped: boolean;
+}
+/**
+ * Drain this engine's spool and any abandoned spool the locks allow.
+ *
+ * A spool is abandoned when its owner is gone; the lock alone decides that, so a live engine's
+ * spool is left alone and a dead one is adopted. The coordinator calls this at startup and each
+ * surface calls it before exit.
+ */
+export declare function drainOutbox(telemetry: string, generation: number, options?: UploadDependencies & {
+    report: boolean;
+}): Promise<DrainResult>;
+/** Queue one event, tagging it with the generation that was in effect when it was decided. */
+export declare function queueEvent(telemetry: string, engineId: string, generation: number, event: TelemetryEvent): Promise<void>;

package/dist/src/telemetry/uploader.js

@@ -0,0 +1,151 @@
+/**
+ * Outbox delivery.
+ *
+ * The route is unauthenticated by design, so nothing here needs a token. `installId` is chosen by
+ * the caller and can be regenerated per request by a hostile client, which is why the server owns
+ * the independent edge limit; the drainer's job is only to deliver what was collected and to stop
+ * rather than lose a record.
+ *
+ * A successful upload removes the entry. A record the server rejects as invalid is dropped — it
+ * would otherwise poison the queue forever — while a transient failure keeps it for the next
+ * drain. A `409` is success: the object already exists, so a retry is idempotent.
+ */
+import { join } from 'node:path';
+import { AUTH_DEPLOYMENT } from '../auth/deployment.js';
+import { enqueue, pruneGeneration, pruneOld, readSpool, rewriteSpool, spoolNames, sweepOutbox, withSpoolLock, withSpoolLockWait, } from './outbox.js';
+import { serializeTelemetryEvent } from './schema.js';
+import { uploadSignal } from './uploads.js';
+/** The configured ingest endpoint, or `undefined` while the deployment does not name one. */
+export function telemetryEndpoint() {
+    const configured = process.env.ANDORRA_TELEMETRY_URL || AUTH_DEPLOYMENT.telemetryBaseUrl;
+    return configured ? configured.replace(/\/+$/, '') : undefined;
+}
+const REQUEST_TIMEOUT_MS = 5_000;
+/** One event's HTTP outcome: `ok`, `drop` (the server will never accept it), or `retry`. */
+async function post(endpoint, event, dependencies) {
+    let body;
+    try {
+        body = serializeTelemetryEvent(event);
+    }
+    catch {
+        return 'drop';
+    }
+    // The process-wide signal is what an opt-out aborts; the caller's signal is a cancellation.
+    const processSignal = uploadSignal();
+    const signal = AbortSignal.any([processSignal, AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(dependencies.signal ? [dependencies.signal] : [])]);
+    try {
+        const response = await (dependencies.fetch ?? globalThis.fetch)(`${endpoint}/events`, {
+            method: 'POST', headers: { 'content-type': 'application/json' }, body, signal, redirect: 'error',
+        });
+        await response.body?.cancel().catch(() => { });
+        if (response.ok || response.status === 409)
+            return 'ok';
+        // A rejected value will be rejected again; a throttle or a server fault may not. The WAF's
+        // rate rule answers 403, which is transient: this route has no auth that could reject one.
+        // 408 is the server timing out before it accepted the event: transient, and idempotent by id.
+        if (response.status === 403 || response.status === 408 || response.status === 429 || response.status >= 500)
+            return 'retry';
+        return 'drop';
+    }
+    catch (error) {
+        if (dependencies.signal?.aborted)
+            throw error;
+        // An opt-out aborted this upload; the purge already removed what it held, so the entry is
+        // simply not resent under the old preference.
+        if (processSignal.aborted)
+            return 'drop';
+        return 'retry';
+    }
+}
+/**
+ * Deliver one spool.
+ *
+ * The lock covers the read and the rewrite, never the uploads: an owner that enqueues during a
+ * slow drain appends under the same lock, and the rewrite removes only the entries this drain
+ * actually handled, so that append survives. Two coordinators can therefore drain the same spool
+ * concurrently — the ingest is idempotent by `eventId`, and the second rewrite finds nothing left.
+ */
+async function drainSpool(telemetry, name, generation, dependencies) {
+    const path = join(telemetry, 'outbox', name);
+    const snapshot = await withSpoolLock(telemetry, name, async () => {
+        const queued = await readSpool(path);
+        const entries = pruneGeneration(pruneOld(queued), generation);
+        return { entries, dropped: queued.length - entries.length };
+    });
+    if (!snapshot)
+        return { sent: 0, dropped: 0, remaining: 0, skipped: true };
+    const handled = new Set();
+    let sent = 0;
+    let dropped = snapshot.dropped;
+    for (const entry of snapshot.entries) {
+        // Another process may have opted out since this snapshot was taken. The check and the post
+        // happen inside the spool lock, which is what the purge queues behind, so this request cannot
+        // complete after the preference was saved: it either went out first or is not sent.
+        const outcome = await withSpoolLockWait(telemetry, name, async () => {
+            if (dependencies.reporting && !(await dependencies.reporting()))
+                return 'stop';
+            return post(dependencies.baseUrl, entry.e, dependencies);
+        });
+        if (outcome === 'stop')
+            break;
+        // Stop at the first transient failure: the rest of the run stays in order behind it.
+        if (outcome === 'retry')
+            break;
+        handled.add(entry.e.eventId);
+        if (outcome === 'ok')
+            sent += 1;
+        else
+            dropped += 1;
+    }
+    const remaining = await withSpoolLock(telemetry, name, async () => {
+        const current = await readSpool(path);
+        const kept = pruneGeneration(pruneOld(current), generation).filter(entry => !handled.has(entry.e.eventId));
+        await rewriteSpool(telemetry, name, kept);
+        return kept.length;
+    });
+    return { sent, dropped, remaining: remaining ?? Math.max(0, snapshot.entries.length - handled.size), skipped: false };
+}
+/**
+ * Drain this engine's spool and any abandoned spool the locks allow.
+ *
+ * A spool is abandoned when its owner is gone; the lock alone decides that, so a live engine's
+ * spool is left alone and a dead one is adopted. The coordinator calls this at startup and each
+ * surface calls it before exit.
+ */
+export async function drainOutbox(telemetry, generation, options = { report: true }) {
+    const aggregate = { sent: 0, dropped: 0, remaining: 0, skipped: false };
+    if (!options.report) {
+        // This process will queue nothing new, but the spool may hold entries another subject queued
+        // under the current generation — a shared installation's Free account, while the newest cache
+        // entry is a Paid opt-out. Only entries older than the generation are discarded; wiping the
+        // spool would delete events that were gated correctly when they were written.
+        for (const name of await spoolNames(telemetry)) {
+            await withSpoolLock(telemetry, name, async () => {
+                const path = join(telemetry, 'outbox', name);
+                const kept = pruneGeneration(pruneOld(await readSpool(path)), generation);
+                await rewriteSpool(telemetry, name, kept);
+            });
+        }
+        return { ...aggregate, skipped: true };
+    }
+    const baseUrl = options.baseUrl ?? telemetryEndpoint();
+    if (!baseUrl) {
+        // Nothing can be delivered while no endpoint is configured, so this is where age and the
+        // installation-wide cap are enforced; otherwise the outbox would only ever grow.
+        await sweepOutbox(telemetry).catch(() => { });
+        return { ...aggregate, skipped: true };
+    }
+    for (const name of await spoolNames(telemetry)) {
+        if (options.signal?.aborted)
+            break;
+        const result = await drainSpool(telemetry, name, generation, { ...options, baseUrl });
+        aggregate.sent += result.sent;
+        aggregate.dropped += result.dropped;
+        aggregate.remaining += result.remaining;
+    }
+    return aggregate;
+}
+/** Queue one event, tagging it with the generation that was in effect when it was decided. */
+export async function queueEvent(telemetry, engineId, generation, event) {
+    await enqueue(telemetry, engineId, { g: generation, run: event.runId ?? null, e: event });
+}

package/dist/src/telemetry/uploads.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The process's in-flight upload signal.
+ *
+ * An opt-out must stop what this process is already sending: the outbox purge removes queued
+ * entries, but an upload that has left the queue would still store a pre-opt-out event after the
+ * preference was saved. The drainer combines this signal with its caller's, and an opt-out aborts
+ * it. Another process's in-flight upload cannot be signalled; its generation check is what keeps
+ * that one from uploading anything it has not already sent.
+ */
+/** The signal every upload combines with its own. */
+export declare function uploadSignal(): AbortSignal;
+/** Abort in-flight uploads and start a fresh epoch for the uploads that follow. */
+export declare function cancelActiveUploads(): void;

package/dist/src/telemetry/uploads.js

@@ -0,0 +1,19 @@
+/**
+ * The process's in-flight upload signal.
+ *
+ * An opt-out must stop what this process is already sending: the outbox purge removes queued
+ * entries, but an upload that has left the queue would still store a pre-opt-out event after the
+ * preference was saved. The drainer combines this signal with its caller's, and an opt-out aborts
+ * it. Another process's in-flight upload cannot be signalled; its generation check is what keeps
+ * that one from uploading anything it has not already sent.
+ */
+let controller = new AbortController();
+/** The signal every upload combines with its own. */
+export function uploadSignal() {
+    return controller.signal;
+}
+/** Abort in-flight uploads and start a fresh epoch for the uploads that follow. */
+export function cancelActiveUploads() {
+    controller.abort();
+    controller = new AbortController();
+}

package/dist/src/telemetry/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This module sits one directory below the CLI's, so the manifest is three levels up from
+ * `dist/src/telemetry/` (and from `src/telemetry/` under a source runner).
+ */
+export declare function appVersion(): Promise<string>;

package/dist/src/telemetry/version.js

@@ -0,0 +1,25 @@
+/**
+ * The build version telemetry reports.
+ *
+ * It is read from the package manifest rather than hard-coded, because a build that reports a
+ * version it does not have makes release comparisons meaningless. A manifest that cannot be read
+ * yields `unknown`, which the ingest counts in totals and excludes from version comparisons.
+ *
+ * This is the same lookup the CLI and the app-server already performed separately; both now ask
+ * here so a future change cannot update one surface and leave the other reporting the old value.
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+/**
+ * This module sits one directory below the CLI's, so the manifest is three levels up from
+ * `dist/src/telemetry/` (and from `src/telemetry/` under a source runner).
+ */
+export async function appVersion() {
+    try {
+        const manifest = JSON.parse(await readFile(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8'));
+        return typeof manifest.version === 'string' && /^[0-9A-Za-z.+-]{1,64}$/.test(manifest.version) ? manifest.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/src/telemetry/workspace.d.ts

@@ -0,0 +1,14 @@
+import { type WorkspaceObservation, type WorkspaceShape } from './classify.js';
+export interface InspectOptions {
+    limit?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Walk the workspace and return the retained shape.
+ *
+ * A workspace that cannot be read yields an empty observation rather than failing the session;
+ * telemetry never gets to break the work it describes.
+ */
+export declare function inspectWorkspace(root: string, options?: InspectOptions): Promise<WorkspaceObservation>;
+/** The final shape, ready to be serialized into an event. */
+export declare function workspaceShape(observation: WorkspaceObservation): WorkspaceShape;