@bli-cockpit/cli 0.2.56 → 0.2.58

package/dist/upload-session-reports.js

@@ -8,430 +8,19 @@
  *
  * Table of contents:
  *
- * - `queueCodexSessionReport` — write the rows down first. A report survives its
- *   source file, so an endpoint outage cannot age the evidence out.
- * - `flushPendingCodexSessionReports` — drain that queue with current
- *   credentials; each report is deleted only against a receipt we can read.
- * - `postCodexSessionReport` — the one-shot path, for a harvest that already has
- *   a repo in hand.
- * - `reportCodexSessionAttributions` / `postCodexSessionAttributionChunk` — the
- *   wire: chunk at the endpoint's session cap, then attempt each chunk under a
- *   decision table of "final answer" versus "worth another attempt".
+ * - `upload-session-reports-queue.ts` — `queueCodexSessionReport` writes the
+ *   rows down first, so a report survives its source file and an endpoint
+ *   outage cannot age the evidence out; `flushPendingCodexSessionReports`
+ *   drains that queue with current credentials, deleting each report only
+ *   against a receipt it can read.
+ * - `upload-session-reports-wire.ts` — `postCodexSessionReport`, the one-shot
+ *   path for a harvest that already has a repo in hand, and
+ *   `reportCodexSessionAttributions`, the wire itself: chunk at the endpoint's
+ *   session cap, then attempt each chunk under a decision table of "final
+ *   answer" versus "worth another attempt".
  *
- * Nothing here throws at the caller. Every failure comes back as a reason label
- * so a dashboard that is old, down or unreachable cannot fail a harvest.
+ * Nothing here throws at the caller. Every failure comes back as a reason
+ * label so a dashboard that is old, down or unreachable cannot fail a harvest.
  */
-import { CODEX_SESSION_REPORT_MAX_SESSIONS, CodexSessionAttributionReportResponseSchema, } from "@bli-cockpit/telemetry-core";
-import path from "node:path";
-import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.js";
-import { readLocalUploadSpoolState, recordPendingSessionReport, recordSessionReportFailure, recordSessionReportSuccess, } from "./spool/local-spool.js";
-import { makeCollectorProvenance, makeUploadWorkContext, safeRepoLabel, } from "./upload-envelope.js";
-import { normalizeDashboardUrl, readResponseJson } from "./upload-http.js";
-import { describeError } from "./health-detail.js";
-/** Attempts per chunk, and the linear 250ms-per-attempt backoff between them. */
-const DEFAULT_REPORT_ATTEMPTS = 3;
-const REPORT_RETRY_BACKOFF_STEP_MS = 250;
-/**
- * Posts a Codex session attribution report using the paired collector
- * credentials and the work context of a representative repo. Failures come
- * back as reason labels so the harvest never hard-fails on reporting.
- */
-export async function postCodexSessionReport(options) {
-    if (options.sessions.length === 0) {
-        return emptyCodexSessionReportResult("no_sessions_observed");
-    }
-    const fetchImpl = options.fetch ?? globalThis.fetch;
-    if (!fetchImpl) {
-        throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
-    }
-    try {
-        const paths = getCollectorRuntimePaths(options.homeDir);
-        const config = await readLocalCollectorConfig(paths);
-        const sessionFile = await readLocalCollectorSessionFile(paths);
-        const session = await readLocalSessionReference(paths);
-        if (session.session_state !== "valid") {
-            return emptyCodexSessionReportResult("collector_not_paired");
-        }
-        const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
-        const activeContext = await readLocalWorkContextForRepo(paths, repoRoot);
-        const repoLabel = safeRepoLabel(activeContext.repo_label ?? repoRoot);
-        const provenance = makeCollectorProvenance({
-            context: makeUploadWorkContext({
-                activeContext,
-                session,
-                repoLabel,
-                now: options.now ?? new Date(),
-            }),
-            session,
-            repoLabel,
-        });
-        return await reportCodexSessionAttributions({
-            fetchImpl,
-            dashboardUrl: normalizeDashboardUrl(options.dashboardUrl ?? sessionFile.dashboard_url ?? config.dashboard_url),
-            deviceToken: sessionFile.device_token,
-            provenance,
-            generatedAt: (options.now ?? new Date()).toISOString(),
-            sessions: options.sessions,
-        });
-    }
-    catch (error) {
-        // `collector_not_ready` covers this whole block — config read, session
-        // read, work-context read AND the report request itself. The label is
-        // kept (it is what the receipt contract carries) but it is broader than
-        // its name suggests: a network failure inside `reportCodexSessionAttributions`
-        // also lands here and reads as "this machine is not set up". The detail is
-        // now the only way to tell those apart. Flagged, not reclassified —
-        // narrowing the label is a contract change (BLI-3238).
-        console.error("[session-reports] could not report session attributions", JSON.stringify({
-            reason: "collector_not_ready",
-            session_count: options.sessions.length,
-            ...describeError(error),
-        }));
-        return emptyCodexSessionReportResult("collector_not_ready");
-    }
-}
-/**
- * Queues the safe session-attribution rows before the network request. The
- * queue is merged per work context, so an endpoint outage retains every
- * observed session without growing one duplicate report per scheduler pass.
- */
-export async function queueCodexSessionReport(options) {
-    if (options.sessions.length === 0)
-        return null;
-    const paths = getCollectorRuntimePaths(options.homeDir);
-    return await recordPendingSessionReport(paths, {
-        attempted_at: options.generatedAt,
-        dashboard_url: normalizeDashboardUrl(options.dashboardUrl),
-        generated_at: options.generatedAt,
-        work_context_id: options.workContextId,
-        repo_label: safeRepoLabel(options.repoLabel),
-        branch: options.branch,
-        repo_fingerprint: options.repoFingerprint,
-        repo_origin_url: options.repoOriginUrl,
-        worktree_label: options.worktreeLabel,
-        worktree_fingerprint: options.worktreeFingerprint,
-        worktree_is_primary: options.worktreeIsPrimary,
-        sessions: options.sessions,
-    });
-}
-/**
- * Flushes every durable session-attribution report using current credentials.
- * Report payloads do not depend on the source files still being inside the live
- * scan window, so a transient endpoint failure cannot silently age them out.
- */
-export async function flushPendingCodexSessionReports(options) {
-    const paths = getCollectorRuntimePaths(options.homeDir);
-    const state = await readLocalUploadSpoolState(paths);
-    if (state.pending_session_reports.length === 0) {
-        return emptyCodexSessionReportResult("no_pending_session_reports");
-    }
-    const attemptedAt = (options.now ?? new Date()).toISOString();
-    const fetchImpl = options.fetch ?? globalThis.fetch;
-    if (!fetchImpl) {
-        throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
-    }
-    let sessionFile;
-    let session;
-    try {
-        [sessionFile, session] = await Promise.all([
-            readLocalCollectorSessionFile(paths),
-            readLocalSessionReference(paths),
-        ]);
-    }
-    catch (error) {
-        // This marks every queued report as failed. The count is what makes it
-        // worth a line: an unreadable session file here strands N reports at once
-        // and the only visible trace is a spool that stops draining (BLI-3238).
-        console.error("[session-reports] session file unreadable, failing the pending reports", JSON.stringify({
-            reason: "collector_not_ready",
-            pending_report_count: state.pending_session_reports.length,
-            ...describeError(error),
-        }));
-        return await failPendingSessionReports(paths, state.pending_session_reports, attemptedAt, "collector_not_ready");
-    }
-    if (session.session_state !== "valid") {
-        return await failPendingSessionReports(paths, state.pending_session_reports, attemptedAt, "collector_not_paired");
-    }
-    const results = [];
-    for (const pending of state.pending_session_reports) {
-        const result = await reportCodexSessionAttributions({
-            fetchImpl,
-            dashboardUrl: normalizeDashboardUrl(pending.dashboard_url || sessionFile.dashboard_url),
-            deviceToken: sessionFile.device_token,
-            provenance: provenanceForPendingReport(pending, session),
-            generatedAt: pending.generated_at,
-            sessions: pending.sessions,
-            maxAttemptsPerRequest: options.maxAttemptsPerRequest,
-            sleep: options.sleep,
-        });
-        results.push(result);
-        if (result.posted) {
-            await recordSessionReportSuccess(paths, {
-                reportId: pending.report_id,
-                attemptedAt,
-            });
-        }
-        else {
-            await recordSessionReportFailure(paths, {
-                reportId: pending.report_id,
-                attemptedAt,
-                reason: result.reason,
-            });
-        }
-    }
-    return combineCodexSessionReportResults(results);
-}
-/**
- * A queued report carries its own repo and worktree identity, captured when the
- * sessions were observed. Only the operator and device session come from the
- * credentials in use now — the report may be days old and from another branch.
- */
-function provenanceForPendingReport(pending, session) {
-    return {
-        capture_source: "collector_runtime",
-        capture_adapter_version: LOCAL_COLLECTOR_VERSION,
-        collector_version: LOCAL_COLLECTOR_VERSION,
-        repo: pending.repo_label,
-        branch: pending.branch,
-        repo_label: pending.repo_label,
-        repo_fingerprint: pending.repo_fingerprint,
-        ...(pending.repo_origin_url
-            ? { repo_origin_url: pending.repo_origin_url }
-            : {}),
-        worktree_label: pending.worktree_label,
-        worktree_fingerprint: pending.worktree_fingerprint,
-        worktree_is_primary: pending.worktree_is_primary,
-        operator_id: session.operator_id,
-        session_id: session.session_id,
-        work_context_id: pending.work_context_id,
-    };
-}
-async function failPendingSessionReports(paths, pendingReports, attemptedAt, reason) {
-    for (const pending of pendingReports) {
-        await recordSessionReportFailure(paths, {
-            reportId: pending.report_id,
-            attemptedAt,
-            reason,
-        });
-    }
-    return {
-        posted: false,
-        reason,
-        chunk_count: 0,
-        recorded_count: 0,
-        failed_count: pendingReports.length,
-        chunks: [],
-    };
-}
-function combineCodexSessionReportResults(results) {
-    if (results.length === 0) {
-        return emptyCodexSessionReportResult("no_pending_session_reports");
-    }
-    const failed = results.filter((result) => !result.posted);
-    return {
-        posted: failed.length === 0,
-        reason: failed[0]?.reason ??
-            (results.every((result) => result.reason === "recorded")
-                ? "recorded"
-                : results[0]?.reason ?? "recorded"),
-        chunk_count: results.reduce((total, result) => total + result.chunk_count, 0),
-        recorded_count: results.reduce((total, result) => total + result.recorded_count, 0),
-        failed_count: results.reduce((total, result) => total + result.failed_count, 0),
-        chunks: results.flatMap((result) => result.chunks),
-    };
-}
-/**
- * Reports Codex session attribution outcomes after sync. Non-fatal by design:
- * older dashboards without the endpoint must not fail the harvest, so the
- * caller receives a posted/skipped label instead of an exception.
- */
-export async function reportCodexSessionAttributions(options) {
-    if (options.sessions.length === 0) {
-        return emptyCodexSessionReportResult("no_sessions_observed");
-    }
-    const chunks = [];
-    const sessionChunks = chunkArray(options.sessions, CODEX_SESSION_REPORT_MAX_SESSIONS);
-    for (const [index, sessions] of sessionChunks.entries()) {
-        const chunk = await postCodexSessionAttributionChunk({
-            ...options,
-            sessions,
-            batchIndex: index + 1,
-        });
-        chunks.push(chunk);
-    }
-    const failedCount = chunks.filter((chunk) => !chunk.posted).length;
-    const recordedCount = chunks.reduce((sum, chunk) => sum + chunk.recorded_count, 0);
-    return {
-        posted: failedCount === 0,
-        reason: failedCount === 0
-            ? "recorded"
-            : chunks.find((chunk) => !chunk.posted)?.reason ?? "report_failed",
-        chunk_count: chunks.length,
-        recorded_count: recordedCount,
-        failed_count: failedCount,
-        chunks,
-    };
-}
-/**
- * One chunk, up to three attempts, as a decision table on what came back:
- *
- * | what came back                      | verdict                                |
- * |-------------------------------------|----------------------------------------|
- * | 404                                 | this dashboard has no endpoint; stop    |
- * | 2xx with a readable, full receipt    | recorded; stop                         |
- * | 2xx malformed or short of the count  | keep the reason, try again             |
- * | 4xx other than 429                   | the server's final answer; stop         |
- * | 429 or 5xx                          | keep the reason, try again             |
- * | transport error                      | keep the reason, try again, no status  |
- *
- * The row that looks wrong is the third one, and it is the important one: a 2xx
- * we cannot read is retried because the server may have died between persisting
- * the rows and answering. Only a schema-valid receipt that accounts for every
- * distinct session is safe to delete a durable pending report against.
- */
-async function postCodexSessionAttributionChunk(options) {
-    const maxAttempts = options.maxAttemptsPerRequest ?? DEFAULT_REPORT_ATTEMPTS;
-    const sleep = options.sleep ?? defaultReportSleep;
-    const requiredAcknowledgements = requiredCodexSessionAcknowledgementCount(options.sessions);
-    let lastStatus = null;
-    let lastFailureReason = null;
-    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-        try {
-            const response = await postSessionAttributionRequest(options);
-            lastStatus = response.status;
-            const body = await readResponseJson(response);
-            if (response.status === 404) {
-                return codexSessionReportChunkResult(options, {
-                    posted: false,
-                    reason: "codex_session_api_unavailable",
-                    httpStatus: response.status,
-                    recordedCount: 0,
-                });
-            }
-            if (response.ok) {
-                const receipt = readSessionReportReceipt(body, requiredAcknowledgements);
-                if (receipt.accepted) {
-                    return codexSessionReportChunkResult(options, {
-                        posted: true,
-                        reason: "recorded",
-                        httpStatus: response.status,
-                        recordedCount: receipt.recorded_count,
-                    });
-                }
-                lastFailureReason = receipt.reason;
-            }
-            else {
-                lastFailureReason = `report_failed_http_${response.status}`;
-                if (isFinalHttpFailure(response.status)) {
-                    return codexSessionReportChunkResult(options, {
-                        posted: false,
-                        reason: lastFailureReason,
-                        httpStatus: response.status,
-                        recordedCount: 0,
-                    });
-                }
-            }
-        }
-        catch (error) {
-            // Logged per attempt, on purpose: the interesting failure is the one
-            // that repeats. Three identical ECONNRESETs and one DNS failure followed
-            // by two resets are different stories, and `report_network_error` alone
-            // tells neither (BLI-3238).
-            console.error("[session-reports] report attempt failed before a status came back", JSON.stringify({
-                reason: "report_network_error",
-                attempt,
-                max_attempts: maxAttempts,
-                batch_index: options.batchIndex,
-                session_count: options.sessions.length,
-                ...describeError(error),
-            }));
-            lastStatus = null;
-            lastFailureReason = "report_network_error";
-        }
-        if (attempt < maxAttempts) {
-            await sleep(REPORT_RETRY_BACKOFF_STEP_MS * attempt);
-        }
-    }
-    return codexSessionReportChunkResult(options, {
-        posted: false,
-        reason: lastFailureReason ??
-            (lastStatus === null
-                ? "report_network_error"
-                : `report_failed_http_${lastStatus}`),
-        httpStatus: lastStatus,
-        recordedCount: 0,
-    });
-}
-function postSessionAttributionRequest(options) {
-    return options.fetchImpl(`${options.dashboardUrl}/api/ambient/codex-sessions`, {
-        method: "POST",
-        headers: {
-            "Authorization": `Bearer ${options.deviceToken}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-            schema_version: "ambient-codex-session-attributions.v1",
-            generated_at: options.generatedAt,
-            provenance: options.provenance,
-            sessions: options.sessions,
-        }),
-    });
-}
-/** Is this status the server's final answer, or worth another attempt? */
-function isFinalHttpFailure(status) {
-    return status < 500 && status !== 429;
-}
-/**
- * Can we take this 2xx body as proof the rows are durable?
- *
- * Only if it parses as the receipt schema AND accounts for every distinct
- * session in the chunk. Anything less is treated as no receipt at all.
- */
-function readSessionReportReceipt(body, requiredAcknowledgements) {
-    const parsed = CodexSessionAttributionReportResponseSchema.safeParse(body);
-    if (!parsed.success) {
-        return { accepted: false, reason: "report_invalid_response" };
-    }
-    if (parsed.data.recorded_count < requiredAcknowledgements) {
-        return { accepted: false, reason: "report_incomplete_acknowledgement" };
-    }
-    return { accepted: true, recorded_count: parsed.data.recorded_count };
-}
-function codexSessionReportChunkResult(options, result) {
-    return {
-        batch_index: options.batchIndex,
-        session_count: options.sessions.length,
-        posted: result.posted,
-        reason: result.reason,
-        http_status: result.httpStatus,
-        recorded_count: result.recordedCount,
-    };
-}
-function emptyCodexSessionReportResult(reason) {
-    return {
-        posted: false,
-        reason,
-        chunk_count: 0,
-        recorded_count: 0,
-        failed_count: 0,
-        chunks: [],
-    };
-}
-function chunkArray(items, size) {
-    const chunks = [];
-    for (let offset = 0; offset < items.length; offset += size) {
-        chunks.push(items.slice(offset, offset + size));
-    }
-    return chunks;
-}
-/**
- * How many rows the server must acknowledge, counted per distinct session
- * rather than per row — the same session observed twice in one chunk is still
- * one row on the far side.
- */
-function requiredCodexSessionAcknowledgementCount(sessions) {
-    return new Set(sessions.map((session) => `${session.source ?? "codex"}:${session.codex_session_id}`)).size;
-}
-function defaultReportSleep(milliseconds) {
-    return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
+export { flushPendingCodexSessionReports, queueCodexSessionReport, } from "./upload-session-reports-queue.js";
+export { postCodexSessionReport, reportCodexSessionAttributions, } from "./upload-session-reports-wire.js";