ima2-gen 1.1.13 → 1.1.16

package/routes/video.js

@@ -0,0 +1,197 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { startJob, finishJob, registerJobAbortController, isJobCanceled } from "../lib/inflight.js";
+import { isGenerationCanceledError, makeGenerationCanceledError } from "../lib/generationCancel.js";
+import { logEvent, logError } from "../lib/logger.js";
+import { invalidateHistoryIndex } from "../lib/historyIndex.js";
+import { generateVideoViaGrok } from "../lib/grokVideoAdapter.js";
+import { normalizeGrokVideoModel, normalizeVideoResolution, normalizeVideoAspectRatio, normalizeVideoDuration, deriveVideoMode, clampVideoDuration, MAX_REF2V_REFERENCES, } from "../lib/imageModels.js";
+import { errInfo } from "../lib/errInfo.js";
+import { requireRuntimeContext } from "../lib/runtimeContext.js";
+function sendSse(res, event, data) {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+function toArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function isNormalizeError(x) {
+    return typeof x === "object" && x !== null && typeof x.error === "string";
+}
+async function resolveSourceImage(ctx, sourceImage, sourceFilename) {
+    if (typeof sourceFilename === "string" && sourceFilename) {
+        const safe = sourceFilename.replace(/^\/+/, "");
+        if (safe.includes(".."))
+            throw { status: 400, code: "GROK_VIDEO_INVALID_MODE", message: "invalid source filename" };
+        const buf = await readFile(join(ctx.config.storage.generatedDir, safe));
+        return { b64: buf.toString("base64"), filename: safe };
+    }
+    if (typeof sourceImage === "string" && sourceImage) {
+        return { b64: sourceImage, filename: null };
+    }
+    return { b64: null, filename: null };
+}
+export function registerVideoRoutes(app, ctxRaw) {
+    const ctx = requireRuntimeContext(ctxRaw);
+    app.post("/api/video/generate", async (req, res) => {
+        const requestId = typeof req.body?.requestId === "string"
+            ? req.body.requestId
+            : typeof req.body?.clientRequestId === "string"
+                ? req.body.clientRequestId
+                : req.id;
+        let finishStatus = "completed";
+        let finishHttpStatus = 200;
+        let finishErrorCode;
+        let finishMeta = {};
+        let finishCanceled = false;
+        const cancelController = new AbortController();
+        res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+        res.flushHeaders?.();
+        const fail = (status, code, error) => {
+            const httpStatus = status ?? 500;
+            finishStatus = "error";
+            finishHttpStatus = httpStatus;
+            finishErrorCode = code;
+            sendSse(res, "error", { error, code, status: httpStatus, requestId });
+        };
+        try {
+            const { prompt, provider = "grok", model: rawModel } = req.body || {};
+            const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
+            const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
+            if (provider !== "grok")
+                return fail(400, "VIDEO_PROVIDER_UNSUPPORTED", "video generation requires provider 'grok'");
+            if (typeof prompt !== "string" || !prompt.trim())
+                return fail(400, "PROMPT_REQUIRED", "Prompt is required");
+            const modelCheck = normalizeGrokVideoModel(rawModel);
+            if (isNormalizeError(modelCheck))
+                return fail(modelCheck.status, modelCheck.code, modelCheck.error);
+            const durationCheck = normalizeVideoDuration(req.body?.duration);
+            if (isNormalizeError(durationCheck))
+                return fail(durationCheck.status, durationCheck.code, durationCheck.error);
+            const resolutionCheck = normalizeVideoResolution(req.body?.resolution);
+            if (isNormalizeError(resolutionCheck))
+                return fail(resolutionCheck.status, resolutionCheck.code, resolutionCheck.error);
+            const aspectCheck = normalizeVideoAspectRatio(req.body?.aspectRatio);
+            if (isNormalizeError(aspectCheck))
+                return fail(aspectCheck.status, aspectCheck.code, aspectCheck.error);
+            // Resolve reference inputs: base64 list + existing-file list + legacy single source.
+            const refInputs = [
+                ...toArray(req.body?.referenceImages).map((image) => ({ image })),
+                ...toArray(req.body?.referenceFilenames).map((filename) => ({ filename })),
+                ...(req.body?.sourceImage || req.body?.sourceFilename
+                    ? [{ image: req.body?.sourceImage, filename: req.body?.sourceFilename }]
+                    : []),
+            ];
+            let resolved;
+            try {
+                const all = await Promise.all(refInputs.map((r) => resolveSourceImage(ctx, r.image, r.filename)));
+                resolved = all.filter((r) => Boolean(r.b64));
+            }
+            catch (e) {
+                return fail(e?.status || 400, e?.code || "GROK_VIDEO_INVALID_MODE", e?.message || "invalid reference image");
+            }
+            if (resolved.length > MAX_REF2V_REFERENCES)
+                return fail(400, "GROK_VIDEO_REF_TOO_MANY", `at most ${MAX_REF2V_REFERENCES} reference images`);
+            const mode = deriveVideoMode(resolved.length);
+            const duration = clampVideoDuration(durationCheck.duration, mode);
+            const referenceImages = mode === "reference-to-video" ? resolved.map((r) => r.b64) : undefined;
+            const sourceB64 = mode === "image-to-video" ? resolved[0]?.b64 : undefined;
+            const sourceFilename = resolved[0]?.filename ?? null;
+            startJob({
+                requestId,
+                kind: "video",
+                prompt,
+                meta: { kind: "video", sessionId, clientNodeId, model: modelCheck.model, mode, duration, resolution: resolutionCheck.resolution },
+            });
+            registerJobAbortController(requestId, cancelController);
+            await mkdir(ctx.config.storage.generatedDir, { recursive: true });
+            logEvent("video", "request", { requestId, mode, duration, resolution: resolutionCheck.resolution, aspectRatio: aspectCheck.aspectRatio });
+            const startTime = Date.now();
+            const onEvent = (ev) => {
+                if (ev.phase === "submitted")
+                    sendSse(res, "submitted", { requestId, xaiVideoRequestId: ev.xaiVideoRequestId });
+                else if (ev.phase === "progress")
+                    sendSse(res, "progress", { requestId, progress: ev.progress ?? null, stalled: Boolean(ev.stalled) });
+                else
+                    sendSse(res, "planning", { requestId });
+            };
+            const result = await generateVideoViaGrok(prompt, ctx, {
+                model: modelCheck.model,
+                mode,
+                duration,
+                resolution: resolutionCheck.resolution,
+                aspectRatio: aspectCheck.aspectRatio,
+                sourceImage: sourceB64,
+                referenceImages,
+                signal: cancelController.signal,
+                requestId,
+                onEvent,
+            });
+            const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
+            const filename = `${Date.now()}_${rand}.mp4`;
+            const elapsed = +((Date.now() - startTime) / 1000).toFixed(1);
+            const meta = {
+                kind: "video",
+                mediaType: "video",
+                requestId,
+                sessionId,
+                clientNodeId,
+                prompt,
+                userPrompt: prompt,
+                revisedPrompt: result.revisedPrompt,
+                provider: "grok",
+                model: modelCheck.model,
+                createdAt: Date.now(),
+                elapsed,
+                usage: result.usage,
+                webSearchCalls: result.webSearchCalls,
+                video: {
+                    duration: result.duration,
+                    resolution: result.resolution,
+                    aspectRatio: result.aspectRatio,
+                    sourceImageFilename: sourceFilename,
+                    xaiVideoRequestId: result.xaiVideoRequestId,
+                },
+            };
+            await writeFile(join(ctx.config.storage.generatedDir, filename), result.videoBuffer);
+            await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => { });
+            invalidateHistoryIndex();
+            finishMeta = { filename, xaiVideoRequestId: result.xaiVideoRequestId };
+            logEvent("video", "saved", { requestId, filename, bytes: result.videoBuffer.length, elapsedMs: Date.now() - startTime });
+            sendSse(res, "done", {
+                requestId,
+                filename,
+                url: `/generated/${encodeURIComponent(filename)}`,
+                mediaType: "video",
+                revisedPrompt: result.revisedPrompt,
+                elapsed,
+                usage: result.usage,
+                video: meta.video,
+            });
+        }
+        catch (e) {
+            const err = errInfo(e);
+            if (isGenerationCanceledError(err.raw) || isJobCanceled(requestId)) {
+                const canceled = makeGenerationCanceledError();
+                finishCanceled = true;
+                finishHttpStatus = canceled.status;
+                finishErrorCode = canceled.code;
+                sendSse(res, "error", { error: canceled.message, code: canceled.code, status: canceled.status, requestId });
+            }
+            else {
+                finishStatus = "error";
+                finishHttpStatus = err.status || 500;
+                finishErrorCode = err.code || "GROK_VIDEO_FAILED";
+                logError("video", "error", err.raw, { requestId, code: finishErrorCode });
+                sendSse(res, "error", { error: err.message, code: finishErrorCode, status: finishHttpStatus, requestId });
+            }
+        }
+        finally {
+            finishJob(requestId, { canceled: finishCanceled, status: finishStatus, httpStatus: finishHttpStatus, errorCode: finishErrorCode, meta: finishMeta });
+            res.end();
+        }
+    });
+}

package/routes/video.ts

@@ -0,0 +1,216 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import type { Express, Request, Response } from "express";
+import { startJob, finishJob, registerJobAbortController, isJobCanceled } from "../lib/inflight.js";
+import { isGenerationCanceledError, makeGenerationCanceledError } from "../lib/generationCancel.js";
+import { logEvent, logError } from "../lib/logger.js";
+import { invalidateHistoryIndex } from "../lib/historyIndex.js";
+import { generateVideoViaGrok, type GrokVideoEvent } from "../lib/grokVideoAdapter.js";
+import {
+  normalizeGrokVideoModel,
+  normalizeVideoResolution,
+  normalizeVideoAspectRatio,
+  normalizeVideoDuration,
+  deriveVideoMode,
+  clampVideoDuration,
+  MAX_REF2V_REFERENCES,
+  type VideoMode,
+} from "../lib/imageModels.js";
+import { errInfo } from "../lib/errInfo.js";
+import { requireRuntimeContext, type RouteRuntimeContext, type RuntimeContext } from "../lib/runtimeContext.js";
+
+function sendSse(res: Response, event: string, data: unknown) {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+}
+
+function toArray(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}
+
+type NormalizeError = { error: string; code: string; status: number };
+
+function isNormalizeError(x: unknown): x is NormalizeError {
+  return typeof x === "object" && x !== null && typeof (x as { error?: unknown }).error === "string";
+}
+
+async function resolveSourceImage(
+  ctx: RuntimeContext,
+  sourceImage: unknown,
+  sourceFilename: unknown,
+): Promise<{ b64: string | null; filename: string | null }> {
+  if (typeof sourceFilename === "string" && sourceFilename) {
+    const safe = sourceFilename.replace(/^\/+/, "");
+    if (safe.includes("..")) throw { status: 400, code: "GROK_VIDEO_INVALID_MODE", message: "invalid source filename" };
+    const buf = await readFile(join(ctx.config.storage.generatedDir, safe));
+    return { b64: buf.toString("base64"), filename: safe };
+  }
+  if (typeof sourceImage === "string" && sourceImage) {
+    return { b64: sourceImage, filename: null };
+  }
+  return { b64: null, filename: null };
+}
+
+export function registerVideoRoutes(app: Express, ctxRaw: RouteRuntimeContext) {
+  const ctx = requireRuntimeContext(ctxRaw);
+  app.post("/api/video/generate", async (req: Request, res: Response) => {
+    const requestId =
+      typeof req.body?.requestId === "string"
+        ? req.body.requestId
+        : typeof req.body?.clientRequestId === "string"
+          ? req.body.clientRequestId
+          : req.id;
+    let finishStatus = "completed";
+    let finishHttpStatus = 200;
+    let finishErrorCode: string | undefined;
+    let finishMeta: Record<string, unknown> = {};
+    let finishCanceled = false;
+    const cancelController = new AbortController();
+
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.flushHeaders?.();
+
+    const fail = (status: number | undefined, code: string, error: string) => {
+      const httpStatus = status ?? 500;
+      finishStatus = "error";
+      finishHttpStatus = httpStatus;
+      finishErrorCode = code;
+      sendSse(res, "error", { error, code, status: httpStatus, requestId });
+    };
+
+    try {
+      const { prompt, provider = "grok", model: rawModel } = req.body || {};
+      const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
+      const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
+
+      if (provider !== "grok") return fail(400, "VIDEO_PROVIDER_UNSUPPORTED", "video generation requires provider 'grok'");
+      if (typeof prompt !== "string" || !prompt.trim()) return fail(400, "PROMPT_REQUIRED", "Prompt is required");
+
+      const modelCheck = normalizeGrokVideoModel(rawModel);
+      if (isNormalizeError(modelCheck)) return fail(modelCheck.status, modelCheck.code, modelCheck.error);
+      const durationCheck = normalizeVideoDuration(req.body?.duration);
+      if (isNormalizeError(durationCheck)) return fail(durationCheck.status, durationCheck.code, durationCheck.error);
+      const resolutionCheck = normalizeVideoResolution(req.body?.resolution);
+      if (isNormalizeError(resolutionCheck)) return fail(resolutionCheck.status, resolutionCheck.code, resolutionCheck.error);
+      const aspectCheck = normalizeVideoAspectRatio(req.body?.aspectRatio);
+      if (isNormalizeError(aspectCheck)) return fail(aspectCheck.status, aspectCheck.code, aspectCheck.error);
+
+      // Resolve reference inputs: base64 list + existing-file list + legacy single source.
+      const refInputs: Array<{ image?: unknown; filename?: unknown }> = [
+        ...toArray(req.body?.referenceImages).map((image) => ({ image })),
+        ...toArray(req.body?.referenceFilenames).map((filename) => ({ filename })),
+        ...(req.body?.sourceImage || req.body?.sourceFilename
+          ? [{ image: req.body?.sourceImage, filename: req.body?.sourceFilename }]
+          : []),
+      ];
+      let resolved: Array<{ b64: string; filename: string | null }>;
+      try {
+        const all = await Promise.all(refInputs.map((r) => resolveSourceImage(ctx, r.image, r.filename)));
+        resolved = all.filter((r): r is { b64: string; filename: string | null } => Boolean(r.b64));
+      } catch (e: any) {
+        return fail(e?.status || 400, e?.code || "GROK_VIDEO_INVALID_MODE", e?.message || "invalid reference image");
+      }
+      if (resolved.length > MAX_REF2V_REFERENCES) return fail(400, "GROK_VIDEO_REF_TOO_MANY", `at most ${MAX_REF2V_REFERENCES} reference images`);
+      const mode: VideoMode = deriveVideoMode(resolved.length);
+      const duration = clampVideoDuration(durationCheck.duration, mode);
+      const referenceImages = mode === "reference-to-video" ? resolved.map((r) => r.b64) : undefined;
+      const sourceB64 = mode === "image-to-video" ? resolved[0]?.b64 : undefined;
+      const sourceFilename = resolved[0]?.filename ?? null;
+
+      startJob({
+        requestId,
+        kind: "video",
+        prompt,
+        meta: { kind: "video", sessionId, clientNodeId, model: modelCheck.model, mode, duration, resolution: resolutionCheck.resolution },
+      });
+      registerJobAbortController(requestId, cancelController);
+      await mkdir(ctx.config.storage.generatedDir, { recursive: true });
+
+      logEvent("video", "request", { requestId, mode, duration, resolution: resolutionCheck.resolution, aspectRatio: aspectCheck.aspectRatio });
+      const startTime = Date.now();
+
+      const onEvent = (ev: GrokVideoEvent) => {
+        if (ev.phase === "submitted") sendSse(res, "submitted", { requestId, xaiVideoRequestId: ev.xaiVideoRequestId });
+        else if (ev.phase === "progress") sendSse(res, "progress", { requestId, progress: ev.progress ?? null, stalled: Boolean(ev.stalled) });
+        else sendSse(res, "planning", { requestId });
+      };
+
+      const result = await generateVideoViaGrok(prompt, ctx, {
+        model: modelCheck.model,
+        mode,
+        duration,
+        resolution: resolutionCheck.resolution,
+        aspectRatio: aspectCheck.aspectRatio,
+        sourceImage: sourceB64,
+        referenceImages,
+        signal: cancelController.signal,
+        requestId,
+        onEvent,
+      });
+
+      const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
+      const filename = `${Date.now()}_${rand}.mp4`;
+      const elapsed = +((Date.now() - startTime) / 1000).toFixed(1);
+      const meta = {
+        kind: "video",
+        mediaType: "video",
+        requestId,
+        sessionId,
+        clientNodeId,
+        prompt,
+        userPrompt: prompt,
+        revisedPrompt: result.revisedPrompt,
+        provider: "grok",
+        model: modelCheck.model,
+        createdAt: Date.now(),
+        elapsed,
+        usage: result.usage,
+        webSearchCalls: result.webSearchCalls,
+        video: {
+          duration: result.duration,
+          resolution: result.resolution,
+          aspectRatio: result.aspectRatio,
+          sourceImageFilename: sourceFilename,
+          xaiVideoRequestId: result.xaiVideoRequestId,
+        },
+      };
+      await writeFile(join(ctx.config.storage.generatedDir, filename), result.videoBuffer);
+      await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => {});
+      invalidateHistoryIndex();
+
+      finishMeta = { filename, xaiVideoRequestId: result.xaiVideoRequestId };
+      logEvent("video", "saved", { requestId, filename, bytes: result.videoBuffer.length, elapsedMs: Date.now() - startTime });
+      sendSse(res, "done", {
+        requestId,
+        filename,
+        url: `/generated/${encodeURIComponent(filename)}`,
+        mediaType: "video",
+        revisedPrompt: result.revisedPrompt,
+        elapsed,
+        usage: result.usage,
+        video: meta.video,
+      });
+    } catch (e) {
+      const err = errInfo(e);
+      if (isGenerationCanceledError(err.raw) || isJobCanceled(requestId)) {
+        const canceled = makeGenerationCanceledError();
+        finishCanceled = true;
+        finishHttpStatus = canceled.status;
+        finishErrorCode = canceled.code;
+        sendSse(res, "error", { error: canceled.message, code: canceled.code, status: canceled.status, requestId });
+      } else {
+        finishStatus = "error";
+        finishHttpStatus = err.status || 500;
+        finishErrorCode = err.code || "GROK_VIDEO_FAILED";
+        logError("video", "error", err.raw, { requestId, code: finishErrorCode });
+        sendSse(res, "error", { error: err.message, code: finishErrorCode, status: finishHttpStatus, requestId });
+      }
+    } finally {
+      finishJob(requestId, { canceled: finishCanceled, status: finishStatus, httpStatus: finishHttpStatus, errorCode: finishErrorCode, meta: finishMeta });
+      res.end();
+    }
+  });
+}

package/server.js

@@ -6,6 +6,7 @@ import { dirname, join } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { onShutdown } from "./bin/lib/platform.js";
 import { ensureDefaultSession } from "./lib/sessionStore.js";
+import { startGrokProxy } from "./lib/grokProxyLauncher.js";
 import { startOAuthProxy } from "./lib/oauthLauncher.js";
 import { migrateGeneratedStorage } from "./lib/storageMigration.js";
 import { purgeStaleJobs } from "./lib/inflight.js";
@@ -105,6 +106,11 @@ function advertise(ctx) {
                 url: ctx.oauthUrl,
                 status: ctx.oauthReadyState,
             },
+            grok: {
+                configuredPort: Number(ctx.grokPort),
+                actualPort: Number(ctx.grokActualPort || ctx.grokPort),
+                url: ctx.grokUrl,
+            },
         }));
     }
     catch (e) {
@@ -132,6 +138,7 @@ export async function createRuntimeContext(overrides = {}) {
     const apiKey = loadedKey.apiKey;
     const openai = overrides.openai ?? await createOpenAI(apiKey);
     const oauthPort = config.oauth.proxyPort;
+    const grokPort = config.grokProvider.proxyPort;
     let resolveOAuthReady = () => { };
     const oauthReadyPromise = new Promise((resolve) => {
         resolveOAuthReady = resolve;
@@ -142,6 +149,9 @@ export async function createRuntimeContext(overrides = {}) {
         serverConfiguredPort: config.server.port,
         serverActualPort: undefined,
         serverUrl: `http://${runtimeHostUrl(config.server.host)}:${config.server.port}`,
+        grokPort,
+        grokActualPort: grokPort,
+        grokUrl: `http://${config.grokProvider.proxyHost}:${grokPort}/v1`,
         oauthPort,
         oauthActualPort: oauthPort,
         oauthUrl: `http://127.0.0.1:${oauthPort}`,
@@ -153,6 +163,14 @@ export async function createRuntimeContext(overrides = {}) {
         startedAt: overrides.startedAt ?? Date.now(),
         packageVersion: overrides.packageVersion ?? readPackageVersion(),
         oauthReadyPromise: oauthReadyPromise,
+        markGrokProxyPort: ({ url, port } = {}) => {
+            if (port)
+                ctx.grokActualPort = port;
+            if (url)
+                ctx.grokUrl = url;
+            else if (port)
+                ctx.grokUrl = `http://${ctx.config.grokProvider.proxyHost}:${port}/v1`;
+        },
         markOAuthReady: ({ url, port } = {}) => {
             if (url)
                 ctx.oauthUrl = url;
@@ -191,6 +209,21 @@ export async function startServer(overrides = {}) {
     if (overrides.oauthChild !== undefined || !ctx.config.oauth.autoStart) {
         ctx.markOAuthReady({ url: ctx.oauthUrl, port: ctx.oauthPort });
     }
+    const grokChild = ctx.config.grokProvider.autoStart
+        ? await startGrokProxy({
+            host: ctx.config.grokProvider.proxyHost,
+            port: ctx.config.grokProvider.proxyPort,
+            restartDelayMs: ctx.config.grokProvider.restartDelayMs,
+            onPortSelected: ({ url, port }) => {
+                ctx.markGrokProxyPort({ url, port });
+                advertise(ctx);
+            },
+            onReady: ({ url, port }) => {
+                ctx.markGrokProxyPort({ url, port });
+                advertise(ctx);
+            },
+        })
+        : null;
     onShutdown(() => {
         unadvertise(ctx);
         try {
@@ -201,6 +234,14 @@ export async function startServer(overrides = {}) {
             oauthChild?.kill?.();
         }
         catch { }
+        try {
+            grokChild?.stop?.();
+        }
+        catch { }
+        try {
+            grokChild?.kill?.();
+        }
+        catch { }
     });
     process.on("exit", () => unadvertise(ctx));
     const server = await listenWithPortFallback(app, ctx.config.server.port, {
@@ -213,7 +254,7 @@ export async function startServer(overrides = {}) {
     ctx.serverActualPort = getServerPort(server) || ctx.config.server.port;
     ctx.serverUrl = `http://${runtimeHostUrl(ctx.config.server.host)}:${ctx.serverActualPort}`;
     console.log(`Image Gen running at ${ctx.serverUrl}`);
-    console.log(`Provider policy: OAuth and API-key Responses providers. OAuth proxy port ${ctx.oauthPort}.`);
+    console.log(`Provider policy: OAuth, API-key Responses, and Grok Images providers. OAuth proxy port ${ctx.oauthPort}; Grok proxy port ${ctx.grokActualPort || ctx.grokPort}.`);
     advertise(ctx);
     try {
         const s = ensureDefaultSession();

package/server.ts

@@ -13,6 +13,7 @@ import { dirname, join } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { onShutdown } from "./bin/lib/platform.js";
 import { ensureDefaultSession } from "./lib/sessionStore.js";
+import { startGrokProxy } from "./lib/grokProxyLauncher.js";
 import { startOAuthProxy } from "./lib/oauthLauncher.js";
 import { migrateGeneratedStorage } from "./lib/storageMigration.js";
 import { purgeStaleJobs } from "./lib/inflight.js";
@@ -27,6 +28,7 @@ import type { RuntimeContext, RuntimeContextOverrides, ApiKeySource } from "./li
 import { errInfo } from "./lib/errInfo.js";
 
 type BootRuntimeContext = RuntimeContext & {
+  markGrokProxyPort: (info?: { url?: string; port?: number }) => void;
   markOAuthReady: (info?: { url?: string; port?: number }) => void;
   markOAuthFailed: () => void;
 };
@@ -125,6 +127,11 @@ function advertise(ctx: RuntimeContext) {
           url: ctx.oauthUrl,
           status: ctx.oauthReadyState,
         },
+        grok: {
+          configuredPort: Number(ctx.grokPort),
+          actualPort: Number(ctx.grokActualPort || ctx.grokPort),
+          url: ctx.grokUrl,
+        },
       }),
     );
   } catch (e) {
@@ -158,6 +165,7 @@ export async function createRuntimeContext(overrides: StartServerOverrides = {})
   const apiKey = loadedKey.apiKey;
   const openai = overrides.openai ?? await createOpenAI(apiKey);
   const oauthPort = config.oauth.proxyPort;
+  const grokPort = config.grokProvider.proxyPort;
   let resolveOAuthReady: (value: string | null) => void = () => {};
   const oauthReadyPromise = new Promise<string | null>((resolve) => {
     resolveOAuthReady = resolve;
@@ -168,6 +176,9 @@ export async function createRuntimeContext(overrides: StartServerOverrides = {})
     serverConfiguredPort: config.server.port,
     serverActualPort: undefined,
     serverUrl: `http://${runtimeHostUrl(config.server.host)}:${config.server.port}`,
+    grokPort,
+    grokActualPort: grokPort,
+    grokUrl: `http://${config.grokProvider.proxyHost}:${grokPort}/v1`,
     oauthPort,
     oauthActualPort: oauthPort,
     oauthUrl: `http://127.0.0.1:${oauthPort}`,
@@ -179,6 +190,11 @@ export async function createRuntimeContext(overrides: StartServerOverrides = {})
     startedAt: overrides.startedAt ?? Date.now(),
     packageVersion: overrides.packageVersion ?? readPackageVersion(),
     oauthReadyPromise: oauthReadyPromise as unknown as Promise<void>,
+    markGrokProxyPort: ({ url, port }: { url?: string; port?: number } = {}) => {
+      if (port) ctx.grokActualPort = port;
+      if (url) ctx.grokUrl = url;
+      else if (port) ctx.grokUrl = `http://${ctx.config.grokProvider.proxyHost}:${port}/v1`;
+    },
     markOAuthReady: ({ url, port }: { url?: string; port?: number } = {}) => {
       if (url) ctx.oauthUrl = url;
       if (port) ctx.oauthActualPort = port;
@@ -216,11 +232,28 @@ export async function startServer(overrides: StartServerOverrides = {}) {
   if (overrides.oauthChild !== undefined || !ctx.config.oauth.autoStart) {
     ctx.markOAuthReady({ url: ctx.oauthUrl, port: ctx.oauthPort });
   }
+  const grokChild = ctx.config.grokProvider.autoStart
+    ? await startGrokProxy({
+        host: ctx.config.grokProvider.proxyHost,
+        port: ctx.config.grokProvider.proxyPort,
+        restartDelayMs: ctx.config.grokProvider.restartDelayMs,
+        onPortSelected: ({ url, port }: { url: string; port: number }) => {
+          ctx.markGrokProxyPort({ url, port });
+          advertise(ctx);
+        },
+        onReady: ({ url, port }: { url: string; port: number }) => {
+          ctx.markGrokProxyPort({ url, port });
+          advertise(ctx);
+        },
+      })
+    : null;
 
   onShutdown(() => {
     unadvertise(ctx);
     try { oauthChild?.stop?.(); } catch {}
     try { oauthChild?.kill?.(); } catch {}
+    try { grokChild?.stop?.(); } catch {}
+    try { grokChild?.kill?.(); } catch {}
   });
   process.on("exit", () => unadvertise(ctx));
 
@@ -234,7 +267,7 @@ export async function startServer(overrides: StartServerOverrides = {}) {
   ctx.serverActualPort = getServerPort(server) || ctx.config.server.port;
   ctx.serverUrl = `http://${runtimeHostUrl(ctx.config.server.host)}:${ctx.serverActualPort}`;
   console.log(`Image Gen running at ${ctx.serverUrl}`);
-  console.log(`Provider policy: OAuth and API-key Responses providers. OAuth proxy port ${ctx.oauthPort}.`);
+  console.log(`Provider policy: OAuth, API-key Responses, and Grok Images providers. OAuth proxy port ${ctx.oauthPort}; Grok proxy port ${ctx.grokActualPort || ctx.grokPort}.`);
   advertise(ctx);
   try {
     const s = ensureDefaultSession();

package/skills/ima2/SKILL.md

@@ -59,6 +59,19 @@ Use request-level overrides only for that one call:
 ima2 gen "cinematic mountain" --model gpt-5.5 --reasoning-effort high
 ```
 
+Use Grok when the request should run through bundled progrok, mandatory xAI Web
+Search, `grok-4.3` planning, and xAI Images API:
+
+```bash
+ima2 grok login
+ima2 grok status
+ima2 gen "cinematic neon city" --provider grok --model grok-imagine-image-quality
+```
+
+Grok requests with reference images use the edit/image-to-image path so the
+references remain attached after planning. Keep Grok references to three total
+input images.
+
 ## Prompting Guidance
 
 GPT Image 2 can follow detailed visual instructions and can render visible text
@@ -140,6 +153,13 @@ ima2 gen "variation 4" --quality high
 Treat `capabilities.limits.maxParallel` as advisory client-side queue guidance only.
 It is not a guaranteed server-side semaphore.
 
+## Agent Mode (web UI only)
+
+Agent Mode is a conversational image workspace (sessions, turns, a durable per-session queue, slash
+commands, `/question`). It is served at `/api/agent/*` and lives in the web UI — there is no
+`ima2 agent` CLI command. From the CLI, drive generation with `ima2 gen`, `ima2 edit`,
+`ima2 multimode`, and `ima2 node generate` instead.
+
 ## Watching Jobs
 
 Use JSON when another agent needs to reason about active work:
@@ -155,6 +175,13 @@ partial completion before a final `done`.
 
 ## Prompt Import
 
+Build a structured image prompt from a message or transcript:
+
+```bash
+ima2 prompt build --message "make this product prompt clearer" --json
+ima2 prompt build --messages @conversation.json --json
+```
+
 Preview a local markdown/text prompt source before committing:
 
 ```bash