@evolinkai/cli 0.14.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -212,6 +212,22 @@ Task pagination returns `page`, `page_size` and `next_page`. `since`/`until` fil
212
212
 
213
213
  All-result downloads accept up to 50 results. `--template '{task_id}-{index}.{ext}'` also supports `{kind}`; templates must produce distinct portable filenames without directories. Local receipts record sizes and SHA-256 hashes. `--resume` verifies saved files and downloads the remainder with the same task/directory/template. Changed files and unrelated existing files are preserved. Partial delivery returns successful files and per-result errors, exits nonzero, and leaves generation marked completed. Recover downloads using the original task; never regenerate to fix delivery.
214
214
 
215
+ ## Workflows
216
+
217
+ A workflow is a set of step-by-step rules that EvoLink sends to a logged-in assistant, for example `ad-rebuild`: rebuild a reference ad of up to 30 seconds with your own product and creator. The package holds only the commands and a short entry page in the skill (`references/ad-rebuild.md`); the rules arrive after login.
218
+
219
+ ```bash
220
+ evolink workflow rules ad-rebuild --json # overview, a run_id and the section list (free)
221
+ evolink workflow rules ad-rebuild --section plan --run RUN_ID --json
222
+ evolink workflow estimate ad-rebuild --run RUN_ID --seconds 15 --keyframes 6 --quality 720p --json # one estimated total (free)
223
+ evolink video analyze FILE_URL --run RUN_ID --step reference_analysis --purpose breakdown --json # paid, by tokens
224
+ evolink video analysis ANALYSIS_ID --json # collect a read that was still running (free)
225
+ ```
226
+
227
+ - `workflow estimate` returns one total for the whole run from the published prices. The assistant shows that total once and asks once; the total depends mostly on the video's length and resolution.
228
+ - `video analyze` reads an EvoLink file link or result link (MP4 or MOV, within the workflow's length limit). It is charged by tokens to the logged-in account and is part of the workflow's estimated total. Repeating exactly the same command within 24 hours returns the first result without a new charge; a failed read exits non-zero with the service's error code and next step, and a read that was cut off still prints what was read.
229
+ - `workflow_unavailable` means the service does not offer workflows for this login yet.
230
+
215
231
  ## Usage and spending limits
216
232
 
217
233
  ```sh
@@ -241,11 +257,11 @@ All machine-readable commands accept `--json`. Stdout contains one envelope with
241
257
 
242
258
  Run installation and tests on the test cloud host, not the development Mac. In this package directory: `npm ci`, `npm test`, `npm run test:mutations`, and `npm pack`. Tests use loopback fixtures and never spend production credits. Real paid acceptance requires a separate quote and user approval.
243
259
 
244
- Development starts in `deeplearning-goethe/evolink-cli`. After acceptance, repository management will arrange migration to `Evolink-AI/evolink-cli`. Keep package/bin names and service identity stable; update repository metadata, publishing permissions and installation links during migration.
260
+ The repository is `Evolink-AI/evolink-cli`. Development started in `deeplearning-goethe/evolink-cli`, which moved here on 2026-11-14 and is now archived: its history and release tags were carried over, while its earlier pull requests and GitHub releases stay in the archived repository. Package and command names and the service identity did not change; the npm package's repository link points here from its next release.
245
261
 
246
262
  ## Platform and MCP paths
247
263
 
248
- The CLI uses REST and does not connect to the hosted MCP server. Browser chat clients continue to use remote MCP. Both paths currently share Passport resource permissions and the internal `EvoLink MCP (OAuth)` account limit. The authorization resource remains `https://mcp.evolink.ai/mcp`; it is distinct from the REST API destination. The gateway MCP emergency switch still applies to both paths. Total and daily limits, model permissions and pause apply to both clients; logging out revokes only the current OAuth session. Separate keys are optional when a project needs independent limits. Backend parameterized media Quote and its OAuth route must be enabled for account estimates.
264
+ The CLI uses REST for everything except the workflow commands. `workflow rules`, `workflow estimate`, `video analyze` and `video analysis` send one `tools/call` request each to the hosted MCP server named by `--server`, because a workflow's rules and the prompts behind a video read are kept on that service and never ship with this package. Browser chat clients continue to use remote MCP. Both paths currently share Passport resource permissions and the internal `EvoLink MCP (OAuth)` account limit. The authorization resource remains `https://mcp.evolink.ai/mcp`; it is distinct from the REST API destination. The gateway MCP emergency switch still applies to both paths. Total and daily limits, model permissions and pause apply to both clients; logging out revokes only the current OAuth session. Separate keys are optional when a project needs independent limits. Backend parameterized media Quote and its OAuth route must be enabled for account estimates.
249
265
 
250
266
  The CLI vendors the reviewed shared platform module from the MCP repository with a SHA-256 source/artifact manifest in `src/platform/source.json`. Refresh it on the test host using `scripts/sync-platform-client.mjs`; never edit generated files. The MCP SDK is a development dependency for compatibility fixtures only. No extra package or MCP plugin installation is needed by CLI users.
251
267
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evolinkai/cli",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "description": "Generate images, video and audio with EvoLink, with browser login and quoted submissions.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -19,7 +19,7 @@
19
19
  ],
20
20
  "repository": {
21
21
  "type": "git",
22
- "url": "git+https://github.com/deeplearning-goethe/evolink-cli.git",
22
+ "url": "git+https://github.com/Evolink-AI/evolink-cli.git",
23
23
  "directory": "packages/cli"
24
24
  },
25
25
  "publishConfig": {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: evolink-cli
3
- description: Generate or edit images, video, music and speech with the EvoLink CLI; discover models, quote tasks, upload references and deliver results. Applies when a terminal is available. Respect an explicitly requested different provider; exclude media analysis and repository development.
3
+ description: Generate or edit images, video, music and speech with the EvoLink CLI; discover models, quote tasks, upload references and deliver results. Also rebuild a reference ad with the user's own product and creator (the ad rebuild workflow). Applies when a terminal is available. Respect an explicitly requested different provider; exclude media analysis and repository development.
4
4
  ---
5
5
 
6
6
  <!-- evolink-media-cli-owned -->
@@ -55,6 +55,10 @@ If the assistant host denies a tool call, stop and explain the required permissi
55
55
 
56
56
  Never ask for credentials in chat, read other applications' tokens, or use API keys on the command line. Use the installed CLI's OS credential store. Missing secure storage requires fixing that storage; do not invent a plaintext-token fallback.
57
57
 
58
+ ## Workflows
59
+
60
+ When the user asks to rebuild, remake or clone a reference ad with their own product and creator, read [Ad rebuild workflow](references/ad-rebuild.md) first and follow it. Its step-by-step rules come from EvoLink after login: fetch them with `evolink workflow rules ad-rebuild --json`, section by section, and do not improvise the steps. It asks the user to confirm one estimated total (`evolink workflow estimate`) instead of each quote; that confirmation covers the quotes inside the total. `evolink video analyze` is paid and belongs to a workflow step; do not use it for other media analysis.
61
+
58
62
  ## Prepare and quote
59
63
 
60
64
  For image edits, reference-based video, speech or music, read [media workflows](references/media-workflows.md) when selecting inputs. Model discovery and `models show` determine actual support; never invent input fields or infer model quality from search order.
@@ -0,0 +1,76 @@
1
+ # Ad rebuild workflow
2
+
3
+ Rebuild a reference ad as a new ad with the user's own product and creator. The structure, hook and rhythm stay; the person, product, room, words and music are new. The result is one finished vertical video with sound, generated in a single video task and delivered with a keyframe contact sheet, a verdict for every shot and the total cost.
4
+
5
+ This page is only the entry point. EvoLink sends the working rules for each step after login. Fetch them with `evolink workflow rules ad-rebuild --json` and follow them; do not improvise the steps from this page.
6
+
7
+ ## What you need from the user
8
+
9
+ - The reference ad: a video of 30 seconds or less. If it is longer, ask for a segment of 30 seconds or less.
10
+ - Product images, one line on what the product does, and which claims are verified.
11
+ - A creator photo if a specific person should appear. Without one, a fictional adult creator is prepared when the ad needs a person.
12
+ - Choices that cannot be inferred: language, on-camera speech or voiceover, music, aspect ratio, length (up to 30 seconds) and resolution.
13
+
14
+ The user must own the product and creator material or have the rights to use it.
15
+
16
+ ## Before you start
17
+
18
+ - The CLI must be logged in: `evolink balance --json` succeeds. If it reports `login_required`, ask the user to run `evolink auth login`, then stop until it is done.
19
+ - If `evolink workflow rules ad-rebuild --json` reports `workflow_unavailable`, the workflow is not offered for this login yet. Say so and stop.
20
+ - Never ask for an API key. Charges go to the logged-in account.
21
+ - Frames, crops and contact sheets: use local ffmpeg and ffprobe. If they are missing, ask before installing them.
22
+
23
+ ## Commands
24
+
25
+ The rules name EvoLink tools. With the CLI, run these commands instead:
26
+
27
+ | The rules say | Run |
28
+ |---|---|
29
+ | `get_media_workflow` | `evolink workflow rules ad-rebuild [--section ID] --run RUN_ID --json` (leave `--run` out only on the first call) |
30
+ | `get_media_workflow` with `estimate` | `evolink workflow estimate ad-rebuild --run RUN_ID --seconds N --keyframes N [--quality 720p] [--aspect-ratio 9:16] [--creator-images N] --json` |
31
+ | `analyze_video` | `evolink video analyze FILE_URL --run RUN_ID --step STEP --purpose breakdown\|sound\|compare [--target-file FILE] [--attempt N] --json` |
32
+ | `get_video_analysis` | `evolink video analysis ANALYSIS_ID --json` |
33
+ | `upload_file`, `prepare_upload` | `evolink upload /absolute/path --json` |
34
+ | `search_models`, `get_model` | `evolink models search --query TEXT --json`, `evolink models show MODEL --json` |
35
+ | `estimate_cost` | `evolink estimate --model MODEL --input-file FILE --json` |
36
+ | `generate_image`, `generate_video`, `generate_audio` | `evolink generate image\|video\|audio --quote ID --confirm --json` |
37
+ | `get_task`, `list_tasks` | `evolink tasks get\|wait\|list\|batch ... --json` |
38
+ | `check_balance` | `evolink balance --json` |
39
+ | `make_frames` | not in the CLI: use local ffmpeg |
40
+
41
+ The first `workflow rules` answer returns a `run_id` and the list of sections. Pass that `run_id` with `--run` on every later `workflow` and `video` command of the same rebuild, and fetch each section when you reach its step.
42
+
43
+ For a comparison (`--purpose compare`), write the whole-ad target sheet and timeline to a text file and pass it with `--target-file`.
44
+
45
+ ## Steps
46
+
47
+ 0. Check inputs and confirm the cost
48
+ 1. Read the reference
49
+ 2. Write the target
50
+ 3. Plan the whole ad
51
+ 4. Build and check all keyframes
52
+ 5. Build the complete video input
53
+ 6. Generate and check
54
+ 7. Deliver
55
+
56
+ ## Cost: one estimate, one confirmation
57
+
58
+ - Before the user confirms, do only free work: login and balance, the reference's duration and aspect ratio, frames and shot count, rules and prices. `workflow rules` and `workflow estimate` are free. `video analyze` is paid.
59
+ - Present the one estimated total from `workflow estimate` and what it covers, and ask once. The total depends mostly on the length and resolution of the video. Charges are then made step by step as the work runs.
60
+ - That confirmation is the approval for the quotes inside the total: after it, estimate each generation and submit it with `--confirm` without asking again, as long as the running total stays within the estimate.
61
+ - Ask again only when the total would be exceeded, when a decision is the user's, or when the finished ad needs a new attempt.
62
+ - If the user asks what the total includes, say the total and what it covers. Every call is listed in the dashboard history: https://evolink.ai/dashboard
63
+
64
+ ## If something stops the run
65
+
66
+ - **Balance too low.** Nothing is charged for the refused step. Give the top-up link from the error. After the user tops up, continue from the same step; finished steps are reused.
67
+ - **A generation fails.** It is not charged. Retry at most twice for a temporary failure, then stop and explain.
68
+ - **A video read fails.** Follow the next step in the error. Repeat exactly the same command when it says so: a finished read is returned without a new charge. Add `--attempt 2` only when the error says to raise the attempt.
69
+ - **The terminal or the conversation restarts.** Fetch the rules again with the same `--run`, and look for submitted tasks with `evolink tasks list --json` before submitting anything again. Result links stay downloadable for 24 hours and uploads for 72 hours.
70
+
71
+ ## Rights and limits
72
+
73
+ - The reference guides structure only. The new ad must not show the reference's people, faces, clothing, room, brand or audio.
74
+ - Do not invent logos, prices, statistics or product claims. Use only claims the user confirmed.
75
+ - Some image and video models refuse inputs that look like real people. Report a refusal; never reword a prompt to get past review.
76
+ - One creator and one product per run unless the user asks otherwise.
package/src/cli.mjs CHANGED
@@ -9,6 +9,7 @@ import { upload, download, downloadAll, getUpload } from './files.mjs';
9
9
  import { commandHelp } from './help.mjs';
10
10
  import { installSkill, skillStatus, validateAgent } from './skills.mjs';
11
11
  import { doctor } from './doctor.mjs';
12
+ import { Workflows } from './workflow.mjs';
12
13
  import { setup } from './setup.mjs';
13
14
  import { checkForUpdate, updateNotice } from './update.mjs';
14
15
  import { CLI_VERSION } from './version.mjs';
@@ -82,6 +83,15 @@ const HELP = `EvoLink CLI ${CLI_VERSION} (Node.js 22+)
82
83
  uploads get ID Read a saved upload receipt (free)
83
84
  download TASK_ID --output FILE [--index N]
84
85
  download TASK_ID --all --output-dir DIR [--template NAME] [--resume]
86
+ workflow rules NAME [--section ID] [--run RUN_ID]
87
+ Step-by-step rules of an EvoLink workflow (free)
88
+ workflow estimate NAME --seconds N --keyframes N [--run RUN_ID]
89
+ [--quality 480p|720p|1080p] [--aspect-ratio RATIO] [--creator-images N]
90
+ One estimated total for a whole run (free)
91
+ video analyze FILE_URL --run RUN_ID --step STEP --purpose PURPOSE
92
+ [--target-file FILE] [--attempt N]
93
+ Read a video for a workflow step (paid, by tokens)
94
+ video analysis ANALYSIS_ID Collect a read that was still running (free)
85
95
  skills install [--agent NAME] [--replace-modified]
86
96
  Install or update; back up replaced files
87
97
  skills status [--agent NAME] Check installed skill content and CLI version
@@ -115,6 +125,9 @@ lower submits; a higher price, a changed input or an expired quote needs a new a
115
125
  who explicitly said not to estimate or confirm.
116
126
  A batch quote submits all its inputs in one call; tasks resume finishes the rest
117
127
  with the same request ID within 23 hours, while the quote holds.
128
+ Workflows (for example ad-rebuild) need the login: their rules and video reads come
129
+ from the EvoLink MCP service named by --server. video analyze is charged to the account;
130
+ the same command repeated within 24 hours returns the first result without a new charge.
118
131
  Spending caps protect the estimate at submission, not final settlement.
119
132
  Ctrl-C stops local waiting; submitted tasks continue on EvoLink.
120
133
  `;
@@ -123,7 +136,8 @@ Ctrl-C stops local waiting; submitted tasks continue on EvoLink.
123
136
  const NO_UPDATE_NOTICE = new Set(['setup', 'doctor', 'auth login', 'auth status']);
124
137
 
125
138
  const OPTIONS = Object.fromEntries(['server', 'api-url', 'files-url', 'query', 'type', 'limit', 'model', 'modality', 'view', 'product-id', 'operation', 'lifecycle', 'input', 'input-file', 'inputs-file', 'prompt', 'media-seconds',
126
- 'pricing-source', 'pricing-parameters', 'refresh-quote', 'max-cost-usd', 'quote', 'timeout', 'status', 'since', 'until', 'page', 'ids', 'references', 'max-pages', 'output', 'output-dir', 'template', 'index', 'upload-path', 'agent'].map(k => [k, { type: 'string' }]));
139
+ 'pricing-source', 'pricing-parameters', 'refresh-quote', 'max-cost-usd', 'quote', 'timeout', 'status', 'since', 'until', 'page', 'ids', 'references', 'max-pages', 'output', 'output-dir', 'template', 'index', 'upload-path', 'agent',
140
+ 'section', 'run', 'seconds', 'keyframes', 'quality', 'aspect-ratio', 'creator-images', 'step', 'purpose', 'target-file', 'attempt'].map(k => [k, { type: 'string' }]));
127
141
  for (const k of ['json', 'token-stdin', 'no-browser', 'replace-modified', 'confirm', 'skip-estimate', 'wait', 'all', 'resume', 'help', 'version']) OPTIONS[k] = { type: 'boolean' };
128
142
 
129
143
  function number(value, name, min, max, integer = false) {
@@ -148,6 +162,8 @@ export function validateCommand(args, options) {
148
162
  'tasks get': [3], 'tasks wait': [3, 'timeout'], 'tasks batch': [2, 'ids'], 'tasks list': [2, 'type', 'status', 'since', 'until', 'model', 'page', 'limit'], 'tasks resume': [2, 'quote'],
149
163
  upload: [2, 'upload-path'], 'uploads get': [3], download: [2, 'output', 'index', 'all', 'output-dir', 'template', 'resume'],
150
164
  'skills install': [2, 'agent', 'replace-modified'], 'skills status': [2, 'agent'], doctor: [1, 'agent'],
165
+ 'workflow rules': [3, 'section', 'run'], 'workflow estimate': [3, 'run', 'seconds', 'keyframes', 'quality', 'aspect-ratio', 'creator-images'],
166
+ 'video analyze': [3, 'run', 'step', 'purpose', 'target-file', 'attempt'], 'video analysis': [3],
151
167
  };
152
168
  const route = routes[`${command} ${action}`] || routes[command];
153
169
  requireThat(route && args.length === route[0], 'unknown_command', 'Unknown command or argument count. Run evolink --help.');
@@ -255,7 +271,7 @@ async function estimateArgs(options) {
255
271
  return { model: options.model, ...body, ...(pricingParameters !== undefined ? { pricing_parameters: pricingParameters } : {}), ...(options['pricing-source'] ? { pricing_source: options['pricing-source'] } : {}), ...(media !== undefined ? { media_seconds: media } : {}), ...(cap !== undefined ? { max_cost_usd: cap } : {}) };
256
272
  }
257
273
 
258
- export async function dispatch(positionals, options, { state, server, credentials, client, mcp = client, signal, progress, skillHome, updates, budget }) {
274
+ export async function dispatch(positionals, options, { state, server, credentials, client, mcp = client, workflows, signal, progress, skillHome, updates, budget }) {
259
275
  // login, setup and doctor always ask the registry and report the outcome, including a disabled check;
260
276
  // loopback test resources never contact it.
261
277
  const update = () => checkForUpdate({ state, server, force: true, signal, ...updates });
@@ -343,6 +359,21 @@ export async function dispatch(positionals, options, { state, server, credential
343
359
  if (command === 'setup') return setup({ state, server, credentials, client, agent: options.agent, skillHome,
344
360
  noBrowser: options['no-browser'], timeout: options.timeout === undefined ? undefined : Number(options.timeout) * 1000, signal, progress, update });
345
361
  if (command === 'doctor') return doctor({ state, server, credentials, client, agent: options.agent, skillHome, update });
362
+ if ((command === 'workflow' || command === 'video') && workflows) {
363
+ if (command === 'workflow' && action === 'rules') return workflows.rules(id, { section: options.section, run: options.run });
364
+ if (command === 'workflow' && action === 'estimate') {
365
+ requireThat(options.seconds !== undefined && options.keyframes !== undefined, 'missing_option', 'Pass --seconds and --keyframes: the planned video length and the expected number of keyframe images.');
366
+ requireThat(options.quality === undefined || ['480p', '720p', '1080p'].includes(options.quality), 'invalid_option', 'quality must be 480p, 720p or 1080p.');
367
+ requireThat(options['aspect-ratio'] === undefined || ['16:9', '9:16', '1:1', '4:3', '3:4', '21:9'].includes(options['aspect-ratio']), 'invalid_option', 'aspect-ratio must be 16:9, 9:16, 1:1, 4:3, 3:4 or 21:9.');
368
+ return workflows.estimate(id, { run: options.run, seconds: number(options.seconds, 'seconds', 1, 600, true), keyframes: number(options.keyframes, 'keyframes', 1, 100, true),
369
+ quality: options.quality, aspectRatio: options['aspect-ratio'], creatorImages: number(options['creator-images'], 'creator-images', 0, 10, true) });
370
+ }
371
+ if (command === 'video' && action === 'analyze') {
372
+ requireThat(options.run && options.step && options.purpose, 'missing_option', 'Pass --run, --step and --purpose, as the workflow rules name them.');
373
+ return workflows.analyze(id, { run: options.run, step: options.step, purpose: options.purpose, targetFile: options['target-file'], attempt: number(options.attempt, 'attempt', 1, 3, true) });
374
+ }
375
+ if (command === 'video' && action === 'analysis') return workflows.analysis(id);
376
+ }
346
377
  throw new CliError('unknown_command', 'Unknown command or missing argument. Run evolink --help.');
347
378
  }
348
379
 
@@ -410,7 +441,8 @@ export async function main(argv = process.argv.slice(2), io = { stdout: process.
410
441
  const client = new Api(credentials, { signal: controller.signal, apiUrl: options['api-url'], filesUrl: options['files-url'] });
411
442
  // Only a fully validated command checks: invalid tokens and service URLs fail without contacting npm.
412
443
  if (!NO_UPDATE_NOTICE.has(positionals[0]) && !NO_UPDATE_NOTICE.has(positionals.slice(0, 2).join(' '))) checkUpdate(server);
413
- const result = publicView(await dispatch(positionals, options, { state, server, credentials, client, signal: controller.signal, progress: message => io.stderr.write(message + '\n'), updates, budget }));
444
+ const workflows = new Workflows(credentials, { signal: controller.signal });
445
+ const result = publicView(await dispatch(positionals, options, { state, server, credentials, client, workflows, signal: controller.signal, progress: message => io.stderr.write(message + '\n'), updates, budget }));
414
446
  const view = { schema_version: 1, ...result, ok: result.ok !== false };
415
447
  io.stdout.write(options.json ? JSON.stringify(view) + '\n' : `${result.text || JSON.stringify(view, null, 2)}\n${result.quote_id ? `Quote: ${result.quote_id}\n` : ''}`);
416
448
  if (!view.ok) process.exitCode = view.error?.code === 'interrupted' ? 130 : 1;
package/src/help.mjs CHANGED
@@ -18,7 +18,7 @@ const COMMANDS = {
18
18
  'models search': ['[options]', 'Search currently available models; search order is not a quality ranking.', { query: string('Search keywords'), type: allMedia, limit: integer(1, 50, 20), page: integer(1, 100000, 1) }],
19
19
  'models show': ['MODEL', 'Read documented parameters, example input, reference fields and pricing. Free.', {}],
20
20
  'models pricing': ['[options]', 'Read public default pricing rules without login. Decimal-string rates, minimums, tiers and expressions are configuration references, not account prices, quotes, bills or final spending caps. Coverage follows returned policies and legacy text adapters; empty results do not mean free.', {
21
- model: string('Exact model ID; omit for the filtered list'), 'product-id': string('Product ID'), operation: string('Operation, e.g. text_generation'),
21
+ model: string('Model ID or a published alias (case-insensitive); omit for the filtered list'), 'product-id': string('Product ID'), operation: string('Operation, e.g. text_generation'),
22
22
  modality: choice(['text', 'image', 'video', 'audio']), lifecycle: choice(['active', 'preview', 'deprecated']), view: { ...choice(['summary', 'full']), default: 'full' },
23
23
  }],
24
24
  'models schema': ['MODEL', 'Read versioned input and generation-submission response schemas. The response schema may omit final task outputs; runtime constraints also apply.', {}],
@@ -47,6 +47,19 @@ const COMMANDS = {
47
47
  output: string('New file path, for a single result'), index: integer(1, 50, 1), all: flag, 'output-dir': string('Directory, required with all'),
48
48
  template: { ...string('Filename placeholders: {task_id}, {index}, {kind}, {ext}; no directories'), default: '{task_id}-{index}.{ext}' }, resume: flag,
49
49
  }],
50
+ 'workflow rules': ['NAME [options]', 'Read the step-by-step rules of an EvoLink workflow (for example ad-rebuild) from the signed-in service. The first call returns the overview, a run_id and the section list; pass --run on every later call so the whole run uses one version of the rules. Free.', {
51
+ section: string('Section ID from an earlier answer; the overview when omitted'), run: string('run_id returned by the first call of this run'),
52
+ }],
53
+ 'workflow estimate': ['NAME --seconds N --keyframes N [options]', 'One estimated total for a whole workflow run, from the published prices of its default models. Show the user this total and what it covers before any paid step. Nothing is charged.', {
54
+ run: string('run_id of this run'), seconds: integer(1, 600), keyframes: integer(1, 100), quality: choice(['480p', '720p', '1080p']),
55
+ 'aspect-ratio': choice(['16:9', '9:16', '1:1', '4:3', '3:4', '21:9']), 'creator-images': integer(0, 10, 0),
56
+ }],
57
+ 'video analyze': ['FILE_URL --run RUN_ID --step STEP --purpose PURPOSE [options]', 'Read a video for a workflow step. Paid, by tokens, to the signed-in account, and part of the workflow\'s estimated total: do not run it before the user confirmed that total. FILE_URL is an EvoLink file link (from evolink upload) or an EvoLink result link to an MP4 or MOV. The same command within 24 hours returns the first result without a new charge. A slow read returns an analysis_id for video analysis.', {
58
+ run: string('Required run_id from workflow rules'), step: string('Required step name from the workflow rules, e.g. reference_analysis'),
59
+ purpose: string('Required purpose named by the workflow rules, e.g. breakdown, sound, compare'),
60
+ 'target-file': string('Local text file with the target to compare the video against; only for a comparison'), attempt: integer(1, 3, 1),
61
+ }],
62
+ 'video analysis': ['ANALYSIS_ID', 'Collect the result of a video analyze call that was still running. Free.', {}],
50
63
  'skills install': ['[options]', 'Install or synchronize bundled skill files; protect modified files and back up replacements.', { agent, 'replace-modified': flag }],
51
64
  'skills status': ['[options]', 'Compare installed skill contents and package version.', { agent }],
52
65
  doctor: ['[options]', 'Check prerequisites, connection, model discovery, skill contents and CLI updates separately. An available update, and installed skill findings without --agent, are guidance only. Free.', { agent }],
@@ -29,8 +29,10 @@ const family25 = (model) => model.trim().toLowerCase().startsWith('gpt-image-2.5
29
29
  const family1 = (model) => model === 'gpt-image-1.5' || model === 'gpt-image-1';
30
30
  /** Models the gateway reserves and bills by token counts. */
31
31
  export const isTokenImageModel = (model) => model === 'gpt-image-2' || family1(model) || family25(model);
32
- function invalid(param, message) { throw new QuoteError('invalid_quote_parameter', message, param); }
33
- const text = (param, value) => value === undefined ? '' : typeof value === 'string' ? value : invalid(param, `${param} must be a string.`);
32
+ function invalid(param, message, check = 'range') {
33
+ throw new QuoteError('invalid_quote_parameter', message, param, undefined, check, 'gpt_image');
34
+ }
35
+ const text = (param, value) => value === undefined ? '' : typeof value === 'string' ? value : invalid(param, `${param} must be a string.`, 'type');
34
36
  const nestedParams = (input) => input.model_params && typeof input.model_params === 'object' && !Array.isArray(input.model_params)
35
37
  ? input.model_params : {};
36
38
  const lower = (value) => typeof value === 'string' ? value.trim().toLowerCase() : '';
@@ -81,8 +83,8 @@ function outputSize(size, resolution) {
81
83
  return pixels;
82
84
  }
83
85
  const ratio = ['', 'auto'].includes(trimmed.toLowerCase()) ? '1:1' : trimmed.toLowerCase();
84
- const aspect = RATIOS[ratio] ?? invalid('size', `size ${size} is not a supported ratio or WxH pixel size.`);
85
- const tier = resolution.trim().toUpperCase() || '1K', budget = BUDGETS[tier] ?? invalid('resolution', `resolution ${resolution} must be 1K, 2K or 4K.`);
86
+ const aspect = RATIOS[ratio] ?? invalid('size', `size ${size} is not a supported ratio or WxH pixel size.`, 'enum');
87
+ const tier = resolution.trim().toUpperCase() || '1K', budget = BUDGETS[tier] ?? invalid('resolution', `resolution ${resolution} must be 1K, 2K or 4K.`, 'enum');
86
88
  const [width, height] = fitBudget(roundToStep(Math.trunc(Math.sqrt(budget * aspect[0] / aspect[1]))), roundToStep(Math.trunc(Math.sqrt(budget * aspect[1] / aspect[0]))));
87
89
  checkPixels(width, height);
88
90
  return [width, height];
@@ -96,7 +98,7 @@ function family1Size(size) {
96
98
  return [1024, 1536];
97
99
  if (['1536x1024', '1536×1024', '3:2'].includes(value))
98
100
  return [1536, 1024];
99
- return invalid('size', `size ${size} must be 1024x1024, 1024x1536, 1536x1024, 1:1, 2:3 or 3:2.`);
101
+ return invalid('size', `size ${size} must be 1024x1024, 1024x1536, 1536x1024, 1:1, 2:3 or 3:2.`, 'enum');
100
102
  }
101
103
  function scaledTiles(base, longer, shorter) {
102
104
  // The calculator's own order of division: base * shorter / longer differs in the last bit for a few sizes.
@@ -152,7 +154,7 @@ function gifSheet(model, size, frames, quality) {
152
154
  if (!['', 'auto'].includes(trimmed.toLowerCase())) {
153
155
  const pixels = trimmed.includes(':') ? undefined : pixelSize(trimmed);
154
156
  if (!pixels)
155
- invalid('size', `With output_format gif, size is auto or the WIDTHxHEIGHT of each frame, not ${size}.`);
157
+ invalid('size', `With output_format gif, size is auto or the WIDTHxHEIGHT of each frame, not ${size}.`, 'shape');
156
158
  [frameWidth, frameHeight] = pixels;
157
159
  if (frameWidth % STEP || frameHeight % STEP || frameWidth > MAX_EDGE || frameHeight > MAX_EDGE) {
158
160
  invalid('size', `GIF frame edges must be multiples of ${STEP} and at most ${MAX_EDGE}px, got ${frameWidth}x${frameHeight}.`);
@@ -205,30 +207,30 @@ function gifOutput(model, input, images) {
205
207
  const params = nestedParams(input);
206
208
  const format = lower(input.output_format) || lower(params.output_format), background = lower(input.background) || lower(params.background);
207
209
  if (background === 'transparent' && (format === 'jpeg' || format === 'jpg'))
208
- invalid('background', `background transparent needs png or webp output; ${format} cannot keep transparency.`);
210
+ invalid('background', `background transparent needs png or webp output; ${format} cannot keep transparency.`, 'conflict');
209
211
  if (!family26(model))
210
212
  return false;
211
213
  // SVG output is paused on the gateway, and its author model would be priced on top, so it is never quoted.
212
214
  if (format === 'svg')
213
- invalid('output_format', `output_format svg is not available on ${model}; use png, jpeg, webp or gif.`);
215
+ invalid('output_format', `output_format svg is not available on ${model}; use png, jpeg, webp or gif.`, 'enum');
214
216
  if (['svg_model', 'svg_reasoning_effort'].some(key => Object.hasOwn(params, key)))
215
- invalid('model_params', 'model_params.svg_model and svg_reasoning_effort need output_format svg, which is not available.');
217
+ invalid('model_params', 'model_params.svg_model and svg_reasoning_effort need output_format svg, which is not available.', 'conflict');
216
218
  if (format !== 'gif' && ['frame_count', 'frame_duration_ms'].some(key => Object.hasOwn(params, key)))
217
- invalid('model_params', 'model_params.frame_count and frame_duration_ms need output_format gif.');
219
+ invalid('model_params', 'model_params.frame_count and frame_duration_ms need output_format gif.', 'conflict');
218
220
  const markup = [input.markup_url, params.markup_url].map(value => typeof value === 'string' ? value.trim() : '').find(Boolean);
219
221
  if (markup) {
220
222
  if (!(referenceCount(input.image_url) + referenceCount(input.image_urls) + referenceCount(params.image_url) + referenceCount(params.image_urls))) {
221
- invalid('markup_url', 'markup_url marks up the first reference image, so it needs image_urls.');
223
+ invalid('markup_url', 'markup_url marks up the first reference image, so it needs image_urls.', 'required');
222
224
  }
223
225
  if ([input.mask_url, params.mask_url].some(value => typeof value === 'string' && value.trim() !== ''))
224
- invalid('markup_url', 'markup_url cannot be combined with mask_url.');
226
+ invalid('markup_url', 'markup_url cannot be combined with mask_url.', 'conflict');
225
227
  }
226
228
  if (format !== 'gif')
227
229
  return false;
228
230
  if (images > 1)
229
- invalid('n', `output_format gif on ${model} needs n=1.`);
231
+ invalid('n', `output_format gif on ${model} needs n=1.`, 'conflict');
230
232
  if (background === 'transparent')
231
- invalid('background', 'background transparent needs png or webp output, not gif.');
233
+ invalid('background', 'background transparent needs png or webp output, not gif.', 'conflict');
232
234
  return true;
233
235
  }
234
236
  /**
@@ -238,11 +240,11 @@ function gifOutput(model, input, images) {
238
240
  * countPromptTokens replaces the approximation when the exact count is known.
239
241
  */
240
242
  export function tokenImageReservation(model, input, countPromptTokens = approximatePromptTokens) {
241
- const n = input.n === undefined ? 1 : Number.isInteger(input.n) ? Math.max(1, input.n) : invalid('n', 'n must be a whole number.');
243
+ const n = input.n === undefined ? 1 : Number.isInteger(input.n) ? Math.max(1, input.n) : invalid('n', 'n must be a whole number.', 'type');
242
244
  const given = text('quality', input.quality);
243
245
  const quality = given === '' ? family1(model) ? 'high' : 'medium' : given.trim().toLowerCase();
244
246
  if (!Object.hasOwn(family1(model) ? TILES_1 : family25(model) ? BASE_25 : BASE_2, quality))
245
- invalid('quality', `quality ${given} is not supported by ${model}.`);
247
+ invalid('quality', `quality ${given} is not supported by ${model}.`, 'enum');
246
248
  const size = text('size', input.size), resolution = text('resolution', input.resolution);
247
249
  const auto = !family1(model) && ['', 'auto'].includes(size.trim().toLowerCase());
248
250
  let output, outputTokens;
@@ -50,7 +50,9 @@ export function approximateOmniPromptTokens(prompt) {
50
50
  }
51
51
  return Math.ceil(hundredths / 100);
52
52
  }
53
- function invalid(param, message) { throw new QuoteError('invalid_quote_parameter', message, param); }
53
+ function invalid(param, message, check = 'count') {
54
+ throw new QuoteError('invalid_quote_parameter', message, param, undefined, check, 'omni');
55
+ }
54
56
  const textOf = (value) => typeof value === 'string' ? value : '';
55
57
  /** parseFlexibleStringArray: one string or a list; empty and non-string entries do not count. */
56
58
  const flexible = (value) => typeof value === 'string' ? value === '' ? [] : [value]
@@ -86,12 +88,12 @@ const upscaleMax = (target) => Math.max(0, ...Object.entries(UPSCALE).filter(([p
86
88
  const upscaleSource = (target) => TIERS.find(tier => UPSCALE[`${tier}>${target}`] === upscaleMax(target));
87
89
  function checkLength(mediaSeconds, max, what, model) {
88
90
  if (mediaSeconds > max)
89
- invalid('media_seconds', `${what} must be ${max} seconds or shorter for ${model}; media_seconds is ${mediaSeconds}.`);
91
+ invalid('media_seconds', `${what} must be ${max} seconds or shorter for ${model}; media_seconds is ${mediaSeconds}.`, 'range');
90
92
  }
91
93
  function requirePrompt(input, model) {
92
94
  const prompt = textOf(input.prompt);
93
95
  if (prompt.trim() === '')
94
- invalid('prompt', `prompt is required for ${model}.`);
96
+ invalid('prompt', `prompt is required for ${model}.`, 'required');
95
97
  return prompt;
96
98
  }
97
99
  /**
@@ -100,7 +102,7 @@ function requirePrompt(input, model) {
100
102
  * countPromptTokens replaces the approximate prompt count when the gateway's exact count is known.
101
103
  */
102
104
  export function omniReservation(model, input, mediaSeconds, options = {}) {
103
- const id = model.trim().toLowerCase(), found = omniModel(id) ?? invalid('model', `${model} is not a Gemini Omni Flash model.`);
105
+ const id = model.trim().toLowerCase(), found = omniModel(id) ?? invalid('model', `${model} is not a Gemini Omni Flash model.`, 'enum');
104
106
  const count = options.countPromptTokens ?? approximateOmniPromptTokens, route = found.route, g = found.generation;
105
107
  const tokensOf = (prompt) => prompt === '' ? 0 : count(prompt);
106
108
  if (!g)
@@ -110,9 +112,9 @@ export function omniReservation(model, input, mediaSeconds, options = {}) {
110
112
  const start = textOf(input.image_start).trim(), end = textOf(input.image_end).trim();
111
113
  if (start || end) {
112
114
  if (route !== 'image')
113
- invalid('image_start', `image_start and image_end are only for gemini-omni-${g.label}-flash-image-to-video.`);
115
+ invalid('image_start', `image_start and image_end are only for gemini-omni-${g.label}-flash-image-to-video.`, 'conflict');
114
116
  if (end && !start)
115
- invalid('image_end', 'image_end needs image_start: a last frame only is not supported.');
117
+ invalid('image_end', 'image_end needs image_start: a last frame only is not supported.', 'required');
116
118
  }
117
119
  const duration = durationOf(input.duration);
118
120
  if (route === 'text' && (images.length || videos.length))
@@ -123,7 +125,7 @@ export function omniReservation(model, input, mediaSeconds, options = {}) {
123
125
  if (videos.length)
124
126
  invalid('video_urls', `${id} takes no video input.`);
125
127
  if (images.length === 2 && duration > g.maxFrameOutput)
126
- invalid('duration', `first and last frame generation supports up to ${g.maxFrameOutput} seconds on ${id}, got ${duration}.`);
128
+ invalid('duration', `first and last frame generation supports up to ${g.maxFrameOutput} seconds on ${id}, got ${duration}.`, 'range');
127
129
  }
128
130
  if (route === 'reference') {
129
131
  if (images.length < 1)
@@ -138,16 +140,16 @@ export function omniReservation(model, input, mediaSeconds, options = {}) {
138
140
  if (videos.length !== 1)
139
141
  invalid('video_urls', `${id} takes exactly 1 video, got ${videos.length}.`);
140
142
  if (!isHTTP(videos[0]))
141
- invalid('video_urls', `${id} takes the video as an http(s) URL.`);
143
+ invalid('video_urls', `${id} takes the video as an http(s) URL.`, 'shape');
142
144
  }
143
145
  // An upscale takes no prompt; the gateway drops one.
144
146
  const prompt = route === 'upscale' ? '' : requirePrompt(input, id);
145
147
  const quality = textOf(input.quality).trim().toLowerCase();
146
148
  const follows = (route === 'edit' || route === 'extend') && (quality === '' || quality === 'auto');
147
149
  if (quality !== '' && !follows && !TIERS.includes(quality))
148
- invalid('quality', `quality ${input.quality} is not supported by ${id}.`);
150
+ invalid('quality', `quality ${input.quality} is not supported by ${id}.`, 'enum');
149
151
  if (route === 'upscale' && (quality === '' || quality === '360p'))
150
- invalid('quality', `quality on ${id} is the target resolution: 720p, 1080p or 4k.`);
152
+ invalid('quality', `quality on ${id} is the target resolution: 720p, 1080p or 4k.`, 'enum');
151
153
  const tier = (quality === '' || quality === 'auto' ? DEFAULT_TIER : quality);
152
154
  // Input and reference videos: the gateway reads their length at submission and refuses one that is too long.
153
155
  let input_videos;
@@ -169,7 +171,7 @@ export function omniReservation(model, input, mediaSeconds, options = {}) {
169
171
  const target = quality, source = options.inputTier ?? upscaleSource(target);
170
172
  const rate = UPSCALE[`${source}>${target}`];
171
173
  if (rate === undefined)
172
- invalid('quality', `${id} cannot upscale ${source} to ${target}; supported: 360p to 720p or 1080p, 720p to 1080p or 4k, 1080p to 4k.`);
174
+ invalid('quality', `${id} cannot upscale ${source} to ${target}; supported: 360p to 720p or 1080p, 720p to 1080p or 4k, 1080p to 4k.`, 'conflict');
173
175
  return { ...base, route, prompt_tokens: 0, output: { resolution: target, seconds: input_videos.seconds },
174
176
  upscale: { target, source, source_assumed: options.inputTier === undefined, tokens_per_second: rate },
175
177
  tokens: { input_tokens: 0, video_output_tokens: cap(rate * input_videos.seconds), other_output_tokens: 0 } };
@@ -195,11 +197,11 @@ function reservation10(id, route, input, mediaSeconds, tokensOf) {
195
197
  const images = media10(input, 'image_urls', 'image_url', 'image'), videos = media10(input, 'video_urls', 'video_url', 'video');
196
198
  // validateGeminiOmniFlashRequest: no resolution or frame fields, an edit takes no duration, and the media each route takes.
197
199
  if (textOf(input.quality) !== '')
198
- invalid('quality', `quality is not supported by ${id}.`);
200
+ invalid('quality', `quality is not supported by ${id}.`, 'conflict');
199
201
  if (textOf(input.image_start) !== '' || textOf(input.image_end) !== '')
200
- invalid('image_start', `image_start and image_end are not supported by ${id}; use image_urls.`);
202
+ invalid('image_start', `image_start and image_end are not supported by ${id}; use image_urls.`, 'conflict');
201
203
  if (route === 'edit' && (durationOf(input.duration) !== 0 || input.duration === 'auto'))
202
- invalid('duration', `duration is not supported by ${id}.`);
204
+ invalid('duration', `duration is not supported by ${id}.`, 'conflict');
203
205
  if (route === 'text' && (images.length || videos.length))
204
206
  invalid('image_urls', `${id} takes no image or video input.`);
205
207
  if (route === 'image' && images.length !== 1)
@@ -214,7 +216,7 @@ function reservation10(id, route, input, mediaSeconds, tokensOf) {
214
216
  if (videos.length !== 1)
215
217
  invalid('video_urls', `${id} takes exactly 1 video, got ${videos.length}.`);
216
218
  if (!isHTTP(videos[0]))
217
- invalid('video_urls', `${id} takes the video as an http(s) URL.`);
219
+ invalid('video_urls', `${id} takes the video as an http(s) URL.`, 'shape');
218
220
  }
219
221
  const prompt = requirePrompt(input, id), promptTokens = tokensOf(prompt);
220
222
  let input_videos, inputTokens = promptTokens;