@bli-cockpit/cli 0.2.27 → 0.2.29

package/dist/raw-evidence-staging.js

@@ -0,0 +1,322 @@
+import { DELIVERY_BACKOFF_HOLDING } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Durable local state for raw-evidence STAGING and DELIVERY ATTEMPTS.
+ *
+ * Two questions this file answers, and BLI-3066 is what it costs when nothing
+ * does:
+ *
+ * 1. "Have I already staged these exact bytes?" — the pack id used to fold
+ *    `now` into its hash, so every 15-minute sync minted a new directory and
+ *    copied the same transcript into it again. One Codex rollout reached 559
+ *    byte-identical copies, 182 GiB, on one laptop.
+ * 2. "How many times have I already offered this object, and how did that go?"
+ *    — nothing counted, so the same commit failed 1,030 times in nine days at
+ *    full 15-minute cadence, and every attempt looked like the first.
+ *
+ * The cursor (`cursors/raw-evidence.json`) answers the *committed* question and
+ * deliberately stays that way: an entry there means the object is durable
+ * remotely. This file is the pre-commit side — staged but not yet acknowledged —
+ * so a cursor reader can never mistake "on this disk" for "safe in the bucket".
+ *
+ * Metadata only: content hashes, byte sizes, pack ids, pack-relative paths,
+ * reason labels, timestamps. Never content, never an absolute path.
+ */
+export const RAW_EVIDENCE_STAGING_FILENAME = "raw-evidence-staging.json";
+/**
+ * Backoff schedule for an object whose delivery keeps failing.
+ *
+ * 15 min (the scheduler's own cadence, so the first retry is simply the next
+ * sync), doubling to a 6 h ceiling. Nine days of failure is then ~40 attempts
+ * instead of 1,030, and the object is still retried four times a day — a server
+ * fix lands within hours, not on the next reinstall.
+ */
+export const EVIDENCE_DELIVERY_BACKOFF_BASE_MS = 15 * 60 * 1000;
+export const EVIDENCE_DELIVERY_BACKOFF_MAX_MS = 6 * 60 * 60 * 1000;
+/**
+ * The reason label written when an object is being held by backoff.
+ *
+ * Aliased from telemetry-core rather than spelled again here: the label is read
+ * by `classifyUploadFailure` on the way through the ledger, and a second copy
+ * of the string is how the collector's word and the server's word drift apart.
+ */
+export const DELIVERY_BACKOFF_HOLDING_REASON = DELIVERY_BACKOFF_HOLDING;
+/** The reason label written when an operator's retry is offered anyway. */
+export const DELIVERY_BACKOFF_BYPASS_REASON = "delivery_backoff_bypassed_operator_retry";
+/** Whether the delivery-backoff window gates this pass. Default: it does. */
+export function deliveryBackoffApplies(mode) {
+    return (mode ?? "scheduled") === "scheduled";
+}
+const MAX_TRACKED_STAGED_OBJECTS = 5_000;
+const MAX_TRACKED_DELIVERY_ATTEMPTS = 5_000;
+export function emptyRawEvidenceStagingState() {
+    return {
+        schema_version: "cockpit-raw-evidence-staging.v1",
+        updated_at: null,
+        staged: {},
+        delivery_attempts: {},
+    };
+}
+export function rawEvidenceStagingStatePath(stateDir) {
+    return path.join(stateDir, RAW_EVIDENCE_STAGING_FILENAME);
+}
+export async function readRawEvidenceStagingState(stateDir) {
+    try {
+        const raw = JSON.parse(await fs.readFile(rawEvidenceStagingStatePath(stateDir), "utf8"));
+        return parseStagingState(raw);
+    }
+    catch {
+        return emptyRawEvidenceStagingState();
+    }
+}
+/**
+ * Atomic write, same shape as the cursor: temp sibling, fsync, rename. A
+ * launchd sync and a hand-run sync can race, and a truncated state file would
+ * lose every attempt count at once — which is exactly the thing that must not
+ * be losable.
+ */
+export async function writeRawEvidenceStagingState(stateDir, state) {
+    const filePath = rawEvidenceStagingStatePath(stateDir);
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const pruned = pruneStagingState(state);
+    const serialized = `${JSON.stringify(pruned, null, 2)}\n`;
+    const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+    let handle = null;
+    try {
+        handle = await fs.open(tempPath, "w", 0o600);
+        await handle.writeFile(serialized);
+        await handle.sync();
+    }
+    finally {
+        await handle?.close();
+    }
+    try {
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    if (process.platform !== "win32") {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}
+export function recordStagedObject(state, contentHash, entry) {
+    state.staged[contentHash] = entry;
+}
+/**
+ * The absolute path of an already-staged copy of these bytes, or null.
+ *
+ * Verified against the filesystem, not trusted from the index: a dedup sweep,
+ * a GC pass, or an operator with `rm -rf` can all have removed the file since
+ * it was recorded. A stale entry is dropped so the caller re-stages rather than
+ * handing the uploader a path that is not there.
+ */
+export async function resolveStagedObject(rawEvidenceRoot, state, contentHash) {
+    const entry = state.staged[contentHash];
+    if (!entry)
+        return null;
+    const localPath = stagedObjectPath(rawEvidenceRoot, entry);
+    const info = await fs.stat(localPath).catch(() => null);
+    if (!info?.isFile() || info.size !== entry.byte_size) {
+        delete state.staged[contentHash];
+        return null;
+    }
+    return { local_path: localPath, entry };
+}
+export function stagedObjectPath(rawEvidenceRoot, entry) {
+    return path.join(rawEvidenceRoot, entry.pack_id, ...entry.relative_path.split("/").filter(Boolean));
+}
+/**
+ * Delay before the next attempt on an object that has failed `attempts` times.
+ * `attempts` is 1-based: the first failure waits one scheduler cadence.
+ */
+export function evidenceDeliveryBackoffMs(attempts) {
+    const safeAttempts = Math.max(1, Math.floor(attempts));
+    const exponent = Math.min(safeAttempts - 1, 32);
+    const delay = EVIDENCE_DELIVERY_BACKOFF_BASE_MS * 2 ** exponent;
+    return Math.min(delay, EVIDENCE_DELIVERY_BACKOFF_MAX_MS);
+}
+export function recordDeliveryFailure(state, contentHash, options) {
+    const previous = state.delivery_attempts[contentHash];
+    const attempts = (previous?.attempts ?? 0) + 1;
+    const attemptedAtIso = options.attemptedAt.toISOString();
+    const entry = {
+        attempts,
+        first_failed_at: previous?.first_failed_at ?? attemptedAtIso,
+        last_attempt_at: attemptedAtIso,
+        last_reason: options.reason,
+        next_attempt_at: new Date(options.attemptedAt.getTime() + evidenceDeliveryBackoffMs(attempts)).toISOString(),
+        byte_size: options.byteSize ?? previous?.byte_size ?? 0,
+        source_key: options.sourceKey ?? previous?.source_key ?? null,
+    };
+    state.delivery_attempts[contentHash] = entry;
+    return entry;
+}
+/** An object that landed clears its history; the next failure starts at one. */
+export function clearDeliveryAttempt(state, contentHash) {
+    if (!state.delivery_attempts[contentHash])
+        return false;
+    delete state.delivery_attempts[contentHash];
+    return true;
+}
+export function deliveryHold(state, contentHash, now) {
+    if (!contentHash)
+        return null;
+    const entry = state.delivery_attempts[contentHash];
+    if (!entry)
+        return null;
+    return Date.parse(entry.next_attempt_at) > now.getTime() ? entry : null;
+}
+/**
+ * Source keys currently held by backoff.
+ *
+ * Collection consults this BEFORE reading a file, so a held 350 MB transcript
+ * costs nothing at all this cycle — no read, no hash, no copy, no upload. The
+ * hold is still a named, retryable gap, never a silent drop.
+ */
+export function heldSourceKeys(state, now) {
+    const held = new Set();
+    for (const entry of Object.values(state.delivery_attempts)) {
+        if (!entry.source_key)
+            continue;
+        if (Date.parse(entry.next_attempt_at) > now.getTime()) {
+            held.add(entry.source_key);
+        }
+    }
+    return held;
+}
+export function evidenceSourceKey(options) {
+    const source = options.sourcePath
+        ? shortHash(options.sourcePath)
+        : options.label
+            ? shortHash(options.label)
+            : "unknown";
+    return `${options.kind}:${options.sessionId ?? "none"}:${source}`;
+}
+/**
+ * What `cockpit status` and the health receipt need in order to be unable to
+ * read green while an object has been failing for nine days.
+ */
+export function summarizeStuckEvidence(state, now) {
+    const entries = Object.values(state.delivery_attempts);
+    const reasons = new Set();
+    let heldCount = 0;
+    let maxAttempts = 0;
+    let oldest = null;
+    for (const entry of entries) {
+        reasons.add(entry.last_reason);
+        if (Date.parse(entry.next_attempt_at) > now.getTime())
+            heldCount += 1;
+        maxAttempts = Math.max(maxAttempts, entry.attempts);
+        if (!oldest || entry.first_failed_at.localeCompare(oldest) < 0) {
+            oldest = entry.first_failed_at;
+        }
+    }
+    return {
+        stuck_object_count: entries.length,
+        held_object_count: heldCount,
+        max_attempts: maxAttempts,
+        oldest_first_failed_at: oldest,
+        reasons: [...reasons].sort(),
+    };
+}
+/**
+ * Pack id derived from CONTENT, never from the clock.
+ *
+ * The manifest is excluded from the hash on purpose: its own object key
+ * contains the pack id, so folding it in would be circular. Hashes are sorted,
+ * so a change in collection order alone does not mint a new pack.
+ */
+export function contentKeyedRawEvidencePackId(options) {
+    const material = [...options.contentHashes].sort().join(",");
+    return `${options.workContextId}-${shortHash(`${options.workContextId}:${material}`)}`;
+}
+function pruneStagingState(state) {
+    return {
+        ...state,
+        staged: pruneNewest(state.staged, MAX_TRACKED_STAGED_OBJECTS, (entry) => entry.staged_at),
+        delivery_attempts: pruneNewest(state.delivery_attempts, MAX_TRACKED_DELIVERY_ATTEMPTS, (entry) => entry.last_attempt_at),
+    };
+}
+function pruneNewest(record, max, sortKey) {
+    const entries = Object.entries(record);
+    if (entries.length <= max)
+        return record;
+    entries.sort((a, b) => sortKey(b[1]).localeCompare(sortKey(a[1])));
+    return Object.fromEntries(entries.slice(0, max));
+}
+function parseStagingState(value) {
+    if (!value || typeof value !== "object") {
+        return emptyRawEvidenceStagingState();
+    }
+    const record = value;
+    return {
+        schema_version: "cockpit-raw-evidence-staging.v1",
+        updated_at: optionalString(record["updated_at"]),
+        staged: parseRecord(record["staged"], parseStagedEntry),
+        delivery_attempts: parseRecord(record["delivery_attempts"], parseAttemptEntry),
+    };
+}
+function parseRecord(value, parseEntry) {
+    if (!value || typeof value !== "object")
+        return {};
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const parsed = parseEntry(entry);
+        if (parsed)
+            out[key] = parsed;
+    }
+    return out;
+}
+function parseStagedEntry(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const packId = optionalString(record["pack_id"]);
+    const relativePath = optionalString(record["relative_path"]);
+    const stagedAt = optionalString(record["staged_at"]);
+    if (!packId || !relativePath || !stagedAt)
+        return null;
+    return {
+        pack_id: packId,
+        relative_path: relativePath,
+        byte_size: optionalNumber(record["byte_size"]),
+        source_key: optionalString(record["source_key"]),
+        staged_at: stagedAt,
+    };
+}
+function parseAttemptEntry(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const lastAttemptAt = optionalString(record["last_attempt_at"]);
+    const nextAttemptAt = optionalString(record["next_attempt_at"]);
+    if (!lastAttemptAt || !nextAttemptAt)
+        return null;
+    const attempts = optionalNumber(record["attempts"]);
+    return {
+        attempts: attempts > 0 ? attempts : 1,
+        first_failed_at: optionalString(record["first_failed_at"]) ?? lastAttemptAt,
+        last_attempt_at: lastAttemptAt,
+        last_reason: optionalString(record["last_reason"]) ?? "unknown",
+        next_attempt_at: nextAttemptAt,
+        byte_size: optionalNumber(record["byte_size"]),
+        source_key: optionalString(record["source_key"]),
+    };
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function optionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function shortHash(value) {
+    return crypto
+        .createHash("sha256")
+        .update(value, "utf8")
+        .digest("hex")
+        .slice(0, 12);
+}

package/dist/upload-agent-artifacts.js

@@ -0,0 +1,153 @@
+/**
+ * Telling the dashboard about images an agent produced or was shown.
+ *
+ * A screenshot pasted into a Codex or Claude session is already uploaded as raw
+ * evidence like any other object; this is the second, separate report that says
+ * "that object is an image, from this session, at this turn" so the dashboard
+ * can queue it for redaction and OCR.
+ *
+ * Non-fatal by design: an older dashboard without the endpoint must not fail a
+ * harvest, so every path here returns a `{ posted, reason }` label instead of
+ * throwing.
+ */
+import { AgentImageArtifactReportRequestSchema, } from "@bli-cockpit/telemetry-core";
+import { readResponseJson } from "./upload-http.js";
+export async function reportAgentImageArtifacts(options) {
+    const artifacts = agentArtifactsFromEvidence(options);
+    if (artifacts.length === 0) {
+        return {
+            posted: false,
+            reason: "no_agent_image_artifacts",
+            recorded_count: 0,
+        };
+    }
+    const payload = AgentImageArtifactReportRequestSchema.parse({
+        schema_version: "ambient-agent-image-artifacts.v1",
+        generated_at: options.generatedAt,
+        provenance: options.provenance,
+        artifacts,
+    });
+    try {
+        const response = await options.fetchImpl(`${options.dashboardUrl}/api/ambient/agent-artifacts`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${options.deviceToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+        if (response.status === 404) {
+            return {
+                posted: false,
+                reason: "agent_artifact_api_unavailable",
+                recorded_count: 0,
+            };
+        }
+        if (!response.ok) {
+            return {
+                posted: false,
+                reason: `report_failed_http_${response.status}`,
+                recorded_count: 0,
+            };
+        }
+        const body = await readResponseJson(response);
+        const recordedCount = body && typeof body === "object"
+            ? Number(body.recorded_count ?? 0)
+            : 0;
+        return {
+            posted: true,
+            reason: "recorded",
+            recorded_count: Number.isFinite(recordedCount) ? recordedCount : 0,
+        };
+    }
+    catch {
+        return { posted: false, reason: "report_network_error", recorded_count: 0 };
+    }
+}
+/**
+ * The images this sync made durable, from both directions.
+ *
+ * Freshly uploaded objects come from the upload outcomes; images whose bytes
+ * this machine already had come from the cursor, which is the only place their
+ * object key still exists. Keyed by pointer id so a replay of the same image
+ * reports once, with the fresher outcome winning.
+ */
+function agentArtifactsFromEvidence(options) {
+    const byPointerId = new Map();
+    for (const outcome of options.outcomes) {
+        if (outcome.upload_state === "upload_failed" || !outcome.artifact_metadata) {
+            continue;
+        }
+        const artifact = agentArtifactFromMetadata({
+            metadata: outcome.artifact_metadata,
+            rawEvidencePointerId: outcome.pointer.raw_evidence_pointer_id,
+            objectKey: outcome.object_key,
+            ticketId: options.ticketId,
+            repoFingerprint: options.repoFingerprint,
+            worktreeFingerprint: options.worktreeFingerprint,
+            uploadState: outcome.upload_state,
+        });
+        byPointerId.set(artifact.raw_evidence_pointer_id, artifact);
+    }
+    for (const entry of options.reused) {
+        if (!entry.artifact_metadata)
+            continue;
+        const objectKey = options.cursorObjects[entry.content_hash_sha256]?.object_key;
+        if (!objectKey)
+            continue;
+        const artifact = agentArtifactFromMetadata({
+            metadata: entry.artifact_metadata,
+            rawEvidencePointerId: objectKey,
+            objectKey,
+            ticketId: options.ticketId,
+            repoFingerprint: options.repoFingerprint,
+            worktreeFingerprint: options.worktreeFingerprint,
+            uploadState: "reused_existing",
+        });
+        byPointerId.set(artifact.raw_evidence_pointer_id, artifact);
+    }
+    return [...byPointerId.values()];
+}
+/**
+ * One report row. Redaction and OCR both start as `not_started`: the dashboard
+ * owns those passes, and the collector must never claim an image has been
+ * cleared when nothing has looked at it yet.
+ */
+function agentArtifactFromMetadata(options) {
+    return {
+        raw_evidence_pointer_id: options.rawEvidencePointerId,
+        agent_source: options.metadata.agent_source,
+        source_session_id: options.metadata.source_session_id,
+        ...(options.metadata.source_message_id
+            ? { source_message_id: options.metadata.source_message_id }
+            : {}),
+        ...(options.metadata.turn_index !== undefined
+            ? { turn_index: options.metadata.turn_index }
+            : {}),
+        occurred_at: options.metadata.occurred_at,
+        artifact_kind: options.metadata.artifact_kind,
+        capture_origin: "agent_session_attachment",
+        ...(options.ticketId ? { ticket_id: options.ticketId } : {}),
+        ...(options.repoFingerprint
+            ? { repo_fingerprint: options.repoFingerprint }
+            : {}),
+        ...(options.worktreeFingerprint
+            ? { worktree_fingerprint: options.worktreeFingerprint }
+            : {}),
+        storage_bucket: "ambient-raw-evidence",
+        object_key: options.objectKey,
+        content_hash_sha256: options.metadata.content_hash_sha256,
+        byte_size: options.metadata.byte_size,
+        media_type: options.metadata.media_type,
+        width: options.metadata.width,
+        height: options.metadata.height,
+        redaction_status: "not_started",
+        ocr_status: "not_started",
+        labels: {
+            collector_upload_state: options.uploadState,
+            ...(options.metadata.source_sidecar_id
+                ? { source_sidecar_id: options.metadata.source_sidecar_id }
+                : {}),
+        },
+    };
+}