@bli-cockpit/cli 0.2.207 → 0.2.208

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.207");
+    writeLine(io?.stdout ?? process.stdout, "0.2.208");
     return 0;
   }
 

package/dist/image-description-session.js

@@ -23,7 +23,7 @@
 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, slimTranscript } from "./slim/slim-transcript.js";
-import { imageStateKey, readDescribedImageKeys, writeDescribedImageKeys, } from "./image-description-state.js";
+import { imageStateKey, imageRetryDelayMs, readDescribedImageKeys, readFailedImages, writeImageDescriptionState, } 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. */
@@ -35,6 +35,8 @@ export async function openImageDescriptions(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     const described = new Set(await readDescribedImageKeys(options.stateDir));
     const orderedKeys = [...described];
+    const failedImages = await readFailedImages(options.stateDir);
+    let stateDirty = false;
     const settledThisRun = new Map();
     const now = options.now ?? Date.now;
     const startedAt = now();
@@ -59,12 +61,33 @@ export async function openImageDescriptions(options) {
             source: input.source,
             session_id: input.sessionId.slice(0, 200),
         });
+        const key = imageStateKey(image.sha256);
         if (outcome.ok) {
             markDescribed(image.sha256);
             settledThisRun.set(image.sha256, outcome.status);
+            if (failedImages[key]) {
+                delete failedImages[key];
+                stateDirty = true;
+            }
             return;
         }
         settledThisRun.set(image.sha256, `failed:${outcome.reason}`);
+        rememberFailure(key, outcome);
+    }
+    /**
+     * BLI-16979: the door answered about THIS image and could not describe it (a 4xx such as
+     * `describer_rejected_image`, or a 5xx). Wait before sending the same bytes again, instead of
+     * re-sending them every sync. A transport error, a 401 and a 429 say nothing about the image, so
+     * they are not remembered.
+     */
+    function rememberFailure(key, outcome) {
+        if (outcome.httpStatus < 400 || outcome.httpStatus === 401 || outcome.httpStatus === 429)
+            return;
+        const attempts = (failedImages[key]?.attempts ?? 0) + 1;
+        const delay = imageRetryDelayMs(attempts, outcome.permanent);
+        failedImages[key] = { reason: outcome.reason, attempts, retry_after: now() + delay };
+        stateDirty = true;
+        console.error(TAG + " image not described, will not be re-sent until later", JSON.stringify({ reason: outcome.reason, http_status: outcome.httpStatus, attempts, retry_in_hours: Math.round(delay / 3_600_000), sha256_prefix: key.slice(0, 16) }));
     }
     async function describeAndReplace(input) {
         const images = findEmbeddedImages(input.text);
@@ -74,7 +97,7 @@ export async function openImageDescriptions(options) {
         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 counts = { already: 0, described_now: 0, known: 0, too_large: 0, over_budget: 0, failed: 0, backing_off: 0 };
         const failedReasons = {};
         const toSend = [];
         for (const image of unique.values()) {
@@ -90,6 +113,11 @@ export async function openImageDescriptions(options) {
                 counts.too_large += 1;
                 continue;
             }
+            const earlierFailure = failedImages[imageStateKey(image.sha256)];
+            if (earlierFailure && earlierFailure.retry_after > now()) {
+                counts.backing_off += 1;
+                continue;
+            }
             toSend.push(image);
         }
         let next = 0;
@@ -116,8 +144,10 @@ export async function openImageDescriptions(options) {
                 failedReasons[reason] = (failedReasons[reason] ?? 0) + 1;
             }
         }
-        if (counts.described_now + counts.known > 0)
-            await writeDescribedImageKeys(options.stateDir, orderedKeys);
+        if (counts.described_now + counts.known > 0 || stateDirty) {
+            await writeImageDescriptionState(options.stateDir, { described: orderedKeys, failed: failedImages });
+            stateDirty = false;
+        }
         const replaced = mode === "describe_and_drop"
             ? replaceImagesWithMarkers(input.text, images, (image) => described.has(imageStateKey(image.sha256)))
             : { text: input.text, replacedCount: 0, charsSaved: 0 };

package/dist/image-description-state.js

@@ -35,10 +35,54 @@ export async function readDescribedImageKeys(stateDir) {
         return [];
     }
 }
-export async function writeDescribedImageKeys(stateDir, keys) {
+/** Oldest failures leave first past this many. */
+export const IMAGE_FAILED_STATE_MAX_KEYS = 5_000;
+const HOUR_MS = 3_600_000;
+/** A refusal that repeats for the same bytes (a 4xx): a week, then a month. */
+const PERMANENT_BACKOFF_MS = [7 * 24 * HOUR_MS, 30 * 24 * HOUR_MS];
+/** A failure that may pass (the door or the model was down): 1 h, 6 h, 24 h, then 72 h. */
+const TRANSIENT_BACKOFF_MS = [HOUR_MS, 6 * HOUR_MS, 24 * HOUR_MS, 72 * HOUR_MS];
+/** How long to leave an image alone after its Nth failed attempt. */
+export function imageRetryDelayMs(attempts, permanent) {
+    const steps = permanent ? PERMANENT_BACKOFF_MS : TRANSIENT_BACKOFF_MS;
+    return steps[Math.min(Math.max(attempts, 1), steps.length) - 1];
+}
+/** The failures on record, key to record. A missing or unreadable file is an empty map, said out loud when unreadable. */
+export async function readFailedImages(stateDir) {
+    try {
+        const raw = (await readJsonFile(imageDescriptionStatePath(stateDir)));
+        if (!raw?.failed || typeof raw.failed !== "object" || Array.isArray(raw.failed))
+            return {};
+        const kept = {};
+        for (const [key, value] of Object.entries(raw.failed)) {
+            const record = value;
+            if (key.length !== KEY_CHARS || !record)
+                continue;
+            if (typeof record.reason !== "string" || typeof record.attempts !== "number" || typeof record.retry_after !== "number")
+                continue;
+            kept[key] = { reason: record.reason, attempts: record.attempts, retry_after: record.retry_after };
+        }
+        return kept;
+    }
+    catch (error) {
+        if (!isMissingFileFailure(error)) {
+            console.error("[image-descriptions] failed-image list unreadable, starting from an empty list", JSON.stringify({ reason: "image_failed_state_unreadable" }));
+        }
+        return {};
+    }
+}
+export async function writeImageDescriptionState(stateDir, state) {
+    const keys = state.described;
     const kept = keys.length > IMAGE_DESCRIPTION_STATE_MAX_KEYS ? keys.slice(keys.length - IMAGE_DESCRIPTION_STATE_MAX_KEYS) : keys;
+    const failedEntries = Object.entries(state.failed).sort((a, b) => a[1].retry_after - b[1].retry_after);
+    const failed = Object.fromEntries(failedEntries.slice(Math.max(0, failedEntries.length - IMAGE_FAILED_STATE_MAX_KEYS)));
     await writeJsonFile(imageDescriptionStatePath(stateDir), {
         schema_version: "cockpit-image-descriptions.v1",
         described: kept,
+        failed,
     });
+}
+/** Writes the described list and keeps whatever failures are on record. */
+export async function writeDescribedImageKeys(stateDir, keys) {
+    await writeImageDescriptionState(stateDir, { described: keys, failed: await readFailedImages(stateDir) });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.207",
+  "version": "0.2.208",
   "private": false,
   "type": "module",
   "bin": {