@bli-cockpit/cli 0.1.9 → 0.1.12

package/README.md

@@ -4,8 +4,9 @@ Public BLI Cockpit command-line interface for approved operators and interns.
 
 The npm package is public; the Cockpit backend and admin tooling are not. The
 CLI pairs a local laptop with the private Cockpit dashboard, records safe
-work context, uploads consented raw Codex/diff evidence to durable private
-storage, and uploads metadata refs after dashboard-approved
+work context, uploads consented raw Codex/Claude/diff evidence and explicit
+images attached into agent sessions to durable private storage, and uploads
+metadata refs after dashboard-approved
 device pairing.
 
 ## One-paste install
@@ -14,8 +15,8 @@ Run this from the repo where work will happen:
 
 ```bash
 COCKPIT_DEVICE_NAME="$(scutil --get ComputerName 2>/dev/null || hostname -s)"
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit onboard \
-  --dashboard-url <DASHBOARD_URL> \
+npm install -g @bli-cockpit/cli@latest
+cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
   --repo "$PWD"
@@ -26,13 +27,20 @@ If a work folder contains multiple repos, run the same command from the parent:
 ```bash
 cd ~/Downloads/bluepearl-workspace
 COCKPIT_DEVICE_NAME="$(scutil --get ComputerName 2>/dev/null || hostname -s)"
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit onboard \
-  --dashboard-url <DASHBOARD_URL> \
+npm install -g @bli-cockpit/cli@latest
+cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
   --repo "$PWD"
 ```
 
+The CLI defaults to the production dashboard. Normal intern/operator setup,
+updates, and syncs omit `--dashboard-url`. Pass `--dashboard-url` only for
+staging, a custom dashboard, or deliberately forcing a different dashboard
+pairing. Already-onboarded users update with
+`npm install -g @bli-cockpit/cli@latest`, then run
+`cockpit sync --repo "$PWD" --json`.
+
 Parent mode scans child git repos/worktrees (3 folder levels deep, up to 50
 repos by default — tune with `--max-depth` / `--max-repos`; a warning prints
 if the repo cap truncates discovery), creates one stable work context per
@@ -47,7 +55,7 @@ being duplicated across repos or dropped.
 
 What happens:
 
-1. npm downloads the public `@bli-cockpit/cli` package.
+1. npm installs or updates the public `@bli-cockpit/cli` package.
 2. `cockpit onboard` writes local user config.
 3. Cockpit prints a dashboard pairing URL and code.
 4. Admin approves the pending request from Ambient -> Collector approvals, or
@@ -62,8 +70,8 @@ What happens:
 `"Savina MacBook"`, `"Box VM 42"`, or the auto-filled macOS computer name.
 On reused laptops or VMs, keep `--email <APPROVED_EMAIL>` in the command.
 `cockpit onboard` skips pairing only when the existing valid session belongs to
-that same email and dashboard URL; a different email or dashboard forces a new
-approval.
+that same email and dashboard URL (the production default unless overridden); a
+different email or dashboard forces a new approval.
 
 Before the command runs, an Admin must create or approve the email in the
 private dashboard. Default launch path is email + temporary password, handed
@@ -74,12 +82,11 @@ separate invite acceptance step.
 When ticket work starts later:
 
 ```bash
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit start \
+cockpit start \
   --ticket <ticket-id> \
   --repo "$PWD"
 
-npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit sync \
-  --dashboard-url <DASHBOARD_URL> \
+cockpit sync \
   --repo "$PWD" \
   --json
 ```
@@ -91,7 +98,8 @@ Only pass `--ticket` when the work really belongs to a visible ticket.
 
 Local files:
 
-- `~/.config/bli-cockpit/config.json`: dashboard URL and local install config.
+- `~/.config/bli-cockpit/config.json`: dashboard URL (production default unless
+  overridden) and local install config.
 - `~/.config/bli-cockpit/session.json`: normal paired device session.
 - `~/.local/state/bli-cockpit/spool/`: safe retry records when upload fails.
 - `~/.local/state/bli-cockpit/cursors/raw-evidence.json`: hashes and labels of
@@ -109,11 +117,14 @@ Remote dashboard:
 - durable private Storage objects accepted by the chunked
   `/api/ambient/evidence/upload/begin|chunk|commit` endpoints, tracked in a
   durable per-object upload ledger;
+- attached image artifact metadata accepted by `/api/ambient/agent-artifacts`
+  for screenshots/images explicitly attached into Codex or Claude sessions;
 - Codex session attribution records (session id, file hash, attribution state
   and reason labels, scores) accepted by `/api/ambient/codex-sessions`.
 
 Never provide Supabase service-role keys, raw DB URLs, root env files, cookies,
-or deployment tokens to this CLI. The collector must never read env files.
+or deployment tokens to this CLI. The collector must never read env files and
+does not collect random desktop screenshots or screen recordings.
 
 ## Public package boundary
 

package/dist/adapters/agent-image-evidence.js

@@ -0,0 +1,97 @@
+import { SECRET_FILE_SEGMENT_PATTERN } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENT_IMAGE_MAX_BYTES, validateAgentImageBytes, } from "./agent-image-validation.js";
+import { imageCandidatesFromRecord, } from "./agent-image-records.js";
+export async function collectAgentImageEvidenceFromJsonlFile(options) {
+    const stat = await fs.stat(options.filePath).catch(() => null);
+    if (!stat?.isFile())
+        return { images: [], skipped: [] };
+    if (stat.size > AGENT_IMAGE_MAX_BYTES) {
+        return {
+            images: [],
+            skipped: [{ label: "transcript", reason: "file_too_large" }],
+        };
+    }
+    const content = await fs.readFile(options.filePath, "utf8").catch(() => null);
+    if (content === null)
+        return { images: [], skipped: [] };
+    const images = [];
+    const skipped = [];
+    let lineIndex = 0;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        lineIndex += 1;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        for (const candidate of imageCandidatesFromRecord(record, {
+            source: options.source,
+            sessionId: options.sessionId,
+            sidecarId: options.sidecarId,
+            fallbackOccurredAt: new Date(stat.mtimeMs).toISOString(),
+            lineIndex,
+        })) {
+            const result = await loadCandidate(candidate, path.dirname(options.filePath));
+            if ("reason" in result) {
+                skipped.push({ label: candidate.label, reason: result.reason });
+            }
+            else {
+                images.push(result);
+            }
+        }
+    }
+    return { images, skipped };
+}
+async function loadCandidate(candidate, transcriptDir) {
+    let bytes;
+    if (candidate.dataValue) {
+        bytes = Buffer.from(candidate.dataValue, "base64");
+    }
+    else if (candidate.pathValue) {
+        const imagePath = path.isAbsolute(candidate.pathValue)
+            ? candidate.pathValue
+            : path.resolve(transcriptDir, candidate.pathValue);
+        if (SECRET_FILE_SEGMENT_PATTERN.test(imagePath)) {
+            return { reason: "secret_like_file_name" };
+        }
+        bytes = await fs.readFile(imagePath).catch(() => Buffer.alloc(0));
+        if (bytes.byteLength === 0)
+            return { reason: "file_read_failed" };
+    }
+    else {
+        return { reason: "missing_image_bytes" };
+    }
+    const validation = validateAgentImageBytes(bytes, candidate.declaredMediaType);
+    if ("reason" in validation)
+        return validation;
+    return {
+        bytes,
+        extension: validation.extension,
+        label: candidate.label,
+        metadata: {
+            agent_source: candidate.source,
+            source_session_id: candidate.sessionId,
+            ...(candidate.sourceMessageId ? { source_message_id: candidate.sourceMessageId } : {}),
+            ...(candidate.sidecarId ? { source_sidecar_id: candidate.sidecarId } : {}),
+            ...(candidate.turnIndex !== undefined ? { turn_index: candidate.turnIndex } : {}),
+            occurred_at: candidate.occurredAt,
+            artifact_kind: candidate.artifactKind,
+            capture_origin: "agent_session_attachment",
+            width: validation.width,
+            height: validation.height,
+            media_type: validation.mediaType,
+            content_hash_sha256: sha256(bytes),
+            byte_size: bytes.byteLength,
+        },
+    };
+}
+function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}

package/dist/adapters/agent-image-records.js

@@ -0,0 +1,147 @@
+export function imageCandidatesFromRecord(record, context) {
+    if (!isRecord(record))
+        return [];
+    const payload = recordOf(record["payload"]);
+    const message = recordOf(record["message"]) ?? recordOf(payload?.["message"]);
+    const sourceMessageId = stringFrom(record, ["id", "message_id", "messageId", "uuid"]) ??
+        stringFrom(payload, ["id", "message_id", "messageId", "uuid"]);
+    const turnIndex = numberFrom(record, ["turn_index", "turnIndex"]) ??
+        numberFrom(payload, ["turn_index", "turnIndex"]);
+    const occurredAt = isoFrom(stringFrom(record, ["timestamp", "created_at", "createdAt", "time"]) ??
+        stringFrom(payload, ["timestamp", "created_at", "createdAt", "time"])) ?? context.fallbackOccurredAt;
+    const candidates = [];
+    const base = {
+        source: context.source,
+        sessionId: context.sessionId,
+        sidecarId: context.sidecarId,
+        sourceMessageId,
+        turnIndex,
+        occurredAt,
+        lineIndex: context.lineIndex,
+    };
+    for (const value of explicitAttachmentObjects(record, payload, message)) {
+        const candidate = candidateFromObject(value, base, true);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    for (const value of explicitImageBlocks(record, payload, message)) {
+        const candidate = candidateFromObject(value, base, false);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    return candidates;
+}
+function explicitAttachmentObjects(record, payload, message) {
+    const out = [];
+    if (isAttachmentRecord(record))
+        out.push(record);
+    if (payload && isAttachmentRecord(payload))
+        out.push(payload);
+    for (const holder of [record, payload, message]) {
+        if (!holder)
+            continue;
+        const single = holder["attachment"];
+        if (isRecord(single))
+            out.push(single);
+        const attachments = holder["attachments"];
+        if (Array.isArray(attachments))
+            out.push(...attachments);
+    }
+    return out;
+}
+function explicitImageBlocks(record, payload, message) {
+    const out = [];
+    for (const holder of [record, payload, message]) {
+        const content = holder?.["content"];
+        if (Array.isArray(content))
+            out.push(...content.filter((value) => isRecord(value)));
+    }
+    return out;
+}
+function candidateFromObject(value, base, attachmentEnvelope) {
+    if (!isRecord(value))
+        return null;
+    const nestedSource = recordOf(value["source"]);
+    const imageUrl = recordOf(value["image_url"]);
+    const typeValue = stringFrom(value, ["type", "kind", "artifact_kind"]);
+    const declaredMediaType = stringFrom(value, ["media_type", "mime_type", "mimeType"]) ??
+        stringFrom(nestedSource, ["media_type", "mime_type", "mimeType"]);
+    const parsedDataUrl = parseDataUrl(stringFrom(imageUrl, ["url"]));
+    const pathValue = stringFrom(value, ["path", "local_path", "file_path", "filePath"]) ??
+        stringFrom(nestedSource, ["path", "local_path", "file_path", "filePath"]);
+    const dataValue = parsedDataUrl?.data ??
+        stringFrom(value, ["data_base64", "base64", "content_base64", "data"]) ??
+        stringFrom(nestedSource, ["data_base64", "base64", "content_base64", "data"]);
+    const mediaType = parsedDataUrl?.mediaType ?? declaredMediaType;
+    if (!pathValue && !dataValue)
+        return null;
+    if (!attachmentEnvelope && !isImageBlockType(typeValue))
+        return null;
+    if (attachmentEnvelope && !isImageish(typeValue, mediaType))
+        return null;
+    const objectId = stringFrom(value, ["id", "attachment_id", "attachmentId", "uuid"]);
+    return {
+        source: base.source,
+        sessionId: base.sessionId,
+        sidecarId: base.sidecarId,
+        sourceMessageId: objectId ?? base.sourceMessageId,
+        turnIndex: base.turnIndex,
+        occurredAt: base.occurredAt,
+        artifactKind: isScreenshot(typeValue) ? "screenshot" : "image_attachment",
+        declaredMediaType: mediaType,
+        pathValue,
+        dataValue,
+        label: objectId ?? base.sourceMessageId ?? `line-${base.lineIndex}`,
+    };
+}
+function parseDataUrl(value) {
+    const match = value?.match(/^data:([^;,]+);base64,(.+)$/i);
+    return match ? { mediaType: match[1] ?? "", data: match[2] ?? "" } : null;
+}
+function isAttachmentRecord(value) {
+    return ["attachment", "image_attachment", "screenshot"].includes(String(value["type"] ?? "").toLowerCase());
+}
+function isImageBlockType(value) {
+    return ["image", "input_image", "image_attachment", "screenshot"].includes(value?.toLowerCase() ?? "");
+}
+function isImageish(typeValue, mediaType) {
+    return isImageBlockType(typeValue) || Boolean(normalizeMediaType(mediaType));
+}
+function isScreenshot(typeValue) {
+    return typeValue?.toLowerCase().includes("screenshot") ?? false;
+}
+function normalizeMediaType(value) {
+    return ["image/png", "image/jpeg", "image/jpg"].includes(value?.trim().toLowerCase() ?? "");
+}
+function isoFrom(value) {
+    if (!value)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function stringFrom(record, keys) {
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function numberFrom(record, keys) {
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (Number.isInteger(value))
+            return value;
+    }
+    return undefined;
+}
+function recordOf(value) {
+    return isRecord(value) ? value : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/adapters/agent-image-validation.js

@@ -0,0 +1,88 @@
+export const AGENT_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+export const AGENT_IMAGE_MAX_DIMENSION_PX = 16_384;
+export const AGENT_IMAGE_MAX_PIXELS = 50_000_000;
+export function validateAgentImageBytes(bytes, declaredMediaType) {
+    if (bytes.byteLength > AGENT_IMAGE_MAX_BYTES)
+        return { reason: "file_too_large" };
+    if (declaredMediaType && !normalizeMediaType(declaredMediaType)) {
+        return { reason: "unsupported_media_type" };
+    }
+    const detected = detectImage(bytes);
+    if (!detected)
+        return { reason: "invalid_image_magic" };
+    if (detected.width <= 0 ||
+        detected.height <= 0 ||
+        detected.width > AGENT_IMAGE_MAX_DIMENSION_PX ||
+        detected.height > AGENT_IMAGE_MAX_DIMENSION_PX ||
+        detected.width * detected.height > AGENT_IMAGE_MAX_PIXELS) {
+        return { reason: "image_pixel_limit_exceeded" };
+    }
+    return {
+        ...detected,
+        extension: detected.mediaType === "image/png" ? "png" : "jpg",
+    };
+}
+function detectImage(bytes) {
+    const png = parsePngDimensions(bytes);
+    if (png)
+        return { mediaType: "image/png", ...png };
+    const jpeg = parseJpegDimensions(bytes);
+    if (jpeg)
+        return { mediaType: "image/jpeg", ...jpeg };
+    return null;
+}
+function parsePngDimensions(bytes) {
+    const signature = "89504e470d0a1a0a";
+    if (bytes.byteLength < 24 || bytes.subarray(0, 8).toString("hex") !== signature) {
+        return null;
+    }
+    if (bytes.subarray(12, 16).toString("ascii") !== "IHDR")
+        return null;
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+function parseJpegDimensions(bytes) {
+    if (bytes.byteLength < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset + 3 < bytes.byteLength) {
+        while (offset < bytes.byteLength && bytes[offset] === 0xff)
+            offset += 1;
+        if (offset + 2 > bytes.byteLength)
+            return null;
+        const marker = bytes[offset];
+        if (marker === undefined)
+            return null;
+        offset += 1;
+        if (marker === 0xd9 || marker === 0xda)
+            break;
+        if (marker !== undefined && marker >= 0xd0 && marker <= 0xd7)
+            continue;
+        if (offset + 2 > bytes.byteLength)
+            return null;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.byteLength)
+            return null;
+        if (isJpegSofMarker(marker) && offset + 7 <= bytes.byteLength) {
+            return {
+                height: bytes.readUInt16BE(offset + 3),
+                width: bytes.readUInt16BE(offset + 5),
+            };
+        }
+        offset += length;
+    }
+    return null;
+}
+function isJpegSofMarker(marker) {
+    return (marker !== undefined &&
+        marker >= 0xc0 &&
+        marker <= 0xcf &&
+        ![0xc4, 0xc8, 0xcc].includes(marker));
+}
+function normalizeMediaType(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "image/png")
+        return "image/png";
+    if (normalized === "image/jpeg" || normalized === "image/jpg")
+        return "image/jpeg";
+    return null;
+}