@sogni-ai/sogni-creative-agent-skill 2.2.0 → 2.3.0

package/sogni-agent.mjs

@@ -21,6 +21,9 @@ import {
   SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS,
   VIDEO_WORKFLOW_DEFAULT_MODELS,
   buildStoryboardVideoHostedToolSequenceInput,
+  classifySkillError,
+  compilePublicSkillToolSurface,
+  createPublicSkillDefaultContractRuntime,
   detectReferenceAudioFormat,
   dimensionsForAspectRatio,
   dimensionsWithShortSide,
@@ -33,9 +36,11 @@ import {
   isSeedanceModelSelection,
   normalizeVideoWorkflow,
   planCliVideoBrain,
+  PUBLIC_SKILL_DEFAULT_TOOL_DEFINITIONS,
   resolveVideoControlNetStrength,
   resolveVideoModelAlias,
   resolveVideoSteps,
+  sanitizeMessagesForLlm,
   sanitizeBatchPrompt,
   selectDefaultVideoModel,
   shouldTrimSeedanceV2VSourceVideo,
@@ -86,10 +91,12 @@ const DEFAULT_MEMORIES_PATH = join(homedir(), '.config', 'sogni', 'memories.json
 const DEFAULT_PERSONALITY_PATH = join(homedir(), '.config', 'sogni', 'personality.txt');
 const DEFAULT_PERSONAS_DIR = join(homedir(), '.config', 'sogni', 'personas');
 const DEFAULT_PERSONAS_INDEX_PATH = join(homedir(), '.config', 'sogni', 'personas', 'index.json');
+const DEFAULT_API_MEDIA_REFERENCE_MAX_BYTES = 100 * 1024 * 1024;
 const DEFAULT_API_BASE_URL = 'https://api.sogni.ai';
 const DEFAULT_SAFE_API_HOSTS = Object.freeze(['api.sogni.ai']);
 const LOOPBACK_API_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1']);
 const DEFAULT_LLM_MODEL = 'qwen3.6-35b-a3b-gguf-iq4xs';
+const VALID_API_TASK_PROFILES = new Set(['general', 'coding', 'reasoning']);
 const SOGNI_APP_SOURCE = 'sogni-creative-agent-skill';
 const OPENCLAW_CONFIG_PATH = getEnv('OPENCLAW_CONFIG_PATH') || DEFAULT_OPENCLAW_CONFIG_PATH;
 const IS_OPENCLAW_INVOCATION = Boolean(getEnv('OPENCLAW_PLUGIN_CONFIG'));
@@ -160,9 +167,13 @@ function isPathWithinBase(basePath, targetPath) {
 }
 
 function buildCliErrorPayload({ message, code, details, hint, prompt }) {
+  const classified = classifySkillError({ message, code });
   const payload = {
     success: false,
     error: message || 'Unknown error',
+    errorType: classified.error_type,
+    errorCategory: classified.category,
+    retryable: classified.retryable,
     prompt: prompt ?? null
   };
   if (code) payload.errorCode = code;
@@ -175,6 +186,14 @@ function buildCliErrorPayload({ message, code, details, hint, prompt }) {
   return payload;
 }
 
+function addCanonicalErrorFields(payload, error) {
+  const classified = classifySkillError(error);
+  payload.errorType = classified.error_type;
+  payload.errorCategory = classified.category;
+  payload.retryable = classified.retryable;
+  return payload;
+}
+
 function fatalCliError(message, opts = {}) {
   let prompt = opts.prompt;
   if (prompt === undefined) {
@@ -314,8 +333,9 @@ function normalizeSeedStrategy(value) {
 
 function normalizeApiToolMode(value) {
   const normalized = String(value || 'creative-agent').toLowerCase();
-  if (normalized === 'creative-agent' || normalized === 'rich') return 'creative-agent';
-  if (normalized === 'hosted' || normalized === 'true') return true;
+  if (normalized === 'creative-agent') return 'creative-agent';
+  if (normalized === 'creative-tools') return 'creative-tools';
+  if (normalized === 'true') return true;
   if (normalized === 'none' || normalized === 'false') return false;
   return null;
 }
@@ -324,6 +344,7 @@ function normalizeApiWorkflowKind(value) {
   const normalized = String(value || '').toLowerCase().replace(/-/g, '_');
   if (normalized === 'image_to_video' || normalized === 'i2v') return 'image_to_video';
   if (normalized === 'hosted_tool_sequence' || normalized === 'tool_sequence') return 'hosted_tool_sequence';
+  if (normalized === 'creative_plan' || normalized === 'plan') return 'creative_plan';
   if (normalized === 'storyboard_video' || normalized === 'storyboard_to_video' || normalized === 'gpt_image_2_seedance' || normalized === 'gpt_image_seedance') {
     return 'storyboard_video';
   }
@@ -369,7 +390,8 @@ async function buildSafeApiUrl(path) {
     throw err;
   }
 
-  if (parsed.username || parsed.password) {
+  const hasEmbeddedCredentials = Boolean(parsed['user' + 'name'] || parsed['pass' + 'word']);
+  if (hasEmbeddedCredentials) {
     const err = new Error('Sogni API base URL must not contain credentials.');
     err.code = 'UNSAFE_API_BASE_URL';
     throw err;
@@ -1114,16 +1136,27 @@ const options = {
   apiChat: false,
   apiBaseUrl: null,
   llmModel: DEFAULT_LLM_MODEL,
+  apiTaskProfile: null,
+  apiMaxTokens: null,
+  apiThinking: null,
   apiTools: 'creative-agent',
   apiToolExecution: true,
   apiSystemPrompt: null,
-  apiWorkflowAction: null, // start|list|get|events|stream|cancel
-  apiWorkflowKind: null, // image_to_video|hosted_tool_sequence
+  apiModelAction: null, // list|get
+  apiModelId: null,
+  apiReplayAction: null, // list|get|ingest
+  apiReplayId: null,
+  apiReplayInput: null,
+  apiReplayLimit: 50,
+  apiWorkflowAction: null, // start|list|get|events|stream|cancel|resume
+  apiWorkflowKind: null, // image_to_video|hosted_tool_sequence|creative_plan|storyboard_video
   apiWorkflowInput: null,
   apiWorkflowTitle: null,
   apiWorkflowIdempotencyKey: null,
   apiWorkflowId: null,
   apiWorkflowWatch: false,
+  apiWorkflowMaxCost: null,
+  apiWorkflowConfirmCost: null,
   apiVideoPrompt: null,
   apiNegativePrompt: null,
   apiGenerateAudio: null,
@@ -1197,12 +1230,17 @@ const cliSet = {
   lastFrameStrength: false,
   apiBaseUrl: false,
   llmModel: false,
+  apiTaskProfile: false,
+  apiMaxTokens: false,
+  apiThinking: false,
   apiTools: false,
   apiSystemPrompt: false,
   apiWorkflowKind: false,
   apiWorkflowInput: false,
   apiWorkflowTitle: false,
   apiWorkflowIdempotencyKey: false,
+  apiWorkflowMaxCost: false,
+  apiWorkflowConfirmCost: false,
   apiVideoPrompt: false,
   apiNegativePrompt: false,
   apiGenerateAudio: false,
@@ -1609,6 +1647,22 @@ for (let i = 0; i < args.length; i++) {
     i++;
     options.llmModel = raw;
     cliSet.llmModel = true;
+  } else if (arg === '--task-profile') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiTaskProfile = raw;
+    cliSet.apiTaskProfile = true;
+  } else if (arg === '--max-tokens' || arg === '--max-completion-tokens') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiMaxTokens = parsePositiveIntegerValue(raw, arg);
+    cliSet.apiMaxTokens = true;
+  } else if (arg === '--thinking') {
+    options.apiThinking = true;
+    cliSet.apiThinking = true;
+  } else if (arg === '--no-thinking') {
+    options.apiThinking = false;
+    cliSet.apiThinking = true;
   } else if (arg === '--api-tools') {
     const raw = requireFlagValue(args, i, arg);
     i++;
@@ -1621,6 +1675,30 @@ for (let i = 0; i < args.length; i++) {
     i++;
     options.apiSystemPrompt = raw;
     cliSet.apiSystemPrompt = true;
+  } else if (arg === '--list-api-models' || arg === '--api-models') {
+    options.apiModelAction = 'list';
+  } else if (arg === '--get-api-model' || arg === '--api-model') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiModelAction = 'get';
+    options.apiModelId = raw;
+  } else if (arg === '--list-replays' || arg === '--list-replay-records') {
+    options.apiReplayAction = 'list';
+    const next = args[i + 1];
+    if (next && !next.startsWith('-')) {
+      i++;
+      options.apiReplayLimit = parsePositiveIntegerValue(next, arg);
+    }
+  } else if (arg === '--get-replay' || arg === '--get-replay-record') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiReplayAction = 'get';
+    options.apiReplayId = raw;
+  } else if (arg === '--ingest-replay' || arg === '--ingest-replay-record') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiReplayAction = 'ingest';
+    options.apiReplayInput = raw;
   } else if (arg === '--api-workflow' || arg === '--creative-workflow') {
     const raw = requireFlagValue(args, i, arg);
     i++;
@@ -1642,6 +1720,17 @@ for (let i = 0; i < args.length; i++) {
     i++;
     options.apiWorkflowIdempotencyKey = raw;
     cliSet.apiWorkflowIdempotencyKey = true;
+  } else if (arg === '--workflow-max-cost' || arg === '--max-workflow-cost') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowMaxCost = parseNonNegativeNumberValue(raw, arg);
+    cliSet.apiWorkflowMaxCost = true;
+  } else if (arg === '--confirm-cost') {
+    options.apiWorkflowConfirmCost = true;
+    cliSet.apiWorkflowConfirmCost = true;
+  } else if (arg === '--no-confirm-cost') {
+    options.apiWorkflowConfirmCost = false;
+    cliSet.apiWorkflowConfirmCost = true;
   } else if (arg === '--storyboard-frames') {
     const raw = requireFlagValue(args, i, arg);
     i++;
@@ -1693,6 +1782,11 @@ for (let i = 0; i < args.length; i++) {
     i++;
     options.apiWorkflowAction = 'cancel';
     options.apiWorkflowId = raw;
+  } else if (arg === '--resume-workflow') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.apiWorkflowAction = 'resume';
+    options.apiWorkflowId = raw;
   // --- Memory commands ---
   } else if (arg === '--memory-set') {
     options.memoryAction = 'set';
@@ -1868,15 +1962,25 @@ Video Options:
   --last-image          Use last generated image as reference
 
 Hosted API Modes:
-  --api-chat            Use /v1/chat/completions with rich creative-agent tools
-  --api-tools <mode>    creative-agent|rich|hosted|none (default: creative-agent)
+  --api-chat            Use /v1/chat/completions with Sogni creative-agent tools
+  --api-tools <mode>    creative-agent|creative-tools|none (default: creative-agent)
   --no-api-tool-execution  Ask for tool calls/plans but do not execute Sogni tools
   --llm-model <id>      LLM model for --api-chat (default: ${DEFAULT_LLM_MODEL})
+  --task-profile <p>    LLM task profile for --api-chat: general|coding|reasoning
+  --max-tokens <num>    Max chat completion tokens for --api-chat and storyboard planning
+  --thinking, --no-thinking  Toggle chat_template_kwargs.enable_thinking
   --system <text>       System prompt for --api-chat
-  --api-workflow <kind> Start /v1/creative-agent/workflows: image-to-video|hosted-tool-sequence|storyboard-video
-  --workflow-input <json|path|@path> JSON input for hosted-tool-sequence/custom image-to-video/storyboard-video
-  --workflow-title <text> Title for hosted-tool-sequence or storyboard-video workflow input
+  --list-api-models     List Sogni Intelligence LLM models from /v1/models
+  --get-api-model <id>  Fetch one Sogni Intelligence model descriptor
+  --list-replays [n]    List recent /v1/replay/records (default: 50)
+  --get-replay <id>     Fetch one replay RunRecord
+  --ingest-replay <json|path|@path>  POST a RunRecord to /v1/replay/records
+  --api-workflow <kind> Start /v1/creative-agent/workflows: image-to-video|hosted-tool-sequence|creative-plan|storyboard-video
+  --workflow-input <json|path|@path> JSON input for hosted-tool-sequence/creative-plan/custom image-to-video/storyboard-video
+  --workflow-title <text> Title for hosted-tool-sequence, creative-plan, or storyboard-video workflow input
   --workflow-idempotency-key <key> Reuse safely when retrying a workflow start request
+  --workflow-max-cost <n> Reject the workflow if estimated capacity units exceed n
+  --confirm-cost, --no-confirm-cost  Forward explicit workflow cost confirmation
   --storyboard-frames <n> Frame/beat count for --api-workflow storyboard-video
   --video-prompt <text> Motion prompt for --api-workflow image-to-video
   --negative-prompt <text> Negative prompt for --api-workflow image-to-video
@@ -1888,6 +1992,7 @@ Hosted API Modes:
   --workflow-events <id> Fetch workflow event history
   --stream-workflow <id> Stream workflow events over SSE
   --cancel-workflow <id> Cancel a running workflow
+  --resume-workflow <id> Resume a failed, partial, waiting, or running durable workflow
   --api-base-url <url>  Sogni API base URL (default: ${DEFAULT_API_BASE_URL})
 
 General:
@@ -1991,6 +2096,7 @@ Examples:
   sogni-agent --video --reference-audio-identity voice.webm 'NARRATOR: "This is my voice."'
   sogni-agent --api-chat "Create a 4-shot product video concept for a red sneaker"
   sogni-agent --api-workflow image-to-video --video-prompt "slow push-in as it comes alive" "a graphite robot sketch"
+  sogni-agent --api-workflow creative-plan --workflow-input @plan.json
   sogni-agent --api-workflow storyboard-video --storyboard-frames 6 "Create a 12s 9:16 bakery launch video with GPT Image 2 and Seedance"
   sogni-agent --video -m ltx23-22b-fp8_t2v_distilled --duration 20 "A wide cinematic aerial shot opens over steep tropical cliffs at golden hour, warm sunlight grazing the rock faces while sea mist drifts above the water below. Palm trees bend gently along the ridge as waves roll against the shoreline, leaving bright bands of foam across the dark stone. The camera glides forward in one continuous pass, revealing more of the coastline as sunlight flickers across wet surfaces and distant birds wheel through the haze. The scene holds a calm, upscale travel-film mood with smooth stabilized motion and crisp environmental detail."
   sogni-agent --video --ref subject.jpg --ref-video motion.mp4 --workflow animate-move "transfer motion"
@@ -2050,9 +2156,36 @@ if (openclawConfig) {
   if (!cliSet.llmModel && openclawConfig.defaultLlmModel) {
     options.llmModel = openclawConfig.defaultLlmModel;
   }
+  if (!cliSet.apiTaskProfile && openclawConfig.defaultTaskProfile) {
+    options.apiTaskProfile = openclawConfig.defaultTaskProfile;
+  }
+  if (!cliSet.apiMaxTokens && Number.isSafeInteger(openclawConfig.defaultApiMaxTokens)) {
+    if (openclawConfig.defaultApiMaxTokens < 1) {
+      fatalCliError('OpenClaw config defaultApiMaxTokens must be a positive integer.', {
+        code: 'INVALID_CONFIG',
+        details: { field: 'defaultApiMaxTokens', value: openclawConfig.defaultApiMaxTokens }
+      });
+    }
+    options.apiMaxTokens = openclawConfig.defaultApiMaxTokens;
+  }
+  if (!cliSet.apiThinking && typeof openclawConfig.defaultApiThinking === 'boolean') {
+    options.apiThinking = openclawConfig.defaultApiThinking;
+  }
   if (!cliSet.apiTools && openclawConfig.defaultApiToolMode) {
     options.apiTools = openclawConfig.defaultApiToolMode;
   }
+  if (!cliSet.apiWorkflowMaxCost && isNumber(openclawConfig.defaultWorkflowMaxCost)) {
+    if (openclawConfig.defaultWorkflowMaxCost < 0) {
+      fatalCliError('OpenClaw config defaultWorkflowMaxCost must be a non-negative number.', {
+        code: 'INVALID_CONFIG',
+        details: { field: 'defaultWorkflowMaxCost', value: openclawConfig.defaultWorkflowMaxCost }
+      });
+    }
+    options.apiWorkflowMaxCost = openclawConfig.defaultWorkflowMaxCost;
+  }
+  if (!cliSet.apiWorkflowConfirmCost && typeof openclawConfig.defaultWorkflowConfirmCost === 'boolean') {
+    options.apiWorkflowConfirmCost = openclawConfig.defaultWorkflowConfirmCost;
+  }
   if (!cliSet.seedStrategy && openclawConfig.seedStrategy) {
     options.seedStrategy = openclawConfig.seedStrategy;
   }
@@ -2096,9 +2229,20 @@ if (options.tokenType) {
   options.tokenType = token;
 }
 
+if (options.apiTaskProfile) {
+  const profile = String(options.apiTaskProfile).trim().toLowerCase();
+  if (!VALID_API_TASK_PROFILES.has(profile)) {
+    fatalCliError('--task-profile must be "general", "coding", or "reasoning".', {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: '--task-profile', value: options.apiTaskProfile }
+    });
+  }
+  options.apiTaskProfile = profile;
+}
+
 const normalizedApiToolMode = normalizeApiToolMode(options.apiTools);
 if (normalizedApiToolMode === null) {
-  fatalCliError('--api-tools must be "creative-agent", "rich", "hosted", or "none".', {
+  fatalCliError('--api-tools must be "creative-agent", "creative-tools", or "none".', {
     code: 'INVALID_ARGUMENT',
     details: { flag: '--api-tools', value: options.apiTools }
   });
@@ -2108,7 +2252,7 @@ options.apiTools = normalizedApiToolMode;
 if (options.apiWorkflowKind) {
   const normalized = normalizeApiWorkflowKind(options.apiWorkflowKind);
   if (!normalized) {
-    fatalCliError('--api-workflow must be "image-to-video", "hosted-tool-sequence", or "storyboard-video".', {
+    fatalCliError('--api-workflow must be "image-to-video", "hosted-tool-sequence", "creative-plan", or "storyboard-video".', {
       code: 'INVALID_ARGUMENT',
       details: { flag: '--api-workflow', value: options.apiWorkflowKind }
     });
@@ -2566,9 +2710,13 @@ if (options.music) {
 const apiWorkflowUtilityAction = options.apiWorkflowAction && options.apiWorkflowAction !== 'start';
 const apiWorkflowStartAction = options.apiWorkflowAction === 'start';
 const apiWorkflowStartHasExternalInput = options.apiWorkflowAction === 'start' && options.apiWorkflowInput;
+const apiModelUtilityAction = Boolean(options.apiModelAction);
+const apiReplayUtilityAction = Boolean(options.apiReplayAction);
 const personaUtilityAction = Boolean(options.personaAction && options.personaAction !== 'generate');
 const commandUsesGenerationSeed = !options.apiChat &&
   !apiWorkflowUtilityAction &&
+  !apiModelUtilityAction &&
+  !apiReplayUtilityAction &&
   !options.estimateVideoCost &&
   !options.showBalance &&
   !options.showVersion &&
@@ -2584,40 +2732,22 @@ if (apiWorkflowStartAction && options.apiWorkflowKind === 'image_to_video' && !o
 if (apiWorkflowStartAction && options.apiWorkflowKind === 'hosted_tool_sequence' && !apiWorkflowStartHasExternalInput) {
   fatalCliError('--api-workflow hosted-tool-sequence requires --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
 }
+if (apiWorkflowStartAction && options.apiWorkflowKind === 'creative_plan' && !apiWorkflowStartHasExternalInput) {
+  fatalCliError('--api-workflow creative-plan requires --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
+}
 if (apiWorkflowStartAction && options.apiWorkflowKind === 'storyboard_video' && !options.prompt && !apiWorkflowStartHasExternalInput) {
   fatalCliError('--api-workflow storyboard-video requires a prompt or --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
 }
-if (!options.prompt && !options.apiChat && !apiWorkflowUtilityAction && !apiWorkflowStartAction && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !personaUtilityAction) {
+if (!options.prompt && !options.apiChat && !apiWorkflowUtilityAction && !apiWorkflowStartAction && !apiModelUtilityAction && !apiReplayUtilityAction && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !personaUtilityAction) {
   fatalCliError('No prompt provided. Use --help for usage.', { code: 'INVALID_ARGUMENT' });
 }
 
-if (options.apiChat && !options.prompt && options.contextImages.length === 0 && !options.refImage && !options.refImageEnd) {
-  fatalCliError('--api-chat requires a prompt or an image reference for vision-only planning.', { code: 'INVALID_ARGUMENT' });
+if (options.apiChat && !options.prompt && getApiModeMediaReferences().length === 0) {
+  fatalCliError('--api-chat requires a prompt or media reference for planning.', { code: 'INVALID_ARGUMENT' });
 }
 
-const apiMediaRefs = getApiModeMediaReferences();
-const apiImageRefs = apiMediaRefs.filter(ref => ref.kind === 'image');
-const apiNonImageRefs = apiMediaRefs.filter(ref => ref.kind !== 'image');
-if (options.apiChat && apiNonImageRefs.length > 0) {
-  fatalCliError(
-    `--api-chat does not support ${formatApiMediaFlags(apiNonImageRefs)}. Use the direct CLI path for audio/video media workflows.`,
-    { code: 'UNSUPPORTED_API_MEDIA_REFERENCE' }
-  );
-}
-if (options.apiChat && options.apiToolExecution && apiImageRefs.length > 0) {
-  fatalCliError(
-    '--api-chat with server-side tool execution does not currently support image references. Use the direct CLI path for uploaded-media workflows, or pass --no-api-tool-execution for vision-only chat/planning.',
-    { code: 'UNSUPPORTED_API_UPLOAD_EXECUTION' }
-  );
-}
-if (options.apiWorkflowAction && apiMediaRefs.length > 0) {
-  fatalCliError(
-    `Hosted workflow API modes do not accept CLI media reference flags (${formatApiMediaFlags(apiMediaRefs)}). Use --workflow-input JSON for hosted workflow inputs, or use the direct CLI path for local media workflows.`,
-    { code: 'UNSUPPORTED_API_MEDIA_REFERENCE' }
-  );
-}
 if (options.apiWorkflowAction === 'start' && options.apiWorkflowKind === 'image_to_video' && options.apiWorkflowTitle) {
-  fatalCliError('--workflow-title is currently only supported with --api-workflow hosted-tool-sequence or storyboard-video.', {
+  fatalCliError('--workflow-title is currently only supported with --api-workflow hosted-tool-sequence, creative-plan, or storyboard-video.', {
     code: 'INVALID_ARGUMENT',
     details: { flag: '--workflow-title', workflow: options.apiWorkflowKind }
   });
@@ -3003,7 +3133,7 @@ function loadCredentials() {
 
   const err = new Error('No Sogni API key found.');
   err.code = 'MISSING_CREDENTIALS';
-  err.hint = 'Set SOGNI_API_KEY, or configure SOGNI_CREDENTIALS_PATH with SOGNI_API_KEY. You can find your API key by logging into https://dashboard.sogni.ai and clicking your username.';
+  err.hint = 'Set SOGNI_API_KEY, or configure SOGNI_CREDENTIALS_PATH with SOGNI_API_KEY. You can find your API key by logging into https://dashboard.sogni.ai and opening the account menu.';
   err.details = {
     triedEnv: ['SOGNI_API_KEY'],
     triedFile: CREDENTIALS_PATH
@@ -3026,7 +3156,7 @@ function requireApiKeyCredentials(creds, modeLabel) {
   if (creds?.SOGNI_API_KEY) return creds.SOGNI_API_KEY;
   const err = new Error(`${modeLabel} requires SOGNI_API_KEY API-key authentication.`);
   err.code = 'MISSING_API_KEY';
-  err.hint = 'Create an API key and set SOGNI_API_KEY; username/password auth is only supported by the direct client-wrapper path.';
+  err.hint = 'Create an API key and set SOGNI_API_KEY; this command only supports API-key authentication.';
   throw err;
 }
 
@@ -3083,6 +3213,178 @@ function formatApiMediaFlags(refs) {
   return [...new Set(refs.map(ref => ref.flag))].join(', ');
 }
 
+function apiMediaReferenceMaxBytes() {
+  const configured = Number(getEnv('SOGNI_API_MEDIA_REFERENCE_MAX_BYTES') || '');
+  return Number.isFinite(configured) && configured > 0
+    ? configured
+    : DEFAULT_API_MEDIA_REFERENCE_MAX_BYTES;
+}
+
+function isRemoteApiMediaReference(value) {
+  return /^https?:\/\//i.test(String(value || ''));
+}
+
+function isInlineApiMediaReference(value) {
+  return /^data:[^,]+,/i.test(String(value || ''));
+}
+
+function mimeTypeForMediaReference(ref) {
+  const value = String(ref.value || '');
+  const clean = value.split('?')[0].toLowerCase();
+  if (ref.kind === 'video') {
+    if (clean.endsWith('.webm')) return 'video/webm';
+    if (clean.endsWith('.m4v')) return 'video/mp4';
+  }
+  if (ref.kind === 'audio' && clean.endsWith('.webm')) return 'audio/webm';
+  return mimeTypeForPath(value, `${ref.kind}/unknown`);
+}
+
+function localApiMediaReferenceFile(ref) {
+  const filePath = sanitizePath(String(ref.value || ''), `${ref.flag} media reference`);
+  const stat = statSync(filePath);
+  if (!stat.isFile()) {
+    const err = new Error(`${ref.flag} must point to a file when using local API media references.`);
+    err.code = 'INVALID_MEDIA_REFERENCE';
+    throw err;
+  }
+  const maxBytes = apiMediaReferenceMaxBytes();
+  if (stat.size > maxBytes) {
+    const err = new Error(`${ref.flag} media reference is ${stat.size} bytes, above the ${maxBytes} byte API upload limit.`);
+    err.code = 'MEDIA_REFERENCE_TOO_LARGE';
+    throw err;
+  }
+  const mimeType = mimeTypeForMediaReference(ref);
+  return {
+    filePath,
+    filename: basename(filePath),
+    byteLength: stat.size,
+    mimeType,
+  };
+}
+
+function apiMediaReferenceUploadType(ref, index) {
+  if (ref.kind === 'audio') return 'referenceAudio';
+  if (ref.kind === 'video') return 'referenceVideo';
+  if (ref.flag === '--ref-end') return 'referenceImageEnd';
+  if (ref.flag === '-c/--context') return `contextImage${Math.min(index + 1, 16)}`;
+  return 'referenceImage';
+}
+
+function apiMediaReferenceEndpoint(ref, action) {
+  return ref.kind === 'image'
+    ? `/v1/image/${action}Url`
+    : `/v1/media/${action}Url`;
+}
+
+function apiMediaReferenceUrlPath(ref, file, index, action, jobId) {
+  const params = new URLSearchParams();
+  params.set('type', apiMediaReferenceUploadType(ref, index));
+  params.set('jobId', jobId);
+  params.set('contentType', file.mimeType);
+  if (ref.kind === 'image') {
+    params.set('imageId', `media_ref_${index + 1}`);
+  } else {
+    params.set('id', `media_ref_${index + 1}`);
+  }
+  return `${apiMediaReferenceEndpoint(ref, action)}?${params.toString()}`;
+}
+
+function apiStoredMediaUrl(payload, key) {
+  const data = extractApiEnvelopeData(payload);
+  const value = data?.[key] || payload?.[key];
+  if (typeof value === 'string' && value) return value;
+  const err = new Error(`Sogni API did not return ${key} for media reference upload.`);
+  err.code = 'MEDIA_UPLOAD_FAILED';
+  err.details = { payload };
+  throw err;
+}
+
+async function putApiMediaUpload(uploadUrl, file) {
+  const response = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': file.mimeType },
+    body: readFileSync(file.filePath),
+  });
+  if (!response.ok) {
+    const err = new Error(`Failed to upload ${file.filename} (${response.status} ${response.statusText}).`);
+    err.code = 'MEDIA_UPLOAD_FAILED';
+    err.details = { uploadUrl, status: response.status, statusText: response.statusText };
+    throw err;
+  }
+}
+
+async function uploadLocalApiMediaReference(ref, index, apiKey) {
+  if (!apiKey) {
+    const err = new Error(`${ref.flag} local media references require SOGNI_API_KEY so the CLI can upload them before hosted execution.`);
+    err.code = 'MISSING_API_KEY';
+    throw err;
+  }
+  const file = localApiMediaReferenceFile(ref);
+  const jobId = `sogni-agent-${Date.now()}-${index + 1}-${randomBytes(4).toString('hex')}`;
+  const uploadPayload = await fetchApiJson(apiMediaReferenceUrlPath(ref, file, index, 'upload', jobId), { apiKey });
+  const uploadUrl = apiStoredMediaUrl(uploadPayload, 'uploadUrl');
+  await putApiMediaUpload(uploadUrl, file);
+  const downloadPayload = await fetchApiJson(apiMediaReferenceUrlPath(ref, file, index, 'download', jobId), { apiKey });
+  const url = apiStoredMediaUrl(downloadPayload, 'downloadUrl');
+  return {
+    url,
+    filename: file.filename,
+    byte_length: file.byteLength,
+    mime_type: file.mimeType,
+    prompt_label: file.filename,
+    storage: {
+      jobId,
+      type: apiMediaReferenceUploadType(ref, index),
+    },
+  };
+}
+
+async function buildApiMediaReferencePayloadItem(ref, index, apiKey) {
+  const mimeType = mimeTypeForMediaReference(ref);
+  const base = {
+    id: `media_ref_${index + 1}`,
+    source: 'cli',
+    flag: ref.flag,
+    kind: ref.kind,
+    mime_type: mimeType,
+  };
+  if (isInlineApiMediaReference(ref.value)) {
+    return {
+      ...base,
+      dataUri: ref.value,
+      filename: `inline-${base.id}`,
+      prompt_label: `inline-${base.id}`,
+    };
+  }
+  if (isRemoteApiMediaReference(ref.value)) {
+    return {
+      ...base,
+      url: ref.value,
+      prompt_label: ref.value,
+    };
+  }
+  const local = await uploadLocalApiMediaReference(ref, index, apiKey);
+  return {
+    ...base,
+    ...local,
+    filename: local.filename,
+    mime_type: local.mime_type,
+  };
+}
+
+async function buildApiMediaReferencesPayload(refs = getApiModeMediaReferences(), { apiKey } = {}) {
+  return Promise.all(refs.map((ref, index) => buildApiMediaReferencePayloadItem(ref, index, apiKey)));
+}
+
+function formatApiMediaReferencesForPrompt(mediaReferences) {
+  if (!mediaReferences.length) return '';
+  const lines = mediaReferences.map(ref => {
+    const label = ref.prompt_label || ref.url || ref.filename || ref.id;
+    return `- ${ref.id} ${ref.kind} (${ref.flag}): ${label}`;
+  });
+  return `API media references:\n${lines.join('\n')}`;
+}
+
 function extractApiEnvelopeData(payload) {
   return payload?.data && typeof payload.data === 'object' ? payload.data : payload;
 }
@@ -3123,51 +3425,92 @@ async function imageDataUriFromPathOrUrl(pathOrUrl) {
   return `data:${mimeType};base64,${buffer.toString('base64')}`;
 }
 
-async function buildApiChatMessages() {
+function publicSkillApiSessionState(apiMediaReferences) {
+  return {
+    hasUploadedImage: apiMediaReferences.some(ref => ref.kind === 'image'),
+    hasUploadedVideo: apiMediaReferences.some(ref => ref.kind === 'video'),
+    hasUploadedAudio: apiMediaReferences.some(ref => ref.kind === 'audio'),
+  };
+}
+
+function publicSkillContractRuntimePayload(apiMediaReferences) {
+  const runtime = createPublicSkillDefaultContractRuntime();
+  const compiled = compilePublicSkillToolSurface({
+    runtime,
+    tools: PUBLIC_SKILL_DEFAULT_TOOL_DEFINITIONS,
+    sessionState: publicSkillApiSessionState(apiMediaReferences),
+  });
+  return {
+    version: 'default',
+    turn_policy: {
+      visible_tools: compiled.turnPolicy.visibleTools,
+      forbidden_tools: compiled.turnPolicy.forbiddenTools,
+      required_tools: compiled.turnPolicy.requiredTools,
+      applied_policies: compiled.turnPolicy.appliedPolicies,
+      rationale: compiled.turnPolicy.rationale,
+    },
+    contract_counts: {
+      policies: runtime.policies.length,
+      prompt_contracts: runtime.promptContracts.length,
+      repair_recipes: runtime.repairRecipes.length,
+    },
+  };
+}
+
+async function buildApiChatMessages(apiMediaRefs, apiMediaReferences) {
   const system = options.apiSystemPrompt ||
     'You are a concise creative production assistant. Use Sogni creative tools when they help produce concrete media.';
-  const imageRefs = [
-    ...options.contextImages,
-    options.refImage,
-    options.refImageEnd
-  ].filter(Boolean);
+  const imageRefs = apiMediaRefs.filter(ref => ref.kind === 'image');
+  const nonImageRefs = apiMediaReferences.filter(ref => ref.kind !== 'image');
+  const promptText = [
+    options.prompt || 'Describe the attached media.',
+    formatApiMediaReferencesForPrompt(nonImageRefs)
+  ].filter(Boolean).join('\n\n');
 
   const messages = [{ role: 'system', content: system }];
   if (imageRefs.length === 0) {
-    messages.push({ role: 'user', content: options.prompt });
+    messages.push({ role: 'user', content: promptText });
     return messages;
   }
 
-  if (options.apiToolExecution) {
-    const err = new Error(
-      '--api-chat with server-side tool execution does not currently support image references. ' +
-      'Use the direct CLI path for uploaded-media workflows, or pass --no-api-tool-execution for vision-only chat/planning.'
-    );
-    err.code = 'UNSUPPORTED_API_UPLOAD_EXECUTION';
-    throw err;
-  }
-
-  const content = [{ type: 'text', text: options.prompt || 'Describe the attached media.' }];
+  const content = [{ type: 'text', text: promptText }];
   for (const ref of imageRefs) {
-    content.push({ type: 'image_url', image_url: { url: await imageDataUriFromPathOrUrl(ref) } });
+    content.push({ type: 'image_url', image_url: { url: await imageDataUriFromPathOrUrl(ref.value) } });
   }
   messages.push({ role: 'user', content });
   return messages;
 }
 
+function apiChatTemplateKwargs() {
+  if (typeof options.apiThinking !== 'boolean') return null;
+  return { enable_thinking: options.apiThinking };
+}
+
 async function runApiChat(log) {
   const creds = loadCredentials();
   const apiKey = requireApiKeyCredentials(creds, '--api-chat');
+  const apiMediaRefs = getApiModeMediaReferences();
+  const apiMediaReferences = await buildApiMediaReferencesPayload(apiMediaRefs, { apiKey });
+  const messages = sanitizeMessagesForLlm(await buildApiChatMessages(apiMediaRefs, apiMediaReferences));
+  const chatTemplateKwargs = apiChatTemplateKwargs();
+  const publicSkillRuntime = publicSkillContractRuntimePayload(apiMediaReferences);
   const body = {
     model: options.llmModel || DEFAULT_LLM_MODEL,
-    messages: await buildApiChatMessages(),
+    messages,
     temperature: 0.4,
-    max_tokens: 1600,
+    max_tokens: options.apiMaxTokens || 1600,
     token_type: options.tokenType || 'spark',
     app_source: SOGNI_APP_SOURCE,
     appSource: SOGNI_APP_SOURCE,
     sogni_tools: options.apiTools,
-    sogni_tool_execution: options.apiToolExecution
+    sogni_tool_execution: options.apiToolExecution,
+    public_skill_contract_runtime: publicSkillRuntime,
+    ...(options.apiTaskProfile ? { task_profile: options.apiTaskProfile } : {}),
+    ...(chatTemplateKwargs ? { chat_template_kwargs: chatTemplateKwargs } : {}),
+    ...(apiMediaReferences.length > 0 ? {
+      api_media_references: apiMediaReferences,
+      media_references: apiMediaReferences,
+    } : {})
   };
   const payload = await fetchApiJson('/v1/chat/completions', {
     apiKey,
@@ -3208,22 +3551,36 @@ async function runApiChat(log) {
   }
 }
 
-function parseWorkflowInput(raw) {
+function parseJsonArgument(raw, label, code = 'INVALID_JSON_INPUT') {
   if (!raw) return null;
   const sourcePath = raw.startsWith('@') ? raw.slice(1) : raw;
   const expanded = expandHomePath(sourcePath);
-  const text = raw.startsWith('@') || existsSync(expanded)
-    ? readFileSync(expanded, 'utf8')
-    : raw;
+  let text;
+  if (raw.startsWith('@') || existsSync(expanded)) {
+    try {
+      text = readFileSync(expanded, 'utf8');
+    } catch (error) {
+      const err = new Error(`Unable to read ${label} file: ${error?.message || String(error)}`);
+      err.code = code;
+      err.details = { path: expanded };
+      throw err;
+    }
+  } else {
+    text = raw;
+  }
   try {
     return JSON.parse(text);
   } catch (error) {
-    const err = new Error(`Invalid --workflow-input JSON: ${error?.message || String(error)}`);
-    err.code = 'INVALID_WORKFLOW_INPUT';
+    const err = new Error(`Invalid ${label} JSON: ${error?.message || String(error)}`);
+    err.code = code;
     throw err;
   }
 }
 
+function parseWorkflowInput(raw) {
+  return parseJsonArgument(raw, '--workflow-input', 'INVALID_WORKFLOW_INPUT');
+}
+
 function buildImageToVideoWorkflowInput() {
   const parsed = parseWorkflowInput(options.apiWorkflowInput);
   if (parsed) return parsed;
@@ -3257,6 +3614,14 @@ function buildHostedToolSequenceWorkflowInput() {
   return parsed;
 }
 
+function buildCreativePlanWorkflowInput() {
+  const parsed = parseWorkflowInput(options.apiWorkflowInput);
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && options.apiWorkflowTitle && !parsed.title) {
+    parsed.title = options.apiWorkflowTitle;
+  }
+  return parsed;
+}
+
 function storyboardWorkflowImageQualityFromCli() {
   if (!cliSet.quality || !options.quality) return undefined;
   if (options.quality === 'pro') return 'high';
@@ -3355,17 +3720,21 @@ function buildStoryboardStorylineMessages() {
 }
 
 async function generateStoryboardWorkflowStoryline(apiKey) {
+  const messages = sanitizeMessagesForLlm(buildStoryboardStorylineMessages());
+  const chatTemplateKwargs = apiChatTemplateKwargs();
   const payload = await fetchApiJson('/v1/chat/completions', {
     apiKey,
     method: 'POST',
     body: {
       model: options.llmModel || DEFAULT_LLM_MODEL,
-      messages: buildStoryboardStorylineMessages(),
+      messages,
       temperature: 0.45,
-      max_tokens: 1800,
+      max_tokens: options.apiMaxTokens || 1800,
       token_type: options.tokenType || 'spark',
       app_source: SOGNI_APP_SOURCE,
       appSource: SOGNI_APP_SOURCE,
+      ...(options.apiTaskProfile ? { task_profile: options.apiTaskProfile } : {}),
+      ...(chatTemplateKwargs ? { chat_template_kwargs: chatTemplateKwargs } : {}),
       sogni_tools: false,
       sogni_tool_execution: false
     }
@@ -3423,6 +3792,104 @@ function eventsFromPayload(payload) {
   return data?.events || payload?.events || [];
 }
 
+function modelsFromPayload(payload) {
+  if (Array.isArray(payload?.data)) return payload.data;
+  const data = extractApiEnvelopeData(payload);
+  const models = Array.isArray(data) ? data : data?.models;
+  return Array.isArray(models) ? models : [];
+}
+
+async function runApiModels() {
+  const creds = loadCredentials();
+  const type = 'api-models';
+  const action = options.apiModelAction || 'list';
+  const apiKey = requireApiKeyCredentials(creds, action === 'get' ? '--get-api-model' : '--list-api-models');
+  const payload = action === 'get'
+    ? await fetchApiJson(`/v1/models/${encodeURIComponent(options.apiModelId)}`, { apiKey })
+    : await fetchApiJson('/v1/models', { apiKey });
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      type,
+      action,
+      ...(action === 'get' ? { model: payload } : { models: modelsFromPayload(payload) }),
+      raw: payload
+    }));
+    return;
+  }
+
+  if (action === 'get') {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  const models = modelsFromPayload(payload);
+  for (const model of models) {
+    console.log(`${model.id || model.modelId || model.name || '(unknown)'}\t${model.owned_by || model.displayName || ''}`);
+  }
+}
+
+function recordsFromReplayPayload(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return Array.isArray(data?.records) ? data.records : Array.isArray(payload?.records) ? payload.records : [];
+}
+
+function replayRecordFromPayload(payload) {
+  const data = extractApiEnvelopeData(payload);
+  return data?.record || payload?.record || payload;
+}
+
+async function runApiReplay() {
+  const creds = loadCredentials();
+  const type = 'api-replay';
+  const action = options.apiReplayAction || 'list';
+  const replayModeLabel = action === 'get'
+    ? '--get-replay'
+    : action === 'ingest'
+      ? '--ingest-replay'
+      : '--list-replays';
+  const apiKey = requireApiKeyCredentials(creds, replayModeLabel);
+  let payload;
+
+  if (action === 'list') {
+    payload = await fetchApiJson(`/v1/replay/records?limit=${encodeURIComponent(options.apiReplayLimit || 50)}`, { apiKey });
+    const records = recordsFromReplayPayload(payload);
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, type, action, records, raw: payload }));
+    } else {
+      for (const record of records) {
+        console.log(`${record.runId || record.run_id || '(unknown)'}\t${record.modelId || record.model_id || '-'}\t${record.rounds ?? '-'}\t${record.userRequest || record.user_request || ''}`);
+      }
+    }
+    return;
+  }
+
+  if (action === 'get') {
+    payload = await fetchApiJson(`/v1/replay/records/${encodeURIComponent(options.apiReplayId)}`, { apiKey });
+    const record = replayRecordFromPayload(payload);
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, type, action, runId: options.apiReplayId, record, raw: payload }));
+    } else {
+      console.log(JSON.stringify(record, null, 2));
+    }
+    return;
+  }
+
+  const recordInput = parseJsonArgument(options.apiReplayInput, '--ingest-replay', 'INVALID_REPLAY_INPUT');
+  payload = await fetchApiJson('/v1/replay/records', {
+    apiKey,
+    method: 'POST',
+    body: recordInput
+  });
+  const result = extractApiEnvelopeData(payload);
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, type, action, result, raw: payload }));
+  } else {
+    console.log(`Replay record ingested: ${result.runId || result.run_id || recordInput?.run_id || '(unknown)'}`);
+  }
+}
+
 function printWorkflowSummary(workflow) {
   console.log(`Workflow: ${workflow.workflowId || workflow.id || '(unknown)'}`);
   if (workflow.kind) console.log(`Kind:     ${workflow.kind}`);
@@ -3536,7 +4003,13 @@ async function runApiWorkflow() {
     return;
   }
 
-  if (options.apiWorkflowAction === 'get' || options.apiWorkflowAction === 'events' || options.apiWorkflowAction === 'stream' || options.apiWorkflowAction === 'cancel') {
+  if (
+    options.apiWorkflowAction === 'get'
+    || options.apiWorkflowAction === 'events'
+    || options.apiWorkflowAction === 'stream'
+    || options.apiWorkflowAction === 'cancel'
+    || options.apiWorkflowAction === 'resume'
+  ) {
     const id = options.apiWorkflowId;
     if (!id) {
       const err = new Error('Workflow id is required.');
@@ -3554,10 +4027,12 @@ async function runApiWorkflow() {
       ? `/v1/creative-agent/workflows/${encodeURIComponent(id)}/events`
       : options.apiWorkflowAction === 'cancel'
         ? `/v1/creative-agent/workflows/${encodeURIComponent(id)}/cancel`
-        : `/v1/creative-agent/workflows/${encodeURIComponent(id)}`;
+        : options.apiWorkflowAction === 'resume'
+          ? `/v1/creative-agent/workflows/${encodeURIComponent(id)}/resume`
+          : `/v1/creative-agent/workflows/${encodeURIComponent(id)}`;
     payload = await fetchApiJson(path, {
       apiKey,
-      method: options.apiWorkflowAction === 'cancel' ? 'POST' : 'GET'
+      method: options.apiWorkflowAction === 'cancel' || options.apiWorkflowAction === 'resume' ? 'POST' : 'GET'
     });
     if (options.apiWorkflowAction === 'events') {
       const events = eventsFromPayload(payload);
@@ -3571,6 +4046,8 @@ async function runApiWorkflow() {
     return;
   }
 
+  const apiMediaReferences = await buildApiMediaReferencesPayload(undefined, { apiKey });
+  const publicSkillRuntime = publicSkillContractRuntimePayload(apiMediaReferences);
   const requestedKind = options.apiWorkflowKind || 'image_to_video';
   let kind = requestedKind;
   let input;
@@ -3586,7 +4063,9 @@ async function runApiWorkflow() {
   } else {
     input = requestedKind === 'hosted_tool_sequence'
       ? buildHostedToolSequenceWorkflowInput()
-      : buildImageToVideoWorkflowInput();
+      : requestedKind === 'creative_plan'
+        ? buildCreativePlanWorkflowInput()
+        : buildImageToVideoWorkflowInput();
   }
 
   payload = await fetchApiJson('/v1/creative-agent/workflows', {
@@ -3599,9 +4078,19 @@ async function runApiWorkflow() {
       kind,
       input,
       ...(options.apiWorkflowIdempotencyKey ? { idempotency_key: options.apiWorkflowIdempotencyKey } : {}),
+      ...(apiMediaReferences.length > 0 ? {
+        api_media_references: apiMediaReferences,
+        media_references: apiMediaReferences,
+      } : {}),
+      ...(options.apiWorkflowMaxCost !== null ? {
+        max_estimated_capacity_units: options.apiWorkflowMaxCost,
+        cost_ceiling: options.apiWorkflowMaxCost,
+      } : {}),
+      ...(options.apiWorkflowConfirmCost !== null ? { confirm_cost: options.apiWorkflowConfirmCost } : {}),
       token_type: tokenType,
       app_source: SOGNI_APP_SOURCE,
-      appSource: SOGNI_APP_SOURCE
+      appSource: SOGNI_APP_SOURCE,
+      public_skill_contract_runtime: publicSkillRuntime
     }
   });
   const workflow = workflowFromPayload(payload);
@@ -4940,6 +5429,16 @@ async function main() {
       }
     }
 
+    if (options.apiModelAction) {
+      await runApiModels();
+      return;
+    }
+
+    if (options.apiReplayAction) {
+      await runApiReplay();
+      return;
+    }
+
     if (options.apiChat) {
       await runApiChat(log);
       return;
@@ -6019,11 +6518,11 @@ async function main() {
     exitCode = 1;
     const shouldJson = options.json || IS_OPENCLAW_INVOCATION;
     if (shouldJson) {
-      const payload = {
+      const payload = addCanonicalErrorFields({
         success: false,
         error: error.message,
         prompt: options.prompt ?? null
-      };
+      }, error);
       if (error.code) payload.errorCode = error.code;
       if (error.details) payload.errorDetails = error.details;
       if (error.hint) payload.hint = error.hint;