ima2-gen 3.13.1 → 3.14.0

package/lib/agyProcess.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { AGY_PROCESS_POLICY } from "../config.js";
+import { buildAgyPathEnv, resolveAgyBin } from "./agyCli.js";
+export function agyError(message, status, code) {
+    const err = new Error(message);
+    err.status = status;
+    err.code = code;
+    return err;
+}
+class AgyProcessLifetime {
+    child;
+    signal;
+    resolve;
+    reject;
+    stdout = "";
+    stderr = "";
+    settled = false;
+    reason;
+    timer;
+    graceTimer;
+    constructor(child, signal, resolve, reject) {
+        this.child = child;
+        this.signal = signal;
+        this.resolve = resolve;
+        this.reject = reject;
+    }
+    start(prompt) {
+        this.child.stdout.on("data", this.onStdout);
+        this.child.stderr.on("data", this.onStderr);
+        this.child.on("error", this.onError);
+        this.child.once("close", this.finish);
+        this.child.stdin.on("error", this.onStdinError);
+        this.timer = setTimeout(() => {
+            this.terminate(agyError("Agy generation timed out", 504, "AGY_TIMEOUT"));
+        }, AGY_PROCESS_POLICY.timeoutMs);
+        this.signal?.addEventListener("abort", this.onAbort, { once: true });
+        if (this.signal?.aborted) {
+            this.onAbort();
+            return;
+        }
+        this.child.stdin.write(prompt);
+        this.child.stdin.end();
+    }
+    onStdout = (chunk) => {
+        if (this.stdout.length < AGY_PROCESS_POLICY.maxOutputBytes)
+            this.stdout += chunk.toString();
+    };
+    onStderr = (chunk) => {
+        if (this.stderr.length < AGY_PROCESS_POLICY.maxOutputBytes)
+            this.stderr += chunk.toString();
+    };
+    onStdinError = () => {
+        // Preserve ignored stdin errors; the child error/close owns the result.
+    };
+    onAbort = () => {
+        this.terminate(agyError("Generation canceled", 499, "GENERATION_CANCELED"));
+    };
+    terminate(reason) {
+        if (this.settled || this.reason)
+            return;
+        this.reason = reason;
+        clearTimeout(this.timer);
+        // Arm before TERM so even a synchronous close clears the grace timer.
+        this.graceTimer = setTimeout(() => {
+            if (!this.settled)
+                this.child.kill("SIGKILL");
+        }, AGY_PROCESS_POLICY.terminateGraceMs);
+        this.child.kill("SIGTERM");
+    }
+    onError = (err) => {
+        if (this.settled || this.reason)
+            return;
+        const bin = resolveAgyBin();
+        const hint = err.code === "ENOENT"
+            ? `. "${bin}" was not found — install agy or set IMA2_AGY_BIN=/absolute/path/to/agy`
+            : "";
+        this.reason = agyError(`Agy process error: ${err.message}${hint}`, 502, "AGY_PROCESS_ERROR");
+    };
+    finish = (code) => {
+        if (this.settled)
+            return;
+        this.settled = true;
+        clearTimeout(this.timer);
+        clearTimeout(this.graceTimer);
+        this.signal?.removeEventListener("abort", this.onAbort);
+        this.child.stdout.removeListener("data", this.onStdout);
+        this.child.stderr.removeListener("data", this.onStderr);
+        this.child.stdin.removeListener("error", this.onStdinError);
+        this.child.removeListener("error", this.onError);
+        this.child.removeListener("close", this.finish);
+        if (this.reason) {
+            this.reject(this.reason);
+            return;
+        }
+        if (code !== 0 && !this.stdout.trim()) {
+            this.reject(agyError(`Agy exited with code ${code}: ${this.stderr.slice(0, 200)}`, 502, "AGY_PROCESS_ERROR"));
+            return;
+        }
+        this.resolve({ stdout: this.stdout, stderr: this.stderr });
+    };
+}
+export function spawnAgy(prompt, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(agyError("Generation canceled", 499, "GENERATION_CANCELED"));
+            return;
+        }
+        const child = spawn(resolveAgyBin(), ["-p", "-"], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                PATH: buildAgyPathEnv(),
+                HOME: process.env.HOME,
+                USERPROFILE: process.env.USERPROFILE,
+                TMPDIR: process.env.TMPDIR,
+                TEMP: process.env.TEMP,
+                LANG: process.env.LANG,
+                GEMINI_API_KEY: process.env.GEMINI_API_KEY,
+            },
+        });
+        new AgyProcessLifetime(child, signal, resolve, reject).start(prompt);
+    });
+}

package/lib/apiRequestBudget.js

@@ -0,0 +1,48 @@
+/** Express routes are case-insensitive by default; do not protect /apix as /api. */
+export function isApiRequestPath(path) {
+    return /^\/api(?:\/|$)/i.test(path);
+}
+function rejectBudget(res, expires, now) {
+    res.setHeader("Retry-After", String(Math.max(1, Math.ceil((expires - now) / 1000))));
+    return res.status(429).json({
+        error: { code: "API_RATE_LIMITED", message: "Too many API requests; retry after the indicated delay" },
+    });
+}
+/** App-owned windows, bounded memory and socket identity (never proxy headers). */
+export function createApiRequestBudget(policy, clock = Date.now) {
+    const peers = new Map();
+    function prune(now) {
+        let earliest = now + policy.windowMs;
+        for (const [peer, window] of peers) {
+            if (window.expires <= now)
+                peers.delete(peer);
+            else
+                earliest = Math.min(earliest, window.expires);
+        }
+        return earliest;
+    }
+    return function apiRequestBudget(req, res, next) {
+        if (!isApiRequestPath(req.path))
+            return next();
+        const now = clock();
+        const peer = req.socket.remoteAddress ?? "unknown-peer";
+        let window = peers.get(peer);
+        if (!window || window.expires <= now) {
+            if (!window && peers.size >= policy.maxPeers) {
+                const earliest = prune(now);
+                if (peers.size >= policy.maxPeers)
+                    return rejectBudget(res, earliest, now);
+            }
+            window = { expires: now + policy.windowMs, requests: 0, mutations: 0 };
+            peers.set(peer, window);
+        }
+        const mutation = !["GET", "HEAD", "OPTIONS"].includes(req.method);
+        if (window.requests >= policy.requests || (mutation && window.mutations >= policy.mutations)) {
+            return rejectBudget(res, window.expires, now);
+        }
+        window.requests++;
+        if (mutation)
+            window.mutations++;
+        return next();
+    };
+}

package/lib/assetLifecycle.js

@@ -1,6 +1,6 @@
 import { getDb } from "./db.js";
 import { mkdir, rename, unlink, lstat, realpath } from "fs/promises";
-import { resolve, sep } from "path";
+import { basename, dirname, join, resolve, sep } from "path";
 import { moveToSystemTrash } from "./systemTrash.js";
 import { config } from "../config.js";
 export function resolveInGenerated(rootDir, relPath) {
@@ -19,7 +19,8 @@ export function resolveInGenerated(rootDir, relPath) {
     }
     const baseDir = resolve(config.storage.generatedDir);
     const target = resolve(baseDir, relPath);
-    if (target !== baseDir && !target.startsWith(baseDir + sep)) {
+    const prefix = baseDir.endsWith(sep) ? baseDir : baseDir + sep;
+    if (target === baseDir || !target.startsWith(prefix)) {
         const err = new Error("filename escapes generated/");
         err.status = 400;
         err.code = "INVALID_FILENAME";
@@ -28,7 +29,16 @@ export function resolveInGenerated(rootDir, relPath) {
     return target;
 }
 export async function assertRegularGeneratedPath(path) {
-    const baseDir = await realpath(resolve(config.storage.generatedDir));
+    try {
+        await regularFileWithin(path, config.storage.generatedDir);
+    }
+    catch (error) {
+        throw error;
+    }
+}
+/** Existing assets only; output filenames use the separate lexical resolver. */
+async function regularFileWithin(path, root) {
+    const baseDir = await realpath(resolve(root));
     const stat = await lstat(path);
     if (stat.isSymbolicLink()) {
         const err = new Error("symbolic links are not valid assets");
@@ -36,13 +46,18 @@ export async function assertRegularGeneratedPath(path) {
         err.code = "INVALID_FILENAME";
         throw err;
     }
+    if (!stat.isFile()) {
+        throw Object.assign(new Error("only regular files are valid assets"), { status: 400, code: "INVALID_FILENAME" });
+    }
     const canonical = await realpath(path);
-    if (canonical !== baseDir && !canonical.startsWith(baseDir + sep)) {
+    const prefix = baseDir.endsWith(sep) ? baseDir : baseDir + sep;
+    if (canonical === baseDir || !canonical.startsWith(prefix)) {
         const err = new Error("filename escapes generated/");
         err.status = 400;
         err.code = "INVALID_FILENAME";
         throw err;
     }
+    return canonical;
 }
 function nodesReferencingFilename(filename) {
     // The client stores imageUrl as `/generated/<encoded filename>` in node data JSON.
@@ -117,7 +132,7 @@ export async function trashAsset(rootDir, filename) {
         trashMethod = "internal";
         const trashDir = resolve(config.storage.trashDir);
         await mkdir(trashDir, { recursive: true });
-        const trashId = `${Date.now()}_${filename}`;
+        const trashId = `${Date.now()}_${basename(src)}`;
         for (const p of paths) {
             const dest = resolve(trashDir, p.endsWith(".json") ? `${trashId}.json` : trashId);
             await rename(p, dest);
@@ -165,16 +180,34 @@ export async function deleteAssetPermanent(rootDir, filename) {
     };
 }
 export async function restoreAsset(rootDir, trashId, originalFilename) {
-    void rootDir;
     const trashDir = resolve(config.storage.trashDir);
     const src = resolve(trashDir, trashId);
-    if (!src.startsWith(trashDir + sep) && src !== trashDir) {
+    const prefix = trashDir.endsWith(sep) ? trashDir : trashDir + sep;
+    if (src === trashDir || !src.startsWith(prefix)) {
         const err = new Error("invalid trashId");
         err.status = 400;
+        err.code = "INVALID_FILENAME";
         throw err;
     }
+    const canonicalSrc = await regularFileWithin(src, trashDir);
+    let canonicalSidecar;
+    try {
+        canonicalSidecar = await regularFileWithin(`${src}.json`, trashDir);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
     const dst = resolveInGenerated(rootDir, originalFilename);
-    await rename(src, dst);
-    await rename(src + ".json", dst + ".json").catch(() => { });
+    const generatedRoot = await realpath(config.storage.generatedDir);
+    const parent = await realpath(dirname(dst));
+    const generatedPrefix = generatedRoot.endsWith(sep) ? generatedRoot : generatedRoot + sep;
+    if (parent !== generatedRoot && !parent.startsWith(generatedPrefix)) {
+        throw Object.assign(new Error("restore destination escapes generated/"), { status: 400, code: "INVALID_FILENAME" });
+    }
+    const canonicalDst = join(parent, basename(dst));
+    await rename(canonicalSrc, canonicalDst);
+    if (canonicalSidecar)
+        await rename(canonicalSidecar, `${canonicalDst}.json`);
     return { ok: true };
 }

package/lib/canvasVersionStore.js

@@ -1,6 +1,5 @@
-import { mkdir, writeFile, access, readFile } from "fs/promises";
-import { constants } from "fs";
-import { basename, join, normalize, parse } from "path";
+import { mkdir, writeFile, readFile, lstat, realpath } from "fs/promises";
+import { basename, dirname, resolve, parse, sep } from "path";
 import { randomBytes } from "crypto";
 import sharp from "sharp";
 import { embedImageMetadataBestEffort } from "./imageMetadataStore.js";
@@ -34,12 +33,20 @@ function assertSafeFilename(filename) {
 }
 function safeSourceBase(sourceFilename) {
     const parsed = parse(basename(String(sourceFilename || "image")));
-    return parsed.name.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "image";
+    const safe = parsed.name.replace(/[^a-zA-Z0-9_-]+/g, "-");
+    let start = 0;
+    let end = safe.length;
+    while (start < end && safe[start] === "-")
+        start++;
+    while (end > start && safe[end - 1] === "-")
+        end--;
+    return safe.slice(start, Math.min(end, start + 80)) || "image";
 }
 function ensureInsideGeneratedDir(generatedDir, filename) {
-    const full = normalize(join(generatedDir, filename));
-    const root = normalize(generatedDir);
-    if (!full.startsWith(root)) {
+    const full = resolve(generatedDir, filename);
+    const root = resolve(generatedDir);
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    if (full === root || !full.startsWith(prefix)) {
         const err = new Error("Canvas version path escapes generated directory");
         err.status = 400;
         err.code = "CANVAS_VERSION_PATH_ESCAPE";
@@ -47,6 +54,28 @@ function ensureInsideGeneratedDir(generatedDir, filename) {
     }
     return full;
 }
+/** Existing leaves must be regular files; only a new output leaf may be absent. */
+async function checkedCanvasPath(generatedDir, filename, allowMissing = false) {
+    const lexical = ensureInsideGeneratedDir(generatedDir, filename);
+    const root = await realpath(generatedDir);
+    const parent = await realpath(dirname(lexical));
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    if (parent !== root && !parent.startsWith(prefix)) {
+        throw Object.assign(new Error("Canvas path escapes generated directory"), { status: 400, code: "CANVAS_VERSION_PATH_ESCAPE" });
+    }
+    const full = resolve(parent, basename(lexical));
+    try {
+        const stat = await lstat(full);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw Object.assign(new Error("Canvas path must be a regular file"), { status: 400, code: "CANVAS_VERSION_PATH_ESCAPE" });
+        }
+    }
+    catch (error) {
+        if (!allowMissing || error.code !== "ENOENT")
+            throw error;
+    }
+    return full;
+}
 function makeCanvasFilename(sourceFilename) {
     const stamp = new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "");
     const rand = randomBytes(3).toString("hex");
@@ -54,12 +83,13 @@ function makeCanvasFilename(sourceFilename) {
 }
 async function writeCanvasPng(ctx, filename, buffer, meta) {
     await mkdir(ctx.config.storage.generatedDir, { recursive: true });
-    const full = ensureInsideGeneratedDir(ctx.config.storage.generatedDir, filename);
+    const full = await checkedCanvasPath(ctx.config.storage.generatedDir, filename, true);
+    const sidecar = await checkedCanvasPath(ctx.config.storage.generatedDir, `${filename}.json`, true);
     const embedded = await embedImageMetadataBestEffort(buffer, "png", meta, {
         version: ctx.packageVersion,
     });
     await writeFile(full, embedded.buffer);
-    await writeFile(`${full}.json`, JSON.stringify(meta)).catch(() => { });
+    await writeFile(sidecar, JSON.stringify(meta)).catch(() => { });
     invalidateHistoryIndex();
 }
 async function readGeneratedMetadata(ctx, filename) {
@@ -67,7 +97,8 @@ async function readGeneratedMetadata(ctx, filename) {
         return null;
     try {
         const full = ensureInsideGeneratedDir(ctx.config.storage.generatedDir, basename(filename));
-        return JSON.parse(await readFile(`${full}.json`, "utf8"));
+        const sidecar = await checkedCanvasPath(ctx.config.storage.generatedDir, `${full}.json`);
+        return JSON.parse(await readFile(sidecar, "utf8"));
     }
     catch {
         return null;
@@ -149,8 +180,9 @@ export async function createCanvasVersion(ctx, input) {
 export async function updateCanvasVersion(ctx, filename, input) {
     assertSafeFilename(filename);
     assertPngBuffer(input.buffer);
-    const full = ensureInsideGeneratedDir(ctx.config.storage.generatedDir, filename);
-    await access(full, constants.F_OK).catch(() => {
+    await checkedCanvasPath(ctx.config.storage.generatedDir, filename).catch((cause) => {
+        if (cause.code !== "ENOENT")
+            throw cause;
         const err = new Error("Canvas version not found");
         err.status = 404;
         err.code = "CANVAS_VERSION_NOT_FOUND";
@@ -185,7 +217,6 @@ export async function updateCanvasVersion(ctx, filename, input) {
 export async function recordCanvasAnnotationBake(ctx, filename, snapshot, annotationOnly) {
     assertSafeFilename(filename);
     assertAnnotationSnapshot(snapshot);
-    const full = ensureInsideGeneratedDir(ctx.config.storage.generatedDir, filename);
     const previousMeta = await readGeneratedMetadata(ctx, filename);
     if (!previousMeta) {
         const err = new Error("Canvas version not found");
@@ -193,6 +224,7 @@ export async function recordCanvasAnnotationBake(ctx, filename, snapshot, annota
         err.code = "CANVAS_VERSION_NOT_FOUND";
         throw err;
     }
+    const full = await checkedCanvasPath(ctx.config.storage.generatedDir, filename);
     const buffer = await readFile(full);
     const meta = {
         ...previousMeta,
@@ -224,7 +256,7 @@ export async function revertCanvasAnnotations(ctx, filename) {
         err.code = "CANVAS_ANNOTATIONS_NOT_BAKED";
         throw err;
     }
-    const sourceFull = ensureInsideGeneratedDir(ctx.config.storage.generatedDir, basename(sourceFilename));
+    const sourceFull = await checkedCanvasPath(ctx.config.storage.generatedDir, basename(sourceFilename));
     const cleanPng = await sharp(await readFile(sourceFull)).png().toBuffer();
     const snapshot = previousMeta.annotationSnapshot ?? null;
     const annotationOnly = Boolean(previousMeta.annotationOnly);

package/lib/capabilities.js

@@ -6,7 +6,8 @@ import { loadAllBundledSnapshots } from "./mcp/snapshotStore.js";
 import { KEY_TO_ENV, WRITABLE_CONFIG_KEYS } from "./configKeys.js";
 import { DEFAULT_IMAGE_QUALITY, VALID_IMAGE_QUALITIES } from "./oauthNormalize.js";
 import { MAX_REF2V_REFERENCES, MAX_REFERENCE_AUDIOS, MAX_VIDEO_DURATION, MIN_VIDEO_DURATION } from "./imageModels.js";
-import { deriveProviderIds } from "./providers/derive.js";
+import { deriveProviderIds, getProviderSurfaceSupport } from "./providers/derive.js";
+import { PROVIDER_SURFACES } from "./providers/surfaceSupport.js";
 const VALID_MODES = ["auto", "direct"];
 const VALID_PROVIDERS = ["auto", ...deriveProviderIds()];
 const AGENT_COMMANDS = [
@@ -39,6 +40,11 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
         server,
         version: packageVersion,
         ...(lanes ? { lanes } : {}),
+        providerSurfaces: Object.fromEntries(deriveProviderIds().map((id) => [id,
+            Object.fromEntries(PROVIDER_SURFACES.map((surface) => [surface,
+                getProviderSurfaceSupport(id, surface),
+            ])),
+        ])),
         commands: AGENT_COMMANDS,
         defaults: {
             oauth: {

package/lib/configKeys.js

@@ -28,6 +28,7 @@ export const WRITABLE_CONFIG_KEYS = new Set([
     "storage.generatedDirName",
     "server.port",
     "server.host",
+    "server.publicOrigins",
     "server.bodyLimit",
     "oauth.proxyPort",
     "oauth.statusTimeoutMs",
@@ -49,6 +50,7 @@ export const KEY_TO_ENV = {
     "features.cardNews": "IMA2_CARD_NEWS",
     "server.port": "IMA2_PORT",
     "server.host": "IMA2_HOST",
+    "server.publicOrigins": "IMA2_PUBLIC_ORIGINS",
     "server.bodyLimit": "IMA2_BODY_LIMIT",
     "oauth.proxyPort": "IMA2_OAUTH_PROXY_PORT",
     "storage.generatedDir": "IMA2_GENERATED_DIR",

package/lib/errors/providerMap.js

@@ -1,3 +1,27 @@
+import { RESPONSE_DIAGNOSTIC_CODES } from "../responsesErrors.js";
+export function statusForErrorCode(code, fallback = 500) {
+    if (code === "GROK_API_KEY_MISSING")
+        return 401;
+    if (code === "OAUTH_UNAVAILABLE" || code === "NETWORK_FAILED")
+        return 503;
+    if (code === "AUTH_CHATGPT_EXPIRED" || code === "AUTH_API_KEY_INVALID")
+        return 401;
+    if (code === "API_KEY_REQUIRED")
+        return 401;
+    if (code === "UPSTREAM_5XX")
+        return 502;
+    if (code === "RESPONSES_STREAM_ERROR")
+        return 502;
+    if (code === "OAUTH_IMAGE_TIMEOUT")
+        return 504;
+    if (code === "INVALID_REQUEST")
+        return 400;
+    if (RESPONSE_DIAGNOSTIC_CODES.has(code))
+        return 422;
+    if (code === "SAFETY_REFUSAL" || code === "MODERATION_REFUSED" || code === "moderation_blocked")
+        return 422;
+    return fallback;
+}
 export const PROVIDER_ERROR_MAP = {
     MINIMAX_API_KEY_MISSING: "AUTH_INVALID",
     MINIMAX_AUTH_FAILED: "AUTH_INVALID",
@@ -43,6 +67,7 @@ export const PROVIDER_ERROR_MAP = {
     GEMINI_API_SAFETY_BLOCKED: "CONTENT_REJECTED",
     GEMINI_API_UPSTREAM_ERROR: "NETWORK_FAILURE",
     GEMINI_API_MASK_UNSUPPORTED: "CAPABILITY_UNSUPPORTED",
+    GROK_API_KEY_MISSING: "AUTH_INVALID",
     GROK_AUTH_FAILED: "AUTH_INVALID",
     GROK_BAD_REQUEST: "CAPABILITY_UNSUPPORTED",
     GROK_EMPTY_RESPONSE: "INTERNAL_STATE_ERROR",
@@ -78,6 +103,7 @@ export const PROVIDER_ERROR_MAP = {
     GROK_MASK_UNSUPPORTED: "CAPABILITY_UNSUPPORTED",
     GROK_REF_TOO_MANY: "CAPABILITY_UNSUPPORTED",
     AGY_ARTIFACT_NOT_FOUND: "INTERNAL_STATE_ERROR",
+    AGY_ARTIFACT_TOO_LARGE: "INTERNAL_STATE_ERROR",
     AGY_GENERATION_FAILED: "INTERNAL_STATE_ERROR",
     AGY_MALFORMED_RESULT: "INTERNAL_STATE_ERROR",
     AGY_PARSE_FAILED: "INTERNAL_STATE_ERROR",

package/lib/eventBus.js

@@ -102,14 +102,18 @@ export function subscribe(listener) {
 export function replayOldestId() {
     return ring.length > 0 ? ring[0]?.id ?? null : null;
 }
-/** True when the ring has evicted events the client still expects from Last-Event-ID. */
+/** Reads the process cursor without allocating an event. */
+export function latestEventId() {
+    return seq;
+}
+/** True for an evicted cursor or a cursor ahead of this process. */
 export function hasReplayGap(lastEventId) {
-    if (lastEventId <= 0 || ring.length === 0)
-        return false;
-    const oldest = ring[0]?.id;
-    if (oldest === undefined)
+    if (!Number.isSafeInteger(lastEventId) || lastEventId < 0)
         return false;
-    return lastEventId < oldest - 1;
+    if (lastEventId > seq)
+        return true;
+    const oldest = replayOldestId();
+    return oldest !== null && lastEventId < oldest - 1;
 }
 export function replaySince(lastEventId) {
     const idx = ring.findIndex(e => e.id > lastEventId);

package/lib/eventsPolicy.js

@@ -0,0 +1,9 @@
+/** Maximum time one accepted SSE write may wait for drain. */
+export const SSE_STREAM_POLICY = Object.freeze({ drainTimeoutMs: 15_000 });
+/** Parse the replay cursor header without accepting numeric coercions or overflow. */
+export function parseEventCursor(value) {
+    if (value === null || !/^\d+$/.test(value))
+        return null;
+    const cursor = Number(value);
+    return Number.isSafeInteger(cursor) ? cursor : null;
+}