@bli-cockpit/cli 0.2.204 → 0.2.206

package/dist/adapters/local-sources.js

@@ -39,6 +39,7 @@ export async function runLocalSourceCollectors(options) {
             byteBudget: options.rawEvidenceByteBudget,
             objectBudget: options.rawEvidenceObjectBudget,
             budget: options.rawEvidenceBudget,
+            images: options.rawEvidenceImages,
             deliveryMode: options.rawEvidenceDeliveryMode,
         })
         : {

package/dist/adapters/raw-evidence-collection-state.js

@@ -59,6 +59,8 @@ export async function openCollection(context, options, places) {
         remainingBytes: byteBudget,
         remainingObjects: objectBudget,
     };
+    if (options.images)
+        budget.images ??= options.images;
     const stagingAllowance = (budget.staging ??= await openStagingAllowance(options.stateDir, options.env ?? process.env, { statfs: options.statfs }));
     return {
         context,

package/dist/adapters/raw-evidence-transcript-file.js

@@ -17,6 +17,7 @@ import { describeError } from "../health-detail.js";
 import { DELIVERY_BACKOFF_HOLDING_REASON, evidenceSourceKey, } from "../raw-evidence-staging.js";
 import { isSecretLikePath, sha256, shortHash, } from "./raw-evidence-keys.js";
 import { maskSecretsInTranscript, } from "./raw-evidence-sanitize.js";
+import { mightHoldEmbeddedImages } from "@bli-cockpit/telemetry-core";
 import { markBudgetCapApplied, markCapApplied, } from "./raw-evidence-completeness.js";
 import { evidenceEntry } from "./raw-evidence-manifest.js";
 import { describeSnapshot, stubReplacementClaim, supersedeClaimFor, } from "./raw-evidence-snapshot-supersede.js";
@@ -57,8 +58,15 @@ export async function collectOneEvidenceFile(collection, options) {
         markCapApplied(collection, options.kind, "max_file_bytes");
         return skip("file_too_large");
     }
+    // BLI-16977: describe each distinct embedded image once and, when the one switch says so, swap the
+    // base64 for a short marker BEFORE masking, so the masker and the content hash see the final bytes.
+    const imagesPrepared = await prepareEmbeddedImages(collection, {
+        bytes: read.bytes,
+        kind: options.kind,
+        sessionId: options.sessionId,
+    });
     const sanitized = maskSecretsInTranscript(collection, {
-        raw: read.bytes,
+        raw: imagesPrepared,
         kind: options.kind,
         evidenceLabel: names.evidenceLabel,
         secretLikeFileName: names.secretLikeFileName,
@@ -96,6 +104,35 @@ export async function collectOneEvidenceFile(collection, options) {
     });
     return true;
 }
+/**
+ * The transcript bytes after the image step. Unchanged (the very same buffer) unless this sync has
+ * an image session AND the switch is `describe_and_drop` (images become markers where a description
+ * is stored, then the slim rules run, see src/slim/). In `describe_and_keep` the bytes always come
+ * back untouched. Never throws: an image step that breaks hands back the original bytes and says so.
+ */
+async function prepareEmbeddedImages(collection, file) {
+    const session = collection.budget.images;
+    const source = file.kind.startsWith("codex") ? "codex" : file.kind.startsWith("claude") ? "claude_code" : null;
+    if (!session || !source)
+        return file.bytes;
+    // Drop mode slims every transcript, image-bearing or not; keep mode only describes the ones that can hold an image.
+    if (session.mode !== "describe_and_drop" && !mightHoldEmbeddedImages(file.bytes))
+        return file.bytes;
+    try {
+        const prepared = await session.prepareTranscript({
+            text: file.bytes.toString("utf8"),
+            source,
+            sessionId: file.sessionId,
+        });
+        if (!prepared.changed)
+            return file.bytes;
+        return Buffer.from(prepared.text, "utf8");
+    }
+    catch (error) {
+        console.error("[raw-evidence] image or slim step failed, uploading the transcript as it was", JSON.stringify({ reason: "image_step_failed", kind: file.kind, ...describeError(error) }));
+        return file.bytes;
+    }
+}
 function nameEvidenceFile(options) {
     const fileName = path.basename(options.filePath);
     const secretLikeFileName = isSecretLikePath(fileName);

package/dist/commands/image.js

@@ -0,0 +1,137 @@
+/**
+ * `cockpit image` (BLI-16977): describe one image by hand, or look a description up.
+ *
+ * Plain words: Tower replaces the base64 pictures inside collected transcripts with a short
+ * written description, kept against the image's sha256. The collector sends each picture once.
+ * `describe` is that same step for one file you point at; `show` finds a stored description from
+ * the sha256 or the 16-character prefix a transcript marker carries.
+ *
+ * Two verbs over the one `/api/ambient/images` door (POST describes, GET reads) on this machine's
+ * device token, the same door the MCP twins (`image_describe`, `image_show`) use. `--json` carries
+ * the door's body on stdout and nothing else. Every refusal names its reason: a file that is too
+ * large or not an image is refused here, before anything is sent.
+ */
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { IMAGE_DESCRIBE_MAX_BYTES, formatImageMarker, imageSizeLabel, sniffImageMediaType, } from "@bli-cockpit/telemetry-core";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[image cli]";
+const READ_DEADLINE_MS = 30_000;
+/** The door runs a vision model inside the request. */
+const DESCRIBE_DEADLINE_MS = 55_000;
+const DOOR_PATH = "/api/ambient/images";
+export async function runImage(command, io) {
+    const prepared = command.action === "describe" ? await readImageFile(command.file ?? "") : null;
+    if (prepared && !prepared.ok)
+        return refuse(io, command.json, prepared.reason, prepared.detail);
+    let door;
+    try {
+        door = await openAgentDoor("image", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        return refuse(io, command.json, "not_paired", detail);
+    }
+    if (prepared?.ok)
+        return describeImage(command, door, prepared.request);
+    return showImage(command, door);
+}
+/** Reads the file and refuses, by name, anything the door would refuse. Nothing is sent from here. */
+async function readImageFile(typed) {
+    const file = path.resolve(typed);
+    let size;
+    try {
+        const info = await stat(file);
+        if (!info.isFile())
+            return { ok: false, reason: "not_a_file", detail: `${typed} is not a file. Point at one image file.` };
+        size = info.size;
+    }
+    catch {
+        return { ok: false, reason: "file_unreadable", detail: `Could not read ${typed}. Check the path. Nothing was sent.` };
+    }
+    if (size > IMAGE_DESCRIBE_MAX_BYTES) {
+        return { ok: false, reason: "image_too_large", detail: `That image is ${imageSizeLabel(size)}; the describe door takes at most ${imageSizeLabel(IMAGE_DESCRIBE_MAX_BYTES)}. Nothing was sent.` };
+    }
+    let bytes;
+    try {
+        bytes = await readFile(file);
+    }
+    catch {
+        return { ok: false, reason: "file_unreadable", detail: `Could not read ${typed}. Check the path and permissions. Nothing was sent.` };
+    }
+    const mediaType = sniffImageMediaType(bytes);
+    if (!mediaType)
+        return { ok: false, reason: "not_an_image", detail: "That file is not a PNG, JPEG, GIF or WebP image (judged by its first bytes, not its name). Nothing was sent." };
+    if (bytes.length > IMAGE_DESCRIBE_MAX_BYTES) {
+        return { ok: false, reason: "image_too_large", detail: `That image is ${imageSizeLabel(bytes.length)}; the describe door takes at most ${imageSizeLabel(IMAGE_DESCRIBE_MAX_BYTES)}. Nothing was sent.` };
+    }
+    const request = {
+        schema_version: "image-describe.v1",
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        media_type: mediaType,
+        byte_size: bytes.length,
+        content_base64: Buffer.from(bytes).toString("base64"),
+        source: "manual",
+    };
+    return { ok: true, request };
+}
+async function describeImage(command, door, request) {
+    const body = command.session ? { ...request, session_id: command.session } : request;
+    const answer = await askAgentDoor(door, { path: DOOR_PATH, method: "POST", label: "image describe", timeoutMs: DESCRIBE_DEADLINE_MS, body });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} describe answered ${JSON.stringify({ status: result.status, sha256: request.sha256.slice(0, 16), media_type: request.media_type, byte_size: request.byte_size, secrets_masked: result.description.secrets_masked })}`);
+    if (door.json)
+        return emitAgentDoor(door, result);
+    const out = door.io.stdout;
+    writeLine(out, result.status === "known" ? "Tower already had a description for this image:" : "Described:");
+    for (const line of descriptionLines(result.description))
+        writeLine(out, line);
+    writeLine(out, "");
+    writeLine(out, `Transcript marker: ${formatImageMarker({ sha256: request.sha256, mediaType: request.media_type, byteSize: request.byte_size })}`);
+    return 0;
+}
+async function showImage(command, door) {
+    const query = new URLSearchParams({ sha256: command.sha256 ?? "" });
+    const answer = await askAgentDoor(door, { path: `${DOOR_PATH}?${query.toString()}`, method: "GET", label: "image show", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} show answered ${JSON.stringify({ sha256: (command.sha256 ?? "").slice(0, 16), returned: result.descriptions.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, result);
+    if (result.descriptions.length === 0) {
+        writeLine(door.io.stdout, "No description stored for that image yet.");
+        return 0;
+    }
+    result.descriptions.forEach((description, index) => {
+        if (index > 0)
+            writeLine(door.io.stdout, "");
+        for (const line of descriptionLines(description))
+            writeLine(door.io.stdout, line);
+    });
+    return 0;
+}
+function descriptionLines(description) {
+    const lines = [
+        description.description,
+        "",
+        `Image: ${description.media_type.replace("image/", "")}, ${imageSizeLabel(description.byte_size)}, sha256 ${description.sha256}`,
+        `Described by ${description.model} on ${description.created_at}.`,
+    ];
+    if (description.secrets_masked)
+        lines.push("Something that looked like a secret was masked in this description.");
+    return lines;
+}
+/** A refusal before or without a door: the reason on stderr, and under `--json` on stdout as `{ ok: false, error, detail }`. */
+function refuse(io, json, reason, detail) {
+    writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason })}`);
+    if (json)
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    else
+        writeLine(io.stderr, detail);
+    return 1;
+}

package/dist/commands/local-args-tower-image.js

@@ -0,0 +1,48 @@
+/**
+ * `cockpit image` argument parsing (BLI-16977).
+ *
+ *   cockpit image describe <file> [--session <id>] [--json]
+ *   cockpit image show <sha256-or-prefix> [--json]
+ *
+ * Tower swaps the base64 pictures inside collected transcripts for a short written description.
+ * `describe` sends one image file through that same door by hand; `show` looks a description up by
+ * the sha256 (or the 16-character prefix a marker in a transcript carries).
+ */
+import { ImageHashQuerySchema } from "@bli-cockpit/telemetry-core";
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const ONE_VERB = "image takes one verb: describe or show. Example: `cockpit image describe screenshot.png` or `cockpit image show ab12cd34ef567890`.";
+const SESSION_ID_MAX_CHARS = 200;
+export function parseImageArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--session", "--home", "--dashboard-url", "--json"],
+        valueFlags: ["--session", "--home", "--dashboard-url"],
+    });
+    const [verb, ...rest] = values.positionals;
+    if (verb !== "describe" && verb !== "show")
+        throw new Error(ONE_VERB);
+    if (rest.length !== 1) {
+        throw new Error(verb === "describe" ? "`cockpit image describe` takes exactly one image file." : "`cockpit image show` takes exactly one sha256 (or its first 12 or more characters).");
+    }
+    const session = optionalNonEmpty(values.flags.get("--session"));
+    if (session !== undefined && verb !== "describe")
+        throw new Error("--session does not belong to `cockpit image show`.");
+    if (session !== undefined && session.length > SESSION_ID_MAX_CHARS)
+        throw new Error(`--session is at most ${SESSION_ID_MAX_CHARS} characters.`);
+    const common = {
+        kind: "image",
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+    if (verb === "describe")
+        return { ...common, action: "describe", file: rest[0], ...(session ? { session } : {}) };
+    return { ...common, action: "show", sha256: readHashQuery(rest[0]) };
+}
+/** A marker is pasted whole as often as not (`sha256:ab12…`), so accept that spelling and trim it. */
+function readHashQuery(typed) {
+    const cleaned = typed.trim().replace(/^sha256:/i, "").replace(/…$|\.\.\.$/, "").toLowerCase();
+    const checked = ImageHashQuerySchema.safeParse(cleaned);
+    if (!checked.success)
+        throw new Error("An image hash is 12 to 64 hex characters, like ab12cd34ef567890 (the 16 characters inside a transcript's [image sha256:…] marker).");
+    return checked.data;
+}

package/dist/commands/local-args-tower.js

@@ -43,6 +43,7 @@ export { parseUsageArgs } from "./local-args-tower-usage.js";
 export { parseLogsArgs } from "./local-args-tower-logs.js";
 export { parseBrainArgs } from "./local-args-tower-brain.js";
 export { parseApprovalsArgs } from "./local-args-tower-approvals.js";
+export { parseImageArgs } from "./local-args-tower-image.js";
 export { parseCareersArgs } from './local-args-tower-careers.js';
 export { parseRenameArgs } from './local-args-tower-rename.js';
 export { parseGlossaryArgs } from "./glossary.js";

package/dist/commands/local-args.js

@@ -19,7 +19,7 @@ import { parseGlossaryArgs } from "./glossary.js";
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseApprovalsArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseApprovalsArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -146,6 +146,8 @@ export function parseLocalArgs(argv) {
             return parseBrainArgs(argv.slice(1));
         case "approvals":
             return parseApprovalsArgs(argv.slice(1));
+        case "image":
+            return parseImageArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }

package/dist/commands/local-command-shapes-image.js

@@ -0,0 +1,5 @@
+/**
+ * `cockpit image` command shape (BLI-16977), beside `local-command-shapes-approvals.ts` for the
+ * same reason: `local-command-shapes.ts` sits at the readability ceiling.
+ */
+export {};

package/dist/commands/local-help-commands-tower-ops.js

@@ -89,6 +89,20 @@ export const TOWER_OPS_COMMAND_HELP = [
             "approvals_edit, approvals_reject, approvals_rules, approvals_rules_create, approvals_rules_revoke.",
         ],
     ],
+    [
+        "image",
+        [
+            "Usage: cockpit image describe <file> [--session <id>] [--dashboard-url <url>] [--json]",
+            "       cockpit image show <sha256-or-prefix> [--dashboard-url <url>] [--json]",
+            "",
+            "Tower swaps the base64 pictures inside collected transcripts for a short written description kept against the image's sha256.",
+            "  describe   send one PNG, JPEG, GIF or WebP file (up to 3 MB) to the describe door; prints the description and the marker a transcript would carry",
+            "  show       look a stored description up by its sha256, or the first 12 to 64 characters of it (a marker carries 16)",
+            "A file that is too large or not an image is refused here by name, before anything is sent. An image Tower already described answers from storage.",
+            "--json writes the door's body to stdout and nothing else; a refusal is { ok: false, error, detail } and exits 1.",
+            "The bli-tower MCP server has the twins: image_describe, image_show.",
+        ],
+    ],
     [
         "github",
         [

package/dist/commands/local-help.js

@@ -87,6 +87,7 @@ export const rootCommandNames = new Set([
     "logs",
     "brain",
     "approvals",
+    "image",
     ...SURFACE_ALIASES.keys(),
 ]);
 /** Public names omit compatibility spellings while the router keeps accepting them. */
@@ -147,6 +148,7 @@ export function localCommandHelp(command) {
         "  cockpit logs <collector|dashboard|railway|railway:<service>|-> [--since 15m|1h|2d|<iso>] [--raw <template-id> [--limit <n>]] [--all-levels] [--table <file>] [--json]",
         "  cockpit brain status [--project <id>] [--show open|running|needs_human|fixed|not_actionable|cleared] [--dashboard-url <url>] [--json]",
         "  cockpit approvals [list|show <id>|create|approve <id> [--edit]|edit <id> [--approve]|reject <id>|rules [--active true|false]|rules create <card-id> [--any-audience] [--label <text>]|rules revoke <rule-id> [--reason <text>]] [--status <s>] [--limit <n>] [--before <cursor>] [--dashboard-url <url>] [--json]",
+        "  cockpit image <describe <file> [--session <id>]|show <sha256-or-prefix>> [--dashboard-url <url>] [--json]",
         "  cockpit setup [--since <7d|30d|date>] [--details] [--person <name|email>] [--compare <name,name>] [--json]",
         "  cockpit usage sessions [--person <exact-name>] [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--tool claude|codex] [--since <window>] [--until <iso>] [--cursor <cursor>] [--limit <n>] [--json]",
         "  cockpit usage session <id> [--from-window <n>] [--json]",

package/dist/commands/local.js

@@ -55,6 +55,7 @@ import { runUsage } from "./usage.js";
 import { runSpeed } from "./speed.js";
 import { runLogs } from "./logs.js";
 import { runApprovals } from "./approvals.js";
+import { runImage } from "./image.js";
 import { runBrain } from "./brain.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
@@ -233,14 +234,11 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
                 return await runMsg(command, io);
             case "issue":
                 return await runIssue(command, io);
-            case "cal":
-                return runCal(command, io);
+            case "cal": return runCal(command, io);
             case "mail":
                 return await runMail(command, io);
-            case "project":
-                return await runProject(command, io);
-            case "search":
-                return await runSearch(command, io);
+            case "project": return await runProject(command, io);
+            case "search": return await runSearch(command, io);
             case "github":
                 return await runGithub(command, io);
             case "release":
@@ -253,6 +251,7 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
             case "logs": return await runLogs(command, io);
             case "brain": return await runBrain(command, io);
             case "approvals": return await runApprovals(command, io);
+            case "image": return await runImage(command, io);
         }
     }
     catch (error) {

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.204");
+    writeLine(io?.stdout ?? process.stdout, "0.2.206");
     return 0;
   }
 

package/dist/image-describe-client.js

@@ -0,0 +1,62 @@
+/**
+ * The collector's one call to the image describe door (BLI-16977).
+ *
+ * POST /api/ambient/images takes one distinct image and answers with its stored description. This
+ * file sends it and reads the answer; it decides nothing about WHICH images to send (that is
+ * `image-description-session.ts`). A refusal keeps the server's own reason label, so a failure in
+ * the log names its cause instead of "failed".
+ *
+ * Metadata only leaves this module: hashes, sizes, status codes and reason labels. Never image
+ * bytes, never a description.
+ */
+import { ImageDescribeResponseSchema, } from "@bli-cockpit/telemetry-core";
+import { describeError } from "./health-detail.js";
+import { safeFailureDetail } from "./evidence-upload-transport.js";
+import { noteSyncProgress } from "./sync-lock.js";
+const REQUEST_TIMEOUT_MS = 60_000;
+const MAX_ATTEMPTS = 2;
+const RETRY_DELAY_MS = 500;
+export async function postImageToDescribeDoor(options, request) {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let last = { ok: false, reason: "transport_error", httpStatus: 0, permanent: false };
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+        try {
+            const response = await options.fetchImpl(`${options.dashboardUrl}/api/ambient/images`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${options.deviceToken}`, "Content-Type": "application/json" },
+                body: JSON.stringify(request),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const body = await readJson(response);
+            noteSyncProgress();
+            if (response.ok) {
+                const parsed = ImageDescribeResponseSchema.safeParse(body);
+                if (parsed.success)
+                    return { ok: true, status: parsed.data.status };
+                return { ok: false, reason: "describe_response_unreadable", httpStatus: response.status, permanent: false };
+            }
+            const reason = safeFailureDetail(body) ?? `http_${response.status}`;
+            last = { ok: false, reason, httpStatus: response.status, permanent: response.status >= 400 && response.status < 500 && response.status !== 429 && response.status !== 401 };
+            if (last.permanent || response.status === 401)
+                return last;
+        }
+        catch (error) {
+            console.error("[image-describe] request failed before a status came back", JSON.stringify({ reason: "transport_error", attempt, max_attempts: MAX_ATTEMPTS, sha256_prefix: request.sha256.slice(0, 16), ...describeError(error) }));
+            last = { ok: false, reason: "transport_error", httpStatus: 0, permanent: false };
+        }
+        if (attempt < MAX_ATTEMPTS)
+            await sleep(RETRY_DELAY_MS * attempt);
+    }
+    return last;
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/image-description-session.js

@@ -0,0 +1,178 @@
+/**
+ * One sync's handling of the images inside transcripts (BLI-16977).
+ *
+ * `prepareTranscript` takes a transcript's text just before it is masked and staged and does four
+ * things, in this order:
+ *
+ *  1. FIND every embedded image (`transcript-images.ts` in telemetry-core) and group them by sha256.
+ *  2. DESCRIBE each distinct image that this machine has not already sent: one POST per image to
+ *     the describe door, a few at a time, inside a per-sync count and time budget. The state file
+ *     remembers what was sent, so a screenshot that appears in 40 turns, or in 3 sessions, is sent
+ *     once. A failure never fails the transcript.
+ *  3. REPLACE, only when the one switch (`IMAGE_HANDLING_MODE` in telemetry-core) says
+ *     `describe_and_drop`: every image whose description is stored becomes its short marker. An
+ *     image with no stored description is KEPT. In `describe_and_keep` (the default) the text
+ *     comes back byte for byte as it went in.
+ *  4. SLIM, only in `describe_and_drop`: the slim transcript (src/slim/): the duplicate copies and
+ *     the bookkeeping go, every line stays. In `describe_and_keep` the slim form is not computed
+ *     and not uploaded.
+ *
+ * Metadata only in the logs: counts, sizes, hashes, reason labels. Never image bytes, never a
+ * description.
+ */
+import { IMAGE_DESCRIBE_MAX_BYTES, IMAGE_HANDLING_MODE, base64Of, findEmbeddedImages, replaceImagesWithMarkers, } from "@bli-cockpit/telemetry-core";
+import { postImageToDescribeDoor } from "./image-describe-client.js";
+import { slimOrKeep } from "./slim/slim-transcript.js";
+import { imageStateKey, readDescribedImageKeys, writeDescribedImageKeys, } from "./image-description-state.js";
+/** New images sent to the door in one sync (all worktrees together). */
+export const IMAGE_DESCRIBE_MAX_PER_RUN = 100;
+/** After this long in one sync, remaining images wait for the next tick. */
+export const IMAGE_DESCRIBE_MAX_RUN_MS = 120_000;
+const CONCURRENCY = 3;
+const TAG = "[image-descriptions]";
+export async function openImageDescriptions(options) {
+    const mode = options.mode ?? IMAGE_HANDLING_MODE;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const described = new Set(await readDescribedImageKeys(options.stateDir));
+    const orderedKeys = [...described];
+    const settledThisRun = new Map();
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const maxPerRun = options.maxPerRun ?? IMAGE_DESCRIBE_MAX_PER_RUN;
+    const maxRunMs = options.maxRunMs ?? IMAGE_DESCRIBE_MAX_RUN_MS;
+    let sentThisRun = 0;
+    const markDescribed = (sha256) => {
+        const key = imageStateKey(sha256);
+        if (described.has(key))
+            return;
+        described.add(key);
+        orderedKeys.push(key);
+    };
+    async function sendOne(image, text, input) {
+        sentThisRun += 1;
+        const outcome = await postImageToDescribeDoor({ fetchImpl, dashboardUrl: options.dashboardUrl, deviceToken: options.deviceToken, sleep: options.sleep }, {
+            schema_version: "image-describe.v1",
+            sha256: image.sha256,
+            media_type: image.mediaType,
+            byte_size: image.byteSize,
+            content_base64: base64Of(text, image),
+            source: input.source,
+            session_id: input.sessionId.slice(0, 200),
+        });
+        if (outcome.ok) {
+            markDescribed(image.sha256);
+            settledThisRun.set(image.sha256, outcome.status);
+            return;
+        }
+        settledThisRun.set(image.sha256, `failed:${outcome.reason}`);
+    }
+    async function describeAndReplace(input) {
+        const images = findEmbeddedImages(input.text);
+        if (images.length === 0)
+            return { text: input.text, imageCount: 0, uniqueCount: 0, replacedCount: 0, charsSaved: 0 };
+        const unique = new Map();
+        for (const image of images)
+            if (!unique.has(image.sha256))
+                unique.set(image.sha256, image);
+        const counts = { already: 0, described_now: 0, known: 0, too_large: 0, over_budget: 0, failed: 0 };
+        const failedReasons = {};
+        const toSend = [];
+        for (const image of unique.values()) {
+            if (described.has(imageStateKey(image.sha256))) {
+                counts.already += 1;
+                continue;
+            }
+            const earlier = settledThisRun.get(image.sha256);
+            if (earlier)
+                continue;
+            if (image.byteSize > IMAGE_DESCRIBE_MAX_BYTES) {
+                settledThisRun.set(image.sha256, "too_large");
+                counts.too_large += 1;
+                continue;
+            }
+            toSend.push(image);
+        }
+        let next = 0;
+        const worker = async () => {
+            while (next < toSend.length) {
+                const image = toSend[next++];
+                if (sentThisRun >= maxPerRun || now() - startedAt > maxRunMs) {
+                    counts.over_budget += 1;
+                    continue;
+                }
+                await sendOne(image, input.text, input);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(CONCURRENCY, toSend.length) }, worker));
+        for (const image of toSend) {
+            const settled = settledThisRun.get(image.sha256);
+            if (settled === "described")
+                counts.described_now += 1;
+            else if (settled === "known")
+                counts.known += 1;
+            else if (settled?.startsWith("failed:")) {
+                counts.failed += 1;
+                const reason = settled.slice("failed:".length);
+                failedReasons[reason] = (failedReasons[reason] ?? 0) + 1;
+            }
+        }
+        if (counts.described_now + counts.known > 0)
+            await writeDescribedImageKeys(options.stateDir, orderedKeys);
+        const replaced = mode === "describe_and_drop"
+            ? replaceImagesWithMarkers(input.text, images, (image) => described.has(imageStateKey(image.sha256)))
+            : { text: input.text, replacedCount: 0, charsSaved: 0 };
+        console.error(TAG + " transcript prepared", JSON.stringify({
+            mode,
+            source: input.source,
+            images: images.length,
+            unique: unique.size,
+            ...counts,
+            failed_reasons: failedReasons,
+            replaced: replaced.replacedCount,
+            chars_saved: replaced.charsSaved,
+            kept_without_description: mode === "describe_and_drop" ? images.length - replaced.replacedCount : 0,
+        }));
+        return {
+            text: replaced.text,
+            imageCount: images.length,
+            uniqueCount: unique.size,
+            replacedCount: replaced.replacedCount,
+            charsSaved: replaced.charsSaved,
+        };
+    }
+    return {
+        mode,
+        async prepareTranscript(input) {
+            const afterImages = await describeAndReplace(input);
+            if (mode !== "describe_and_drop")
+                return { ...afterImages, text: input.text, changed: false, slim: null };
+            const slim = slimOrKeep(afterImages.text, input.source, { sessionId: input.sessionId });
+            return { ...afterImages, text: slim.text, changed: slim.text !== input.text, slim: slim.stats };
+        },
+    };
+}
+/**
+ * The image step for one build of an envelope. When a sync-wide budget is shared across worktrees
+ * the session lives on it (one count budget and one state file for the whole sync); otherwise this
+ * build gets its own. A failure to open it is logged by name and the transcripts simply go up as
+ * they are.
+ */
+export async function openImageStepForSync(options) {
+    if (options.budget?.images)
+        return options.budget.images;
+    try {
+        const session = await openImageDescriptions({
+            stateDir: options.stateDir,
+            dashboardUrl: options.dashboardUrl,
+            deviceToken: options.deviceToken,
+            fetchImpl: options.fetchImpl,
+        });
+        if (options.budget)
+            options.budget.images = session;
+        return session;
+    }
+    catch (error) {
+        console.error(TAG + " could not open, transcripts upload with their images", JSON.stringify({ reason: "image_step_unavailable", error_name: error instanceof Error ? error.name : typeof error }));
+        return undefined;
+    }
+}