ima2-gen 1.0.5 → 1.0.7

package/bin/lib/star-prompt.js

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { config } from "../../config.js";
+
+const REPO = "lidge-jun/ima2-gen";
+
+export function starPromptStatePath() {
+  return join(config.storage.configDir, "state", "star-prompt.json");
+}
+
+export async function hasBeenPrompted() {
+  const path = starPromptStatePath();
+  if (!existsSync(path)) return false;
+  try {
+    const content = await readFile(path, "utf8");
+    const state = JSON.parse(content);
+    return typeof state.prompted_at === "string";
+  } catch {
+    return false;
+  }
+}
+
+export async function markPrompted() {
+  const path = starPromptStatePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify({ prompted_at: new Date().toISOString() }, null, 2));
+}
+
+export function isGhInstalled() {
+  const result = spawnSync("gh", ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "ignore"],
+    timeout: 3000,
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+export function starRepo(spawnSyncFn = spawnSync) {
+  const result = spawnSyncFn("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10000,
+    windowsHide: true,
+  });
+
+  if (result.error) return { ok: false, error: result.error.message };
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").trim();
+    const stdout = (result.stdout || "").trim();
+    return { ok: false, error: stderr || stdout || `gh exited ${result.status}` };
+  }
+  return { ok: true };
+}
+
+async function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export async function maybePromptGithubStar(deps = {}) {
+  const stdinIsTTY = deps.stdinIsTTY ?? process.stdin.isTTY;
+  const stdoutIsTTY = deps.stdoutIsTTY ?? process.stdout.isTTY;
+  if (!stdinIsTTY || !stdoutIsTTY) return;
+
+  const hasBeenPromptedImpl = deps.hasBeenPromptedFn ?? hasBeenPrompted;
+  if (await hasBeenPromptedImpl()) return;
+
+  const isGhInstalledImpl = deps.isGhInstalledFn ?? isGhInstalled;
+  if (!isGhInstalledImpl()) return;
+
+  const markPromptedImpl = deps.markPromptedFn ?? markPrompted;
+  await markPromptedImpl();
+
+  const askYesNoImpl = deps.askYesNoFn ?? askYesNo;
+  const approved = await askYesNoImpl("[ima2] Enjoying ima2-gen? Star it on GitHub? [Y/n] ");
+  if (!approved) return;
+
+  const starRepoImpl = deps.starRepoFn ?? starRepo;
+  const star = starRepoImpl();
+  if (star.ok) {
+    const log = deps.logFn ?? console.log;
+    log("[ima2] Thanks for the star!");
+    return;
+  }
+
+  const warn = deps.warnFn ?? console.warn;
+  warn(`[ima2] Could not star repository automatically: ${star.error}`);
+}

package/config.js

@@ -0,0 +1,167 @@
+// config.js — centralized runtime configuration (0.09.12).
+//
+// Single source of truth for ports, limits, paths, and tunables. All server,
+// lib, and script code should import `config` (or named legacy constants) from
+// here rather than reading `process.env` directly.
+//
+// Priority: env var > ${IMA2_CONFIG_DIR}/config.json > built-in default.
+// `config.json` is loaded once at module import. Mutating the file at runtime
+// requires a server restart (same as env vars).
+//
+// Keep this module dependency-free aside from node:* built-ins to avoid
+// circular imports with lib/*.
+
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+
+const env = process.env;
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+const configDir = env.IMA2_CONFIG_DIR || join(homedir(), ".ima2");
+
+// ── Optional config.json layer ─────────────────────────────────────────
+// Users can drop `${configDir}/config.json` to override defaults without
+// setting env vars. Shape: same as the `config` object below (partial).
+function loadConfigJson() {
+  const candidates = [
+    join(configDir, "config.json"),
+    join(packageRoot, ".ima2", "config.json"),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const raw = readFileSync(p, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      // ignore malformed config.json; env+defaults still apply
+    }
+  }
+  return {};
+}
+const fileCfg = loadConfigJson();
+
+function firstDefined(...vals) {
+  return vals.find((v) => v !== undefined && v !== "");
+}
+function pickInt(envVal, fileVal, fallback) {
+  const candidate = firstDefined(envVal, fileVal);
+  if (candidate === undefined) return fallback;
+  const n = Number(candidate);
+  return Number.isFinite(n) ? n : fallback;
+}
+function pickStr(envVal, fileVal, fallback) {
+  return firstDefined(envVal, fileVal) ?? fallback;
+}
+function pickBool(envVal, fileVal, fallback) {
+  const v = firstDefined(envVal, fileVal);
+  if (v === undefined) return fallback;
+  if (typeof v === "boolean") return v;
+  const s = String(v).toLowerCase();
+  return s === "1" || s === "true" || s === "yes";
+}
+
+export const config = {
+  server: {
+    // Accept both IMA2_PORT and legacy PORT.
+    port: pickInt(firstDefined(env.IMA2_PORT, env.PORT), fileCfg.server?.port, 3333),
+    host: pickStr(env.IMA2_HOST, fileCfg.server?.host, "127.0.0.1"),
+    bodyLimit: pickStr(env.IMA2_BODY_LIMIT, fileCfg.server?.bodyLimit, "50mb"),
+  },
+  limits: {
+    maxRefB64Bytes: pickInt(env.IMA2_MAX_REF_B64_BYTES, fileCfg.limits?.maxRefB64Bytes, 7 * 1024 * 1024),
+    maxRefCount: pickInt(env.IMA2_MAX_REF_COUNT, fileCfg.limits?.maxRefCount, 5),
+    maxParallel: pickInt(env.IMA2_MAX_PARALLEL, fileCfg.limits?.maxParallel, 8),
+    graphMaxNodes: pickInt(env.IMA2_GRAPH_MAX_NODES, fileCfg.limits?.graphMaxNodes, 500),
+    graphMaxEdges: pickInt(env.IMA2_GRAPH_MAX_EDGES, fileCfg.limits?.graphMaxEdges, 1000),
+  },
+  history: {
+    defaultPageSize: pickInt(
+      env.IMA2_HISTORY_PAGE_SIZE,
+      fileCfg.history?.defaultPageSize ?? fileCfg.limits?.historyDefaultPageSize,
+      50,
+    ),
+    maxPageCap: pickInt(
+      env.IMA2_HISTORY_MAX_PAGE,
+      fileCfg.history?.maxPageCap ?? fileCfg.limits?.historyMaxPageCap,
+      500,
+    ),
+  },
+  oauth: {
+    // Accept both IMA2_OAUTH_PROXY_PORT and legacy OAUTH_PORT.
+    proxyPort: pickInt(firstDefined(env.IMA2_OAUTH_PROXY_PORT, env.OAUTH_PORT), fileCfg.oauth?.proxyPort, 10531),
+    // IMA2_NO_OAUTH_PROXY=1 disables auto-start; default is auto-start enabled.
+    autoStart: !pickBool(env.IMA2_NO_OAUTH_PROXY, fileCfg.oauth?.disableAutoStart, false),
+    statusTimeoutMs: pickInt(env.IMA2_OAUTH_STATUS_TIMEOUT_MS, fileCfg.oauth?.statusTimeoutMs, 3000),
+    restartDelayMs: pickInt(env.IMA2_OAUTH_RESTART_DELAY_MS, fileCfg.oauth?.restartDelayMs, 5000),
+    researchSuffix: pickStr(
+      env.IMA2_RESEARCH_SUFFIX,
+      fileCfg.oauth?.researchSuffix,
+      "\n\nIf the subject matter requires factual accuracy (faces, products, places, recent events), search the web for accurate visual references first, then generate.",
+    ),
+    validModeration: new Set(
+      Array.isArray(fileCfg.oauth?.validModeration) && fileCfg.oauth.validModeration.length
+        ? fileCfg.oauth.validModeration
+        : ["auto", "low"],
+    ),
+  },
+  storage: {
+    configDir,
+    packageRoot,
+    generatedDir: pickStr(env.IMA2_GENERATED_DIR, fileCfg.storage?.generatedDir, join(packageRoot, "generated")),
+    trashDir: pickStr(env.IMA2_TRASH_DIR, fileCfg.storage?.trashDir, join(packageRoot, "generated", ".trash")),
+    generatedDirName: pickStr(env.IMA2_GENERATED_DIRNAME, fileCfg.storage?.generatedDirName, "generated"),
+    trashDirName: pickStr(env.IMA2_TRASH_DIRNAME, fileCfg.storage?.trashDirName, ".trash"),
+    dbPath: pickStr(env.IMA2_DB_PATH, fileCfg.storage?.dbPath, join(configDir, "sessions.db")),
+    configFile: join(configDir, "config.json"),
+    advertiseFile: pickStr(env.IMA2_ADVERTISE_FILE, fileCfg.storage?.advertiseFile, join(configDir, "server.json")),
+    staticMaxAge: pickStr(env.IMA2_STATIC_MAX_AGE, fileCfg.storage?.staticMaxAge, "1y"),
+  },
+  ids: {
+    generatedHexBytes: pickInt(env.IMA2_GENERATED_HEX_BYTES, fileCfg.ids?.generatedHexBytes, 4),
+    nodeHexBytes: pickInt(env.IMA2_NODE_HEX_BYTES, fileCfg.ids?.nodeHexBytes, 5),
+  },
+  inflight: {
+    ttlMs: pickInt(env.IMA2_INFLIGHT_TTL_MS, fileCfg.inflight?.ttlMs, 10 * 60 * 1000),
+    reapMs: pickInt(env.IMA2_INFLIGHT_REAP_MS, fileCfg.inflight?.reapMs, 60 * 1000),
+    terminalTtlMs: pickInt(env.IMA2_INFLIGHT_TERMINAL_TTL_MS, fileCfg.inflight?.terminalTtlMs, 30 * 1000),
+  },
+  trash: {
+    ttlMs: pickInt(env.IMA2_TRASH_TTL_MS, fileCfg.trash?.ttlMs, 10_000),
+  },
+  styleSheet: {
+    maxPrefix: pickInt(env.IMA2_STYLE_SHEET_MAX_PREFIX, fileCfg.styleSheet?.maxPrefix, 4000),
+    model: pickStr(env.IMA2_STYLE_MODEL, fileCfg.styleSheet?.model, "gpt-5.4-mini"),
+  },
+  log: {
+    level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, "info"),
+    pretty: env.NODE_ENV !== "production",
+  },
+  dev: {
+    viteDevMode: pickBool(env.VITE_IMA2_DEV, fileCfg.dev?.viteDevMode, false),
+  },
+};
+
+export default config;
+
+// ── Backward-compatible flat re-exports (used by lib/inflight.js & earlier
+//    call sites). Prefer `import { config } from "./config.js"` going forward.
+export const PORT = config.server.port;
+export const OAUTH_PORT = config.oauth.proxyPort;
+export const OAUTH_URL = `http://127.0.0.1:${config.oauth.proxyPort}`;
+export const CONFIG_DIR = config.storage.configDir;
+export const CONFIG_FILE = config.storage.configFile;
+export const ADVERTISE_FILE = config.storage.advertiseFile;
+export const DB_FILE = config.storage.dbPath;
+export const GENERATED_DIR = config.storage.generatedDir;
+export const BODY_LIMIT = config.server.bodyLimit;
+export const MAX_REF_B64_BYTES = config.limits.maxRefB64Bytes;
+export const MAX_REFS = config.limits.maxRefCount;
+export const MAX_N = config.limits.maxParallel;
+export const INFLIGHT_TTL_MS = config.inflight.ttlMs;
+export const INFLIGHT_REAP_MS = config.inflight.reapMs;
+export const INFLIGHT_TERMINAL_TTL_MS = config.inflight.terminalTtlMs;
+export const STYLE_SHEET_MAX_PREFIX = config.styleSheet.maxPrefix;
+export const LOG_LEVEL = config.log.level;
+export const NO_OAUTH_PROXY = !config.oauth.autoStart;
+export const DEV_MODE = config.dev.viteDevMode;

package/lib/assetLifecycle.js

@@ -1,10 +1,11 @@
 import { getDb } from "./db.js";
 import { rename, unlink, mkdir, access } from "fs/promises";
 import { join, resolve, sep } from "path";
+import { config } from "../config.js";
 
-const DIR = "generated";
-const TRASH = ".trash";
-const TRASH_TTL_MS = 10_000;
+const DIR = config.storage.generatedDirName;
+const TRASH = config.storage.trashDirName;
+const TRASH_TTL_MS = config.trash.ttlMs;
 
 function resolveInGenerated(rootDir, relPath) {
   if (typeof relPath !== "string" || relPath.length === 0) {

package/lib/db.js

@@ -1,15 +1,12 @@
 import Database from "better-sqlite3";
 import { mkdirSync, existsSync } from "fs";
-import { dirname, join } from "path";
-import { homedir } from "os";
-
-const DEFAULT_DB_DIR = join(homedir(), ".ima2");
-const DEFAULT_DB_PATH = join(DEFAULT_DB_DIR, "sessions.db");
+import { dirname } from "path";
+import { config } from "../config.js";
 
 let db = null;
 
 export function getDbPath() {
-  return process.env.IMA2_DB_PATH || DEFAULT_DB_PATH;
+  return config.storage.dbPath;
 }
 
 export function getDb() {
@@ -73,6 +70,14 @@ function migrate(database) {
       "ALTER TABLE sessions ADD COLUMN graph_version INTEGER NOT NULL DEFAULT 0",
     );
   }
+  if (!sessionColumns.includes("style_sheet")) {
+    database.exec("ALTER TABLE sessions ADD COLUMN style_sheet TEXT");
+  }
+  if (!sessionColumns.includes("style_sheet_enabled")) {
+    database.exec(
+      "ALTER TABLE sessions ADD COLUMN style_sheet_enabled INTEGER NOT NULL DEFAULT 0",
+    );
+  }
 
   const row = database.prepare("SELECT value FROM _meta WHERE key = 'schema_version'").get();
   if (!row) {

package/lib/errorClassify.js

@@ -0,0 +1,62 @@
+// 0.09.8 — upstream error classifier.
+// Pattern-match upstream OpenAI / OAuth / network errors into stable ImaErrorCode
+// values so the UI can surface localized, actionable messages with CTAs.
+
+/** @typedef {"REF_TOO_LARGE"|"REF_NOT_BASE64"|"REF_EMPTY"|"REF_TOO_MANY"|"MODERATION_REFUSED"|"UPSTREAM_5XX"|"AUTH_CHATGPT_EXPIRED"|"AUTH_API_KEY_INVALID"|"NETWORK_FAILED"|"OAUTH_UNAVAILABLE"|"INVALID_MODERATION"|"APIKEY_DISABLED"|"SAFETY_REFUSAL"|"DB_ERROR"|"UNKNOWN"} ImaErrorCode */
+
+/**
+ * Classify an upstream error message into an ImaErrorCode.
+ * Order matters: auth session expiry must beat generic "token" matches,
+ * and moderation must beat generic 5xx.
+ * @param {string | undefined | null} msg
+ * @returns {ImaErrorCode}
+ */
+export function classifyUpstreamError(msg) {
+  const s = String(msg || "").toLowerCase();
+  if (!s) return "UNKNOWN";
+
+  if (s.includes("content generation refused") || s.includes("moderation_blocked") || s.includes("moderation refused")) {
+    return "MODERATION_REFUSED";
+  }
+
+  // ChatGPT sign-in session expiry must precede the generic api-key checks
+  // so it is not misclassified when messages contain both "token" and "api".
+  if (
+    s.includes("token is expired") ||
+    s.includes("sign in again") ||
+    (s.includes("access token") && s.includes("expired")) ||
+    (s.includes("token") && s.includes("expired") && !s.includes("api key"))
+  ) {
+    return "AUTH_CHATGPT_EXPIRED";
+  }
+
+  if (
+    s.includes("incorrect api key") ||
+    s.includes("invalid authentication") ||
+    s.includes("exceeded your current quota") ||
+    s.includes("incorrect organization")
+  ) {
+    return "AUTH_API_KEY_INVALID";
+  }
+
+  if (
+    s.includes("failed to fetch") ||
+    s.includes("econnrefused") ||
+    s.includes("econnreset") ||
+    s.includes("enotfound") ||
+    s.includes("etimedout") ||
+    s.includes("network error")
+  ) {
+    return "NETWORK_FAILED";
+  }
+
+  if (s.includes("oauth") && (s.includes("not running") || s.includes("unavailable"))) {
+    return "OAUTH_UNAVAILABLE";
+  }
+
+  if (s.includes("an error occurred while processing") || /\b5\d\d\b/.test(s)) {
+    return "UPSTREAM_5XX";
+  }
+
+  return "UNKNOWN";
+}

package/lib/historyList.js

@@ -0,0 +1,66 @@
+import { mkdir, readFile, readdir, stat } from "fs/promises";
+import { join } from "path";
+import { config } from "../config.js";
+
+async function listImageFiles(baseDir) {
+  const out = [];
+
+  async function walk(dir, depth) {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (entry.name === config.storage.trashDirName) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && depth > 0) {
+        await walk(full, depth - 1);
+      } else if (entry.isFile() && /\.(png|jpe?g|webp)$/i.test(entry.name)) {
+        out.push({ full, rel: full.slice(baseDir.length + 1), name: entry.name });
+      }
+    }
+  }
+
+  await walk(baseDir, 2);
+  return out;
+}
+
+export async function listHistoryRows(baseDir = config.storage.generatedDir) {
+  await mkdir(baseDir, { recursive: true });
+  const imgs = await listImageFiles(baseDir);
+  const rows = await Promise.all(imgs.map(async ({ full, rel, name }) => {
+    const st = await stat(full).catch(() => null);
+    let meta = null;
+    try {
+      const raw = await readFile(full + ".json", "utf-8");
+      meta = JSON.parse(raw);
+    } catch (e) {
+      if (e.code !== "ENOENT") console.warn("[history] sidecar parse fail:", rel, e.message);
+    }
+    return {
+      filename: rel,
+      url: `/generated/${rel.split("/").map(encodeURIComponent).join("/")}`,
+      createdAt: meta?.createdAt || st?.mtimeMs || 0,
+      prompt: meta?.prompt || null,
+      userPrompt: meta?.userPrompt || meta?.prompt || null,
+      revisedPrompt: meta?.revisedPrompt || null,
+      promptMode: meta?.promptMode || null,
+      quality: meta?.quality || null,
+      size: meta?.size || null,
+      format: meta?.format || name.split(".").pop(),
+      provider: meta?.provider || "oauth",
+      usage: meta?.usage || null,
+      webSearchCalls: meta?.webSearchCalls || 0,
+      sessionId: meta?.sessionId || null,
+      nodeId: meta?.nodeId || null,
+      parentNodeId: meta?.parentNodeId || null,
+      clientNodeId: meta?.clientNodeId || null,
+      kind: meta?.kind || null,
+      refsCount: Number.isFinite(meta?.refsCount) ? meta.refsCount : 0,
+    };
+  }));
+
+  rows.sort((a, b) => {
+    if (b.createdAt !== a.createdAt) return b.createdAt - a.createdAt;
+    return b.filename < a.filename ? -1 : b.filename > a.filename ? 1 : 0;
+  });
+
+  return rows;
+}

package/lib/inflight.js

@@ -1,3 +1,6 @@
+import { config } from "../config.js";
+import { logEvent } from "./logger.js";
+
 // In-memory inflight job registry.
 // Tracks generation requests that are currently running on the server so clients
 // can reconcile optimistic UI state after a reload or across tabs.
@@ -6,20 +9,30 @@
 // are lost (which is correct — the fetch they came from is already gone).
 
 const jobs = new Map(); // requestId -> { requestId, kind, prompt, meta, startedAt, phase, phaseAt }
+const terminalJobs = new Map(); // requestId -> terminal snapshot, active-only API stays default
 
 // Phases: "queued" → "streaming" (upstream connection open, waiting for image)
 //                 → "decoding" (b64 received, writing to disk)
-// finishJob removes the entry entirely.
 export function startJob({ requestId, kind, prompt, meta = {} }) {
   if (!requestId) return;
+  const startedAt = Date.now();
   jobs.set(requestId, {
     requestId,
     kind,
     prompt: typeof prompt === "string" ? prompt.slice(0, 500) : "",
     meta,
-    startedAt: Date.now(),
+    startedAt,
     phase: "queued",
-    phaseAt: Date.now(),
+    phaseAt: startedAt,
+  });
+  terminalJobs.delete(requestId);
+  logEvent("inflight", "start", {
+    requestId,
+    kind,
+    sessionId: meta?.sessionId || null,
+    parentNodeId: meta?.parentNodeId || null,
+    clientNodeId: meta?.clientNodeId || null,
+    promptChars: typeof prompt === "string" ? prompt.length : 0,
   });
 }
 
@@ -29,18 +42,56 @@ export function setJobPhase(requestId, phase) {
   if (!j) return;
   j.phase = phase;
   j.phaseAt = Date.now();
+  logEvent("inflight", "phase", { requestId, kind: j.kind, phase });
 }
 
-export function finishJob(requestId, _options = {}) {
+export function finishJob(requestId, options = {}) {
   if (!requestId) return;
+  const j = jobs.get(requestId);
+  if (j) {
+    const finishedAt = Date.now();
+    const status = options.canceled ? "canceled" : options.status || "completed";
+    terminalJobs.set(requestId, {
+      requestId,
+      kind: j.kind,
+      status,
+      startedAt: j.startedAt,
+      finishedAt,
+      durationMs: finishedAt - j.startedAt,
+      phase: j.phase,
+      phaseAt: j.phaseAt,
+      httpStatus: options.httpStatus,
+      errorCode: options.errorCode,
+      meta: {
+        ...j.meta,
+        ...(options.meta || {}),
+      },
+    });
+    logEvent("inflight", "finish", {
+      requestId,
+      kind: j.kind,
+      status,
+      durationMs: finishedAt - j.startedAt,
+      httpStatus: options.httpStatus,
+      errorCode: options.errorCode,
+    });
+  }
   jobs.delete(requestId);
+  reapTerminalJobs();
+}
+
+function reapTerminalJobs() {
+  const now = Date.now();
+  for (const [id, j] of terminalJobs) {
+    if (now - j.finishedAt > config.inflight.terminalTtlMs) terminalJobs.delete(id);
+  }
 }
 
 export function listJobs(filters = {}) {
-  // Stale reaping: > 10 min is almost certainly a crashed fetch.
+  // Stale reaping: > TTL is almost certainly a crashed fetch.
   const now = Date.now();
   for (const [id, j] of jobs) {
-    if (now - j.startedAt > 10 * 60 * 1000) jobs.delete(id);
+    if (now - j.startedAt > config.inflight.ttlMs) jobs.delete(id);
   }
   const { kind, sessionId } = filters;
   return Array.from(jobs.values())
@@ -52,6 +103,19 @@ export function listJobs(filters = {}) {
     .sort((a, b) => a.startedAt - b.startedAt);
 }
 
+export function listTerminalJobs(filters = {}) {
+  reapTerminalJobs();
+  const { kind, sessionId } = filters;
+  return Array.from(terminalJobs.values())
+    .filter((j) => {
+      if (kind && j.kind !== kind) return false;
+      if (sessionId && j.meta?.sessionId !== sessionId) return false;
+      return true;
+    })
+    .sort((a, b) => b.finishedAt - a.finishedAt);
+}
+
 export function _resetForTests() {
   jobs.clear();
+  terminalJobs.clear();
 }

package/lib/logger.js

@@ -0,0 +1,116 @@
+const REDACTED = "[redacted]";
+const MAX_VALUE_LEN = 240;
+
+const SECRET_KEYS = new Set([
+  "authorization",
+  "cookie",
+  "headers",
+  "apiKey",
+  "token",
+  "password",
+  "secret",
+  "body",
+  "prompt",
+  "effectivePrompt",
+  "userPrompt",
+  "revisedPrompt",
+  "textPrompt",
+  "styleSheet",
+  "style_sheet",
+  "image",
+  "imageB64",
+  "image_url",
+  "references",
+  "rawResponse",
+]);
+
+const ALLOWED_PROMPT_METRICS = new Set(["promptChars", "promptMode"]);
+
+function shouldRedactKey(key) {
+  if (ALLOWED_PROMPT_METRICS.has(key)) return false;
+  if (SECRET_KEYS.has(key)) return true;
+  const lower = key.toLowerCase();
+  return (
+    lower.includes("token") ||
+    lower.includes("authorization") ||
+    lower.includes("cookie") ||
+    lower.includes("apikey") ||
+    lower.includes("api_key") ||
+    lower.includes("secret") ||
+    lower.includes("b64") ||
+    lower.includes("base64") ||
+    lower.includes("dataurl")
+  );
+}
+
+function sanitizeValue(value) {
+  if (value == null) return value;
+  if (value instanceof Error) return sanitizeError(value);
+  if (Array.isArray(value)) return `[array:${value.length}]`;
+  if (Buffer.isBuffer(value)) return `[buffer:${value.length}]`;
+  if (typeof value === "object") return "[object]";
+  if (typeof value === "string") {
+    const oneLine = value
+      .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+      .replace(/data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi, "data:image/[redacted]")
+      .replace(/\s+/g, " ")
+      .trim();
+    return oneLine.length > MAX_VALUE_LEN ? `${oneLine.slice(0, MAX_VALUE_LEN)}...` : oneLine;
+  }
+  return value;
+}
+
+export function sanitizeError(err) {
+  if (!err) return { message: "Unknown error" };
+  return {
+    name: err.name || "Error",
+    code: err.code || undefined,
+    status: err.status || undefined,
+    message: sanitizeValue(err.message || "Unknown error"),
+  };
+}
+
+export function sanitizeFields(fields = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    out[key] = shouldRedactKey(key) ? REDACTED : sanitizeValue(value);
+  }
+  return out;
+}
+
+function formatValue(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return "null";
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  return JSON.stringify(String(value));
+}
+
+export function formatLog(scope, event, fields = {}) {
+  const safeFields = sanitizeFields(fields);
+  const parts = Object.entries(safeFields)
+    .map(([key, value]) => {
+      const formatted = formatValue(value);
+      return formatted === undefined ? null : `${key}=${formatted}`;
+    })
+    .filter(Boolean);
+  return `[${scope}.${event}]${parts.length ? ` ${parts.join(" ")}` : ""}`;
+}
+
+export function logEvent(scope, event, fields = {}) {
+  console.log(formatLog(scope, event, fields));
+}
+
+export function logWarn(scope, event, fields = {}) {
+  console.warn(formatLog(scope, event, fields));
+}
+
+export function logError(scope, event, err, fields = {}) {
+  const safe = sanitizeError(err);
+  console.error(formatLog(scope, event, {
+    ...fields,
+    errorName: safe.name,
+    errorCode: safe.code,
+    errorStatus: safe.status,
+    errorMessage: safe.message,
+  }));
+}