onbuzz 4.2.0 → 4.3.0

package/src/tools/imageTool.js

@@ -7,6 +7,7 @@ import path from 'path';
 import os from 'os';
 import { promises as fs } from 'fs';
 import { BaseTool } from './baseTool.js';
+import { getGalleryService } from '../services/galleryService.js';
 
 /**
  * Configuration constants for image generation
@@ -15,20 +16,50 @@ const IMAGE_CONFIG = {
   DEFAULT_MODEL: null, // Resolved dynamically from modelsService via aiService
   DEFAULT_SIZE: '1024x1024',
   DEFAULT_QUALITY: 'standard',
-  // Flux 1.1 Pro size constraints
+  // Flux-family size rules (used when the effective model matches FLUX_MODELS).
   SIZE_MIN: 256,
   SIZE_MAX: 1440,
   SIZE_INCREMENT: 32,  // Must be multiples of 32
-  // Common presets for convenience (all valid per constraints above)
+
+  /**
+   * Per-model size rules. Two kinds of rule:
+   *   { kind: 'enum',  values: ['1024x1024', ...] }      — exact match required
+   *   { kind: 'range', min, max, increment }             — W×H in grid
+   * Key matching is substring, case-insensitive (so 'gpt-image-1.5' matches
+   * 'gpt-image-1.5-preview', etc.). The first matching entry wins; anything
+   * else falls back to `default`.
+   *
+   * This table is the SINGLE SOURCE OF TRUTH for what the tool accepts
+   * client-side. Previously the validator was hardcoded to Flux rules and
+   * actively rejected valid gpt-image-1.5 sizes (1024x1536, 1536x1024, auto)
+   * while the tool's own docstring advertised them. See _validateParameters.
+   */
+  MODEL_SIZES: {
+    'gpt-image-1.5': { kind: 'enum',  values: ['1024x1024', '1024x1536', '1536x1024', 'auto'] },
+    'gpt-image-1':   { kind: 'enum',  values: ['1024x1024', '1024x1536', '1536x1024', 'auto'] },
+    'flux':          { kind: 'range', min: 256, max: 1440, increment: 32 },
+    'default':       { kind: 'range', min: 256, max: 1440, increment: 32 },
+  },
+
+  /**
+   * Size presets, model-aware. Each entry is a shape key; the resolver
+   * picks the variant for the effective model. If the model isn't listed,
+   * the `default` variant is used (Flux-shaped).
+   *
+   * Agents were previously confused because `portrait` → 1024x1440 always,
+   * even when the tool silently auto-switched to gpt-image-1.5 (where that
+   * size is invalid). Now `portrait` resolves to 1024x1536 for gpt-image.
+   */
   SIZE_PRESETS: {
-    'square': '1024x1024',
-    'square_hd': '1440x1440',
-    'portrait': '1024x1440',
-    'landscape': '1440x1024',
-    'portrait_4_3': '768x1024',
-    'landscape_4_3': '1024x768',
-    'small': '512x512'
+    'square':         { default: '1024x1024', 'gpt-image-1.5': '1024x1024' },
+    'square_hd':      { default: '1440x1440', 'gpt-image-1.5': '1024x1024' },
+    'portrait':       { default: '1024x1440', 'gpt-image-1.5': '1024x1536' },
+    'landscape':      { default: '1440x1024', 'gpt-image-1.5': '1536x1024' },
+    'portrait_4_3':   { default: '768x1024',  'gpt-image-1.5': '1024x1536' },
+    'landscape_4_3':  { default: '1024x768',  'gpt-image-1.5': '1536x1024' },
+    'small':          { default: '512x512',   'gpt-image-1.5': '1024x1024' },
   },
+
   VALID_FORMATS: ['png', 'jpg', 'jpeg', 'webp'],
   MAX_CONCURRENT: 3,
   QUEUE_LIMIT: 10,
@@ -37,6 +68,100 @@ const IMAGE_CONFIG = {
   DOWNLOAD_TIMEOUT: 60000 // 60 seconds
 };
 
+/**
+ * Resolve the effective model given the caller's inputs.
+ *
+ * The tool auto-switches to `gpt-image-1.5` when the caller asks for
+ * transparency or supplies a sourceImage (only gpt-image-1.5 supports
+ * those features). Previously this logic lived inside the async worker,
+ * AFTER _validateParameters ran — so validation applied Flux rules even
+ * when the real model would end up being gpt-image-1.5 and vice versa.
+ * Hoisted here so validators, error messages, and preset resolution all
+ * see the same truth.
+ *
+ * @param {object} params - imageParams with { model, transparency, sourceImage }
+ * @returns {string} — the effective model id (lowercase)
+ */
+export function resolveEffectiveImageModel(params = {}) {
+  const explicit = (params.model || '').toLowerCase();
+  if (explicit && explicit !== 'auto') return explicit;
+  if (params.transparency === true) return 'gpt-image-1.5';
+  if (params.sourceImage)            return 'gpt-image-1.5';
+  // Null → defer to downstream (aiService resolves from catalog). We
+  // still return a sentinel so validators can use `default` rules.
+  return '';
+}
+
+/**
+ * Translate an image-generation error into an actionable message for the
+ * agent. The backend (`aiService._generateImageOpenAI` / Flux) wraps HTTP
+ * responses as `"HTTP 400: Bad Request - <provider text>"` and throws.
+ * That passes through to the agent as raw stack text — agents don't know
+ * whether they tripped a size rule, a moderation rule, or something else.
+ *
+ * This helper parses the incoming `Error` for the common signatures and
+ * produces a message that includes (a) the effective model, (b) what
+ * class of failure it was, and (c) a concrete next-action.
+ *
+ * @param {Error}  error - Thrown from aiService / downstream
+ * @param {object} job   - The queued job (provides model + size + prompt)
+ * @returns {string}
+ */
+export function _translateImageError(error, job = {}) {
+  const raw = (error && error.message) || String(error || 'unknown error');
+  const effectiveModel = resolveEffectiveImageModel(job) || job.model || 'auto';
+  const size = job.size || IMAGE_CONFIG.DEFAULT_SIZE;
+  const lower = raw.toLowerCase();
+
+  // Content moderation family — providers use various phrasings.
+  if (/moderat|content[_ -]policy|safety|flagged|unsafe/.test(lower)) {
+    return (
+      `Image generation rejected by content moderation (model=${effectiveModel}). ` +
+      `The prompt was flagged. Rephrase rather than retrying verbatim: soften explicit ` +
+      `adjectives (e.g. drop "blood", "gore", "bones"), describe style instead of violence, ` +
+      `and avoid real-person likenesses. Original provider message: ${raw}`
+    );
+  }
+
+  // Size-shaped rejections from the provider (leaks through when our
+  // client-side validator missed, or when the catalogue changes).
+  if (/size|dimension|unsupported|out of range|must be one of|invalid image size/.test(lower)) {
+    const { rule } = _getModelSizeRule(effectiveModel);
+    const valid = rule.kind === 'enum'
+      ? `Valid sizes for ${effectiveModel}: ${rule.values.join(', ')}.`
+      : `Valid for ${effectiveModel}: WIDTHxHEIGHT in ${rule.min}-${rule.max}, multiples of ${rule.increment}.`;
+    return (
+      `Image generation rejected: size "${size}" not accepted by ${effectiveModel}. ${valid} ` +
+      `Original provider message: ${raw}`
+    );
+  }
+
+  // Auth / quota.
+  if (/unauthorized|forbidden|quota|rate.?limit|429|401|403/.test(lower)) {
+    return (
+      `Image generation failed for ${effectiveModel}: authentication or quota problem. ` +
+      `Retrying with the same inputs will likely fail again — check API keys / billing. ` +
+      `Original: ${raw}`
+    );
+  }
+
+  // Fall-through: still tell the agent which model ran.
+  return `Image generation failed (model=${effectiveModel}, size=${size}): ${raw}`;
+}
+
+/**
+ * Look up the size rule for an effective model id. Substring match.
+ * Always returns a rule (falls back to `default`).
+ */
+export function _getModelSizeRule(effectiveModel) {
+  const key = String(effectiveModel || '').toLowerCase();
+  for (const [needle, rule] of Object.entries(IMAGE_CONFIG.MODEL_SIZES)) {
+    if (needle === 'default') continue;
+    if (key.includes(needle)) return { modelKey: needle, rule };
+  }
+  return { modelKey: 'default', rule: IMAGE_CONFIG.MODEL_SIZES.default };
+}
+
 /**
  * ImageTool - Generate images using AI models
  * Supports queueing, async processing, and both temp/project directory storage
@@ -140,20 +265,34 @@ export class ImageTool extends BaseTool {
 **Parameters:**
 - **prompt** (required): Description of image to generate OR editing instruction
 - **outputPath** (optional): Path to save image (permanent). Omit for temp file.
-- **size** (optional): Custom WIDTHxHEIGHT or preset name (default: 1024x1024)
-  - For Flux models: 256-1440px, multiples of 32 (e.g., 1024x768, 1280x960)
-  - For gpt-image-1.5: 1024x1024, 1024x1536, 1536x1024, or "auto"
-  - Presets: square (1024x1024), square_hd (1440x1440), portrait (1024x1440), landscape (1440x1024), portrait_4_3 (768x1024), landscape_4_3 (1024x768), small (512x512)
+- **size** (optional): WIDTHxHEIGHT or preset name. DIFFERENT MODELS ACCEPT DIFFERENT SIZES — read the rules below. Default: 1024x1024.
 - **quality** (optional): "standard" or "hd" (default: standard)
-- **model** (optional): Use "gpt-image-1.5" for transparency and editing capabilities (default: auto)
-- **sourceImage** (optional): Path to source image for editing (enables edit mode)
+- **model** (optional): "gpt-image-1.5" or a flux variant. Default: auto. Auto-switches to gpt-image-1.5 if transparency=true OR sourceImage is set.
+- **sourceImage** (optional): Path to source image for editing (forces gpt-image-1.5)
 - **mask** (optional): Path to mask image for editing (white=edit area, black=keep area)
-- **transparency** (optional): true to generate image with transparent background (auto-selects gpt-image-1.5)
+- **transparency** (optional): true to generate with transparent background (forces gpt-image-1.5)
+
+⚠ SIZE RULES — read before picking a size:
+
+  (A) gpt-image-1.5 (auto-selected on transparency=true or sourceImage, or set explicitly):
+      size MUST be one of: 1024x1024, 1024x1536 (portrait), 1536x1024 (landscape), or "auto".
+      Any other value is rejected; the error lists the valid options.
+      Presets remap automatically — e.g. "portrait" → 1024x1536 on this model.
+
+  (B) Flux models (the default when transparency is not required):
+      size must be WIDTHxHEIGHT, both in 256-1440, both multiples of 32 (e.g. 1024x768, 1280x960).
+      "auto" is NOT valid for Flux.
+
+Presets (shape names — resolved per the chosen model):
+  square, square_hd, portrait, landscape, portrait_4_3, landscape_4_3, small
+
+Content moderation:
+- Prompts with graphic violence, gore, explicit sexual content, or real-person likenesses are commonly rejected by the provider as "Bad request". If you hit one of those, REPHRASE — don't retry verbatim. Soften explicit adjectives (e.g. "dark fantasy queen with crimson rubies" works; "blood tears, bone crown, dripping" typically doesn't).
 
 **Notes:**
 - Images take 15-30 seconds to generate
 - Be descriptive in prompts for better results
-- Use **gpt-image-1.5** when you need: transparent backgrounds, image editing, or image-to-image transformations
+- Use gpt-image-1.5 when you need transparent backgrounds, image editing, or image-to-image transformations
 - Max ${IMAGE_CONFIG.QUEUE_LIMIT} images in queue`;
   }
 
@@ -335,6 +474,10 @@ export class ImageTool extends BaseTool {
           quality: imageParams.quality,
           projectDir: projectDir || process.cwd(),
           directoryAccess,
+          // Carry the caller's per-agent image-gen config onto the job
+          // so the async processor (which doesn't have the original
+          // context) can still honor `saveToGallery` etc.
+          toolConfig: context?.toolConfig || null,
           status: 'queued',
           createdAt: new Date().toISOString()
         };
@@ -402,35 +545,88 @@ export class ImageTool extends BaseTool {
         throw new Error(`Prompt too long (max ${IMAGE_CONFIG.MAX_PROMPT_LENGTH} characters)`);
       }
 
-      if (img.size) {
-        // Check for preset names first
-        if (IMAGE_CONFIG.SIZE_PRESETS[img.size]) {
-          img.size = IMAGE_CONFIG.SIZE_PRESETS[img.size];
-        }
+      // Resolve the effective model FIRST so size validation, preset
+      // resolution, and error messages all see the model that will
+      // actually run. Previously this logic lived downstream in the
+      // async worker so Flux rules were applied even when the tool
+      // would silently switch to gpt-image-1.5 (transparency=true,
+      // sourceImage set, or explicit model) — and vice versa.
+      const effectiveModel = resolveEffectiveImageModel(img);
+      const { modelKey: ruleKey, rule } = _getModelSizeRule(effectiveModel);
 
-        // Validate WxH format
-        const sizeMatch = img.size.match(/^(\d+)x(\d+)$/);
-        if (!sizeMatch) {
-          throw new Error(`Invalid size format: ${img.size}. Use WIDTHxHEIGHT (e.g., 1024x768) or preset: ${Object.keys(IMAGE_CONFIG.SIZE_PRESETS).join(', ')}`);
+      if (img.size) {
+        // Step 1: expand preset names. Presets are model-aware — e.g.
+        // `portrait` is 1024x1440 on Flux but 1024x1536 on gpt-image-1.5
+        // (the latter only accepts specific enum values). Previously the
+        // preset was resolved Flux-shaped and then rejected downstream.
+        const presetEntry = IMAGE_CONFIG.SIZE_PRESETS[img.size];
+        if (presetEntry) {
+          img.size = presetEntry[ruleKey] || presetEntry.default;
         }
 
-        const width = parseInt(sizeMatch[1], 10);
-        const height = parseInt(sizeMatch[2], 10);
-
-        // Validate constraints
-        const { SIZE_MIN, SIZE_MAX, SIZE_INCREMENT } = IMAGE_CONFIG;
-
-        if (width < SIZE_MIN || width > SIZE_MAX) {
-          throw new Error(`Width ${width} out of range. Must be ${SIZE_MIN}-${SIZE_MAX}px.`);
-        }
-        if (height < SIZE_MIN || height > SIZE_MAX) {
-          throw new Error(`Height ${height} out of range. Must be ${SIZE_MIN}-${SIZE_MAX}px.`);
-        }
-        if (width % SIZE_INCREMENT !== 0) {
-          throw new Error(`Width ${width} must be a multiple of ${SIZE_INCREMENT}.`);
-        }
-        if (height % SIZE_INCREMENT !== 0) {
-          throw new Error(`Height ${height} must be a multiple of ${SIZE_INCREMENT}.`);
+        // Step 2: per-model rule check.
+        if (rule.kind === 'enum') {
+          // gpt-image-1.5 et al — exact enum.
+          if (!rule.values.includes(img.size)) {
+            const modelLabel = effectiveModel || 'gpt-image-1.5';
+            const autoHint = img.transparency
+              ? ' (auto-selected because transparency=true)'
+              : img.sourceImage
+                ? ' (auto-selected because sourceImage was provided)'
+                : '';
+            throw new Error(
+              `Image size "${img.size}" is not supported by ${modelLabel}${autoHint}. ` +
+              `Valid sizes: ${rule.values.join(', ')}. ` +
+              `For portrait orientation use "1024x1536"; for landscape use "1536x1024".`
+            );
+          }
+        } else {
+          // Range rule (Flux and default). `auto` is an enum-only value
+          // that makes no sense for a range model — reject with a hint.
+          if (img.size === 'auto') {
+            throw new Error(
+              `Image size "auto" is only valid for gpt-image-1.5. ` +
+              `For the current model (${effectiveModel || 'flux'}) pick a WIDTHxHEIGHT ` +
+              `between ${rule.min} and ${rule.max} in ${rule.increment}-pixel steps ` +
+              `(e.g. 1024x1024).`
+            );
+          }
+          const sizeMatch = img.size.match(/^(\d+)x(\d+)$/);
+          if (!sizeMatch) {
+            throw new Error(
+              `Invalid size format: "${img.size}". ` +
+              `Use WIDTHxHEIGHT (e.g. 1024x768) or one of these presets: ` +
+              `${Object.keys(IMAGE_CONFIG.SIZE_PRESETS).join(', ')}.`
+            );
+          }
+          const width  = parseInt(sizeMatch[1], 10);
+          const height = parseInt(sizeMatch[2], 10);
+          const { min, max, increment } = rule;
+          const modelLabel = effectiveModel || 'flux';
+          if (width < min || width > max) {
+            throw new Error(
+              `Width ${width} out of range for ${modelLabel}. Must be ${min}-${max}px ` +
+              `(multiple of ${increment}).`
+            );
+          }
+          if (height < min || height > max) {
+            throw new Error(
+              `Height ${height} out of range for ${modelLabel}. Must be ${min}-${max}px ` +
+              `(multiple of ${increment}).`
+            );
+          }
+          if (width % increment !== 0) {
+            throw new Error(
+              `Width ${width} must be a multiple of ${increment} for ${modelLabel}. ` +
+              `Nearest valid: ${Math.round(width / increment) * increment}.`
+            );
+          }
+          if (height % increment !== 0) {
+            throw new Error(
+              `Height ${height} must be a multiple of ${increment} for ${modelLabel}. ` +
+              `Nearest valid: ${Math.round(height / increment) * increment}.`
+            );
+          }
         }
       }
 
@@ -492,6 +688,42 @@ export class ImageTool extends BaseTool {
             // Image was saved successfully - use our server endpoint
             imageUrl = this._convertToWebUrl(result.resolvedOutputPath, job.sessionId);
             this.logger?.info('Using local server URL for image', { imageUrl });
+
+            // Durable gallery copy (non-blocking, non-fatal).
+            // Gated by per-agent `toolConfig.image-gen.saveToGallery`.
+            // Default is ON — users who want to keep disk usage down can
+            // opt out via the image-gen configurator in the agent modal.
+            const saveToGallery = job.toolConfig?.saveToGallery !== false;
+            if (saveToGallery) {
+              try {
+                let agentName = null;
+                if (this.agentPool && job.agentId) {
+                  try {
+                    const a = await this.agentPool.getAgent(job.agentId);
+                    agentName = a?.name || null;
+                  } catch { /* non-fatal */ }
+                }
+                await getGalleryService(this.logger).saveImage({
+                  sourcePath: result.resolvedOutputPath,
+                  metadata: {
+                    prompt: job.prompt,
+                    model: job.model,
+                    size: job.size,
+                    quality: job.quality,
+                    agentId: job.agentId,
+                    agentName,
+                    sessionId: job.sessionId,
+                    jobId: job.jobId,
+                    createdAt: job.completedAt || job.createdAt,
+                  },
+                });
+              } catch (galErr) {
+                this.logger?.warn?.('Gallery save failed (non-fatal)', {
+                  jobId: job.jobId,
+                  error: galErr.message,
+                });
+              }
+            }
           } else if (result.temporaryUrl) {
             // Download failed - use temporary AI-generated URL (expires in ~1 hour)
             imageUrl = result.temporaryUrl;
@@ -619,7 +851,13 @@ export class ImageTool extends BaseTool {
         this.logger?.error(`Image generation failed: ${job.jobId}`, error);
 
         job.status = 'failed';
-        job.error = error.message;
+        // Translate opaque backend errors into something actionable. The
+        // downstream aiService wraps HTTP errors as "HTTP 400: Bad Request - …"
+        // with the provider text tacked on; agents previously saw that
+        // verbatim and had to guess whether it was a size mismatch, a
+        // content-policy trip, or an auth problem. Route known signals
+        // to a structured hint.
+        job.error = _translateImageError(error, job);
         job.completedAt = new Date().toISOString();
 
         this.completedJobs.set(job.jobId, job);

package/src/tools/taskManagerTool.js

@@ -576,10 +576,21 @@ Always use a detailed task description to provide context for the task, and leve
       };
 
     } catch (error) {
+      // IMPORTANT: do NOT log the raw `context` object. The tool-execute
+      // context contains back-references to AgentPool ⇄ MessageProcessor
+      // (plus agentPool.messageProcessor.agentPool…), which triggers
+      // "Converting circular structure to JSON" in the logger's
+      // JSON.stringify — and THAT throw escapes this catch, corrupting
+      // the error surfaced to the agent. Pluck only plain-data fields.
+      // Regression guard: src/utilities/logger.js also has a defensive
+      // replacer that strips known back-ref keys if anyone else leaks a
+      // context-shaped object into logs.
       this.logger?.error('TaskManager execution failed', {
         error: error.message,
-        context,
-        params
+        stack: error.stack,
+        agentId: context?.agentId,
+        action: params?.action,
+        paramKeys: params ? Object.keys(params) : [],
       });
 
       return {

package/src/tools/videoTool.js

@@ -7,6 +7,7 @@ import path from 'path';
 import os from 'os';
 import { promises as fs } from 'fs';
 import { BaseTool } from './baseTool.js';
+import { getGalleryService } from '../services/galleryService.js';
 
 /**
  * Configuration constants for video generation
@@ -72,6 +73,92 @@ export class VideoTool extends BaseTool {
     this.pollTimers = new Map();
   }
 
+  /**
+   * Snapshot of the job state for the web-UI `/api/videos/jobs` endpoint.
+   * Serialises the three job maps into a stable JSON shape that the
+   * Video Jobs page can render + poll on. Intentionally excludes the
+   * large `result` blobs for completed jobs to keep the list light —
+   * consumers that want the full result hit the file-serve URL instead.
+   *
+   * @returns {{
+   *   queued: Array<JobSummary>,
+   *   active: Array<JobSummary>,
+   *   completed: Array<JobSummary>,
+   *   limits: { concurrency: number, queue: number },
+   * }}
+   */
+  getJobsSnapshot() {
+    const summarize = (j) => ({
+      jobId: j.jobId,
+      agentId: j.agentId,
+      sessionId: j.sessionId,
+      prompt: typeof j.prompt === 'string' ? j.prompt.slice(0, 300) : '',
+      model: j.model,
+      width: j.width,
+      height: j.height,
+      duration: j.duration,
+      variants: j.variants,
+      status: j.status || 'unknown',
+      soraJobId: j.soraJobId || null,
+      outputPath: j.outputPath || null,
+      createdAt: j.createdAt || null,
+      startedAt: j.startedAt || null,
+      completedAt: j.completedAt || null,
+      error: j.error || null,
+      // Best-effort URL to the final video file if known. The existing
+      // /api/videos/:sessionId/:filename serve route locates the file.
+      videoUrl: (j.status === 'completed' && j.outputPath && j.sessionId)
+        ? `/api/videos/${encodeURIComponent(j.sessionId)}/${encodeURIComponent(
+            typeof j.outputPath === 'string' ? j.outputPath.split(/[\\/]/).pop() : ''
+          )}`
+        : null,
+    });
+    return {
+      queued:    Array.from(this.queue).map(summarize),
+      active:    Array.from(this.activeJobs.values()).map(summarize),
+      completed: Array.from(this.completedJobs.values()).map(summarize),
+      limits: {
+        concurrency: (typeof VIDEO_CONFIG !== 'undefined' && VIDEO_CONFIG?.CONCURRENCY_LIMIT) || this.activeJobs.size + this.queue.length,
+        queue:       (typeof VIDEO_CONFIG !== 'undefined' && VIDEO_CONFIG?.QUEUE_LIMIT) || null,
+      },
+    };
+  }
+
+  /**
+   * Cancel a video generation job by id. Removes from queue if still
+   * pending, marks active jobs for cancellation (best-effort — an
+   * in-flight Sora API call will still complete, but we stop polling
+   * and stop persisting the result). Returns { success, state }.
+   *
+   * Completed and already-failed jobs are not cancellable.
+   */
+  cancelJob(jobId) {
+    // Queued — just remove from the queue.
+    const qIdx = this.queue.findIndex(j => j.jobId === jobId);
+    if (qIdx !== -1) {
+      const [job] = this.queue.splice(qIdx, 1);
+      job.status = 'cancelled';
+      job.completedAt = new Date().toISOString();
+      this.completedJobs.set(job.jobId, job);
+      this.logger?.info('Video job cancelled (was queued)', { jobId });
+      return { success: true, state: 'queued' };
+    }
+    // Active — mark + stop polling.
+    if (this.activeJobs.has(jobId)) {
+      const job = this.activeJobs.get(jobId);
+      job.status = 'cancelled';
+      job.completedAt = new Date().toISOString();
+      const timer = this.pollTimers?.get(jobId);
+      if (timer) { clearTimeout(timer); this.pollTimers.delete(jobId); }
+      this.activeJobs.delete(jobId);
+      this.completedJobs.set(jobId, job);
+      this.logger?.info('Video job cancelled (was active)', { jobId });
+      return { success: true, state: 'active' };
+    }
+    // Completed / unknown.
+    return { success: false, error: 'Job not found or already terminal' };
+  }
+
   /**
    * Set AI service for video generation
    * @param {AIService} aiService - AI service instance
@@ -329,6 +416,9 @@ Sora simulates a physical world, so write prompts as narratives, not camera comm
           variants: videoParams.variants,
           projectDir: projectDir || process.cwd(),
           directoryAccess,
+          // Per-agent video-gen config (reaches the async processor
+          // through the job). Used to gate `saveToGallery` below.
+          toolConfig: context?.toolConfig || null,
           status: 'queued',
           soraJobId: null, // Will be set when submitted to Sora
           createdAt: new Date().toISOString()
@@ -626,6 +716,42 @@ Sora simulates a physical world, so write prompts as narratives, not camera comm
 
       this.completedJobs.set(job.jobId, job);
 
+      // Durable gallery copy — non-blocking, non-fatal. Skipped when
+      // the agent has opted out via `toolConfig.video-gen.saveToGallery`.
+      if (savedToDisk && resolvedOutputPath && job.toolConfig?.saveToGallery !== false) {
+        try {
+          let agentName = null;
+          if (this.agentPool && job.agentId) {
+            try {
+              const a = await this.agentPool.getAgent(job.agentId);
+              agentName = a?.name || null;
+            } catch { /* non-fatal */ }
+          }
+          await getGalleryService(this.logger).saveVideo({
+            sourcePath: resolvedOutputPath,
+            metadata: {
+              prompt: job.prompt,
+              model: job.model,
+              width: job.width,
+              height: job.height,
+              duration: job.duration,
+              variants: job.variants,
+              agentId: job.agentId,
+              agentName,
+              sessionId: job.sessionId,
+              jobId: job.jobId,
+              soraJobId: job.soraJobId,
+              createdAt: job.completedAt,
+            },
+          });
+        } catch (galErr) {
+          this.logger?.warn?.('Gallery save failed (non-fatal)', {
+            jobId: job.jobId,
+            error: galErr.message,
+          });
+        }
+      }
+
       // Broadcast success
       this._broadcastJobResult(job, savedToDisk ? resolvedOutputPath : null, videoUrl, savedToDisk);