@bli-cockpit/cli 0.2.55 → 0.2.57

package/dist/upload-session-reports-queue.js

@@ -0,0 +1,156 @@
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorSessionFile, readLocalSessionReference, } from "./local-state.js";
+import { readLocalUploadSpoolState, recordPendingSessionReport, recordSessionReportFailure, recordSessionReportSuccess, } from "./spool/local-spool.js";
+import { safeRepoLabel } from "./upload-envelope.js";
+import { normalizeDashboardUrl } from "./upload-http.js";
+import { describeError } from "./health-detail.js";
+import { emptyCodexSessionReportResult, reportCodexSessionAttributions, } from "./upload-session-reports-wire.js";
+/**
+ * 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),
+    };
+}

package/dist/upload-session-reports-wire.js

@@ -0,0 +1,275 @@
+/**
+ * The wire: posting Codex session attribution rows and reading back a receipt.
+ *
+ * - `postCodexSessionReport` — the one-shot path, for a harvest that already
+ *   has a repo in hand; builds its own provenance and posts immediately.
+ * - `reportCodexSessionAttributions` — chunk at the endpoint's session cap,
+ *   then attempt each chunk under `postCodexSessionAttributionChunk`'s
+ *   decision table of "final answer" versus "worth another attempt".
+ *
+ * `upload-session-reports-queue.ts` calls `reportCodexSessionAttributions`
+ * once per queued report; nothing here touches the durable queue.
+ */
+import { CODEX_SESSION_REPORT_MAX_SESSIONS, CodexSessionAttributionReportResponseSchema, } from "@bli-cockpit/telemetry-core";
+import path from "node:path";
+import { getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.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");
+    }
+}
+/**
+ * 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,
+    };
+}
+export 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));
+}