taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/devices/resolve-device-assignments.js

@@ -0,0 +1,60 @@
+function failure(code, message, missingRoles) {
+    return {
+        ok: false,
+        code,
+        message,
+        ...(missingRoles === undefined ? {} : { missingRoles })
+    };
+}
+export function resolveDeviceAssignments(input) {
+    const { declaredRoles, explicit, onlineSerials } = input;
+    const duplicateRole = explicit.find((mapping, index) => explicit.some((other, otherIndex) => otherIndex > index && other.role === mapping.role));
+    if (duplicateRole !== undefined) {
+        return failure("CONFIG_INVALID", `Duplicate --device mapping for role: ${duplicateRole.role}`);
+    }
+    const unknownRole = explicit.find((mapping) => !declaredRoles.includes(mapping.role));
+    if (unknownRole !== undefined) {
+        return failure("CONFIG_INVALID", `Device role is not declared by the journey: ${unknownRole.role}`);
+    }
+    const reusedSerial = explicit.find((mapping, index) => explicit.some((other, otherIndex) => otherIndex > index
+        && other.deviceSerial === mapping.deviceSerial));
+    if (reusedSerial !== undefined) {
+        return failure("CONFIG_INVALID", `Device serial is mapped to multiple roles: ${reusedSerial.deviceSerial}`);
+    }
+    const online = new Set(onlineSerials);
+    const offlineSerial = explicit.find((mapping) => !online.has(mapping.deviceSerial));
+    if (offlineSerial !== undefined) {
+        return failure("DEVICE_UNAVAILABLE", `Requested device is not online: ${offlineSerial.deviceSerial}`);
+    }
+    if (explicit.length === 0) {
+        if (declaredRoles.length > 1) {
+            return failure("DEVICE_ROLE_UNMAPPED", `Journey declares multiple devices; map each role with --device <role>=<serial> for: ${declaredRoles.join(", ")}`, [...declaredRoles]);
+        }
+        if (onlineSerials.length !== 1) {
+            return failure("DEVICE_UNAVAILABLE", `Expected exactly one online device, found ${String(onlineSerials.length)}`);
+        }
+        const autoSerial = onlineSerials[0];
+        const autoRole = declaredRoles[0];
+        if (autoSerial === undefined || autoRole === undefined) {
+            return failure("DEVICE_UNAVAILABLE", "Expected exactly one online device, found 1");
+        }
+        return {
+            ok: true,
+            assignments: [{ role: autoRole, deviceSerial: autoSerial }]
+        };
+    }
+    const explicitRoles = new Set(explicit.map((mapping) => mapping.role));
+    const missingRoles = declaredRoles.filter((role) => !explicitRoles.has(role));
+    if (missingRoles.length > 0) {
+        return failure("DEVICE_ROLE_UNMAPPED", `No device mapping for journey role(s): ${missingRoles.join(", ")}`, missingRoles);
+    }
+    return {
+        ok: true,
+        assignments: declaredRoles.flatMap((role) => {
+            const mapping = explicit.find((entry) => entry.role === role);
+            return mapping === undefined
+                ? []
+                : [{ role, deviceSerial: mapping.deviceSerial }];
+        })
+    };
+}

package/dist/application/diagnosis/failure-classifier.d.ts

@@ -0,0 +1,23 @@
+import { type FailureClassification } from "../../domain/failure-classification.js";
+import type { TapHoundReport } from "../../domain/report.js";
+export interface FailureClassifierInput {
+    report: TapHoundReport;
+    classificationId?: string | undefined;
+}
+export interface FailureClassifierDependencies {
+    now: () => Date;
+}
+/**
+ * Deterministic Failure Classifier (architecture doc §20, P1.5).
+ *
+ * Maps a completed run report into a concise, structured failure contract for
+ * a Coding Agent: type, likely stage, expected vs actual, step index, locator,
+ * and evidence refs. No model call, no log dump; raw evidence stays on disk
+ * and is referenced by path. Classification is pure derivation from the
+ * published report.
+ */
+export declare class FailureClassifier {
+    private readonly dependencies;
+    constructor(dependencies: FailureClassifierDependencies);
+    readonly classify: (input: FailureClassifierInput) => FailureClassification;
+}

package/dist/application/diagnosis/failure-classifier.js

@@ -0,0 +1,179 @@
+import { FAILURE_CODE_TYPES, FAILURE_TYPE_STAGES, FailureClassificationSchema } from "../../domain/failure-classification.js";
+function expectedActualFor(type, report) {
+    const primary = report.primaryFailure;
+    if (primary === undefined) {
+        return {};
+    }
+    if (type === "activity_mismatch") {
+        const step = report.steps.find((candidate) => (candidate.status === "failed"));
+        const check = step?.activity?.after.status === "failed"
+            ? step.activity.after
+            : step?.activity?.before.status === "failed"
+                ? step.activity.before
+                : undefined;
+        if (check !== undefined) {
+            return {
+                expected: check.expected,
+                actual: check.actual ?? "missing"
+            };
+        }
+    }
+    if (type === "expect_failed") {
+        const step = report.steps.find((candidate) => (candidate.expectation?.status === "failed"));
+        const expectation = step?.expectation;
+        if (expectation !== undefined) {
+            return {
+                expected: expectation.type,
+                actual: expectation.message ?? "missing"
+            };
+        }
+    }
+    if (type === "target_not_found"
+        || type === "target_ambiguous"
+        || type === "target_unresolved") {
+        const step = report.steps.find((candidate) => (candidate.status === "failed"));
+        const locator = step?.locator;
+        if (locator !== undefined) {
+            const source = locator.anchorId ?? locator.message ?? locator.matchedBy;
+            if (source === undefined) {
+                return {};
+            }
+            return {
+                expected: locator.status === "found"
+                    ? `found ${source}`
+                    : source,
+                actual: locator.status === "failed"
+                    ? "not found in layout"
+                    : locator.status
+            };
+        }
+    }
+    if (type === "app_crash") {
+        return {
+            expected: "process alive",
+            actual: "process exited"
+        };
+    }
+    if (type === "contract_invalid" || type === "evidence_failed") {
+        return {
+            expected: "binding satisfied",
+            actual: primary.message
+        };
+    }
+    return {};
+}
+function evidenceRefsFor(report) {
+    const refs = [];
+    for (const screenshot of report.artifacts.screenshots) {
+        refs.push(screenshot.path);
+    }
+    for (const logcat of report.artifacts.logcats) {
+        refs.push(logcat.path);
+    }
+    for (const stepLog of report.artifacts.stepLogs) {
+        refs.push(stepLog);
+    }
+    const failedStepLog = report.steps.find((step) => (step.status === "failed" && step.logcatPath !== undefined));
+    if (failedStepLog?.logcatPath !== undefined) {
+        refs.push(failedStepLog.logcatPath);
+    }
+    return refs;
+}
+function requestOutcomeFor(report) {
+    const failedIndex = report.primaryFailure?.stepIndex;
+    const events = report.steps.filter((step) => (step.expectation?.type === "logcatEvent"
+        && step.expectation.status === "passed"
+        && step.expectation.logcatEvent?.matchedCount === 1
+        && step.expectation.logcatEvent.matchedLineSha256 !== undefined
+        && (failedIndex === undefined || step.index <= failedIndex)));
+    if (events.length === 0) {
+        return { errorClass: "unknown", evidenceRefs: [] };
+    }
+    const classes = new Set(events.map((step) => step.expectation?.logcatEvent?.requestErrorClass));
+    const errorClass = classes.size === 1
+        ? [...classes][0] ?? "unknown"
+        : "unknown";
+    const refs = new Set([report.artifacts.report]);
+    for (const step of events) {
+        if (step.logcatPath !== undefined)
+            refs.add(step.logcatPath);
+    }
+    return { errorClass, evidenceRefs: [...refs] };
+}
+function locatorFor(type, report) {
+    if (type !== "target_not_found"
+        && type !== "target_ambiguous"
+        && type !== "target_unresolved") {
+        return undefined;
+    }
+    const locator = report.steps.find((step) => step.status === "failed")?.locator;
+    if (locator === undefined) {
+        return undefined;
+    }
+    // Rebuild a canonical Locator from a report locator: report locators carry
+    // runtime status fields the domain Locator does not accept.
+    if (locator.anchorId !== undefined) {
+        return { resourceId: `anchor:${locator.anchorId}` };
+    }
+    if (locator.matchedBy === "resourceId") {
+        return { resourceId: locator.message ?? "resourceId" };
+    }
+    if (locator.matchedBy === "text") {
+        return { text: locator.message ?? "text" };
+    }
+    if (locator.matchedBy === "contentDescription") {
+        return { contentDescription: locator.message ?? "contentDescription" };
+    }
+    return { resourceId: "unknown" };
+}
+/**
+ * Deterministic Failure Classifier (architecture doc §20, P1.5).
+ *
+ * Maps a completed run report into a concise, structured failure contract for
+ * a Coding Agent: type, likely stage, expected vs actual, step index, locator,
+ * and evidence refs. No model call, no log dump; raw evidence stays on disk
+ * and is referenced by path. Classification is pure derivation from the
+ * published report.
+ */
+export class FailureClassifier {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    classify = (input) => {
+        const { report } = input;
+        const primary = report.primaryFailure;
+        if (primary === undefined) {
+            throw new Error(`Cannot classify run ${report.runId}: the report has no primary failure`);
+        }
+        const type = FAILURE_CODE_TYPES[primary.code] ?? "internal_error";
+        const stage = FAILURE_TYPE_STAGES[type];
+        const expectedActual = expectedActualFor(type, report);
+        const locator = locatorFor(type, report);
+        const classificationId = input.classificationId
+            ?? `${report.runId}:${primary.code}:${String(primary.stepIndex ?? "-")}`;
+        const classification = FailureClassificationSchema.parse({
+            version: 1,
+            runId: report.runId,
+            classificationId,
+            type,
+            stage,
+            code: primary.code,
+            message: primary.message,
+            ...(primary.stepIndex === undefined
+                ? {}
+                : { stepIndex: primary.stepIndex }),
+            ...(expectedActual.expected === undefined
+                ? {}
+                : { expected: expectedActual.expected }),
+            ...(expectedActual.actual === undefined
+                ? {}
+                : { actual: expectedActual.actual }),
+            ...(locator === undefined ? {} : { locator }),
+            evidenceRefs: evidenceRefsFor(report),
+            requestOutcome: requestOutcomeFor(report),
+            sourceReportPath: report.artifacts.report
+        });
+        return classification;
+    };
+}

package/dist/application/diagnostics/diagnostics-exporter.d.ts

@@ -0,0 +1,29 @@
+import { type DiagnosticsBundle } from "../../domain/diagnostics.js";
+import type { DiagnosticsJournal } from "../../ports/diagnostics.js";
+export interface DiagnosticsExporterDependencies {
+    journal: DiagnosticsJournal;
+    readJson: (path: string) => Promise<unknown>;
+    now: () => Date;
+    taphoundVersion: string;
+    host: DiagnosticsBundle["host"];
+}
+export interface DiagnosticsExportInput {
+    projectRoot: string;
+    /** Most recent journal events to include. */
+    eventLimit: number;
+    /** Most recent referenced runs to summarize. */
+    runLimit: number;
+}
+/**
+ * Builds a feedback bundle from the local journal and the reports it
+ * references. Only allowlisted structural facts survive: identifying strings
+ * become ordinal aliases or salted digests, and everything else is dropped.
+ * The result is validated against the strict bundle schema before return.
+ */
+export declare class DiagnosticsExporter {
+    private readonly dependencies;
+    constructor(dependencies: DiagnosticsExporterDependencies);
+    export(input: DiagnosticsExportInput): Promise<DiagnosticsBundle>;
+    private readConfig;
+    private readReport;
+}

package/dist/application/diagnostics/diagnostics-exporter.js

@@ -0,0 +1,283 @@
+import { createHmac } from "node:crypto";
+import { join, resolve } from "node:path";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { CommandEventSchema, DiagnosticsBundleSchema } from "../../domain/diagnostics.js";
+import { TapHoundReportSchema } from "../../domain/report.js";
+import { CONFIG_PATH, DEFAULT_ARTIFACTS_DIR } from "../../domain/workspace.js";
+const TOKEN = /^[a-zA-Z][a-zA-Z\d]{0,31}$/;
+const VERSION = /^[\w.+-]{1,64}$/;
+const TOOL_NAMES = ["node", "adb", "android"];
+const LOCATOR_FIELDS = ["resourceId", "text", "contentDescription", "index", "within"];
+/** Stable ordinal names for identifying strings, shared across one bundle. */
+class Aliases {
+    prefix;
+    values = new Map();
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    of(value) {
+        let alias = this.values.get(value);
+        if (alias === undefined) {
+            alias = `${this.prefix}#${String(this.values.size + 1)}`;
+            this.values.set(value, alias);
+        }
+        return alias;
+    }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonical(entry)]));
+    }
+    return value;
+}
+function parseEvents(lines) {
+    const events = [];
+    let skipped = 0;
+    for (const line of lines) {
+        try {
+            const parsed = CommandEventSchema.safeParse(JSON.parse(line));
+            if (parsed.success) {
+                events.push(parsed.data);
+                continue;
+            }
+        }
+        catch {
+            // A torn or foreign line is counted, never exported.
+        }
+        skipped += 1;
+    }
+    return { events, skipped };
+}
+function configSummary(config) {
+    return {
+        idle: {
+            strategy: config.idle.strategy,
+            pollIntervalMs: config.idle.pollIntervalMs,
+            stablePolls: config.idle.stablePolls,
+            timeoutMs: config.idle.timeoutMs,
+            ...(config.idle.ignoreCursorBlink === undefined
+                ? {}
+                : { ignoreCursorBlink: config.idle.ignoreCursorBlink }),
+            ...(config.idle.ignoreLayoutDrift === undefined
+                ? {}
+                : { ignoreLayoutDrift: config.idle.ignoreLayoutDrift }),
+            deviceProfiles: config.idle.deviceProfiles?.length ?? 0
+        },
+        ...(config.ui === undefined
+            ? {}
+            : {
+                ui: {
+                    backend: config.ui.backend,
+                    ...(config.ui.snapshotTimeoutMs === undefined
+                        ? {}
+                        : { snapshotTimeoutMs: config.ui.snapshotTimeoutMs }),
+                    ...(config.ui.cacheEnabled === undefined
+                        ? {}
+                        : { cacheEnabled: config.ui.cacheEnabled })
+                }
+            }),
+        ...(config.runtime === undefined ? {} : { runtime: { backend: config.runtime.backend } })
+    };
+}
+/**
+ * Builds a feedback bundle from the local journal and the reports it
+ * references. Only allowlisted structural facts survive: identifying strings
+ * become ordinal aliases or salted digests, and everything else is dropped.
+ * The result is validated against the strict bundle schema before return.
+ */
+export class DiagnosticsExporter {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async export(input) {
+        const { events: allEvents, skipped } = parseEvents(await this.dependencies.journal.readLines(input.projectRoot));
+        const events = allEvents.slice(-Math.max(0, input.eventLimit));
+        const config = await this.readConfig(input.projectRoot);
+        const salt = await this.dependencies.journal.salt(input.projectRoot);
+        const runs = new Aliases("run");
+        const activities = new Aliases("activity");
+        const journeys = new Aliases("journey");
+        const devices = new Aliases("device");
+        const locatorId = (locator) => createHmac("sha256", salt)
+            .update(JSON.stringify(canonical(locator)))
+            .digest("hex")
+            .slice(0, 16);
+        const runIds = [...new Set(events.flatMap((event) => (event.runId === undefined ? [] : [event.runId])))];
+        // Aliases follow journal order, whichever runs end up summarized.
+        for (const runId of runIds)
+            runs.of(runId);
+        const artifactsDir = resolve(input.projectRoot, config?.artifactsDir ?? DEFAULT_ARTIFACTS_DIR);
+        const summaries = [];
+        for (const runId of runIds.slice(-Math.max(0, input.runLimit))) {
+            const report = await this.readReport(join(artifactsDir, runId, "report.json"));
+            if (report === undefined)
+                continue;
+            summaries.push(summarizeRun(report, runs.of(runId), {
+                activity: (value) => activities.of(value),
+                journey: (value) => journeys.of(value),
+                device: (value) => devices.of(value),
+                locatorId
+            }));
+        }
+        return DiagnosticsBundleSchema.parse({
+            version: 1,
+            generatedAt: this.dependencies.now().toISOString(),
+            taphoundVersion: this.dependencies.taphoundVersion,
+            host: this.dependencies.host,
+            ...(config === undefined ? {} : { config: configSummary(config) }),
+            journal: {
+                events: events.map((event) => ({
+                    ...event,
+                    ...(event.runId === undefined ? {} : { runId: runs.of(event.runId) })
+                })),
+                skippedLines: skipped
+            },
+            runs: summaries
+        });
+    }
+    async readConfig(projectRoot) {
+        try {
+            const parsed = TapHoundConfigSchema.safeParse(await this.dependencies.readJson(join(projectRoot, CONFIG_PATH)));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async readReport(path) {
+        try {
+            const parsed = TapHoundReportSchema.safeParse(await this.dependencies.readJson(path));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function summarizeStep(step, redact) {
+    const locator = step.locator;
+    const requested = locator?.requested;
+    return {
+        index: step.index,
+        action: step.action,
+        status: step.status,
+        ...(step.device === undefined ? {} : { device: redact.device(step.device) }),
+        durationMs: step.durationMs,
+        ...(locator === undefined
+            ? {}
+            : {
+                locator: {
+                    status: locator.status,
+                    ...(locator.matchedBy === undefined ? {} : { matchedBy: locator.matchedBy }),
+                    requestedFields: requested === undefined
+                        ? []
+                        : LOCATOR_FIELDS.filter((field) => requested[field] !== undefined),
+                    ...(requested === undefined ? {} : { locatorId: redact.locatorId(requested) }),
+                    ...(locator.anchor === undefined ? {} : { anchorStatus: locator.anchor.status }),
+                    fallbackUsed: locator.fallbackUsed
+                }
+            }),
+        ...(step.idle === undefined
+            ? {}
+            : {
+                idle: {
+                    status: step.idle.status,
+                    polls: step.idle.polls,
+                    ...(step.idle.durationMs === undefined ? {} : { durationMs: step.idle.durationMs }),
+                    ...(step.idle.samplingDurationMs === undefined
+                        ? {}
+                        : { samplingDurationMs: step.idle.samplingDurationMs }),
+                    ...(step.idle.strategy === undefined ? {} : { strategy: step.idle.strategy }),
+                    ...(step.idle.backend === undefined ? {} : { backend: step.idle.backend }),
+                    ...(step.idle.fallbackUsed === undefined
+                        ? {}
+                        : { fallbackUsed: step.idle.fallbackUsed }),
+                    ...(step.idle.frameActivityDetected === undefined
+                        ? {}
+                        : { frameActivityDetected: step.idle.frameActivityDetected }),
+                    ...(step.idle.lastDiff === undefined
+                        ? {}
+                        : { lastDiffCount: step.idle.lastDiff.length })
+                }
+            }),
+        ...(step.activity === undefined
+            ? {}
+            : {
+                activity: {
+                    before: activityCheck(step.activity.before, redact),
+                    after: activityCheck(step.activity.after, redact)
+                }
+            }),
+        ...(step.expectation === undefined
+            ? {}
+            : {
+                expectation: {
+                    type: step.expectation.type,
+                    status: step.expectation.status,
+                    ...(step.expectation.code === undefined ? {} : { code: step.expectation.code })
+                }
+            }),
+        ...(step.scroll === undefined ? {} : { scroll: { ...step.scroll } })
+    };
+}
+function activityCheck(check, redact) {
+    return {
+        status: check.status,
+        expected: redact.activity(check.expected),
+        ...(check.actual === undefined ? {} : { actual: redact.activity(check.actual) })
+    };
+}
+function summarizeRun(report, run, redact) {
+    const failure = report.primaryFailure;
+    return {
+        run,
+        status: report.status,
+        durationMs: report.durationMs,
+        journey: redact.journey(report.journey.name),
+        devices: report.environment.devices.map((device) => ({
+            device: redact.device(device.role),
+            ...(device.uiBackend === undefined
+                ? {}
+                : {
+                    uiBackend: {
+                        id: device.uiBackend.id,
+                        adapterVersion: VERSION.test(device.uiBackend.adapterVersion)
+                            ? device.uiBackend.adapterVersion
+                            : "unknown",
+                        ...(device.uiBackend.engineVersion !== undefined
+                            && VERSION.test(device.uiBackend.engineVersion)
+                            ? { engineVersion: device.uiBackend.engineVersion }
+                            : {})
+                    }
+                }),
+            ...(device.uiCache === undefined ? {} : { uiCache: { ...device.uiCache } })
+        })),
+        tools: Object.fromEntries(TOOL_NAMES.flatMap((name) => {
+            const version = report.environment.tools[name];
+            return version !== undefined && VERSION.test(version) ? [[name, version]] : [];
+        })),
+        layers: { ...report.layers },
+        ...(failure === undefined
+            ? {}
+            : {
+                primaryFailure: {
+                    code: failure.code,
+                    phase: TOKEN.test(failure.phase) ? failure.phase : "other",
+                    ...(failure.stepIndex === undefined ? {} : { stepIndex: failure.stepIndex })
+                }
+            }),
+        secondaryErrorCodes: report.secondaryErrors.map((error) => error.code),
+        fallbackUsed: report.fallbackUsed,
+        logcatEvidence: (report.logcatEvidence ?? []).map((entry) => ({
+            device: redact.device(entry.role),
+            droppedLines: entry.droppedLines,
+            droppedBytes: entry.droppedBytes
+        })),
+        steps: report.steps.map((step) => summarizeStep(step, redact))
+    };
+}

package/dist/application/diagnostics/ui-capture-telemetry.d.ts

@@ -0,0 +1,16 @@
+import { type UiBackendTelemetry, type UiCaptureFailureKind } from "../../domain/diagnostics.js";
+import type { UiBackendId } from "../../domain/ui-backend.js";
+import type { UiCaptureObserver } from "../../ports/diagnostics.js";
+/**
+ * Classifies a capture failure from its type and status only, walking the
+ * cause chain. The message is read solely to spot a timeout and is never kept.
+ */
+export declare function classifyCaptureFailure(error: unknown): UiCaptureFailureKind;
+/** Aggregates UI backend captures for one CLI invocation. */
+export declare class UiCaptureTelemetry implements UiCaptureObserver {
+    private readonly backends;
+    captured(backend: UiBackendId, durationMs: number, error?: unknown): void;
+    sessionRecovered(backend: UiBackendId, succeeded: boolean): void;
+    summary(): UiBackendTelemetry[];
+    private entry;
+}

package/dist/application/diagnostics/ui-capture-telemetry.js

@@ -0,0 +1,81 @@
+import { UI_CAPTURE_LATENCY_BUCKETS_MS } from "../../domain/diagnostics.js";
+/**
+ * Classifies a capture failure from its type and status only, walking the
+ * cause chain. The message is read solely to spot a timeout and is never kept.
+ */
+export function classifyCaptureFailure(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && current !== null && typeof current === "object"; depth += 1) {
+        const record = current;
+        if (record.name === "TimeoutError")
+            return "timeout";
+        if (record.name === "AbortError")
+            return "cancelled";
+        if (typeof record.status === "number") {
+            if (record.status >= 500)
+                return "http5xx";
+            if (record.status >= 400)
+                return "http4xx";
+        }
+        if (typeof record.message === "string" && /timed? ?out/i.test(record.message)) {
+            return "timeout";
+        }
+        current = record.cause;
+    }
+    return "error";
+}
+function emptyTelemetry(backend) {
+    return {
+        backend,
+        captures: 0,
+        failures: { timeout: 0, cancelled: 0, http4xx: 0, http5xx: 0, error: 0 },
+        totalMs: 0,
+        maxMs: 0,
+        latencyBuckets: new Array(UI_CAPTURE_LATENCY_BUCKETS_MS.length + 1).fill(0),
+        sessionRecoveries: 0,
+        sessionRecoveryFailures: 0
+    };
+}
+/** Aggregates UI backend captures for one CLI invocation. */
+export class UiCaptureTelemetry {
+    backends = new Map();
+    captured(backend, durationMs, error) {
+        const entry = this.entry(backend);
+        const duration = Math.max(0, durationMs);
+        entry.captures += 1;
+        entry.totalMs += duration;
+        entry.maxMs = Math.max(entry.maxMs, duration);
+        const bucket = UI_CAPTURE_LATENCY_BUCKETS_MS.findIndex((limit) => duration < limit);
+        const index = bucket === -1 ? UI_CAPTURE_LATENCY_BUCKETS_MS.length : bucket;
+        entry.latencyBuckets[index] = (entry.latencyBuckets[index] ?? 0) + 1;
+        if (error !== undefined) {
+            entry.failures[classifyCaptureFailure(error)] += 1;
+        }
+    }
+    sessionRecovered(backend, succeeded) {
+        const entry = this.entry(backend);
+        if (succeeded) {
+            entry.sessionRecoveries += 1;
+        }
+        else {
+            entry.sessionRecoveryFailures += 1;
+        }
+    }
+    summary() {
+        return [...this.backends.values()].map((entry) => ({
+            ...entry,
+            totalMs: Math.round(entry.totalMs),
+            maxMs: Math.round(entry.maxMs),
+            failures: { ...entry.failures },
+            latencyBuckets: [...entry.latencyBuckets]
+        }));
+    }
+    entry(backend) {
+        let entry = this.backends.get(backend);
+        if (entry === undefined) {
+            entry = emptyTelemetry(backend);
+            this.backends.set(backend, entry);
+        }
+        return entry;
+    }
+}