ima2-gen 3.20.0 → 3.21.0

package/lib/codexBackend/normalize.js

@@ -0,0 +1,141 @@
+/**
+ * Pure request/response transforms for the Codex backend. No I/O here, so each rule is
+ * unit-testable on its own.
+ */
+export const RESPONSES_LITE_HEADER = "x-openai-internal-codex-responses-lite";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Plain strings and string-content messages become the typed content parts the backend expects. */
+export function normalizeInput(input) {
+    if (typeof input === "string")
+        return [{ role: "user", content: [{ type: "input_text", text: input }] }];
+    if (!Array.isArray(input))
+        return [];
+    return input.map((item) => {
+        if (!isRecord(item) || typeof item.content !== "string" || typeof item.role !== "string")
+            return item;
+        const type = item.role === "assistant" ? "output_text" : "input_text";
+        return { ...item, content: [{ type, text: item.content }] };
+    });
+}
+/**
+ * Shape a Responses body for the Codex backend. Lite models (catalog \`use_responses_lite\`, which
+ * includes every GPT-6 model) take tools as an \`additional_tools\` developer item, instructions as
+ * a developer message, \`reasoning.context: "all_turns"\`, and no parallel tool calls.
+ */
+export function normalizeResponsesBody(body, lite) {
+    const out = { ...body, input: normalizeInput(body.input), store: false, stream: true };
+    const instructions = typeof body.instructions === "string" ? body.instructions : "";
+    if (!lite) {
+        out.instructions = instructions;
+        return out;
+    }
+    const prefix = [];
+    const tools = Array.isArray(body.tools) ? body.tools : [];
+    if (tools.length)
+        prefix.push({ type: "additional_tools", role: "developer", tools });
+    if (instructions)
+        prefix.push({ role: "developer", content: [{ type: "input_text", text: instructions }] });
+    out.input = [...prefix, ...out.input];
+    out.instructions = "";
+    out.parallel_tool_calls = false;
+    out.reasoning = { ...(isRecord(body.reasoning) ? body.reasoning : {}), context: "all_turns" };
+    delete out.tools;
+    // A named tool_choice points at \`tools\`, which lite requests no longer carry.
+    if (isRecord(out.tool_choice))
+        delete out.tool_choice;
+    return out;
+}
+/** Chat Completions → Responses, for the JSON planners that still speak chat. */
+export function chatToResponsesBody(body) {
+    const messages = Array.isArray(body.messages) ? body.messages : [];
+    const input = messages.filter(isRecord).map((message) => ({
+        role: message.role === "system" ? "developer" : message.role,
+        content: message.content,
+    }));
+    const format = isRecord(body.response_format) ? body.response_format : null;
+    return {
+        model: body.model,
+        input,
+        ...(format?.type === "json_object" ? { text: { format: { type: "json_object" } } } : {}),
+        ...(isRecord(body.reasoning) ? { reasoning: body.reasoning } : {}),
+    };
+}
+/** Pull the final assistant text out of a completed Responses object. */
+export function responseOutputText(response) {
+    if (typeof response.output_text === "string")
+        return response.output_text;
+    const parts = [];
+    for (const item of Array.isArray(response.output) ? response.output : []) {
+        if (!isRecord(item) || item.type !== "message" || !Array.isArray(item.content))
+            continue;
+        for (const part of item.content)
+            if (isRecord(part) && typeof part.text === "string")
+                parts.push(part.text);
+    }
+    return parts.join("");
+}
+export function responsesToChatCompletion(response) {
+    return {
+        id: response.id,
+        object: "chat.completion",
+        model: response.model,
+        choices: [{ index: 0, message: { role: "assistant", content: responseOutputText(response) }, finish_reason: "stop" }],
+        ...(isRecord(response.usage) ? { usage: response.usage } : {}),
+    };
+}
+/** Read an SSE body and return the completed response object, or the stream's error. */
+export async function collectCompletedResponse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = {};
+    const consume = (block) => {
+        const data = block.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("");
+        if (!data || data === "[DONE]")
+            return;
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(event))
+            return;
+        if ((event.type === "response.completed" || event.type === "response.done") && isRecord(event.response))
+            result = { response: event.response };
+        if (event.type === "response.failed" && isRecord(event.response))
+            result = { error: isRecord(event.response.error) ? event.response.error : { message: "response failed" } };
+        if (event.type === "error")
+            result = { error: isRecord(event.error) ? event.error : event };
+    };
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const blocks = buffer.split(/\r?\n\r?\n/);
+        buffer = blocks.pop() ?? "";
+        for (const block of blocks)
+            consume(block);
+    }
+    if (buffer.trim())
+        consume(buffer);
+    return result;
+}
+const EDIT_SCALARS = ["model", "prompt", "background", "quality", "size", "moderation", "output_format", "n"];
+/** The Codex images edit endpoint takes JSON with data-URL images; accept the OpenAI multipart shape too. */
+export async function editsFormToJson(form) {
+    const body = {};
+    for (const key of EDIT_SCALARS) {
+        const value = form.get(key);
+        if (typeof value === "string" && value)
+            body[key] = key === "n" ? Number(value) : value;
+    }
+    const files = [...form.getAll("image"), ...form.getAll("image[]")]
+        .filter((value) => typeof value !== "string");
+    body.images = await Promise.all(files.map(async (file) => ({
+        image_url: `data:${file.type || "image/png"};base64,${Buffer.from(await file.arrayBuffer()).toString("base64")}`,
+    })));
+    return body;
+}

package/lib/codexBackend/session.js

@@ -0,0 +1,130 @@
+/**
+ * ChatGPT session for direct calls to the Codex backend (chatgpt.com/backend-api/codex).
+ *
+ * The session file is the source of truth: `ima2 gpt login`, the web login, or Codex CLI can
+ * rotate or replace it at any time, and ChatGPT refresh tokens rotate on use. So:
+ *   - every request re-reads the file;
+ *   - a near-expiry token and an upstream 401 share ONE serialized refresh;
+ *   - compare-before-write: a login that replaced the file during a refresh wins;
+ *   - the write-back is atomic, keeps unknown keys, and stays mode 0600.
+ * This is the contract the former openai-oauth proxy carried as the ima2 patch.
+ */
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { CHATGPT_OAUTH_CLIENT_ID, CHATGPT_TOKEN_URL, chatgptSessionCandidates, decodeJwtPayload, extractChatgptAccountId, jwtExpiryMs, } from "../chatgptAuth.js";
+const EXPIRY_SKEW_MS = 60_000;
+export class CodexSessionError extends Error {
+    code = "OAUTH_SESSION_REQUIRED";
+    status = 401;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === "string" && value.length > 0 ? value : undefined);
+const tokensOf = (data) => (isRecord(data?.tokens) ? data.tokens : {});
+function isFedRamp(token) {
+    const auth = decodeJwtPayload(token)?.["https://api.openai.com/auth"];
+    return isRecord(auth) && auth.chatgpt_account_is_fedramp === true;
+}
+async function readSessionFile(configDir) {
+    for (const candidate of chatgptSessionCandidates(configDir)) {
+        try {
+            const parsed = JSON.parse(await readFile(candidate.path, "utf8"));
+            if (isRecord(parsed) && str(tokensOf(parsed).access_token))
+                return { path: candidate.path, data: parsed };
+        }
+        catch {
+            // Missing or unreadable candidates are skipped, as resolveChatgptSessionFile does.
+        }
+    }
+    return null;
+}
+function toSession(file) {
+    const tokens = tokensOf(file.data);
+    const accessToken = str(tokens.access_token);
+    const idToken = str(tokens.id_token);
+    const accountId = str(tokens.account_id) ?? extractChatgptAccountId(idToken, accessToken);
+    if (!accountId)
+        throw new CodexSessionError("ChatGPT account id not found in the session file. Run `ima2 gpt login`.");
+    return {
+        accessToken,
+        accountId,
+        isFedRamp: isFedRamp(idToken) || isFedRamp(accessToken),
+        refreshToken: str(tokens.refresh_token),
+        path: file.path,
+    };
+}
+async function writeAtomic(target, data) {
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const tmp = `${target}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+    await rename(tmp, target);
+    await chmod(target, 0o600).catch(() => undefined);
+}
+export const refreshChatgptTokens = async (refreshToken) => {
+    const res = await fetch(CHATGPT_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: CHATGPT_OAUTH_CLIENT_ID }),
+    });
+    if (!res.ok)
+        throw new CodexSessionError(`ChatGPT token refresh failed with HTTP ${res.status}. Run \`ima2 gpt login\`.`);
+    const body = await res.json();
+    if (!isRecord(body) || !str(body.access_token))
+        throw new CodexSessionError("ChatGPT token refresh returned no access token.");
+    return body;
+};
+export function createCodexSessionStore(options = {}) {
+    const refresher = options.refresher ?? refreshChatgptTokens;
+    let inflight = null;
+    const load = async () => {
+        const file = await readSessionFile(options.configDir);
+        if (!file)
+            throw new CodexSessionError("No ChatGPT session. Run `ima2 gpt login`.");
+        return file;
+    };
+    const doRefresh = async (failedToken) => {
+        const before = await load();
+        const current = str(tokensOf(before.data).access_token);
+        // Another writer already rotated the token: use theirs instead of spending ours.
+        if (current && current !== failedToken)
+            return toSession(before);
+        const refreshToken = str(tokensOf(before.data).refresh_token);
+        if (!refreshToken)
+            throw new CodexSessionError("The ChatGPT session cannot be refreshed. Run `ima2 gpt login`.");
+        const refreshed = await refresher(refreshToken);
+        const after = await load();
+        // A login replaced the file while we refreshed: it wins, and the stale refresh is dropped.
+        if (str(tokensOf(after.data).access_token) !== current)
+            return toSession(after);
+        const tokens = tokensOf(after.data);
+        const idToken = str(refreshed.id_token) ?? str(tokens.id_token);
+        const accessToken = str(refreshed.access_token);
+        const next = {
+            ...after.data,
+            auth_mode: "chatgpt",
+            tokens: {
+                ...tokens,
+                access_token: accessToken,
+                ...(idToken ? { id_token: idToken } : {}),
+                refresh_token: str(refreshed.refresh_token) ?? refreshToken,
+                account_id: str(tokens.account_id) ?? extractChatgptAccountId(idToken, accessToken),
+            },
+            last_refresh: new Date().toISOString(),
+        };
+        await writeAtomic(after.path, next);
+        return toSession({ path: after.path, data: next });
+    };
+    const refresh = (failedToken) => {
+        inflight ??= doRefresh(failedToken).finally(() => { inflight = null; });
+        return inflight;
+    };
+    const get = async () => {
+        if (inflight)
+            return inflight;
+        const session = toSession(await load());
+        const expiresAt = jwtExpiryMs(session.accessToken);
+        const expiring = expiresAt !== undefined && expiresAt - Date.now() < EXPIRY_SKEW_MS;
+        return session.refreshToken && expiring ? refresh(session.accessToken) : session;
+    };
+    return { get, refresh };
+}

package/lib/codexDetect.js

@@ -3,7 +3,7 @@
 // - OpenAI Codex stores auth under CODEX_HOME (default ~/.codex/auth.json).
 // - Legacy chatgpt-local stores auth under ~/.chatgpt-local/auth.json.
 // - Auth may live in OS keyring instead of a file (file absence ≠ unauth).
-// - openai-oauth can only consume a file-backed Codex session.
+// - ima2's GPT OAuth client (lib/codexBackend) can only consume a file-backed Codex session.
 import { existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";

package/lib/comfyPngWorkflow.js

@@ -58,7 +58,7 @@ export function readPngTextChunks(buffer) {
                     else {
                         // keyword \0 compressionFlag compressionMethod langTag \0 translatedKeyword \0 text
                         const flag = body[nul + 1];
-                        let cursor = nul + 3;
+                        const cursor = nul + 3;
                         const langEnd = body.indexOf(0, cursor);
                         if (langEnd < 0) {
                             offset = dataEnd + 4;

package/lib/errInfo.js

@@ -30,3 +30,13 @@ export function errInfo(e) {
 export function asError(e) {
     return e instanceof Error ? e : new Error(typeof e === "string" ? e : JSON.stringify(e));
 }
+/** Field view of a caught value; non-object throws expose no fields. */
+export function thrownFields(e) {
+    return e !== null && typeof e === "object" ? e : {};
+}
+export function stringField(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function numberField(value) {
+    return typeof value === "number" ? value : undefined;
+}

package/lib/generatePipeline.js

@@ -164,12 +164,12 @@ export async function runGeneratePipeline(req, res, ctx) {
         const activeProvider = providerOptions.provider;
         // Resolved AFTER provider resolution on purpose: the raw request `provider`
         // defaults to "auto", so only `activeProvider` names the lane that will
-        // actually run. Atlas Cloud talks to the gpt-image-2 API directly and
-        // accepts a forced transparent background; the OAuth proxy rejects it
-        // (see lib/imageBackgroundParam.ts).
+        // actually run. Atlas Cloud and GPT OAuth (the Codex Images API since the
+        // native client, lib/oauthImages.ts) render with gpt-image-2 and accept a
+        // forced transparent background; verified 2026-09-25 with a real alpha PNG.
         const backgroundParams = resolveImageBackgroundParams({
             preset: backgroundPreset,
-            supportsForcedTransparent: activeProvider === "atlascloud",
+            supportsForcedTransparent: activeProvider === "atlascloud" || activeProvider === "oauth",
             requestedFormat: typeof format === "string" ? format : undefined,
         });
         // Grok/Gemini/Agy/MiniMax have no background parameter and their branches
@@ -184,7 +184,7 @@ export async function runGeneratePipeline(req, res, ctx) {
             ? req.body.elementIds.filter((id) => typeof id === "string" && id)
             : [];
         let elementNotesFragment = "";
-        let elementResolvedRefs = [];
+        const elementResolvedRefs = [];
         let appliedElementIds = [];
         let elementDroppedRefs = [];
         let elementRefReadFailures = [];

package/lib/generationErrors.js

@@ -106,6 +106,10 @@ export function isNonRetryableGenerationError(err) {
     const status = Number(err?.status);
     return code === "INVALID_REQUEST" || code === "OAUTH_IMAGE_TIMEOUT" || (Number.isFinite(status) && status >= 400 && status < 500);
 }
+function generationFailure(message) {
+    const fields = {};
+    return Object.assign(new Error(message), fields);
+}
 function copyEmptyResponseMetadata(target, source) {
     if (!source)
         return;
@@ -172,7 +176,7 @@ function decorateProviderFailure(target, source) {
 export function normalizeGenerationFailure(lastErr, options = {}) {
     const code = errorCodeFrom(lastErr);
     if (PASSTHROUGH_CODES.has(code)) {
-        const err = new Error(lastErr?.message || options.proxyMessage || "GPT OAuth proxy/network failure");
+        const err = generationFailure(lastErr?.message || options.proxyMessage || "GPT OAuth proxy/network failure");
         err.code = code;
         err.status = lastErr?.status || statusForErrorCode(code);
         err.cause = lastErr;
@@ -190,7 +194,7 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
     }
     if (SAFETY_CODES.has(code)) {
         const stage = classifyModerationStage(lastErr?.message);
-        const err = new Error(options.safetyMessage || lastErr?.message || "Content generation refused after retries");
+        const err = generationFailure(options.safetyMessage || lastErr?.message || "Content generation refused after retries");
         err.code = "SAFETY_REFUSAL";
         err.status = 422;
         err.moderationStage = stage;
@@ -198,7 +202,7 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         return decorateProviderFailure(err, lastErr);
     }
     if (RESPONSE_DIAGNOSTIC_CODES.has(code)) {
-        const err = new Error(lastErr?.message || "Image generation did not return image data");
+        const err = generationFailure(lastErr?.message || "Image generation did not return image data");
         err.code = code;
         err.status = lastErr?.status || statusForErrorCode(code, 422);
         err.cause = lastErr;
@@ -226,7 +230,7 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         const msg = meta.length
             ? `No image data returned. This may be an unsupported ${meta.join(", ")} combination. Try a different size or model.`
             : "No image data returned from the image backend. Try a different size, quality, or prompt.";
-        const err = new Error(msg);
+        const err = generationFailure(msg);
         err.code = "EMPTY_RESPONSE";
         err.status = 422;
         err.cause = lastErr;
@@ -247,7 +251,7 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         return decorateProviderFailure(err, lastErr);
     }
     // Unrecognized errors → UNKNOWN (do not pretend they are safety refusals)
-    const err = new Error(lastErr?.message || options.proxyMessage || "Image generation failed");
+    const err = generationFailure(lastErr?.message || options.proxyMessage || "Image generation failed");
     err.code = "UNKNOWN";
     err.status = lastErr?.status || 500;
     err.cause = lastErr;

package/lib/githubStar.js

@@ -0,0 +1,177 @@
+/**
+ * GitHub star state shared by the CLI prompt (bin/lib/star-prompt.ts) and the
+ * studio's star dialog (routes/github.ts).
+ *
+ * Starring always goes through the user's own `gh` login; ima2 never holds a
+ * GitHub token. Both surfaces build their gh arguments here and share one
+ * "prompted" state file, so answering once in either place quiets the other.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { delimiter, dirname, join, posix, win32 } from "node:path";
+import { homedir } from "node:os";
+import { config } from "../config.js";
+export const STAR_REPO = "lidge-ai/ima2-gen";
+export const STAR_REPO_URL = `https://github.com/${STAR_REPO}`;
+/** Pinned so a GHES login cannot answer (or be starred) for a same-named repository. */
+export const GH_HOSTNAME = "github.com";
+const CACHE_TTL_MS = 10 * 60_000;
+const AUTH_TIMEOUT_MS = 5_000;
+const API_TIMEOUT_MS = 10_000;
+export function ghVersionArgs() {
+    return ["--version"];
+}
+export function ghAuthStatusArgs(hostname) {
+    return hostname ? ["auth", "status", "--hostname", hostname] : ["auth", "status"];
+}
+export function ghStarredProbeArgs() {
+    return ["api", "--hostname", GH_HOSTNAME, `/user/starred/${STAR_REPO}`];
+}
+export function ghStarWriteArgs(hostname) {
+    const path = `/user/starred/${STAR_REPO}`;
+    return hostname ? ["api", "--hostname", hostname, "-X", "PUT", path] : ["api", "-X", "PUT", path];
+}
+export function starPromptStatePath() {
+    return join(config.storage.configDir, "state", "star-prompt.json");
+}
+export async function hasBeenPrompted(path = starPromptStatePath()) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const state = JSON.parse(await readFile(path, "utf8"));
+        return typeof state.prompted_at === "string";
+    }
+    catch {
+        return false;
+    }
+}
+export async function markPrompted(path = starPromptStatePath()) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ prompted_at: new Date().toISOString() }, null, 2));
+}
+/** Literal install roots only: the server never resolves gh through the caller's PATH. */
+export function trustedGhDirectories(platform = process.platform) {
+    if (platform === "win32")
+        return ["C:\\Program Files\\GitHub CLI", "C:\\Program Files (x86)\\GitHub CLI"];
+    return [
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        "/opt/local/bin",
+        "/home/linuxbrew/.linuxbrew/bin",
+        "/snap/bin",
+        "/run/current-system/sw/bin",
+    ];
+}
+export function resolveTrustedGh(platform = process.platform, exists = existsSync) {
+    const paths = platform === "win32" ? win32 : posix;
+    const name = platform === "win32" ? "gh.exe" : "gh";
+    for (const dir of trustedGhDirectories(platform)) {
+        const candidate = paths.join(dir, name);
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+async function spawnGh(args, timeoutMs) {
+    const executable = resolveTrustedGh();
+    if (!executable)
+        return null;
+    const pathApi = process.platform === "win32" ? win32 : posix;
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "path"));
+    // gh's own directory plus system tools only: credential helpers and the macOS keychain
+    // (/usr/bin/security) still resolve, while the caller's PATH never picks the binary.
+    const systemDirs = process.platform === "win32" ? [] : ["/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+    env.PATH = [pathApi.dirname(executable), ...systemDirs].join(delimiter);
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        let child;
+        try {
+            child = spawn(executable, args, { cwd: homedir(), env, stdio: "ignore", windowsHide: true, shell: false });
+        }
+        catch {
+            settle(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            settle(null);
+        }, timeoutMs);
+        child.once("error", () => { clearTimeout(timer); settle(null); });
+        child.once("exit", (code) => { clearTimeout(timer); settle({ status: code }); });
+    });
+}
+const productionDeps = { runGh: spawnGh, nowMs: () => Date.now(), statePath: starPromptStatePath };
+let defaultDeps = productionDeps;
+let cached = null;
+let inflight = null;
+/** Bumped by every star write; a probe that started earlier must not overwrite its result. */
+let generation = 0;
+export async function probeStarState(deps = defaultDeps) {
+    const auth = await deps.runGh(ghAuthStatusArgs(GH_HOSTNAME), AUTH_TIMEOUT_MS);
+    if (!auth || auth.status !== 0)
+        return "unauthenticated";
+    const probe = await deps.runGh(ghStarredProbeArgs(), API_TIMEOUT_MS);
+    if (!probe)
+        return "unauthenticated";
+    return probe.status === 0 ? "starred" : "not-starred";
+}
+async function cachedStarState(deps) {
+    const now = deps.nowMs();
+    if (cached && now - cached.at < CACHE_TTL_MS)
+        return cached.state;
+    if (!inflight) {
+        const startedGeneration = generation;
+        const probe = probeStarState(deps).then((state) => {
+            if (inflight === probe)
+                inflight = null;
+            if (startedGeneration !== generation)
+                return cached?.state ?? state;
+            cached = { at: now, state };
+            return state;
+        }, (error) => {
+            if (inflight === probe)
+                inflight = null;
+            throw error;
+        });
+        inflight = probe;
+    }
+    return inflight;
+}
+export async function getStarStatus(deps = defaultDeps) {
+    const prompted = await hasBeenPrompted(deps.statePath());
+    const state = prompted ? null : await cachedStarState(deps);
+    return { state, prompted, repo: STAR_REPO, url: STAR_REPO_URL };
+}
+export async function starRepository(deps = defaultDeps) {
+    const auth = await deps.runGh(ghAuthStatusArgs(GH_HOSTNAME), AUTH_TIMEOUT_MS);
+    if (!auth || auth.status !== 0)
+        return { ok: false, code: "gh_unauthenticated" };
+    const write = await deps.runGh(ghStarWriteArgs(GH_HOSTNAME), API_TIMEOUT_MS);
+    if (!write || write.status !== 0)
+        return { ok: false, code: "gh_failed" };
+    generation += 1;
+    inflight = null;
+    cached = { at: deps.nowMs(), state: "starred" };
+    // The star already landed; an unwritable config dir must not report it as a failure.
+    await markPrompted(deps.statePath()).catch(() => { });
+    return { ok: true };
+}
+export async function dismissStarPrompt(deps = defaultDeps) {
+    await markPrompted(deps.statePath());
+}
+/** Tests install deterministic deps (never the user's gh) and must reset afterwards. */
+export function setStarDepsForTests(deps) {
+    defaultDeps = deps ?? productionDeps;
+    generation += 1;
+    cached = null;
+    inflight = null;
+}

package/lib/grokImageCore.js

@@ -1,3 +1,4 @@
+import { thrownFields } from "./errInfo.js";
 import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
 import { detectImageMimeFromB64 } from "./refs.js";
 import { getGrokEndpoint } from "./grokRuntime.js";
@@ -5,7 +6,7 @@ export { downloadGrokImageUrl } from "./grokImageDownload.js";
 export { getGrokEndpoint } from "./grokRuntime.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
 export function getGrokTimeout(ctx) {
-    return ctx.config.grokProvider?.generationTimeoutMs || 300_000;
+    return ctx.config?.grokProvider?.generationTimeoutMs || 300_000;
 }
 export function grokError(message, status, code) {
     const err = new Error(message);
@@ -24,7 +25,7 @@ export function grokStageError(stage, message, status) {
     return grokError(`Grok ${stage} bad request: ${message}`, status, `${prefix}_BAD_REQUEST`);
 }
 export function getPlannerConfig(ctx) {
-    const grokCfg = ctx.config.grokProvider || {};
+    const grokCfg = ctx.config?.grokProvider || {};
     return {
         model: grokCfg.plannerModel || DEFAULT_GROK_PLANNER_MODEL,
         timeoutMs: grokCfg.plannerTimeoutMs || 900_000,
@@ -106,14 +107,15 @@ export async function postGrokImages(ctx, payload, signal, path = "/v1/images/ge
         return await res.json();
     }
     catch (e) {
+        const eFields = thrownFields(e);
         clearTimeout(timer);
-        if (e.name === "AbortError") {
+        if (eFields.name === "AbortError") {
             if (signal?.aborted)
                 throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
             throw grokError("Grok image generation timed out", 504, "GENERATION_TIMEOUT");
         }
-        if (e.code && e.status)
+        if (eFields.code && eFields.status)
             throw e;
-        throw grokError(`Grok request failed: ${e.message}`, 502, "GROK_NETWORK_FAILED");
+        throw grokError(`Grok request failed: ${eFields.message}`, 502, "GROK_NETWORK_FAILED");
     }
 }

package/lib/grokImagePlanner.js

@@ -1,3 +1,4 @@
+import { thrownFields } from "./errInfo.js";
 import { logEvent } from "./logger.js";
 import { SAFETY_INTENT_POLICY } from "./promptSafetyPolicy.js";
 import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
@@ -222,15 +223,16 @@ export async function searchGrokVisualContext(prompt, ctx, options = {}) {
         return { summary };
     }
     catch (e) {
+        const eFields = thrownFields(e);
         clearTimeout(timer);
-        if (e.name === "AbortError") {
+        if (eFields.name === "AbortError") {
             if (options.signal?.aborted)
                 throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
             throw grokError("Grok web search timed out", 504, "GROK_SEARCH_TIMEOUT");
         }
-        if (e.code && e.status)
+        if (eFields.code && eFields.status)
             throw e;
-        throw grokError(`Grok web search request failed: ${e.message}`, 502, "GROK_SEARCH_NETWORK_FAILED");
+        throw grokError(`Grok web search request failed: ${eFields.message}`, 502, "GROK_SEARCH_NETWORK_FAILED");
     }
 }
 export function parseGrokImagePlan(response, fallbackModel) {
@@ -252,7 +254,7 @@ export function parseGrokImagePlan(response, fallbackModel) {
     return { prompt: args.prompt.trim(), model: fallbackModel, webSearchCalls: 1 };
 }
 export async function planGrokImage(prompt, ctx, options = {}) {
-    const imageModel = options.model || ctx.config.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
+    const imageModel = options.model || ctx.config?.grokProvider?.defaultImageModel || "grok-imagine-image-quality";
     const planner = getPlannerConfig(ctx);
     const plannerModel = options.plannerModel || planner.model;
     const sizeParams = mapSizeToGrokImageParams(options.size);
@@ -300,14 +302,15 @@ export async function planGrokImage(prompt, ctx, options = {}) {
         return plan;
     }
     catch (e) {
+        const eFields = thrownFields(e);
         clearTimeout(timer);
-        if (e.name === "AbortError") {
+        if (eFields.name === "AbortError") {
             if (options.signal?.aborted)
                 throw grokError("Generation canceled", 499, "GENERATION_CANCELED");
             throw grokError("Grok planner timed out", 504, "GROK_PLANNER_TIMEOUT");
         }
-        if (e.code && e.status)
+        if (eFields.code && eFields.status)
             throw e;
-        throw grokError(`Grok planner request failed: ${e.message}`, 502, "GROK_PLANNER_NETWORK_FAILED");
+        throw grokError(`Grok planner request failed: ${eFields.message}`, 502, "GROK_PLANNER_NETWORK_FAILED");
     }
 }