@gentbajko/slopify 2.0.2 → 2.1.0

package/dist/adapters/image/fal.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noImage, unreadable } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
 // The HTTP gateway adapter for fal.ai: `fetch` and the downloader beside this file, no SDK.
@@ -88,12 +89,12 @@ export function falImage(deps) {
             refused(answer, req.prompt);
             const first = answer.images[0];
             if (first === undefined) {
-                throw providerError({ kind: "other", message: "fal answered with no image" });
+                throw providerError({ kind: "other", message: noImage("fal.ai") });
             }
             // The download rides inside the attempt: a link that 404s is a failed attempt.
             return await downloadImage({
                 fetch: deps.fetch,
-                provider: "fal",
+                provider: "fal.ai",
                 url: first.url,
                 signal: req.signal,
             });
@@ -104,7 +105,7 @@ function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no fal key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("fal.ai") });
     }
     return key;
 }
@@ -116,7 +117,7 @@ function refused(answer, prompt) {
     if (flags.length > 0 && flags.every((flagged) => flagged)) {
         throw providerError({
             kind: "refusal",
-            message: `fal's safety checker rejected every image for this prompt: ${redact(prompt)}`,
+            message: `fal.ai's safety checker blocked the image for this prompt: "${redact(prompt)}". Reword the image prompt in the Images section of Edit project, or choose another image provider in its Providers section.`,
         });
     }
 }
@@ -140,7 +141,12 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `fal answered ${String(response.status)}: ${message}`,
+        message: httpFailure({
+            provider: "fal.ai",
+            status: response.status,
+            detail: message,
+            subject: "image request",
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -160,7 +166,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "fal's answer was not in the shape this app can read",
+            message: unreadable("fal.ai"),
         });
     }
     return parsed.data;

package/dist/adapters/image/google.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noImage, quoted, refusedImage, unreadable } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
 import { discoverGoogleImages } from "./models.js";
@@ -92,7 +93,7 @@ function imageOf(answer) {
             }
         }
     }
-    throw providerError({ kind: "other", message: "Google answered with no image" });
+    throw providerError({ kind: "other", message: noImage("Google") });
 }
 // The bytes arrive with the call. They are still sniffed rather than trusted: what the port
 // stores is a PNG or a JPEG, and a truncated payload that decodes to something else must
@@ -104,7 +105,7 @@ function decode(part) {
         const claimed = part.mime_type ?? "nothing";
         throw providerError({
             kind: "other",
-            message: `Google called it ${claimed} but it decoded to ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+            message: `Google sent back something that is not a PNG or JPEG image (labelled ${claimed}, but ${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };
@@ -113,7 +114,7 @@ function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no Google key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("Google") });
     }
     return key;
 }
@@ -155,12 +156,21 @@ async function failure(response) {
         ? parsed.data.error.details?.find((one) => one["@type"] === "type.googleapis.com/google.rpc.RetryInfo")?.retryDelay
         : undefined;
     const retryAfterMs = retryAfter(response.headers.get("retry-after")) ?? googleRetryDelay(delay, message);
-    const guidance = kind === "unsupported"
-        ? "Google reports zero image quota for this model. Check the API key's project, billing and model quota in Google AI Studio, or choose another image provider. Retrying will not help until quota is available. "
-        : "";
+    const detail = message || response.statusText;
     return providerError({
         kind,
-        message: `${guidance}Google answered ${String(response.status)}: ${message || response.statusText}`,
+        message: kind === "unsupported"
+            ? `Google gives this API key no image quota for this model${quoted(`error ${String(response.status)}`, detail)}. Retrying will not help: turn on billing for the key's project in Google AI Studio, or choose another image provider in the Providers section of Edit project.`
+            : // PERMISSION_DENIED and FAILED_PRECONDITION also cover keys without access, billing
+                // and region limits, so they read as a content refusal only when Google says so.
+                kind === "refusal" && refusalWords.test(message)
+                    ? refusedImage("Google", detail)
+                    : httpFailure({
+                        provider: "Google",
+                        status: response.status,
+                        detail,
+                        subject: "image request",
+                    }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -177,7 +187,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "Google's answer was not in the shape this app can read",
+            message: unreadable("Google"),
         });
     }
     return parsed.data;

package/dist/adapters/image/models.js

@@ -64,9 +64,15 @@ export async function discoverGoogleImages(deps) {
 function requireKey(deps) {
     const key = deps.key();
     if (key === undefined || key === "")
-        throw providerError({ kind: "missing_key", message: "Save an API key to load models." });
+        throw providerError({
+            kind: "missing_key",
+            message: "Save this provider's API key in Settings → Providers to load its models.",
+        });
     return key;
 }
 function unavailable() {
-    return providerError({ kind: "other", message: "The provider model list could not be loaded." });
+    return providerError({
+        kind: "other",
+        message: "Slopify could not load this provider's model list. Check the API key in Settings → Providers and your internet connection, then refresh the list.",
+    });
 }

package/dist/adapters/image/openai.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noImage, refusedImage, unreadable } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
 import { discoverOpenAiImages } from "./models.js";
@@ -72,7 +73,7 @@ export function openAiImage(deps) {
             }
             const first = parse(await response.text()).data[0]?.b64_json;
             if (first === undefined || first === null || first === "") {
-                throw providerError({ kind: "other", message: "OpenAI answered with no image" });
+                throw providerError({ kind: "other", message: noImage("OpenAI") });
             }
             return decode(first);
         },
@@ -87,7 +88,7 @@ function decode(b64) {
     if (mime === undefined) {
         throw providerError({
             kind: "other",
-            message: `OpenAI's image decoded to ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+            message: `OpenAI sent back something that is not a PNG or JPEG image (${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };
@@ -96,7 +97,7 @@ function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no OpenAI image key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("OpenAI") });
     }
     return key;
 }
@@ -122,9 +123,17 @@ async function failure(response) {
     // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(parsed.success ? parsed.data.error.message : text.trim() || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+    const kind = kindOf(response.status, parsed.success ? parsed.data.error.code : undefined);
     return providerError({
-        kind: kindOf(response.status, parsed.success ? parsed.data.error.code : undefined),
-        message: `OpenAI answered ${String(response.status)}: ${message}`,
+        kind,
+        message: kind === "refusal"
+            ? refusedImage("OpenAI", message)
+            : httpFailure({
+                provider: "OpenAI",
+                status: response.status,
+                detail: message,
+                subject: "image request",
+            }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -133,7 +142,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "OpenAI's answer was not in the shape this app can read",
+            message: unreadable("OpenAI"),
         });
     }
     return parsed.data;

package/dist/adapters/image/replicate.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noImage, providerSaid, refusedImage, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
 // The HTTP gateway adapter for Replicate: `fetch`, the injected clock and the downloader
@@ -81,7 +82,7 @@ async function settle(deps, first, signal) {
         if (next === undefined) {
             throw providerError({
                 kind: "other",
-                message: `Replicate left the prediction ${current.status} and named no address to read it from`,
+                message: unreadable("Replicate"),
             });
         }
         await deps.clock.sleep(replicatePollMs, signal);
@@ -100,7 +101,7 @@ function outputOf(current) {
     const output = current.output;
     const url = typeof output === "string" ? output : output?.[0];
     if (url === undefined || url === "") {
-        throw providerError({ kind: "other", message: "Replicate succeeded with no image" });
+        throw providerError({ kind: "other", message: noImage("Replicate") });
     }
     return url;
 }
@@ -114,16 +115,19 @@ function declined(current) {
     // ceiling: read off the sentence, because a failed prediction carries no machine-readable
     // reason. A phrase the list does not know costs the user three more images; the upgrade
     // is a structured field, when Replicate ships one.
+    const refusal = refusalWords.test(message);
     return providerError({
-        kind: refusalWords.test(message) ? "refusal" : "other",
-        message: `Replicate answered: ${message}`,
+        kind: refusal ? "refusal" : "other",
+        message: refusal
+            ? refusedImage("Replicate", message)
+            : providerSaid("Replicate", "could not make the image", message, "Use Retry stage; if it keeps happening, reword the image prompt in the Images section of Edit project or choose another image model in its Providers section."),
     });
 }
 function auth(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no Replicate key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("Replicate") });
     }
     return { Authorization: `Bearer ${key}` };
 }
@@ -149,7 +153,12 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `Replicate answered ${String(response.status)}: ${message || response.statusText}`,
+        message: httpFailure({
+            provider: "Replicate",
+            status: response.status,
+            detail: message || response.statusText,
+            subject: "image request",
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -158,7 +167,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "Replicate's answer was not in the shape this app can read",
+            message: unreadable("Replicate"),
         });
     }
     return parsed.data;

package/dist/adapters/llm/claude-code-models.js

@@ -38,7 +38,7 @@ const responseSchema = z.object({
 });
 const supportedEfforts = ["low", "medium", "high", "xhigh"];
 function unavailable() {
-    return new Error("Claude Code model discovery is unavailable. Refresh the list or enter an exact model ID.");
+    return new Error("Slopify could not get the model list from the Claude Code CLI. Check the CLI is installed and signed in (Settings → Providers), then refresh the list, or type an exact model ID.");
 }
 function discoveryEnv() {
     const names = [

package/dist/adapters/llm/claude-code.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliReported, commandOf } from "../explain.js";
 import { nodeClaudeCodeModels } from "./claude-code-models.js";
 import { cliLoginError } from "./cli-login-error.js";
 import { documentToolName, documentWorkspace, } from "./document-workspace.js";
-import { cliEvent, cliInput, cliShaped, endedWithout, promptOf, stopCliRun } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 // The local-agent adapter for Claude Code: spawned non-interactively, authenticated by the
 // CLI's own login, no key anywhere in this file. Readiness is not computed here - `adapters/**`
@@ -142,7 +143,7 @@ export function claudeCodeLlm(deps) {
                 catch {
                     throw providerError({
                         kind: "unavailable",
-                        message: "The full prompt could not be delivered to Claude Code. Review before retrying.",
+                        message: "Slopify could not hand the whole prompt to the Claude Code CLI, so it cannot tell what the CLI worked on (it may already have used your quota). Use Retry stage to run it again.",
                     });
                 }
                 if (result.is_error === true || result.subtype !== "success") {
@@ -151,7 +152,7 @@ export function claudeCodeLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: kindOf(result.api_error_status ?? null),
-                        message: redact(result.result ?? result.subtype),
+                        message: cliReported(binary, redact(result.result ?? result.subtype), nextStep(binary, result.api_error_status ?? null)),
                     });
                 }
                 documents?.verifyRead();
@@ -188,15 +189,13 @@ export function claudeCodeLlm(deps) {
         req.signal.throwIfAborted();
         // The stream ended with no result event at all.
         if (!run)
-            throw new Error("Claude Code could not be started.");
+            throw new Error("The Claude Code CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.");
         const login = cliLoginError("claude-code", run.stderr());
         if (login)
             throw login;
         throw providerError({
             kind: "other",
-            message: ended === undefined
-                ? `the ${binary} CLI did not stop after forced termination`
-                : endedWithout(binary, ended, run.stderr()),
+            message: ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()),
         });
     }
     return {
@@ -218,6 +217,16 @@ function kindOf(status) {
     }
     return "other";
 }
+// What most often fixes the upstream status the CLI passed on.
+function nextStep(binary, status) {
+    if (status === 401 || status === 403)
+        return `Run "${commandOf(binary)} auth login" in a terminal to sign in again, then use Retry stage.`;
+    if (status === 429)
+        return "Your Claude usage limit may be used up: wait until it resets, then use Retry stage.";
+    if (status === 404)
+        return "The chosen model may not exist or not be available to your account: choose another in the Providers section of Edit project, then use Retry stage.";
+    return cliCheck(binary);
+}
 // `modelUsage` is keyed by model id and a run may touch more than one - a fallback model,
 // a sub-agent - so the counts are summed. An empty object means the CLI reported none.
 function usageOf(usage) {

package/dist/adapters/llm/cli-login-error.js

@@ -1,4 +1,5 @@
 import { providerError } from "../../kernel/ports/model.js";
+import { cliName } from "../explain.js";
 export function cliLoginError(provider, text) {
     if (/invalid api key/i.test(text))
         return undefined;
@@ -11,6 +12,6 @@ export function cliLoginError(provider, text) {
             : "codex login";
     return providerError({
         kind: "missing_key",
-        message: `${provider}: sign in on the machine running the CLI with ${command}, then review the affected rebuild.`,
+        message: `The ${cliName(provider)} is not signed in, or its sign-in has expired. Open a terminal on the computer running the CLI, run "${command}" and sign in, then use Retry stage.`,
     });
 }

package/dist/adapters/llm/codex-models.js

@@ -58,7 +58,7 @@ export async function nodeCodexModels(env = process.env, binary = "codex", timeo
         }
         catch {
             // Do not expose cache contents, home paths or raw JSON errors to the browser.
-            throw new Error("Codex model metadata is unavailable. Check the CLI and refresh, or enter a custom model ID.");
+            throw new Error("Slopify could not get the model list from the Codex CLI. Check the CLI is installed and signed in (Settings → Providers), then refresh the list, or type an exact model ID.");
         }
     }
 }

package/dist/adapters/llm/codex.js

@@ -4,10 +4,11 @@ import { join } from "node:path";
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliReported } from "../explain.js";
 import { cliLoginError } from "./cli-login-error.js";
 import { nodeCodexModels } from "./codex-models.js";
 import { documentServerName, documentTool, documentWorkspace, } from "./document-workspace.js";
-import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 // The local-agent adapter for the Codex CLI. Same shape as Claude Code's and a different
 // vocabulary: Codex writes a JSONL thread of `thread.started`, `item.*` and `turn.*`
@@ -164,7 +165,7 @@ export function codexLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: "other",
-                        message: redact(cliShaped(binary, turnFailed, event.value).error.message),
+                        message: cliReported(binary, redact(cliShaped(binary, turnFailed, event.value).error.message), cliCheck(binary)),
                     });
                 }
                 if (event.type === "error") {
@@ -173,7 +174,7 @@ export function codexLlm(deps) {
                         throw login;
                     throw providerError({
                         kind: "other",
-                        message: redact(cliShaped(binary, errorEvent, event.value).message),
+                        message: cliReported(binary, redact(cliShaped(binary, errorEvent, event.value).message), cliCheck(binary)),
                     });
                 }
             }
@@ -202,9 +203,7 @@ export function codexLlm(deps) {
             throw login;
         throw providerError({
             kind: "other",
-            message: ended === undefined
-                ? `the ${binary} CLI did not stop after forced termination`
-                : endedWithout(binary, ended, run.stderr()),
+            message: ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()),
         });
     }
     return {

package/dist/adapters/llm/document-workspace.js

@@ -16,7 +16,7 @@ export function documentWorkspace(input) {
     if (!parsed.success)
         throw providerError({
             kind: "unsupported",
-            message: "Research documents are invalid or exceed the supported request size. No document was truncated.",
+            message: "The research notes are too large, or not in a form the AI model can be given, so nothing was sent. Make the inputs shorter in Edit project, then use Retry stage; if it keeps happening, use Download diagnostics in Settings and report it.",
         });
     const documents = parsed.data;
     const directory = mkdtempSync(join(tmpdir(), "slopify-documents-"));
@@ -82,6 +82,6 @@ export function documentWorkspace(input) {
 function unread() {
     return providerError({
         kind: "unavailable",
-        message: "The CLI did not read every research document in full. Review the work before retrying; the provider may have charged for this attempt.",
+        message: "The AI model did not read all of the research notes, so its answer was not used (the attempt may still have used your quota). Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project.",
     });
 }

package/dist/adapters/llm/gemini-models.js

@@ -38,7 +38,7 @@ export async function nodeGeminiModels(binary) {
         throw new Error("No installed model metadata");
     }
     catch {
-        throw new Error("Gemini CLI model metadata is unavailable. Use a documented CLI alias or enter a custom model ID.");
+        throw new Error("Slopify could not get the model list from the Gemini CLI. Check the CLI is installed (Settings → Providers), then refresh the list, or type a model name the Gemini CLI accepts.");
     }
 }
 async function bundledModels(entry) {

package/dist/adapters/llm/gemini-workspace.js

@@ -33,7 +33,7 @@ export function geminiWorkspace(webSearch, request, documents, env = process.env
             catch {
                 throw providerError({
                     kind: "unavailable",
-                    message: "Gemini CLI login settings could not be read. Check its settings.json before retrying.",
+                    message: "Slopify could not read the Gemini CLI's settings file (settings.json in the .gemini folder of your home directory), which says how it signs in. Fix or remove that file, run gemini in a terminal to sign in again, then use Retry stage.",
                 });
             }
         const oauth = join(originalState, "oauth_creds.json");

package/dist/adapters/llm/gemini.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliCheck, cliName, cliReported } from "../explain.js";
 import { documentWorkspace } from "./document-workspace.js";
 import { nodeGeminiModels } from "./gemini-models.js";
 import { geminiWorkspace } from "./gemini-workspace.js";
-import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, } from "./run-cli.js";
+import { cliEvent, cliInput, cliShaped, deliveredInput, endedWithout, promptOf, stopCliRun, stuckCli, } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
 export const geminiBinary = "gemini";
 // Verified against installed Gemini CLI 0.16.0's config/nonInteractiveCli sources.
@@ -65,12 +66,12 @@ export function geminiLlm(deps) {
                 else if (event.type === "error") {
                     const error = cliShaped(binary, errorSchema, event.value);
                     if (error.severity !== "warning")
-                        throw failure(error.message);
+                        throw failure(binary, error.message);
                 }
                 else if (event.type === "result") {
                     const result = cliShaped(binary, resultSchema, event.value);
                     if (result.status !== "success")
-                        throw failure(result.error?.message ?? result.status);
+                        throw failure(binary, result.error?.message ?? result.status);
                     await deliveredInput(run);
                     documents?.verifyRead();
                     yield {
@@ -103,12 +104,10 @@ export function geminiLlm(deps) {
         }
         req.signal.throwIfAborted();
         if (run === undefined)
-            throw failure(`the ${binary} CLI could not be started`);
+            throw failure(binary, "", `The ${cliName(binary)} could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.`);
         if (authRequired(run.stderr()))
             throw authFailure();
-        throw failure(ended === undefined
-            ? `the ${binary} CLI did not stop after forced termination`
-            : endedWithout(binary, ended, run.stderr()));
+        throw failure(binary, run.stderr(), ended === undefined ? stuckCli(binary) : endedWithout(binary, ended, run.stderr()));
     }
     return {
         id: "gemini",
@@ -117,16 +116,21 @@ export function geminiLlm(deps) {
         complete,
     };
 }
-function failure(message) {
+// `message` is what the CLI said, read for the two failures that need the user's hand;
+// `sentence` replaces the default wording when Slopify already knows what happened.
+function failure(binary, message, sentence) {
     if (/(?:#?3501\b|do not have a valid licen[cs]e of this product)/i.test(message)) {
         return providerError({
             kind: "unsupported",
-            message: "Gemini CLI access was denied by Google's license check (#3501). Update Gemini CLI and sign in again. For a managed account, contact your administrator to request a license.",
+            message: "Google refused the Gemini CLI because the signed-in account has no licence for it (#3501). Update the Gemini CLI, run gemini in a terminal to sign in again, then use Retry stage; for a work or school account, ask your administrator for a Gemini licence.",
         });
     }
     return authRequired(message)
         ? authFailure()
-        : providerError({ kind: "other", message: redact(message) });
+        : providerError({
+            kind: "other",
+            message: sentence ?? cliReported(binary, redact(message), cliCheck(binary)),
+        });
 }
 function authRequired(message) {
     return /Code Assist login required|authorize the application|authorization code|Please set an Auth method|re-authenticate|reauthenticate/i.test(message);
@@ -134,7 +138,7 @@ function authRequired(message) {
 function authFailure() {
     return providerError({
         kind: "missing_key",
-        message: "Gemini CLI needs sign-in. Run gemini in your terminal, complete login, then retry in Slopify.",
+        message: 'The Gemini CLI is not signed in, or its sign-in has expired. Open a terminal on the computer running the CLI, run "gemini" and sign in, then use Retry stage.',
     });
 }
 async function* authChecked(source) {

package/dist/adapters/llm/openrouter.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { documentMessages } from "../../kernel/ports/llm-documents.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { droppedStream, httpFailure, missingKey, providerSaid, refreshList, unreadable, } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { sseData } from "./sse-lines.js";
 // The HTTP gateway adapter: the platform's own `fetch` plus the line reader beside this
@@ -62,7 +63,7 @@ export function openRouterLlm(deps) {
             throw await failure(response);
         }
         if (response.body === null) {
-            throw providerError({ kind: "other", message: "OpenRouter answered with no body" });
+            throw providerError({ kind: "other", message: droppedStream("OpenRouter") });
         }
         let usage = null;
         let finishReason = null;
@@ -81,7 +82,7 @@ export function openRouterLlm(deps) {
                 // frame; without this the stage would store half an article as a success.
                 throw providerError({
                     kind: kindOf(statusOf(chunk.error.code)),
-                    message: redact(chunk.error.message),
+                    message: streamFailure(statusOf(chunk.error.code), redact(chunk.error.message)),
                 });
             }
             const choice = chunk.choices?.[0];
@@ -108,7 +109,7 @@ export function openRouterLlm(deps) {
             // Saying so is what stops a truncated answer being stored as a whole one.
             throw providerError({
                 kind: "other",
-                message: "OpenRouter's stream ended before the response was complete",
+                message: droppedStream("OpenRouter"),
             });
         }
         yield { type: "done", usage, finishReason };
@@ -122,13 +123,13 @@ export function openRouterLlm(deps) {
                 headers: headers(deps.key()),
             });
             if (!response.ok) {
-                throw await failure(response);
+                throw await failure(response, refreshList);
             }
             const parsed = modelList.safeParse(await response.json());
             if (!parsed.success) {
                 throw providerError({
                     kind: "other",
-                    message: "OpenRouter's model list was not in the shape this app can read",
+                    message: unreadable("OpenRouter"),
                 });
             }
             // /models defaults to text output. Also reject an explicit non-text row
@@ -146,7 +147,7 @@ function headers(key) {
     // rather than `auth` because the same rule makes it terminal: there is nothing to
     // retry until the user saves a key, and the wrapper is where that is decided.
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no OpenRouter key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("OpenRouter") });
     }
     return { Authorization: `Bearer ${key}`, ...appHeaders };
 }
@@ -163,7 +164,7 @@ function kindOf(status) {
     // error contract first, which is not this adapter's to widen.
     return "other";
 }
-async function failure(response) {
+async function failure(response, next) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
     // The provider's own words, through the redactor - an error body may quote the key back.
@@ -171,10 +172,21 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `OpenRouter answered ${response.status}: ${message}`,
+        message: httpFailure({
+            provider: "OpenRouter",
+            status: response.status,
+            detail: message,
+            next,
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
+// A mid-stream error carries an HTTP-like code; with none, the provider's words are all there is.
+function streamFailure(status, detail) {
+    return status >= 400
+        ? httpFailure({ provider: "OpenRouter", status, detail })
+        : providerSaid("OpenRouter", "stopped part-way through the answer", detail, "Use Retry stage; if it keeps happening, choose another model in the Providers section of Edit project.");
+}
 function statusOf(code) {
     return typeof code === "number" ? code : Number(code ?? 0);
 }
@@ -186,7 +198,7 @@ function parseChunk(data) {
         // a half-written frame is noise, and the wrapper stores whatever is thrown.
         throw providerError({
             kind: "other",
-            message: "OpenRouter sent a stream frame this app could not read",
+            message: unreadable("OpenRouter"),
         });
     }
     return parsed.data;