@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/telemetry/outbox.js

@@ -0,0 +1,356 @@
+/**
+ * The client outbox.
+ *
+ * A Free or Legacy installation cannot opt out of collecting, so the queue that makes the
+ * lifecycle pair reliable must itself be bounded and self-cleaning. Each engine process owns one
+ * spool file, named by its engine id; a spool whose owner is gone is adopted by the next
+ * coordinator through its lock, because without adoption an abrupt exit while offline would strand
+ * a spool no later process owns — losing exactly the unfinished-start records the pair exists to
+ * expose.
+ *
+ * Entries are tagged with the preference generation they were written under. A purge increments
+ * that generation in the configuration; the drainer discards anything older, which closes the race
+ * where a task engine appends a finish just after the purge.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readFile, rename, rm, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acquireSaveLock, SaveLockBusyError } from '../save-lock.js';
+import { isPidAlive } from '../run-records.js';
+import { cancelActiveUploads } from './uploads.js';
+/** At most this many queued events, or ten megabytes, whichever is reached first. */
+export const OUTBOX_EVENT_LIMIT = 5_000;
+export const OUTBOX_BYTE_LIMIT = 10 * 1024 * 1024;
+/** Anything older is discarded on the next drain: the ingest would refuse it anyway. */
+export const OUTBOX_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+export function outboxDirectory(telemetry) { return join(telemetry, 'outbox'); }
+/** Engine ids name files, so they are limited to a filesystem-safe alphabet. */
+export function sanitizeEngineId(engineId) {
+    const safe = engineId.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 96);
+    return safe || 'engine';
+}
+export function spoolPath(telemetry, engineId) {
+    return join(outboxDirectory(telemetry), `${sanitizeEngineId(engineId)}.jsonl`);
+}
+function parse(lines) {
+    const entries = [];
+    for (const line of lines.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (Number.isSafeInteger(value.g) && value.e && typeof value.e === 'object')
+                entries.push(value);
+        }
+        catch { /* a torn final line from a crash is discarded, not fatal */ }
+    }
+    return entries;
+}
+export function serialize(entry) { return JSON.stringify(entry) + '\n'; }
+/** Read one spool; a missing file is an empty spool. */
+export async function readSpool(path) {
+    try {
+        return parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function write(path, entries) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(temporary, entries.map(serialize).join(''), { mode: 0o600 });
+    await rename(temporary, path);
+}
+/**
+ * Evict by whole runs to the limits.
+ *
+ * A completed `run.started` and `run.finished` leave together, so a cap cannot strand a finish
+ * without the start it joins. A run that is still open is left alone: its finish is appended to
+ * this same spool later, so evicting its lone start would leave that finish unmatched, and an
+ * open run is by definition younger than the age bound that removes it instead (that is
+ * `pruneOld`). Session events are independent and evict on their own.
+ */
+export function enforceLimits(entries, now = Date.now()) {
+    const bytes = () => entries.reduce((sum, entry) => sum + serialize(entry).length, 0);
+    if (entries.length <= OUTBOX_EVENT_LIMIT && bytes() <= OUTBOX_BYTE_LIMIT)
+        return entries;
+    const runs = new Map();
+    for (const entry of entries) {
+        const key = entry.run ?? `session:${entry.e.eventId}`;
+        const group = runs.get(key) ?? [];
+        group.push(entry);
+        runs.set(key, group);
+    }
+    const complete = (group) => {
+        const started = group.some(entry => entry.e.event === 'run.started');
+        const finished = group.some(entry => entry.e.event === 'run.finished');
+        // A session event or a completed pair is terminal; half a pair is a run still in flight.
+        return started === finished;
+    };
+    const ordered = [...runs.values()].filter(complete).sort((a, b) => Math.min(...a.map(entry => Date.parse(entry.e.ts))) - Math.min(...b.map(entry => Date.parse(entry.e.ts))));
+    const kept = new Set(runs.values());
+    const over = () => entries.filter(entry => kept.has(runs.get(entry.run ?? `session:${entry.e.eventId}`)));
+    while (ordered.length && (over().length > OUTBOX_EVENT_LIMIT || over().reduce((sum, entry) => sum + serialize(entry).length, 0) > OUTBOX_BYTE_LIMIT)) {
+        kept.delete(ordered.shift());
+    }
+    return over();
+}
+/**
+ * Discard entries the ingest would refuse for age.
+ *
+ * A run leaves whole: an offline run can cross the window between its start and its finish, and
+ * dropping only the older start would upload a finish nothing joins. Session events (`run` is
+ * null) are independent and expire on their own.
+ */
+export function pruneOld(entries, now = Date.now()) {
+    const fresh = (entry) => {
+        const at = Date.parse(entry.e.ts);
+        return Number.isFinite(at) && now - at <= OUTBOX_MAX_AGE_MS;
+    };
+    const expiredRuns = new Set(entries.filter(entry => !fresh(entry) && entry.run !== null).map(entry => entry.run));
+    return entries.filter(entry => entry.run !== null ? !expiredRuns.has(entry.run) : fresh(entry));
+}
+/** Discard entries collected under an older preference generation. */
+export function pruneGeneration(entries, generation) {
+    return entries.filter(entry => entry.g >= generation);
+}
+/**
+ * Queue one event on this engine's spool.
+ *
+ * The append takes the spool's lock because the drainer rewrites the same file: an append that
+ * landed between a drainer's read and its rename would be replaced by the rewrite. The lock is
+ * held for milliseconds here, and the drainer never holds it across a network call, so waiting for
+ * it does not block a run's exit behind an upload.
+ */
+export async function enqueue(telemetry, engineId, entry) {
+    const directory = outboxDirectory(telemetry);
+    await mkdir(directory, { recursive: true });
+    const path = spoolPath(telemetry, engineId);
+    const append = async () => {
+        await appendFile(path, serialize(entry), { mode: 0o600 });
+        const entries = await readSpool(path);
+        const bounded = enforceLimits(entries);
+        if (bounded.length !== entries.length)
+            await write(path, bounded);
+    };
+    // A busy lock belongs to a drain in progress; wait for it rather than drop the event. The lock
+    // is only ever held across a read and a rename, so the wait is short even mid-drain, and a
+    // holder that died is reclaimed by the lock itself.
+    let delay = 25;
+    for (;;) {
+        const name = `${sanitizeEngineId(engineId)}.jsonl`;
+        const done = await withSpoolLock(telemetry, name, async () => { await append(); return true; });
+        if (done) {
+            // The per-file cap is not the installation's bound; abandoned spools from other processes
+            // are swept here so an installation with no endpoint cannot grow without limit.
+            await sweepOutbox(telemetry, name).catch(() => { });
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, delay));
+        delay = Math.min(250, delay * 2);
+    }
+}
+/**
+ * Enforce the installation-wide bound across every spool.
+ *
+ * Each process owns its own spool, so a per-file cap alone cannot bound the outbox: with no
+ * endpoint configured nothing drains, and repeated short-lived runs would leave one small file
+ * each. Aged entries are pruned in place under each spool's lock; if the surviving total is still
+ * over the cap, whole spool files are removed oldest first. A file is a run's entries, so removing
+ * one never strands a finish without its start.
+ */
+export async function sweepOutbox(telemetry, ownName, limits = {}) {
+    const eventLimit = limits.events ?? OUTBOX_EVENT_LIMIT;
+    const byteLimit = limits.bytes ?? OUTBOX_BYTE_LIMIT;
+    const names = await spoolNames(telemetry);
+    const files = [];
+    for (const name of names) {
+        const path = join(outboxDirectory(telemetry), name);
+        const info = await stat(path).catch(() => undefined);
+        if (info === undefined)
+            continue;
+        const pruned = await withSpoolLock(telemetry, name, async () => {
+            const entries = await readSpool(path);
+            const kept = pruneOld(entries);
+            if (kept.length !== entries.length)
+                await rewriteSpool(telemetry, name, kept);
+            return kept;
+        });
+        // A spool that could not be locked is measured as it is on disk; one that was pruned is
+        // measured from what survived, so the byte bound reflects the rewrite rather than the old size.
+        const bytes = pruned === undefined ? info.size : pruned.reduce((sum, entry) => sum + serialize(entry).length, 0);
+        // A locked spool (a drain mid-post) still contributes its on-disk count: treating it as empty
+        // lets a sweep of thousands of small events in locked spools never reach the event cap.
+        const entries = pruned?.length ?? (await readSpool(path).catch(() => [])).length;
+        files.push({ name, entries, bytes, mtime: info.mtimeMs });
+    }
+    let totalEvents = files.reduce((sum, file) => sum + file.entries, 0);
+    let totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
+    if (totalEvents <= eventLimit && totalBytes <= byteLimit)
+        return;
+    // Eviction is by run, not by file: a crash's finish is written by the recovering process into a
+    // newer spool, so removing the older file that holds its start would strand the pair. A run's
+    // entries leave together wherever they live; the process's own spool is left alone.
+    const runs = new Map();
+    for (const name of names) {
+        const path = join(outboxDirectory(telemetry), name);
+        const entries = await withSpoolLock(telemetry, name, async () => readSpool(path)).catch(() => undefined);
+        if (entries === undefined)
+            continue;
+        const kept = new Set(pruneOld(entries).map(entry => entry.e.eventId));
+        const info = files.find(file => file.name === name);
+        for (const entry of entries) {
+            if (!kept.has(entry.e.eventId))
+                continue;
+            const key = entry.e.runId ?? `event:${entry.e.eventId}`;
+            const run = runs.get(key) ?? { events: 0, bytes: 0, mtime: info?.mtime ?? 0, files: new Set(), evictable: name !== ownName, started: false, finished: false };
+            if (entry.e.event === 'run.started')
+                run.started = true;
+            if (entry.e.event === 'run.finished')
+                run.finished = true;
+            run.events += 1;
+            run.bytes += serialize(entry).length;
+            run.files.add(name);
+            // A run that reaches the process's own spool cannot be removed from it, so it stays whole
+            // only by staying entirely.
+            if (name === ownName)
+                run.evictable = false;
+            runs.set(key, run);
+        }
+    }
+    const ordered = [...runs.entries()].filter(([, run]) => run.evictable && evictableRun(run)).sort((a, b) => a[1].mtime - b[1].mtime);
+    const removed = new Set();
+    for (const [key, run] of ordered) {
+        if (totalEvents <= eventLimit && totalBytes <= byteLimit)
+            break;
+        removed.add(key);
+        for (const name of run.files) {
+            const path = join(outboxDirectory(telemetry), name);
+            await withSpoolLock(telemetry, name, async () => {
+                const current = await readSpool(path);
+                const kept = current.filter(entry => !removed.has(entry.e.runId ?? `event:${entry.e.eventId}`));
+                await rewriteSpool(telemetry, name, kept);
+            }).catch(() => { });
+        }
+        // The totals were measured before the rewrite; a concurrent append may put events back, and
+        // the next sweep applies the bound again.
+        totalEvents -= run.events;
+        totalBytes -= run.bytes;
+    }
+}
+/**
+ * Whether a run may leave, judged by whether removing it can strand the other half of its pair.
+ *
+ * A completed pair is always safe to remove. A run that is only half written belongs to an engine
+ * that may still be working: evicting its start while the owning process is alive lets that
+ * process append a finish to a spool the start has left, which is the unmatched pair the whole-run
+ * rule exists to prevent. A standalone event has no pair, and a pid that is gone cannot append.
+ */
+function evictableRun(run) {
+    if (run.started && run.finished)
+        return true;
+    if (!run.started && !run.finished)
+        return true;
+    for (const name of run.files) {
+        if (spoolOwnerAlive(name) === true)
+            return false;
+    }
+    return true;
+}
+/** The pid an engine spool name carries, and whether it is still running. */
+function spoolOwnerAlive(name) {
+    const match = /^[a-z]+-(\d+)-/.exec(name);
+    return match ? isPidAlive(Number(match[1])) : undefined;
+}
+/**
+ * Purge the whole outbox for an opt-out.
+ *
+ * Whole runs leave together because every spool file is removed at once; an engine that appends
+ * after this point writes an entry tagged with the pre-purge generation, and the next drain
+ * discards it. Uploads in flight are cancelled by the caller's abort signal.
+ */
+export async function purgeOutbox(telemetry) {
+    // Stop what this process is already sending: a request in flight would otherwise store a
+    // pre-opt-out event after the preference was saved.
+    cancelActiveUploads();
+    const directory = outboxDirectory(telemetry);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    // Each removal queues behind that spool's in-flight upload, whose last act inside the lock is to
+    // re-check the preference. An event is therefore either sent before this purge or never sent.
+    await Promise.all(names.filter(name => name.endsWith('.jsonl')).map(name => withSpoolLockWait(telemetry, name, async () => {
+        await rm(join(directory, name), { force: true });
+    })));
+}
+/**
+ * Lock one spool for draining.
+ *
+ * Ownership is decided by the lock alone: a recorded pid is not sufficient, because a dead owner's
+ * pid can be reused by an unrelated process, which would leave the spool undrained until it aged
+ * out. The save lock already reclaims a lock whose owner is gone.
+ */
+export async function withSpoolLock(telemetry, name, run) {
+    try {
+        const release = await acquireSaveLock(join(outboxDirectory(telemetry), '.locks', name));
+        try {
+            return await run();
+        }
+        finally {
+            await release();
+        }
+    }
+    catch (error) {
+        if (error instanceof SaveLockBusyError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Take a spool lock, waiting out a holder instead of giving up.
+ *
+ * Used where a lock must be held across work another process's operation has to queue behind: a
+ * purge waits for an in-flight upload, and that upload checks the preference inside the lock, so
+ * an event is either sent before the opt-out finished or not sent at all.
+ */
+export async function withSpoolLockWait(telemetry, name, run) {
+    let delay = 25;
+    for (;;) {
+        // The value is wrapped: `withSpoolLock` answers `undefined` for a busy lock, and a caller's
+        // own `void` result must not be mistaken for it.
+        const held = await withSpoolLock(telemetry, name, async () => ({ value: await run() }));
+        if (held !== undefined)
+            return held.value;
+        await new Promise(resolve => setTimeout(resolve, delay));
+        delay = Math.min(250, delay * 2);
+    }
+}
+/** Every spool name, including this process's own. */
+export async function spoolNames(telemetry) {
+    try {
+        return (await readdir(outboxDirectory(telemetry))).filter(name => name.endsWith('.jsonl'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Replace a spool with the entries that remain after a drain. */
+export async function rewriteSpool(telemetry, name, entries) {
+    const path = join(outboxDirectory(telemetry), name);
+    if (entries.length === 0)
+        await unlink(path).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+    else
+        await write(path, entries);
+}

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

@@ -0,0 +1,184 @@
+/** The only schema version this build emits and accepts. */
+export declare const TELEMETRY_SCHEMA = 1;
+/** The ingest and the client both cap a request body here. */
+export declare const TELEMETRY_BODY_LIMIT: number;
+export declare const TELEMETRY_EVENTS: readonly ["session.started", "run.started", "run.finished"];
+export type TelemetryEventName = typeof TELEMETRY_EVENTS[number];
+export declare const TELEMETRY_SURFACES: readonly ["cli", "desktop", "remote", "subagent"];
+export type TelemetrySurface = typeof TELEMETRY_SURFACES[number];
+export declare const TELEMETRY_PLANS: readonly ["free", "legacy", "paid", "unknown"];
+export type TelemetryPlan = typeof TELEMETRY_PLANS[number];
+export declare const TELEMETRY_OUTCOMES: readonly ["completed", "failed", "cancelled", "needs_clarification", "interrupted"];
+export type TelemetryOutcome = typeof TELEMETRY_OUTCOMES[number];
+export declare const TELEMETRY_FAILURE_CLASSES: readonly ["provider_error", "tool_error", "timeout", "limit", "infrastructure"];
+export type TelemetryFailureClass = typeof TELEMETRY_FAILURE_CLASSES[number];
+export declare const TELEMETRY_PROVIDER_TYPES: readonly ["openai-compatible", "anthropic", "codex", "other"];
+export type TelemetryProviderType = typeof TELEMETRY_PROVIDER_TYPES[number];
+export declare const TELEMETRY_ENDPOINTS: readonly ["hosted", "local", "other"];
+export type TelemetryEndpoint = typeof TELEMETRY_ENDPOINTS[number];
+export declare const TELEMETRY_ROLES: readonly ["agent", "orchestrator", "subagent", "jev", "other"];
+export type TelemetryRole = typeof TELEMETRY_ROLES[number];
+export declare const TELEMETRY_GRAPH_BUCKETS: readonly ["software-engineer", "andorra", "custom"];
+export type TelemetryGraph = typeof TELEMETRY_GRAPH_BUCKETS[number];
+export declare const TELEMETRY_ROUTING: readonly ["off", "shadow", "active"];
+export type TelemetryRouting = typeof TELEMETRY_ROUTING[number];
+export declare const TELEMETRY_TASK_CATEGORIES: readonly ["implement", "fix", "test", "docs", "investigate"];
+export type TelemetryTaskCategory = typeof TELEMETRY_TASK_CATEGORIES[number];
+export declare const TELEMETRY_WORKSPACE_BUCKETS: readonly ["0", "1-9", "10-99", "100-999", "1000-9999", "10000+"];
+export type TelemetryWorkspaceBucket = typeof TELEMETRY_WORKSPACE_BUCKETS[number];
+/** The permission values ordinary runs persist, in the order `PERMISSION_MODES` lists them. */
+export declare const TELEMETRY_PERMISSION_MODES: readonly ["read-only", "ask-for-approval", "approve-for-me", "full-access"];
+export declare const TELEMETRY_OPERATING_SYSTEMS: readonly ["darwin", "win32", "linux", "freebsd", "openbsd", "sunos", "aix", "android", "other"];
+export declare const TELEMETRY_ARCHITECTURES: readonly ["x64", "arm64", "arm", "ia32", "ppc64", "s390x", "riscv64", "loong64", "mips", "mipsel", "ppc", "s390", "other"];
+export declare const TELEMETRY_LANGUAGES: readonly ["typescript", "javascript", "python", "go", "rust", "java", "kotlin", "swift", "csharp", "cpp", "c", "ruby", "php", "scala", "elixir", "dart", "shell", "sql", "html", "css", "other"];
+export type TelemetryLanguage = typeof TELEMETRY_LANGUAGES[number];
+export declare const TELEMETRY_FRAMEWORKS: readonly ["react", "vue", "angular", "svelte", "nextjs", "nestjs", "express", "fastapi", "django", "flask", "spring", "rails", "laravel", "dotnet", "actix", "axum", "gin", "flutter", "electron", "tauri", "other"];
+export type TelemetryFramework = typeof TELEMETRY_FRAMEWORKS[number];
+/** Product-owned tool names, plus the three buckets user- or server-named tools collapse into. */
+export declare const TELEMETRY_TOOL_NAMES: readonly ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "PowerShell", "git_read", "read_artifact", "write_artifact", "repo_explore", "memory_search", "set_timer", "pull_request", "read_skill_resource", "ask_user", "spawn_subagent", "qa.browser", "qa.browser_session", "qa.deep", "qa.fast", "qa.inspect_project", "qa.security", "qa.status", "qa.terminal", "qa.test", "browser.panel", "mcp", "plugin", "other"];
+export type TelemetryToolName = typeof TELEMETRY_TOOL_NAMES[number];
+/**
+ * Public model ids a run may name. Provider configuration accepts a user-supplied string of up to
+ * 500 characters, so a private deployment can put a tenant name in it; only a value that matches
+ * this list is transmitted, and everything else is `other`.
+ */
+export declare const TELEMETRY_MODELS: readonly ["gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-4-turbo", "gpt-4", "o1", "o1-mini", "o3", "o3-mini", "o4-mini", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "claude-opus-4", "claude-sonnet-4", "claude-sonnet-4-6", "claude-3-7-sonnet", "claude-3-5-sonnet", "claude-3-5-haiku", "gemini-2.5-pro", "gemini-2.5-flash", "llama-3.3-70b", "deepseek-chat", "qwen-2.5-coder", "other"];
+/**
+ * The shape a published release version must have to be transmitted.
+ *
+ * A fixed list of released versions was wrong by construction: every release bumps the manifest and
+ * nothing rewrote the list, so every version after `0.1.0` was stored as `other`. A bounded public
+ * SemVer — including the build metadata the release workflow accepts (`1.2.3+linux`) — is still
+ * finite and carries no user data, which is what the unauthenticated ingest needs; anything else (a
+ * private build string, a branch name) stays `other`.
+ */
+export declare const APP_VERSION_PATTERN: RegExp;
+/**
+ * The local price-table versions compiled into this release. No table ships at launch, so the set
+ * is empty and no event carries `pricingVersion`; a release that adds a table adds its version here
+ * and in `infra/andorra-auth/telemetry_schema.py` in the same change.
+ */
+export declare const TELEMETRY_PRICING_VERSIONS: readonly string[];
+export interface TelemetryModelRecord {
+    providerType: TelemetryProviderType;
+    endpoint: TelemetryEndpoint;
+    model: string;
+    role: TelemetryRole;
+    requests: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costMicroUsd?: number;
+    tuples?: number;
+    coverage?: TelemetryCoverage;
+    pricingVersion?: string;
+}
+export interface TelemetryCoverage {
+    inputTokens: 'all' | 'partial' | 'none';
+    outputTokens: 'all' | 'partial' | 'none';
+    cacheReadTokens: 'all' | 'partial' | 'none';
+    cacheWriteTokens: 'all' | 'partial' | 'none';
+    costMicroUsd: 'all' | 'partial' | 'none';
+}
+export interface TelemetryToolRecord {
+    name: TelemetryToolName;
+    calls: number;
+    failures: number;
+}
+export interface TelemetryJevCounters {
+    requested: number;
+    completed: number;
+    applied: number;
+    fallback: number;
+    unavailable: number;
+}
+export interface TelemetryIdentity {
+    schema: number;
+    eventId: string;
+    runId?: string;
+    installId: string;
+    ts: string;
+    appVersion: string;
+    surface: TelemetrySurface;
+    os: string;
+    osMajor: number;
+    arch: string;
+    plan: TelemetryPlan;
+}
+export interface TelemetryEvent extends TelemetryIdentity {
+    event: TelemetryEventName;
+    workspaceFiles?: TelemetryWorkspaceBucket;
+    graph?: TelemetryGraph;
+    nodes?: number;
+    subagents?: boolean;
+    permissionMode?: string;
+    jevEnabled?: boolean;
+    decisionRouting?: TelemetryRouting;
+    outcome?: TelemetryOutcome;
+    failureClass?: TelemetryFailureClass;
+    attempts?: number;
+    retries?: number;
+    durationMs?: number;
+    toolCalls?: number;
+    toolFailures?: number;
+    models?: TelemetryModelRecord[];
+    tools?: TelemetryToolRecord[];
+    jev?: TelemetryJevCounters;
+    languages?: TelemetryLanguage[];
+    frameworks?: TelemetryFramework[];
+    taskCategory?: TelemetryTaskCategory;
+}
+/** Field maxima: far above any real run, low enough that a hostile one cannot dominate a rollup. */
+export declare const TELEMETRY_BOUNDS: {
+    readonly token: 1000000000000;
+    readonly requests: 1000000000000000;
+    readonly costMicroUsd: 1000000000000;
+    readonly durationMs: 1000000000000;
+    readonly counter: 10000000000000;
+    readonly jevCounter: 1000000;
+    readonly nodes: 10000;
+    readonly osMajor: 999;
+};
+/** The ISO-8601 minute-precision form the schema stores; seconds and milliseconds are noise. */
+export declare function telemetryTimestamp(date?: Date): string;
+export declare function telemetryEventId(): string;
+export declare function telemetryRunId(): string;
+/** Map a configured model id onto the public allowlist; anything else is `other`. */
+export declare function bucketModel(model: string | undefined): string;
+/** The provider class, restricted to the three configured types plus `other`. */
+export declare function bucketProviderType(type: string | undefined): TelemetryProviderType;
+/**
+ * Whether a base URL addresses this machine. A placement, not a provider class: a local server is
+ * still an OpenAI-compatible endpoint, it just is not a remote service.
+ */
+export declare function bucketEndpoint(baseUrl: string | undefined): TelemetryEndpoint;
+/** The graph bucket: a shape, never a user-chosen title that may name a client. */
+export declare function bucketGraph(id: string | undefined): TelemetryGraph;
+export declare function bucketOperatingSystem(platform: string | undefined): string;
+export declare function bucketArchitecture(arch: string | undefined): string;
+export declare function bucketAppVersion(value: string | undefined): string;
+/**
+ * Map an executed tool name onto a product-owned name or one of the `mcp`, `plugin`, `other`
+ * buckets. MCP and plugin tool names are user-configured or server-advertised strings, so they are
+ * never sent as themselves.
+ */
+export declare function bucketToolName(name: string): TelemetryToolName | undefined;
+export declare function isMetadataTool(name: string): boolean;
+export declare function isGraphRuntimeTool(name: string): boolean;
+export declare function bucketWorkspaceFiles(count: number): TelemetryWorkspaceBucket;
+/** The canonical order a list of buckets is emitted in, so identical inputs report identically. */
+export declare function rankByTable<T extends string>(values: readonly T[], table: readonly T[]): T[];
+/**
+ * Validate one event and return the sanitized record.
+ *
+ * Unknown keys are dropped, not rejected: that is the server-side rule for version skew, and the
+ * client serializer is the guard that a field the ADR does not list is not sent in the first place.
+ * A known field of the wrong type, outside its enum, or outside its numeric range rejects the whole
+ * event instead of storing it partially.
+ */
+export declare function validateTelemetryEvent(value: unknown): TelemetryEvent;
+/** The serialized form the client posts and the server stores. Field order is stable for tests. */
+export declare function serializeTelemetryEvent(event: TelemetryEvent): string;
+/** Reject a timestamp the ingest would refuse: older than 30 days or more than 5 minutes ahead. */
+export declare function telemetryTimestampFresh(ts: string, now?: number): boolean;