onbuzz 4.5.0 → 4.6.1

package/src/tools/platformControlTool.js

@@ -36,6 +36,10 @@ import {
   isTeamAccessDisabled,
   checkTeamAccess,
   filterAccessibleTeams,
+  FLOW_ACCESS_LEVELS,
+  getFlowAccessLevel,
+  getMaxFlowsCreated,
+  checkFlowMutationAccess,
 } from './platformControl/permissions.js';
 import { isProtectedFromCaller, makeAgentLookup } from './platformControl/ancestry.js';
 import { cascadeDeleteAgent, cascadeDeleteTeam } from './platformControl/cascadeService.js';
@@ -68,6 +72,14 @@ const SUPPORTED_ACTIONS = [
   'delete-team',
   'add-team-member',
   'remove-team-member',
+  // Flow CRUD + execution. Permission key: `flows`. Mirrors agents.
+  'list-flows',
+  'get-flow',
+  'create-flow',
+  'update-flow',
+  'delete-flow',
+  'execute-flow',
+  'dry-run-flow',
 ];
 
 /**
@@ -106,6 +118,7 @@ class PlatformControlTool extends BaseTool {
     /** @type {object|null} */ this.agentPool       = null;
     /** @type {object|null} */ this.stateManager    = null;
     /** @type {object|null} */ this.memoryService   = null;
+    /** @type {object|null} */ this.flowExecutor    = null;
   }
 
   /** Injected from src/index.js after ScheduleService is initialized. */
@@ -132,6 +145,12 @@ class PlatformControlTool extends BaseTool {
     this.logger?.info?.(`[platformcontrol] MemoryService ${memoryService ? 'attached' : 'detached'}`);
   }
 
+  /** Injected — needed for execute-flow / dry-run-flow actions. */
+  setFlowExecutor(flowExecutor) {
+    this.flowExecutor = flowExecutor;
+    this.logger?.info?.(`[platformcontrol] FlowExecutor ${flowExecutor ? 'attached' : 'detached'}`);
+  }
+
   getDescription() {
     return `
 Platform Control Tool: control Loxia platform features (scheduled tasks today; more later).
@@ -178,6 +197,20 @@ ACTIONS — teams (per-agent multi-select scope: member / ownedByMe / all; defau
   add-team-member  { teamId, agentId }                 — add an agent to a team. agentId='self' adds caller.
   remove-team-member { teamId, agentId }               — remove an agent. agentId='self' = leave the team.
 
+ACTIONS — flows (per-agent permission: 'disabled' | 'self-created' | 'all'; default 'disabled'):
+  list-flows                                           — list all flows reachable in your scope (read is unrestricted at any non-disabled level)
+  get-flow         { flowId }                          — fetch a flow's full definition (nodes + edges + variables)
+  create-flow      { name, description?, nodes, edges?, variables? }
+                                                       — create a new flow. Definition must pass schema validation.
+                                                         createdBy is set to YOU automatically.
+                                                         Per-creator quota (maxFlowsCreated, default unlimited) applies.
+  update-flow      { flowId, ...fields }               — patch a flow you have permission to mutate.
+                                                         The full re-validated definition is required when changing nodes/edges.
+  delete-flow      { flowId }                          — cascade-delete: run history + checkpoints + version snapshots.
+  execute-flow     { flowId, input? }                  — kick off a run. Returns runId for polling.
+  dry-run-flow     { flowId } OR { flow }              — lint-only check without execution; surfaces structural issues
+                                                         (orphaned nodes, missing required fields, etc.) before live runs.
+
   list-capabilities                                    — what permission level + scope this agent has
 
 EXAMPLES:
@@ -274,6 +307,14 @@ NOTES:
         case 'delete-team':          return await this._deleteTeam(cfg, callerAgentId, params);
         case 'add-team-member':      return await this._addTeamMember(cfg, callerAgentId, params);
         case 'remove-team-member':   return await this._removeTeamMember(cfg, callerAgentId, params);
+        // Flow CRUD + execution
+        case 'list-flows':           return await this._listFlows(cfg, callerAgentId);
+        case 'get-flow':             return await this._getFlow(cfg, callerAgentId, params);
+        case 'create-flow':          return await this._createFlow(cfg, callerAgentId, params);
+        case 'update-flow':          return await this._updateFlow(cfg, callerAgentId, params);
+        case 'delete-flow':          return await this._deleteFlow(cfg, callerAgentId, params);
+        case 'execute-flow':         return await this._executeFlow(cfg, callerAgentId, params);
+        case 'dry-run-flow':         return await this._dryRunFlow(cfg, callerAgentId, params);
         default:
           return {
             success: false,
@@ -326,6 +367,20 @@ NOTES:
             'Leaving a team you\'re a member of is allowed.',
           ],
         },
+        flows: {
+          level: getFlowAccessLevel(fullCfg),
+          maxFlowsCreated: getMaxFlowsCreated(fullCfg),
+          canList:        getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canCreate:      getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canMutateSelfCreated: getFlowAccessLevel(fullCfg) !== FLOW_ACCESS_LEVELS.DISABLED,
+          canMutateAll:   getFlowAccessLevel(fullCfg) === FLOW_ACCESS_LEVELS.ALL,
+          notes: [
+            'Permission key: flows. Default level is "disabled".',
+            'Flow definitions are validated against the v2 schema before save — invalid flows are rejected with detailed errors.',
+            'delete-flow cascades through run history, checkpoints, and version snapshots.',
+            'execute-flow respects existing flow permission levels — at "self-created" level you can only run flows you created.',
+          ],
+        },
       },
     };
   }
@@ -848,6 +903,173 @@ NOTES:
     const team = await this.stateManager.removeAgentFromTeam(params.teamId, agentId);
     return { success: true, action: 'remove-team-member', teamId: params.teamId, agentId, team };
   }
+
+  // ─── Flow CRUD + execution ─────────────────────────────────────────
+  //
+  // Permission key: `flows`. Default 'disabled'. Same shape as agents:
+  // 'self-created' = only flows you authored, 'all' = admin scope.
+  // Read endpoints (list/get) are unrestricted at any non-disabled
+  // level so an agent can browse what's available before deciding which
+  // to run; mutations (create/update/delete/execute/dry-run) all go
+  // through `checkFlowMutationAccess`.
+
+  /** Resolve the project dir the same way every other path here does. */
+  _flowProjectDir() {
+    return this.stateManager?.config?.project?.directory
+        || this.stateManager?.config?.projectDir
+        || process.cwd();
+  }
+
+  async _listFlows(cfg, callerAgentId) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!this.stateManager) {
+      return { success: false, error: 'StateManager not available.' };
+    }
+    const all = await this.stateManager.getAllFlows(this._flowProjectDir());
+    // List is unrestricted at any non-disabled level — agents can see
+    // what they could run / what the platform offers. Mutability is
+    // surfaced per-row so the LLM knows what it can act on.
+    const list = (all || []).map(f => ({
+      id: f.id,
+      name: f.name,
+      description: f.description || '',
+      version: f.version,
+      createdBy: f.createdBy || null,
+      nodeCount: Array.isArray(f.nodes) ? f.nodes.length : 0,
+      mutable: checkFlowMutationAccess(level, callerAgentId, f).allow,
+    }));
+    return { success: true, action: 'list-flows', count: list.length, flows: list, scope: level };
+  }
+
+  async _getFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const flow = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!flow) return { success: false, error: `Flow not found: ${params.flowId}` };
+    return {
+      success: true, action: 'get-flow', flow,
+      mutable: checkFlowMutationAccess(level, callerAgentId, flow).allow,
+    };
+  }
+
+  async _createFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.name || typeof params.name !== 'string') {
+      return { success: false, error: 'name is required' };
+    }
+    if (!Array.isArray(params.nodes) || params.nodes.length === 0) {
+      return { success: false, error: 'nodes array is required (must have at least one node)' };
+    }
+    // Quota enforcement — count flows the caller has authored so far.
+    const max = getMaxFlowsCreated(cfg);
+    if (max !== null) {
+      const owned = (await this.stateManager.getAllFlows(this._flowProjectDir()))
+        .filter(f => f.createdBy === callerAgentId);
+      if (owned.length >= max) {
+        return {
+          success: false,
+          error: `maxFlowsCreated quota reached: you have created ${owned.length} of ${max} allowed flows.`,
+        };
+      }
+    }
+    // Schema validation runs inside stateManager.createFlow already
+    // (via the route layer); we additionally call validate here so an
+    // invalid create returns a clean structured error rather than going
+    // through the route. Defensive — duplicate guard, no harm.
+    const created = await this.stateManager.createFlow({
+      name:        params.name,
+      description: params.description || '',
+      nodes:       params.nodes,
+      edges:       params.edges || [],
+      variables:   params.variables || {},
+      // Stamp the caller as the author so self-created scope can find it.
+      createdBy:   callerAgentId,
+    }, this._flowProjectDir());
+    return { success: true, action: 'create-flow', flow: created };
+  }
+
+  async _updateFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    // Strip identity-level fields the caller shouldn't be able to spoof.
+    const { id: _id, createdBy: _cb, version: _v, ...patch } = params;
+    const updated = await this.stateManager.updateFlow(params.flowId, patch, this._flowProjectDir());
+    return { success: true, action: 'update-flow', flow: updated };
+  }
+
+  async _deleteFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    await this.stateManager.deleteFlow(params.flowId, this._flowProjectDir());
+    return { success: true, action: 'delete-flow', flowId: params.flowId };
+  }
+
+  async _executeFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    if (!params?.flowId) return { success: false, error: 'flowId is required' };
+    if (!this.flowExecutor) return { success: false, error: 'FlowExecutor not available on this server.' };
+    const target = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+    if (!target) return { success: false, error: `Flow not found: ${params.flowId}` };
+    // Execute counts as a mutation (it consumes credits + writes run history).
+    const access = checkFlowMutationAccess(level, callerAgentId, target);
+    if (!access.allow) return { success: false, error: access.reason };
+    const run = await this.flowExecutor.executeFlow(params.flowId, params.input || {}, {
+      projectDir: this._flowProjectDir(),
+      // Tag the run with the agent that triggered it so audit trails
+      // attribute correctly when an agent kicks a flow off via the tool.
+      triggeredBy: { kind: 'agent', agentId: callerAgentId },
+    });
+    return { success: true, action: 'execute-flow', runId: run?.runId || run?.id || null, status: run?.status || 'queued' };
+  }
+
+  async _dryRunFlow(cfg, callerAgentId, params) {
+    const level = getFlowAccessLevel(cfg);
+    if (level === FLOW_ACCESS_LEVELS.DISABLED) {
+      return { success: false, disabled: true, error: 'Flow management is disabled for this caller.' };
+    }
+    // Dry-run accepts EITHER an existing flowId OR an inline flow def
+    // (so an agent can lint a draft before saving).
+    let flow;
+    if (params?.flowId) {
+      flow = await this.stateManager.getFlow(params.flowId, this._flowProjectDir());
+      if (!flow) return { success: false, error: `Flow not found: ${params.flowId}` };
+    } else if (params?.flow && typeof params.flow === 'object') {
+      flow = params.flow;
+    } else {
+      return { success: false, error: 'Pass either { flowId } or { flow: {...} }' };
+    }
+    if (!this.flowExecutor || typeof this.flowExecutor.dryRun !== 'function') {
+      return { success: false, error: 'FlowExecutor.dryRun not available on this server.' };
+    }
+    const report = await this.flowExecutor.dryRun(flow);
+    return { success: true, action: 'dry-run-flow', report };
+  }
 }
 
 export default PlatformControlTool;

package/src/tools/videoTool.js

@@ -10,34 +10,40 @@ import { BaseTool } from './baseTool.js';
 import { getGalleryService } from '../services/galleryService.js';
 
 /**
- * Configuration constants for video generation
- * Updated for Sora 2 API specifications (supports both Sora 1 and Sora 2)
+ * Configuration constants for video generation.
+ *
+ * Per-model limits (allowed resolutions, allowed durations, whether
+ * variants are supported) are NOT hardcoded here — they live in the
+ * model catalog (`video_config` block on each video-generation row) and
+ * are enforced authoritatively by the backend route. The CLI sends the
+ * request and surfaces the backend's 400 verbatim if the inputs aren't
+ * compatible with the chosen model. This keeps the CLI provider-agnostic
+ * (Sora 1, Sora 2, future video models all just work) and avoids
+ * silently-stale validation tables here.
+ *
+ * The constants below are CLI-side controls only (queue/concurrency/
+ * polling/temp file lifetime/timeout). No model-specific values.
  */
 const VIDEO_CONFIG = {
-  DEFAULT_MODEL: null, // Resolved dynamically from modelsService via aiService
-  DEFAULT_WIDTH: 1920,
-  DEFAULT_HEIGHT: 1080,
-  DEFAULT_DURATION: 10, // seconds
-  DEFAULT_VARIANTS: 1,
-  // Sora 2 supported resolutions (superset of Sora 1 + new HD/4K options)
-  VALID_RESOLUTIONS: [
-    // Landscape
-    '1920x1080', '1792x1024', '1280x720', '854x480',
-    // Portrait
-    '1080x1920', '1024x1792', '720x1280', '480x854',
-    // Square
-    '1080x1080', '720x720', '480x480'
-  ],
-  MIN_DURATION: 1,
-  MAX_DURATION: 25,  // seconds (Sora 2 supports up to 25s)
-  MAX_VARIANTS: 4,
+  DEFAULT_MODEL: null,           // resolved dynamically by aiService
+  DEFAULT_WIDTH:  1280,          // sensible default; any video model in the
+  DEFAULT_HEIGHT: 720,           // catalog with `1280x720` accepts these
+  DEFAULT_DURATION: 4,           // Sora 2's smallest unit; safe across providers
+  DEFAULT_VARIANTS: 1,           // single video per job (Sora 2; Sora 1 supported up to 4)
+  MAX_PROMPT_LENGTH: 4000,
+  // Hard CLI safety bounds — let the backend/catalog be authoritative on
+  // *which specific values* are allowed for the chosen model, but reject
+  // obviously-bogus inputs locally so the user gets immediate feedback.
+  ABSOLUTE_MIN_DURATION: 1,
+  ABSOLUTE_MAX_DURATION: 60,
+  ABSOLUTE_MAX_VARIANTS: 8,
+  // Queue + scheduler controls (CLI-side only).
   MAX_CONCURRENT: 2,
   QUEUE_LIMIT: 5,
-  POLL_INTERVAL: 5000,   // 5 seconds between status checks
-  MAX_POLL_TIME: 600000, // 10 minutes max wait
-  TEMP_CLEANUP_MS: 86400000, // 24 hours (videos expire after 24h anyway)
-  MAX_PROMPT_LENGTH: 4000,
-  DOWNLOAD_TIMEOUT: 300000 // 5 minutes for video download
+  POLL_INTERVAL: 5000,           // ms between status checks
+  MAX_POLL_TIME: 600000,         // 10 minutes max wait per job
+  TEMP_CLEANUP_MS: 86400000,     // 24 h (Sora 2 expires content after 24 h anyway)
+  DOWNLOAD_TIMEOUT: 300000       // 5 minutes for video download
 };
 
 /**
@@ -118,8 +124,12 @@ export class VideoTool extends BaseTool {
       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,
+        // Was reading the non-existent VIDEO_CONFIG.CONCURRENCY_LIMIT and
+        // falling through to `activeJobs.size + queue.length`, which is
+        // 0 when idle and produced a misleading `"concurrency": 0` in the
+        // /api/videos/jobs snapshot (the real cap is MAX_CONCURRENT=2).
+        concurrency: VIDEO_CONFIG?.MAX_CONCURRENT ?? null,
+        queue:       VIDEO_CONFIG?.QUEUE_LIMIT    ?? null,
       },
     };
   }
@@ -182,14 +192,14 @@ export class VideoTool extends BaseTool {
    * @returns {string} Formatted tool description
    */
   getDescription() {
-    return `Tool: Video Generator - Generate videos using Sora 2
+    return `Tool: Video Generator — generate videos from text using the platform's video model.
 
-**Purpose:** Generate videos from text descriptions using Sora 2. Videos are saved to files and displayed in chat.
+**Purpose:** Generate short videos from text descriptions. Videos are saved to disk and made available in chat. The active video model is resolved automatically from the model catalog (currently Sora 2 on this deployment); model-specific limits like allowed resolutions and durations come from the catalog and are enforced by the backend.
 
 **CRITICAL: Automatic Execution**
-- ANY \`\`\`json block with "toolId": "video-gen" will be EXECUTED IMMEDIATELY
-- Just output the command when you want to generate a video
-- Video generation takes several minutes - a job ID is returned immediately
+- ANY \`\`\`json block with "toolId": "video-gen" will be EXECUTED IMMEDIATELY.
+- Just output the command when you want to generate a video.
+- Video generation takes minutes — a job ID is returned immediately and the file lands when the job finishes.
 
 **USAGE:**
 \`\`\`json
@@ -198,22 +208,27 @@ export class VideoTool extends BaseTool {
   "parameters": {
     "prompt": "Detailed description of the video",
     "outputPath": "videos/filename.mp4",
-    "width": 1920,
-    "height": 1080,
-    "duration": 10
+    "width": 1280,
+    "height": 720,
+    "duration": 4
   }
 }
 \`\`\`
 
 **Parameters:**
-- **prompt** (required): Detailed description of video to generate
-- **outputPath** (optional): Path to save video (permanent). Omit for temp file.
-- **width** (optional): Video width - 480, 720, 854, 1024, 1080, 1280, 1792, 1920 (default: 1920)
-- **height** (optional): Video height - 480, 720, 854, 1024, 1080, 1280, 1792, 1920 (default: 1080)
-- **duration** (optional): Duration in seconds, 1-25 (default: 10)
-- **variants** (optional): Number of video variants to generate, 1-4 (default: 1)
+- **prompt** (required): Detailed description of the video.
+- **outputPath** (optional): Where to save the .mp4 (permanent). Omit for a temp file.
+- **width** / **height** (optional): Resolution. The catalog defines allowed pairs per model; the backend rejects unsupported pairs with a clear 400 listing valid values.
+- **duration** (optional): Duration in seconds. The catalog defines allowed values per model.
+- **variants** (optional): Number of video variants. Some models (e.g. Sora 2) only return one video per job; the backend will reject \`variants > 1\` with a clear message naming the model's limit.
+- **model** (optional): Override the auto-resolved model. Must be a video-generation model in the catalog.
+
+**Current model limits (Sora 2):**
+- Resolutions: \`720x1280\`, \`1280x720\`, \`1024x1792\`, \`1792x1024\` (16:9 / 9:16 only — no square or 480p)
+- Durations: \`4\`, \`8\`, or \`12\` seconds (those exact values, no others)
+- Variants: 1 per job — request multiple separately if you need more
 
-**Valid Resolutions:** 1920x1080, 1792x1024, 1280x720, 854x480, 1080x1920, 1024x1792, 720x1280, 480x854, 1080x1080, 720x720, 480x480
+These limits live in the catalog row, not in this tool. If the model rotates (e.g. Sora 3) or a new video model is added, the allowed values update automatically and you'll see them in the backend's 400 if you submit unsupported inputs.
 
 **EXAMPLE:**
 User: "create a video of a cat playing"
@@ -224,20 +239,20 @@ You output:
   "parameters": {
     "prompt": "A fluffy orange tabby cat with white paws crouches low on a sunlit hardwood floor, eyes locked on a red laser dot. The cat pounces forward, slides slightly on the polished wood, then quickly pivots to chase the dot as it darts away. Warm afternoon sunlight streams through sheer curtains, casting soft golden highlights on the cat's fur. Cozy living room with a beige sofa in the background.",
     "outputPath": "videos/cat-playing.mp4",
-    "width": 1080,
-    "height": 1080,
-    "duration": 5
+    "width": 1280,
+    "height": 720,
+    "duration": 4
   }
 }
 \`\`\`
 
 **Prompt Guidelines (IMPORTANT):**
-Sora simulates a physical world, so write prompts as narratives, not camera commands. Use the CAST method: describe the **Character** (appearance, clothing, posture), **Action** (break into beats like "takes three steps, pauses, looks back"), **Setting** (time of day, weather, specific objects), and **Tone/Atmosphere** (lighting quality, color palette, mood). Be specific and sensory—replace "beautiful street" with "rain-slick Tokyo asphalt reflecting neon signs." Keep prompts under 120 words, focus on ONE action per clip, and use simple camera cues only if needed ("wide shot," "close-up"). Anchor lighting explicitly ("warm golden hour sunlight with soft shadows") and name colors (teal, amber, magenta) for palette consistency. For character consistency across clips, repeat the same distinctive details (clothing colors, accessories, features) in each prompt. Avoid real people, copyrighted characters, and sensitive content.
+Sora simulates a physical world — write prompts as narratives, not camera commands. Use the CAST method: describe the **Character** (appearance, clothing, posture), **Action** (broken into beats: "takes three steps, pauses, looks back"), **Setting** (time of day, weather, specific objects), and **Tone/Atmosphere** (lighting quality, color palette, mood). Be specific and sensory — replace "beautiful street" with "rain-slick Tokyo asphalt reflecting neon signs." Keep prompts under 120 words, focus on ONE action per clip, and use simple camera cues only if needed ("wide shot," "close-up"). Anchor lighting explicitly ("warm golden hour sunlight with soft shadows") and name colors (teal, amber, magenta) for palette consistency. For character consistency across clips, repeat the same distinctive details (clothing colors, accessories, features) in each prompt. Avoid real people, copyrighted characters, and sensitive content.
 
 **Notes:**
-- Videos take 3-10 minutes to generate
-- Max ${VIDEO_CONFIG.QUEUE_LIMIT} videos in queue, max 2 concurrent jobs
-- Videos expire after 24 hours`;
+- Videos take 1-3 minutes to generate (Sora 2 short clips).
+- Max ${VIDEO_CONFIG.QUEUE_LIMIT} videos in queue, max ${VIDEO_CONFIG.MAX_CONCURRENT} concurrent jobs.
+- Generated videos expire on the provider after 24 hours; if you need to keep them, set an \`outputPath\` so the local copy persists.`;
   }
 
   /**
@@ -471,7 +486,17 @@ Sora simulates a physical world, so write prompts as narratives, not camera comm
   }
 
   /**
-   * Validate parameters
+   * Sanity-check inputs before submitting to the backend. Per-model limits
+   * (which exact resolutions and durations a given video model accepts)
+   * are NOT enforced here — the catalog declares them and the backend
+   * route validates against the catalog row. This keeps the CLI
+   * provider-agnostic; if the inputs aren't compatible with the chosen
+   * model, the backend's 400 surfaces back through the queue's `error`
+   * field with a clear message naming the allowed values.
+   *
+   * Local checks below cover only "obviously wrong" inputs that no video
+   * provider would accept — empty prompts, non-positive dimensions, etc.
+   *
    * @private
    */
   _validateParameters(params) {
@@ -483,25 +508,34 @@ Sora simulates a physical world, so write prompts as narratives, not camera comm
       if (!vid.prompt || vid.prompt.trim().length === 0) {
         throw new Error('Video prompt is required');
       }
-
       if (vid.prompt.length > VIDEO_CONFIG.MAX_PROMPT_LENGTH) {
         throw new Error(`Prompt too long (max ${VIDEO_CONFIG.MAX_PROMPT_LENGTH} characters)`);
       }
 
-      // Validate resolution
-      const resolution = `${vid.width}x${vid.height}`;
-      if (!VIDEO_CONFIG.VALID_RESOLUTIONS.includes(resolution)) {
-        throw new Error(`Invalid resolution: ${resolution}. Valid resolutions: ${VIDEO_CONFIG.VALID_RESOLUTIONS.join(', ')}`);
+      // Width/height must be positive integers — backend + provider
+      // decide which exact pairs are valid for the chosen model.
+      if (vid.width != null && (!Number.isInteger(vid.width) || vid.width <= 0)) {
+        throw new Error(`Invalid width: ${vid.width}. Must be a positive integer.`);
+      }
+      if (vid.height != null && (!Number.isInteger(vid.height) || vid.height <= 0)) {
+        throw new Error(`Invalid height: ${vid.height}. Must be a positive integer.`);
       }
 
-      // Validate duration
-      if (vid.duration < VIDEO_CONFIG.MIN_DURATION || vid.duration > VIDEO_CONFIG.MAX_DURATION) {
-        throw new Error(`Invalid duration: ${vid.duration}. Must be between ${VIDEO_CONFIG.MIN_DURATION} and ${VIDEO_CONFIG.MAX_DURATION} seconds`);
+      // Duration: only catch absurd values here; the catalog declares
+      // the per-model allowed list (e.g. Sora 2: {4, 8, 12} seconds).
+      if (vid.duration != null) {
+        if (typeof vid.duration !== 'number' || vid.duration < VIDEO_CONFIG.ABSOLUTE_MIN_DURATION || vid.duration > VIDEO_CONFIG.ABSOLUTE_MAX_DURATION) {
+          throw new Error(`Invalid duration: ${vid.duration}. Must be a number between ${VIDEO_CONFIG.ABSOLUTE_MIN_DURATION} and ${VIDEO_CONFIG.ABSOLUTE_MAX_DURATION} seconds. The chosen model may support a narrower set — see /llm/models.`);
+        }
       }
 
-      // Validate variants
-      if (vid.variants < 1 || vid.variants > VIDEO_CONFIG.MAX_VARIANTS) {
-        throw new Error(`Invalid variants: ${vid.variants}. Must be between 1 and ${VIDEO_CONFIG.MAX_VARIANTS}`);
+      // Variants: same approach — sanity-only. Some models (e.g. Sora 2)
+      // only return a single video per job; the backend will 400 if the
+      // model doesn't support multiple variants.
+      if (vid.variants != null) {
+        if (!Number.isInteger(vid.variants) || vid.variants < 1 || vid.variants > VIDEO_CONFIG.ABSOLUTE_MAX_VARIANTS) {
+          throw new Error(`Invalid variants: ${vid.variants}. Must be an integer between 1 and ${VIDEO_CONFIG.ABSOLUTE_MAX_VARIANTS}. The chosen model may only support 1.`);
+        }
       }
 
       if (vid.outputPath) {

package/src/tools/webTool.js

@@ -3073,6 +3073,15 @@ If blocked (CAPTCHA, access denied), use stealthLevel: "maximum" (visible browse
     this.cleanupTimer = setInterval(() => {
       this.cleanupIdleTabs();
     }, this.CLEANUP_INTERVAL);
+    // Don't let this background-maintenance timer hold the event loop
+    // open. When all real work is done (CLI exits, test suite finishes),
+    // the process should be free to exit on its own. Tests that create
+    // a WebTool without explicit cleanup() previously left jest workers
+    // hanging until --forceExit. unref() is the industry-standard fix
+    // for periodic-maintenance timers.
+    if (typeof this.cleanupTimer.unref === 'function') {
+      this.cleanupTimer.unref();
+    }
   }
 
   /**

package/src/utilities/__tests__/apiKeyPlaceholders.test.js

@@ -0,0 +1,120 @@
+/**
+ * Unit tests for the API-key placeholder detection helpers (shared by
+ * apiKeyManager + the web UI).
+ *
+ * Locks the heuristic that prevents UI display strings ("lx_•••• …
+ * (server-managed)" and the legacy "platform-managed" sentinel) from
+ * leaking into persistence and overwriting real keys with garbage.
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  isPlaceholderApiKey,
+  sanitizeApiKeyValue,
+  sanitizeApiKeysObject,
+  LEGACY_BULLET_PLACEHOLDER,
+  LEGACY_PLATFORM_MANAGED_SENTINEL,
+} from '../apiKeyPlaceholders.js';
+
+describe('isPlaceholderApiKey', () => {
+  test('detects the canonical bullet placeholder', () => {
+    expect(isPlaceholderApiKey(LEGACY_BULLET_PLACEHOLDER)).toBe(true);
+    expect(isPlaceholderApiKey('lx_••••••••••••••••(server-managed)')).toBe(true);
+  });
+
+  test('detects any string containing bullets', () => {
+    expect(isPlaceholderApiKey('••••••••')).toBe(true);
+    expect(isPlaceholderApiKey('lx_•••')).toBe(true);
+  });
+
+  test('detects the platform-managed sentinel exactly', () => {
+    expect(isPlaceholderApiKey(LEGACY_PLATFORM_MANAGED_SENTINEL)).toBe(true);
+    expect(isPlaceholderApiKey('platform-managed')).toBe(true);
+  });
+
+  test('detects (server-managed) and [server-managed] tags anywhere in the string', () => {
+    expect(isPlaceholderApiKey('lx_abc(server-managed)')).toBe(true);
+    expect(isPlaceholderApiKey('foo[server-managed]bar')).toBe(true);
+    expect(isPlaceholderApiKey('(server-managed)')).toBe(true);
+  });
+
+  test('treats real-looking keys as not-placeholder', () => {
+    expect(isPlaceholderApiKey('lx_1234567890abcdef')).toBe(false);
+    expect(isPlaceholderApiKey('sk-proj-abcdefghijk')).toBe(false);
+    expect(isPlaceholderApiKey('FfX3H7zwazdmDG3wIslbiawTYLVxXyzGKa97IaXcH9nUjVprZ0HqJQQJ99BEACfhMk5XJ3w3AAAAACOG6efc')).toBe(false);
+  });
+
+  test('returns false for empty / null / undefined / non-string', () => {
+    expect(isPlaceholderApiKey('')).toBe(false);
+    expect(isPlaceholderApiKey(null)).toBe(false);
+    expect(isPlaceholderApiKey(undefined)).toBe(false);
+    expect(isPlaceholderApiKey(123)).toBe(false);
+    expect(isPlaceholderApiKey({})).toBe(false);
+    expect(isPlaceholderApiKey([])).toBe(false);
+  });
+
+  test('does NOT treat the substring "managed" alone as a placeholder', () => {
+    // Real keys should be allowed even if they happen to contain English
+    // words. Only the bracketed/parenthesised tag triggers detection.
+    expect(isPlaceholderApiKey('lx_managed_account_key_12345')).toBe(false);
+    expect(isPlaceholderApiKey('server')).toBe(false);
+  });
+});
+
+describe('sanitizeApiKeyValue', () => {
+  test('passes real keys through unchanged', () => {
+    expect(sanitizeApiKeyValue('lx_real_key_abc123')).toBe('lx_real_key_abc123');
+  });
+
+  test('strips placeholder values to empty string', () => {
+    expect(sanitizeApiKeyValue(LEGACY_BULLET_PLACEHOLDER)).toBe('');
+    expect(sanitizeApiKeyValue('platform-managed')).toBe('');
+    expect(sanitizeApiKeyValue('foo(server-managed)')).toBe('');
+  });
+
+  test('returns "" for non-string inputs (avoids leaking nulls into UI state)', () => {
+    expect(sanitizeApiKeyValue(null)).toBe('');
+    expect(sanitizeApiKeyValue(undefined)).toBe('');
+    expect(sanitizeApiKeyValue(0)).toBe('');
+    expect(sanitizeApiKeyValue({ value: 'real' })).toBe('');
+  });
+
+  test('preserves empty string', () => {
+    expect(sanitizeApiKeyValue('')).toBe('');
+  });
+});
+
+describe('sanitizeApiKeysObject', () => {
+  test('returns an empty object for null / undefined / non-object', () => {
+    expect(sanitizeApiKeysObject(null)).toEqual({});
+    expect(sanitizeApiKeysObject(undefined)).toEqual({});
+    expect(sanitizeApiKeysObject('not-an-object')).toEqual({});
+  });
+
+  test('strips placeholders, preserves real keys', () => {
+    const result = sanitizeApiKeysObject({
+      loxiaBackend: LEGACY_BULLET_PLACEHOLDER,
+      anthropic:    'sk-ant-real-key-1234567890',
+      openai:       'platform-managed',
+      azure:        'lx_real_azure_key',
+      deepseek:     'foo(server-managed)bar',
+    });
+    expect(result).toEqual({
+      loxiaBackend: '',
+      anthropic:    'sk-ant-real-key-1234567890',
+      openai:       '',
+      azure:        'lx_real_azure_key',
+      deepseek:     '',
+    });
+  });
+
+  test('does not mutate the input', () => {
+    const input = { loxiaBackend: LEGACY_BULLET_PLACEHOLDER };
+    sanitizeApiKeysObject(input);
+    expect(input.loxiaBackend).toBe(LEGACY_BULLET_PLACEHOLDER);
+  });
+
+  test('roundtrip: clean object passes through unchanged-shape', () => {
+    const clean = { loxiaBackend: 'lx_abc', anthropic: 'sk-ant-xyz' };
+    expect(sanitizeApiKeysObject(clean)).toEqual(clean);
+  });
+});