@bitkyc08/opencodex 2.7.42 → 2.7.43

package/src/storage/restore-job.ts

@@ -0,0 +1,242 @@
+/**
+ * Single-flight controller for trash restore runs.
+ *
+ * Heavy work (file moves, SQLite reconcile) runs in a Bun Worker so the proxy
+ * event loop stays responsive while the management API awaits the outcome.
+ *
+ * Restore shares the CODEX_HOME storage-mutation coordinator with manual cleanup
+ * and (Phase 3) policy-driven cleanup. Concurrent callers receive
+ * `storage_mutation_busy` (409) instead of queueing.
+ */
+import { resolveCodexHomeDir } from "../codex/home";
+import { restoreTrashEntry, type RestoreResult, type RestoreTestHooks } from "./cleanup";
+import {
+  resetStorageMutationCoordinatorForTests,
+  setStorageMutationCoordinatorTestHooks,
+  withStorageMutationSlot,
+  type StorageMutationCoordinatorTestHooks,
+} from "./storage-mutation-coordinator";
+
+export interface RestoreJobTestHooks extends StorageMutationCoordinatorTestHooks {
+  /**
+   * When true, run on the main thread via dynamic import + optional sleep.
+   * Responsiveness tests must leave this unset so work stays in a Worker.
+   */
+  runInProcess?: boolean;
+  /** Expose GET /api/storage/trash/restore/test-stream for responsiveness tests. */
+  enableTestStream?: boolean;
+  /** Forwarded to restoreTrashEntry _test hooks. */
+  restoreTest?: RestoreTestHooks;
+}
+
+const WORKER_TIMEOUT_MS = 10 * 60 * 1000;
+
+const WORKER_REJECTION_CODES: Record<string, RestoreResult["error"]> = {
+  restore_worker_timeout: "restore_worker_timeout",
+  aborted: "restore_worker_aborted",
+  worker_failed: "restore_worker_failed",
+};
+
+/** Map a rejected worker promise to a precise restore outcome (exported for tests). */
+export function restoreResultFromWorkerRejection(err: unknown, trashId: string): RestoreResult {
+  const raw = err instanceof Error ? err.message : String(err);
+  const error = WORKER_REJECTION_CODES[raw] ?? "restore_worker_failed";
+  const detail =
+    error === "restore_worker_failed" && raw !== "worker_failed" && raw.trim().length > 0
+      ? raw
+      : undefined;
+  console.error(
+    `[storage] trash restore worker failed (${error}) trashId=${trashId}${detail ? `: ${detail}` : ""}`,
+  );
+  return {
+    ok: false,
+    count: 0,
+    bytes: 0,
+    restoredPaths: [],
+    error,
+    ...(detail ? { message: detail } : {}),
+  };
+}
+
+let activeWorker: Worker | null = null;
+let testHooks: RestoreJobTestHooks | null = null;
+let cancelActiveRun: (() => void) | null = null;
+
+export function setRestoreTrashJobTestHooks(hooks: RestoreJobTestHooks | null): void {
+  testHooks = hooks;
+  setStorageMutationCoordinatorTestHooks(hooks);
+}
+
+export function resetRestoreTrashJobForTests(): void {
+  if (activeWorker) {
+    try { activeWorker.terminate(); } catch { /* */ }
+    activeWorker = null;
+  }
+  cancelActiveRun?.();
+  cancelActiveRun = null;
+  testHooks = null;
+  resetStorageMutationCoordinatorForTests();
+}
+
+/** Terminate an in-flight worker during process shutdown. */
+export function abortRestoreTrashJob(): void {
+  if (activeWorker) {
+    try { activeWorker.terminate(); } catch { /* */ }
+    activeWorker = null;
+  }
+  cancelActiveRun?.();
+  cancelActiveRun = null;
+}
+
+/** Test-only SSE/text stream served from the proxy while a worker is blocked. */
+export function getRestoreTrashTestStreamResponse(): Response | null {
+  if (!testHooks?.enableTestStream) return null;
+  const encoder = new TextEncoder();
+  return new Response(
+    new ReadableStream({
+      async start(controller) {
+        for (let i = 0; i < 8; i++) {
+          controller.enqueue(encoder.encode(`chunk-${i}\n`));
+          await Bun.sleep(50);
+        }
+        controller.close();
+      },
+    }),
+    { headers: { "content-type": "text/plain; charset=utf-8" } },
+  );
+}
+
+function runInWorker(opts: {
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  blockMs?: number;
+  restoreTest?: RestoreTestHooks;
+}): Promise<RestoreResult> {
+  return new Promise((resolve, reject) => {
+    const requestId = crypto.randomUUID();
+    let settled = false;
+    const worker = new Worker(new URL("./restore-worker.ts", import.meta.url).href);
+    activeWorker = worker;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cancelActiveRun = null;
+      try { worker.terminate(); } catch { /* */ }
+      if (activeWorker === worker) activeWorker = null;
+      reject(new Error("restore_worker_timeout"));
+    }, WORKER_TIMEOUT_MS);
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      cancelActiveRun = null;
+      clearTimeout(timer);
+      if (activeWorker === worker) activeWorker = null;
+      try { worker.terminate(); } catch { /* */ }
+      fn();
+    };
+
+    cancelActiveRun = () => {
+      finish(() => reject(new Error("aborted")));
+    };
+
+    worker.onmessage = (event: MessageEvent<unknown>) => {
+      const data = event.data;
+      if (!data || typeof data !== "object") return;
+      const msg = data as Record<string, unknown>;
+      if (msg.requestId !== requestId) return;
+      if (msg.type === "done" && msg.result && typeof msg.result === "object") {
+        finish(() => resolve(msg.result as RestoreResult));
+        return;
+      }
+      if (msg.type === "error") {
+        const message = typeof msg.message === "string" ? msg.message : "worker_failed";
+        finish(() => reject(new Error(message)));
+      }
+    };
+
+    worker.onerror = (err: ErrorEvent) => {
+      finish(() => reject(err.error instanceof Error ? err.error : new Error(err.message || "worker_failed")));
+    };
+
+    worker.postMessage({
+      type: "run",
+      requestId,
+      trashId: opts.trashId,
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(opts.blockMs !== undefined ? { blockMs: opts.blockMs } : {}),
+      ...(opts.restoreTest ? { restoreTest: opts.restoreTest } : {}),
+      env: {
+        ...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
+        ...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),
+      },
+    });
+  });
+}
+
+async function executeRestore(opts: {
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  _test?: RestoreTestHooks;
+}): Promise<RestoreResult> {
+  const blockMs = testHooks?.blockMs;
+  const restoreTest = opts._test ?? testHooks?.restoreTest;
+
+  if (testHooks?.runInProcess) {
+    if (typeof blockMs === "number" && blockMs > 0) await Bun.sleep(blockMs);
+    return restoreTrashEntry(opts.trashId, {
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(restoreTest ? { _test: restoreTest } : {}),
+    });
+  }
+
+  try {
+    return await runInWorker({
+      trashId: opts.trashId,
+      ...(opts.codexHome ? { codexHome: opts.codexHome } : {}),
+      ...(opts.busyTimeoutMs !== undefined ? { busyTimeoutMs: opts.busyTimeoutMs } : {}),
+      ...(typeof blockMs === "number" && blockMs > 0 ? { blockMs } : {}),
+      ...(restoreTest ? { restoreTest } : {}),
+    });
+  } catch (err) {
+    return restoreResultFromWorkerRejection(err, opts.trashId);
+  }
+}
+
+function busyRestoreResult(): RestoreResult {
+  return {
+    ok: false,
+    count: 0,
+    bytes: 0,
+    restoredPaths: [],
+    error: "storage_mutation_busy",
+  };
+}
+
+/**
+ * Run trash restore off the event loop under the shared storage-mutation gate.
+ * Returns `storage_mutation_busy` when cleanup or another restore is in flight.
+ */
+export async function runRestoreTrashEntryJob(
+  trashId: string,
+  options?: {
+    codexHome?: string;
+    busyTimeoutMs?: number;
+    _test?: RestoreTestHooks;
+  },
+): Promise<RestoreResult> {
+  const codexHome = options?.codexHome ?? resolveCodexHomeDir();
+  const result = await withStorageMutationSlot("restore", codexHome, () =>
+    executeRestore({ trashId, ...options }),
+  );
+  if (result && typeof result === "object" && "ok" in result && result.ok === false
+    && "error" in result && result.error === "storage_mutation_busy") {
+    return busyRestoreResult();
+  }
+  return result as RestoreResult;
+}

package/src/storage/restore-worker.ts

@@ -0,0 +1,52 @@
+/**
+ * Worker-thread entry for trash restore runs.
+ * Keeps file moves and SQLite reconcile off the proxy event loop.
+ */
+import { restoreTrashEntry, type RestoreResult, type RestoreTestHooks } from "./cleanup";
+
+interface RunMessage {
+  type: "run";
+  requestId: string;
+  trashId: string;
+  codexHome?: string;
+  busyTimeoutMs?: number;
+  /** Test-only: block before restore so responsiveness tests can probe /healthz. */
+  blockMs?: number;
+  restoreTest?: RestoreTestHooks;
+  /** Env snapshot — Workers may not see parent mutations on all platforms. */
+  env?: { CODEX_HOME?: string; OPENCODEX_HOME?: string };
+}
+
+function isRunMessage(data: unknown): data is RunMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const o = data as Record<string, unknown>;
+  return o.type === "run" && typeof o.requestId === "string" && typeof o.trashId === "string";
+}
+
+declare const self: Worker;
+
+self.onmessage = async (event: MessageEvent<unknown>) => {
+  if (!isRunMessage(event.data)) return;
+  const { requestId, trashId, codexHome, busyTimeoutMs, blockMs, restoreTest, env } = event.data;
+  try {
+    if (env?.CODEX_HOME) process.env.CODEX_HOME = env.CODEX_HOME;
+    if (env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = env.OPENCODEX_HOME;
+    if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
+      await Bun.sleep(Math.floor(blockMs));
+    }
+    const result = restoreTrashEntry(trashId, {
+      ...(codexHome ? { codexHome } : {}),
+      ...(busyTimeoutMs !== undefined ? { busyTimeoutMs } : {}),
+      ...(restoreTest ? { _test: restoreTest } : {}),
+    });
+    self.postMessage({ type: "done", requestId, result });
+  } catch (err) {
+    self.postMessage({
+      type: "error",
+      requestId,
+      message: err instanceof Error ? err.message : "worker_failed",
+    });
+  }
+};
+
+export type { RestoreResult };

package/src/storage/storage-mutation-coordinator.ts

@@ -0,0 +1,109 @@
+/**
+ * Single-flight gate for CODEX_HOME storage mutations (cleanup, restore, policy).
+ *
+ * Manual cleanup, trash restore, and (Phase 3) policy-driven cleanup share one
+ * in-flight slot per resolved CODEX_HOME. A second caller receives
+ * `storage_mutation_busy` immediately — no per-operation queues.
+ */
+import { resolve } from "node:path";
+import { resolveCodexHomeDir } from "../codex/home";
+
+export type StorageMutationKind = "cleanup" | "restore" | "policy";
+
+export type StorageMutationBusyError = "storage_mutation_busy";
+
+export interface StorageMutationCoordinatorTestHooks {
+  /** Block after acquiring the slot, before mutation work (race tests). */
+  blockMs?: number;
+}
+
+interface ActiveSlot {
+  kind: StorageMutationKind;
+  startedAt: number;
+}
+
+const slots = new Map<string, ActiveSlot>();
+let testHooks: StorageMutationCoordinatorTestHooks | null = null;
+
+function slotKey(codexHome?: string): string {
+  return resolve(codexHome ?? resolveCodexHomeDir());
+}
+
+export function setStorageMutationCoordinatorTestHooks(
+  hooks: StorageMutationCoordinatorTestHooks | null,
+): void {
+  testHooks = hooks;
+}
+
+export function resetStorageMutationCoordinatorForTests(): void {
+  testHooks = null;
+  slots.clear();
+}
+
+export function getActiveStorageMutation(
+  codexHome?: string,
+): { kind: StorageMutationKind; startedAt: number } | null {
+  const active = slots.get(slotKey(codexHome));
+  return active ? { kind: active.kind, startedAt: active.startedAt } : null;
+}
+
+export function tryBeginStorageMutation(
+  kind: StorageMutationKind,
+  codexHome?: string,
+): { acquired: true } | { acquired: false; error: StorageMutationBusyError } {
+  const key = slotKey(codexHome);
+  if (slots.has(key)) {
+    return { acquired: false, error: "storage_mutation_busy" };
+  }
+  slots.set(key, { kind, startedAt: Date.now() });
+  return { acquired: true };
+}
+
+export function endStorageMutation(codexHome?: string): void {
+  slots.delete(slotKey(codexHome));
+}
+
+async function applyCoordinatorBlock(): Promise<void> {
+  const blockMs = testHooks?.blockMs;
+  if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
+    await Bun.sleep(Math.floor(blockMs));
+  }
+}
+
+/**
+ * Phase 3 policy worker integration — wrap policy-driven cleanup FS/DB work.
+ * Returns `{ ok: false, error: 'storage_mutation_busy' }` when another mutation
+ * holds the CODEX_HOME slot.
+ */
+export async function runPolicyStorageMutation<T>(
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation("policy", codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    endStorageMutation(codexHome);
+  }
+}
+
+export async function withStorageMutationSlot<T>(
+  kind: StorageMutationKind,
+  codexHome: string | undefined,
+  work: () => T | Promise<T>,
+): Promise<T | { ok: false; error: StorageMutationBusyError }> {
+  const gate = tryBeginStorageMutation(kind, codexHome);
+  if (!gate.acquired) {
+    return { ok: false, error: "storage_mutation_busy" };
+  }
+  try {
+    await applyCoordinatorBlock();
+    return await work();
+  } finally {
+    endStorageMutation(codexHome);
+  }
+}

package/src/tray/windows.ts

@@ -6,6 +6,7 @@ import { join, resolve } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
 import { durableBunPath } from "../lib/bun-runtime";
 import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
 const RUN_PARENT_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion";
@@ -476,6 +477,7 @@ export function installWindowsTray(startNow = true): WindowsTrayStatus {
   for (const path of [entry.bun, entry.cli, sourceScript, ...iconPairs.map(pair => pair.source)]) {
     if (!existsSync(path)) throw new Error(`Cannot install the tray because a required file is missing: ${path}`);
   }
+  recordOwnedConfigPath(getConfigDir(), trayStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
   const runCommand = buildWindowsTrayRunCommand(entry);
   const runValue = windowsTrayRunValue(entry.opencodexHome);

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { KiroOAuthMetadata } from "./oauth/types";
+
 export interface OcxParsedRequest {
   modelId: string;
   previousResponseId?: string;
@@ -23,6 +25,8 @@ export interface OcxParsedRequest {
    * derived from the parent thread id.
    */
   _cursorIsolateConversation?: boolean;
+  /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
+  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion">;
   /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
   _providerContinuation?: OcxProviderContinuationState;
   /**
@@ -31,6 +35,8 @@ export interface OcxParsedRequest {
    * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
    */
   _webSearch?: Record<string, unknown>;
+  /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
+  _imageGeneration?: { toolNames: Set<string>; originalTool?: Record<string, unknown> };
   /**
    * True when Codex requested structured output (`text.format` = json_schema/json_object). The
    * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
@@ -152,6 +158,10 @@ export interface OcxTool {
   loadedFromToolSearch?: boolean;
   /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
   webSearch?: boolean;
+  /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
+  imageGeneration?: boolean;
+  /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
+  videoGeneration?: boolean;
 }
 
 /**
@@ -432,6 +442,11 @@ export interface OcxClaudeCodeConfig {
    * free. Only ocx-*.md files are owned/pruned. Default: enabled.
    */
   injectAgents?: boolean;
+  /**
+   * Optional Claude Code effort pinned in every generated ocx-* subagent
+   * definition. Unset inherits the parent session effort.
+   */
+  subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
   /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
   webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
@@ -459,6 +474,25 @@ export interface OcxClaudeDesktopProfile {
   appliedAt?: string;
 }
 
+/**
+ * Opt-in archived-session auto-cleanup policy (issue #42 Phase 3).
+ * Persisted under `OcxConfig.storageCleanupPolicy`. Default `enabled: false`.
+ */
+export interface StorageCleanupPolicy {
+  /** When false/unset, the engine never mutates. Default false. */
+  enabled: boolean;
+  /** Run when archived session bytes exceed this threshold. */
+  trigger: { archivedBytesOver: number };
+  /** Either shrink archives toward a byte floor, or remove the oldest N%. */
+  target: { reduceToBytes?: number } | { removeOldestPercent?: number };
+  schedule: "startup" | "daily" | "weekly" | "manual";
+  /** Default quarantine. Permanent only when explicitly set. */
+  mode: "quarantine" | "permanent";
+  lastRun?: { at: number; freedBytes: number; removed: number };
+  /** Epoch ms when the next scheduled evaluation is due. */
+  nextRun?: number;
+}
+
 /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
 export interface OcxCustomModel {
   /** 고유 ID (crypto.randomUUID()) */
@@ -501,6 +535,11 @@ export interface OcxConfig {
    */
   subagentModelFallbackPollMs?: number;
   injectionModel?: string;
+  /**
+   * Opt in to synchronizing the selected injection model into Codex's native
+   * sub-agent defaults. Only meaningful while `injectionModel` is set.
+   */
+  syncCodexSubagentDefaults?: boolean;
   /**
    * Optional reasoning effort the delegation prompt tells the agent to pass in spawn_agent calls
    * (`reasoning_effort` argument). Only meaningful while `injectionModel` is set; validated against
@@ -613,6 +652,12 @@ export interface OcxConfig {
   shutdownTimeoutMs?: number;
   /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */
   websockets?: boolean;
+  /**
+   * Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
+   * Default OFF (`enabled` false / unset). Never enabled implicitly.
+   * See `src/storage/policy.ts`.
+   */
+  storageCleanupPolicy?: StorageCleanupPolicy;
   /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
   apiKeys?: Array<{ id: string; name: string; key: string; createdAt: string }>;
   /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
@@ -640,12 +685,38 @@ export interface OcxConfig {
   search?: OcxSearchConfig;
   /** Codex multi-account pool. */
   codexAccounts?: CodexAccount[];
+  /** Account ids administratively excluded from future pool selection until resumed. */
+  pausedCodexAccountIds?: string[];
+  /**
+   * Public model-selector namespaces bound to one Codex account. Values are stored account ids;
+   * `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
+   * are intentionally separate from these selectors.
+   */
+  codexAccountNamespaces?: Record<string, string>;
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
   activeCodexAccountId?: string;
   /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
   autoSwitchThreshold?: number;
+  /** New-session account rotation strategy for the Codex pool. Default quota (today's behaviour). */
+  accountPoolStrategy?: OcxAccountPoolRotationStrategy;
+  /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+  accountPoolStickyLimit?: number;
   /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
   upstreamFailoverThreshold?: number;
+  /**
+   * Opt-in Anthropic OAuth account pool (#294). Default OFF.
+   * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
+   * Experimental — see docs and GUI warning before enabling.
+   */
+  anthropicAccountPool?: {
+    enabled?: boolean;
+    /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
+    autoSwitchThreshold?: number;
+    /** New-session rotation strategy. Default quota (today's behaviour). */
+    strategy?: OcxAccountPoolRotationStrategy;
+    /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+    stickyLimit?: number;
+  };
   /** Virtual `combo/<id>` models spanning concrete provider/model targets (issue #133). */
   combos?: Record<string, OcxComboConfig>;
   /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
@@ -654,6 +725,8 @@ export interface OcxConfig {
   corsAllowOrigins?: string[];
 }
 
+export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
+
 export type OcxComboStrategy = "failover" | "round-robin";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
 
@@ -714,8 +787,24 @@ export interface OcxTokenGuardianConfig {
 export interface OcxImagesConfig {
   /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
   provider?: string;
-  /** Upstream timeout (ms) for one /v1/images relay. Default 300000 — generation is slow. */
+  /** Upstream timeout (ms) for one image generation/edit call (bridge xAI + /v1/images relay). Default 60000 for the bridge; relay may use a higher default (300000). */
   timeoutMs?: number;
+  /** Master switch for the image bridge. Default false — set true to enable paid xAI Grok Imagine generation. */
+  bridgeEnabled?: boolean;
+  /** xAI image model id. Default "grok-imagine-image-quality" (see DEFAULT_MODEL in images/plan.ts). */
+  bridgeModel?: string;
+  /** Max image-generation loop iterations before forced-final. Default 3; clamped to [0, 10]. */
+  maxRounds?: number;
+  /** Max files retained under artifacts/. Oldest deleted when exceeded. Default 200. */
+  artifactsKeepCount?: number;
+  /** Master switch for the video bridge. Default false — must be explicitly opted in. */
+  videoBridgeEnabled?: boolean;
+  /** Model for xAI video generation. Default "grok-imagine-video". */
+  videoBridgeModel?: string;
+  /** Max video-gen rounds before forced-final. Default 2 (video is slower than image). */
+  videoMaxRounds?: number;
+  /** Per-video generation timeout (ms) including polling. Default 300000 (5 min). */
+  videoTimeoutMs?: number;
 }
 
 export interface OcxSearchConfig {
@@ -817,6 +906,12 @@ export interface OcxProviderConfig {
    */
   codexAccountMode?: CodexAccountMode;
   apiKey?: string;
+  /**
+   * Key-auth header style for Anthropic-compatible providers.
+   * Defaults to the native Anthropic `x-api-key`; gateways may require
+   * `Authorization: Bearer <key>` instead.
+   */
+  apiKeyTransport?: "x-api-key" | "bearer";
   /**
    * Multi-key pool (API-key twin of OAuth multiauth). `apiKey` always mirrors the ACTIVE
    * entry so routing stays single-key; managed via /api/providers/keys. A legacy bare