@evolinkai/cli 0.11.0 → 0.13.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.
Files changed (33) hide show
  1. package/README.md +6 -3
  2. package/package.json +2 -2
  3. package/skills/evolink-cli/SKILL.md +5 -3
  4. package/skills/evolink-cli/references/usage-and-budget.md +3 -1
  5. package/src/api.mjs +7 -6
  6. package/src/auth.mjs +14 -3
  7. package/src/cli.mjs +21 -6
  8. package/src/media.mjs +149 -16
  9. package/src/platform/core/src/data/model-constraints.js +9 -0
  10. package/src/platform/core/src/data/model-params.overrides.generated.js +1 -1
  11. package/src/platform/core/src/platform-operations.js +1 -1
  12. package/src/platform/core/src/services/api-client.js +56 -18
  13. package/src/platform/core/src/services/catalog-client.js +28 -2
  14. package/src/platform/core/src/services/http-policy.js +39 -11
  15. package/src/platform/core/src/services/mj-prompt.js +18 -0
  16. package/src/platform/core/src/services/model-capabilities.js +2 -1
  17. package/src/platform/core/src/services/pricing-call-limit.js +40 -0
  18. package/src/platform/core/src/services/pricing-derived.js +59 -0
  19. package/src/platform/core/src/services/pricing-quote-client.js +30 -7
  20. package/src/platform/core/src/services/pricing-rules-client.js +38 -3
  21. package/src/platform/core/src/services/pricing-rules-estimate.js +128 -10
  22. package/src/platform/core/src/tools/estimate-cost.js +26 -10
  23. package/src/platform/core/src/tools/generate.js +27 -12
  24. package/src/platform/core/src/tools/get-model.js +16 -0
  25. package/src/platform/core/src/tools/get-pricing-rules.js +13 -4
  26. package/src/platform/core/src/tools/get-task.js +37 -13
  27. package/src/platform/core/src/tools/list-tasks.js +47 -10
  28. package/src/platform/core/src/tools/search-models.js +4 -1
  29. package/src/platform/core/src/tools/shared.js +15 -1
  30. package/src/platform/core/src/tools/task-format.js +58 -9
  31. package/src/platform/core/src/version.js +1 -1
  32. package/src/platform/source.json +51 -45
  33. package/src/state.mjs +12 -1
@@ -0,0 +1,40 @@
1
+ // Copyright 2024 EvoLink AI. SPDX-License-Identifier: Apache-2.0
2
+ // Generated from Evolink-AI/evolink-mcp; adapted for direct REST operations. See platform/LICENSE and platform/NOTICE.
3
+ import { currentRequestCredentials } from '../request-context.js';
4
+ const WINDOW_MS = 60_000;
5
+ const MAX_KEYS = 10_000;
6
+ const calls = new Map();
7
+ let clock = () => Date.now();
8
+ /**
9
+ * Price checks (estimate_cost, get_pricing_rules) each signed-in account may make per minute, per tool. The hosted
10
+ * service reaches the platform's per-IP catalog limit from one address for everyone, so one busy assistant must not
11
+ * use it up. A local server serves one user and is not limited here. EVOLINK_MCP_PRICING_CALLS_PER_MINUTE changes
12
+ * the number; 0 turns the limit off.
13
+ */
14
+ export function pricingCallsPerMinute() {
15
+ const raw = process.env.EVOLINK_MCP_PRICING_CALLS_PER_MINUTE;
16
+ const value = raw === undefined || raw.trim() === '' ? 30 : Number(raw);
17
+ return Number.isInteger(value) && value >= 0 && value <= 100_000 ? value : 30;
18
+ }
19
+ /** Counts one call. An account already at its limit is not counted; the result says when its oldest call leaves the window. */
20
+ export function pricingCallLimitReached(tool) {
21
+ const owner = currentRequestCredentials()?.uploadOwner, limit = pricingCallsPerMinute();
22
+ if (!owner || limit === 0)
23
+ return undefined;
24
+ const key = `${tool} ${owner}`, now = clock();
25
+ const recent = (calls.get(key) ?? []).filter(at => now - at < WINDOW_MS);
26
+ calls.delete(key);
27
+ if (recent.length >= limit) {
28
+ calls.set(key, recent);
29
+ return { limit, retryAfterSeconds: Math.max(1, Math.ceil((recent[0] + WINDOW_MS - now) / 1000)) };
30
+ }
31
+ calls.set(key, [...recent, now]);
32
+ // The least recently used account leaves first once the map is full.
33
+ if (calls.size > MAX_KEYS)
34
+ calls.delete(calls.keys().next().value);
35
+ return undefined;
36
+ }
37
+ export function resetPricingCallsForTests(now) {
38
+ calls.clear();
39
+ clock = now ?? (() => Date.now());
40
+ }
@@ -0,0 +1,59 @@
1
+ // Copyright 2024 EvoLink AI. SPDX-License-Identifier: Apache-2.0
2
+ // Generated from Evolink-AI/evolink-mcp; adapted for direct REST operations. See platform/LICENSE and platform/NOTICE.
3
+ // Rule parameters the gateway derives from differently named request fields. Each mapping mirrors the gateway's
4
+ // pre-deduction code (GroAPI feat/task-microservice-split); without it the published default quotes the cheaper case.
5
+ const proTiers = { '1K': '1K', '1.5K': '1.5K', '2K': '2K' };
6
+ const proTier = (value) => typeof value === 'string' ? proTiers[value.trim().toUpperCase()] : undefined;
7
+ // service/multi_sku_billing_service.go seedDreamProOutputTierThresholdPixels. Every 1K and 1.5K ratio preset is
8
+ // below it and every 2K preset above it, so a ratio follows quality.
9
+ const SEEDREAM_PRO_2K_PIXELS = 2_610_000;
10
+ /** controller preprocessSeedream5ProParams, then service ResolveSeedDreamProOutput. */
11
+ function seedreamProTier(input) {
12
+ const size = typeof input.size === 'string' ? input.size.trim() : '';
13
+ if (size === '' || size === 'auto' || size.includes(':'))
14
+ return proTier(input.quality) ?? '1K';
15
+ const named = proTier(size);
16
+ if (named)
17
+ return named;
18
+ const pixels = /^(\d+)\s*x\s*(\d+)$/.exec(size.toLowerCase().replace(/\u00d7/g, 'x'));
19
+ return pixels && Number(pixels[1]) * Number(pixels[2]) > SEEDREAM_PRO_2K_PIXELS ? '2K' : '1K';
20
+ }
21
+ /** service/minimax_h3_models.go MiniMaxH3CountInputImages: first frame, last frame and references all count. */
22
+ function inputImageCount(input) {
23
+ const filled = (value) => typeof value === 'string' && value.trim() !== '';
24
+ return ['image_start', 'image_end'].filter(key => filled(input[key])).length
25
+ + (Array.isArray(input.image_urls) ? input.image_urls.filter(filled).length : 0);
26
+ }
27
+ const derived = {
28
+ 'doubao-seedream-5.0-pro output_images_2k': input => seedreamProTier(input) === '2K' ? 1 : 0,
29
+ 'doubao-seedream-5.0-pro output_images_standard': input => seedreamProTier(input) === '2K' ? 0 : 1,
30
+ 'minimax-h3-reference-to-video image_count': inputImageCount,
31
+ 'minimax-h3-max-reference-to-video image_count': inputImageCount,
32
+ // service/tencent_video_upscale.go: the output keeps the source frame rate up to max_fps (120 when unset),
33
+ // so only a 30 fps cap fixes the price tier before the source is measured.
34
+ 'tencent-video-upscale output_fps': (_input, modelParams) => String(modelParams.max_fps).trim() === '30' ? 30 : undefined,
35
+ };
36
+ /** Keys ("model parameter") the generation input decides; a different pricing_parameters value conflicts. */
37
+ export const DERIVED_QUOTE_PARAMETERS = new Set(Object.keys(derived));
38
+ export function derivedQuoteParameter(model, name, input, modelParams) {
39
+ return derived[`${model.toLowerCase()} ${name}`]?.(input, modelParams);
40
+ }
41
+ /** Settings the generation input cannot carry: without measured usage the higher-priced value is quoted. */
42
+ export const CONSERVATIVE_QUOTE_PARAMETERS = {
43
+ // controller/unified_videos.go rejects content_filter on a draft conversion; the draft's own setting is kept.
44
+ 'seedance-2.5-draft-to-video content_filter': { value: false,
45
+ note: 'Assumes the source draft was generated without the content filter (10% more); if it kept the default content_filter=true, pass pricing_parameters.content_filter=true.' },
46
+ };
47
+ /**
48
+ * A documented setting value that stands for the rule's own default. Kling 4.0 video edit documents duration "auto"
49
+ * (as long as the input video); its rule reads duration_seconds 0 as the input length.
50
+ */
51
+ const RULE_DEFAULT_WORDS = { 'kling-v4-video-edit duration_seconds': 'auto' };
52
+ export function isRuleDefaultWord(model, name, value) {
53
+ const word = RULE_DEFAULT_WORDS[`${model.toLowerCase()} ${name}`];
54
+ return word !== undefined && typeof value === 'string' && value.trim().toLowerCase() === word;
55
+ }
56
+ /** Usage the request cannot state: quoting it needs pricing_parameters unless a mapping above fixes it. */
57
+ export function derivedUsage(model, name) {
58
+ return model.toLowerCase() === 'tencent-video-upscale' && name === 'output_fps';
59
+ }
@@ -6,6 +6,8 @@ import { requestAccountQuote } from './api-client.js';
6
6
  import { getPricingRules, PricingMoney } from './pricing-rules-client.js';
7
7
  import { isSeedanceGeneration } from './seedance-input.js';
8
8
  import { searchUsage } from './search-usage.js';
9
+ import { effectiveMjV7EditPrompt } from './mj-prompt.js';
10
+ import { CONSERVATIVE_QUOTE_PARAMETERS, derivedQuoteParameter, derivedUsage, isRuleDefaultWord } from './pricing-derived.js';
9
11
  const decimal = z.string().max(64).regex(/^(?:0|[1-9]\d*)(?:\.\d+)?$/);
10
12
  const identifier = z.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/);
11
13
  const rational = z.string().max(128).regex(/^(?:0|[1-9]\d*)(?:\.\d+|\/[1-9]\d*)?$/);
@@ -51,6 +53,8 @@ function fail(code, message, param) { throw new QuoteError(code, message, param)
51
53
  const aliases = { duration_seconds: ['duration'], output_seconds: ['duration'], image_count: ['n', 'count'],
52
54
  video_count: ['n', 'count'], resolution: ['quality'], quality: ['resolution'] };
53
55
  const measured = /(?:tokens|input_seconds|output_seconds|source_output_seconds|first_input_video_seconds|search_count)$/;
56
+ /** A rule parameter that measures usage (tokens, seconds, searches, a derived rate) rather than a setting. */
57
+ export const isUsageParameter = (model, name) => measured.test(name) || derivedUsage(model, name);
54
58
  /** Map only declared billing parameters. Prompts and asset URLs stay in generation input. */
55
59
  export function prepareQuoteParameters(rule, entry, input, pricingParameters = {}, mediaSeconds, allowMissingUsage = false) {
56
60
  const declared = new Map((rule.parameters ?? []).map(p => [p.name, p]));
@@ -60,17 +64,34 @@ export function prepareQuoteParameters(rule, entry, input, pricingParameters = {
60
64
  }
61
65
  const parameters = {};
62
66
  const searches = searchUsage(entry, input);
67
+ // Midjourney documents speed and upscale type inside model_params. A setting is read there only where the
68
+ // documentation puts it, so another model's model_params never changes its price.
69
+ const nestedSpec = entry.spec?.params.model_params?.properties ?? {};
70
+ const nestedInput = input.model_params && typeof input.model_params === 'object' && !Array.isArray(input.model_params)
71
+ ? input.model_params : {};
72
+ const documented = (key) => entry.spec?.params[key] ?? nestedSpec[key];
73
+ const given = (key) => input[key] !== undefined ? input[key] : nestedSpec[key] ? nestedInput[key] : undefined;
74
+ const model = entry.id ?? '';
75
+ const usage = (key) => isUsageParameter(model, key);
63
76
  for (const [name, p] of declared) {
64
77
  const search = searches.find(item => item.parameter === name);
65
78
  // A declared duration and duration_seconds have different meanings (smart duration).
66
79
  // Video edit's duration=-1 is an operation setting, never expected output seconds.
67
80
  const expectedEditDuration = name === 'duration_seconds' && entry.id === 'seedance-2.5-video-edit' && isSeedanceGeneration(entry);
68
81
  const generationNames = [name, ...(aliases[name] ?? []).filter(alias => !declared.has(alias) && !(expectedEditDuration && alias === 'duration'))];
69
- const supplied = generationNames.filter(key => input[key] !== undefined).map(key => input[key]);
82
+ // A documented word for the rule's own default (Kling 4.0 edit duration "auto") prices as that default.
83
+ const asRule = (value) => isRuleDefaultWord(model, name, value) ? p.default ?? value : value;
84
+ const supplied = generationNames.map(given).filter(value => value !== undefined).map(asRule);
70
85
  if (supplied.some(value => String(value) !== String(supplied[0]))) {
71
86
  fail('conflicting_quote_parameter', `Conflicting generation values for ${name}.`, name);
72
87
  }
73
88
  let value = supplied[0];
89
+ // A promptless Midjourney V7 edit runs and bills as fast whatever speed was requested.
90
+ if (value === undefined && name === 'prompt_present')
91
+ value = typeof input.prompt === 'string' && effectiveMjV7EditPrompt(input.prompt) !== '';
92
+ // Some rule parameters come from differently named request fields, as the gateway pre-deducts them.
93
+ if (value === undefined)
94
+ value = derivedQuoteParameter(model, name, input, nestedInput);
74
95
  if (value === undefined && name === 'input_images') {
75
96
  if (Array.isArray(input.image_urls))
76
97
  value = input.image_urls.length;
@@ -80,9 +101,9 @@ export function prepareQuoteParameters(rule, entry, input, pricingParameters = {
80
101
  value = 0;
81
102
  }
82
103
  // Expected usage cannot change settings or references the model will actually receive.
83
- if (value === undefined && pricingParameters[name] !== undefined && !measured.test(name)
84
- && generationNames.some(key => entry.spec?.params[key] !== undefined)) {
85
- value = generationNames.map(key => entry.spec?.params[key]?.default).find(v => v !== undefined) ?? p.default;
104
+ if (value === undefined && pricingParameters[name] !== undefined && !usage(name)
105
+ && generationNames.some(key => documented(key) !== undefined)) {
106
+ value = asRule(generationNames.map(key => documented(key)?.default).find(v => v !== undefined) ?? p.default);
86
107
  }
87
108
  if (pricingParameters[name] !== undefined) {
88
109
  if (value !== undefined && String(value) !== String(pricingParameters[name])) {
@@ -111,8 +132,8 @@ export function prepareQuoteParameters(rule, entry, input, pricingParameters = {
111
132
  continue;
112
133
  fail('quote_usage_required', `Provide expected generated ${name} in pricing_parameters.`, name);
113
134
  }
114
- if (value === undefined && !measured.test(name)) {
115
- const defaults = generationNames.map(key => entry.spec?.params[key]?.default).filter(v => v !== undefined);
135
+ if (value === undefined && !usage(name)) {
136
+ const defaults = generationNames.map(key => documented(key)?.default).filter(v => v !== undefined).map(asRule);
116
137
  value = defaults[0];
117
138
  }
118
139
  const references = Array.isArray(input.video_urls) && input.video_urls.length > 0
@@ -122,11 +143,13 @@ export function prepareQuoteParameters(rule, entry, input, pricingParameters = {
122
143
  // The rules evaluator separately records the missing actual/expected search count.
123
144
  if (value === undefined && search?.enabled && allowMissingUsage)
124
145
  value = '0';
125
- if (value === undefined && measured.test(name) && (p.required || references || /tokens$/.test(name) || search?.enabled || (name === 'search_count' && input.web_search === true) || p.default === undefined)) {
146
+ if (value === undefined && usage(name) && (p.required || references || /tokens$/.test(name) || search?.enabled || (name === 'search_count' && input.web_search === true) || p.default === undefined)) {
126
147
  if (allowMissingUsage)
127
148
  continue;
128
149
  fail('quote_usage_required', `Provide measured or expected usage for ${name} in pricing_parameters.`, name);
129
150
  }
151
+ if (value === undefined)
152
+ value = CONSERVATIVE_QUOTE_PARAMETERS[`${model.toLowerCase()} ${name}`]?.value;
130
153
  if (value === undefined)
131
154
  value = p.default;
132
155
  if (value === undefined) {
@@ -197,15 +197,49 @@ async function readBody(response) {
197
197
  reader.releaseLock();
198
198
  }
199
199
  }
200
- export async function getPricingRules(input, options = {}) {
201
- const query = PricingRulesQuery.parse(input), base = controlBaseURL();
200
+ function rulesURL(query) {
201
+ const base = controlBaseURL();
202
202
  const url = new URL(query.model ? `${base}/v1/catalog/models/${encodeURIComponent(query.model)}/pricing-rules`
203
203
  : `${base}/v1/catalog/pricing-rules`);
204
204
  for (const key of ['product_id', 'operation', 'modality', 'lifecycle', 'view']) {
205
205
  if (query[key] !== undefined)
206
206
  url.searchParams.set(key, query[key]);
207
207
  }
208
+ return url;
209
+ }
210
+ /** The cached answer to this query while it is still within its cache time; nothing is requested. */
211
+ export function cachedPricingRules(input) {
212
+ const old = cache.get(rulesURL(PricingRulesQuery.parse(input)).href);
213
+ return old && old.expires > Date.now() ? old.body : undefined;
214
+ }
215
+ const stillFresh = (entry) => Date.parse(entry.body.meta.fresh_until) > Date.now();
216
+ /** One model's full rules from the cache: its own entry, else its row in the cached full list. */
217
+ function cachedModel(model, usable) {
218
+ const own = cache.get(rulesURL(PricingRulesQuery.parse({ model, view: 'full' })).href);
219
+ if (own && usable(own))
220
+ return own;
221
+ const list = cache.get(rulesURL(PricingRulesQuery.parse({ view: 'full' })).href);
222
+ const rule = list && usable(list) && 'models' in list.body ? list.body.models.find(item => item.model_id === model) : undefined;
223
+ return list && rule ? { body: { meta: list.body.meta, model: rule }, fetchedAt: list.fetchedAt } : undefined;
224
+ }
225
+ /** One model's full rules read at most maxAgeMs ago, even past their fresh_until: an estimate's fallback while the platform limits requests. */
226
+ export function recentModelRules(model, maxAgeMs) {
227
+ return cachedModel(model, entry => Date.now() - entry.fetchedAt <= maxAgeMs);
228
+ }
229
+ /**
230
+ * `reuseUntilFresh` serves a model's full rules from the cache (its own entry or the full list) until the rules' own
231
+ * fresh_until, which estimates use so a burst of them does not spend the platform's per-IP catalog limit; generation
232
+ * reads `fresh` rules and asks for a new approval when the price moved.
233
+ */
234
+ export async function getPricingRules(input, options = {}) {
235
+ const query = PricingRulesQuery.parse(input), url = rulesURL(query);
208
236
  const key = url.href, old = cache.get(key);
237
+ if (options.reuseUntilFresh) {
238
+ const reusable = query.model && query.view === 'full' && !query.product_id && !query.operation && !query.modality && !query.lifecycle
239
+ ? cachedModel(query.model, stillFresh) : old && stillFresh(old) ? old : undefined;
240
+ if (reusable)
241
+ return { body: reusable.body, source: 'cache' };
242
+ }
209
243
  if (!options.fresh && old && old.expires > Date.now())
210
244
  return { body: old.body, source: 'cache' };
211
245
  const existing = pending.get(key);
@@ -226,6 +260,7 @@ export async function getPricingRules(input, options = {}) {
226
260
  continue;
227
261
  }
228
262
  old.expires = Math.min(Date.now() + CACHE_TTL_MS, Date.parse(old.body.meta.fresh_until));
263
+ old.fetchedAt = Date.now();
229
264
  return { body: old.body, source: 'revalidated' };
230
265
  }
231
266
  if (!response.ok) {
@@ -246,7 +281,7 @@ export async function getPricingRules(input, options = {}) {
246
281
  if (cache.size >= MAX_CACHE_ENTRIES)
247
282
  cache.delete(cache.keys().next().value);
248
283
  cache.set(key, { body, etag: response.headers.get('ETag') ?? undefined,
249
- expires: Math.min(Date.now() + CACHE_TTL_MS, Date.parse(body.meta.fresh_until)) });
284
+ expires: Math.min(Date.now() + CACHE_TTL_MS, Date.parse(body.meta.fresh_until)), fetchedAt: Date.now() });
250
285
  return { body, source: 'live' };
251
286
  }
252
287
  throw new PricingRulesError('expired_pricing_rules');
@@ -1,10 +1,11 @@
1
1
  // Copyright 2024 EvoLink AI. SPDX-License-Identifier: Apache-2.0
2
2
  // Generated from Evolink-AI/evolink-mcp; adapted for direct REST operations. See platform/LICENSE and platform/NOTICE.
3
3
  import { z } from 'zod';
4
- import { getPricingRules } from './pricing-rules-client.js';
5
- import { QuoteError, prepareQuoteParameters, quoteRequestHash } from './pricing-quote-client.js';
4
+ import { PricingRulesError, getPricingRules, recentModelRules } from './pricing-rules-client.js';
5
+ import { QuoteError, isUsageParameter, prepareQuoteParameters, quoteRequestHash } from './pricing-quote-client.js';
6
6
  import { prepareSeedanceInput } from './seedance-input.js';
7
7
  import { searchUsage } from './search-usage.js';
8
+ import { CONSERVATIVE_QUOTE_PARAMETERS } from './pricing-derived.js';
8
9
  /**
9
10
  * How long an approval from estimate_cost may be passed to generate_*. The rules' own
10
11
  * `fresh_until` is a short refresh window (minutes); people confirming a price in a chat
@@ -97,6 +98,58 @@ function checkExpression(node, declared, depth = 0, budget = { nodes: 0 }) {
97
98
  for (const child of node.args ?? [])
98
99
  checkExpression(child, declared, depth + 1, budget);
99
100
  }
101
+ /** Every value an expression reads, so a component short of several usages can name all of them. */
102
+ function variables(node, found) {
103
+ if (!node)
104
+ return;
105
+ if (node.op === 'variable' && node.name)
106
+ found.add(node.name);
107
+ if (node.op === 'lookup')
108
+ variables(node.key, found);
109
+ for (const child of node.args ?? [])
110
+ variables(child, found);
111
+ }
112
+ function componentReads(c) {
113
+ const read = new Set();
114
+ for (const expr of [c.condition, c.quantity_rule, ...c.tiers.map(t => t.when)])
115
+ variables(expr, read);
116
+ return read;
117
+ }
118
+ /** How to give a usage value an estimate lacks, or why only the finished task knows it. */
119
+ function usageHint(name, entry, declared) {
120
+ if (name === 'input_seconds' || name === 'first_input_video_seconds')
121
+ return 'pass the length of the input video or audio, in seconds, as media_seconds.';
122
+ if (name === 'source_output_seconds')
123
+ return `pass the length of the source task's output, in seconds, in pricing_parameters.${name}.`;
124
+ if (name === 'output_seconds' || name === 'duration_seconds') {
125
+ // As prepareQuoteParameters reads it: media_seconds stands for the billed length only where the model takes no duration.
126
+ return entry.spec && !entry.spec.params.duration && !declared.has('duration') && entry.spec.constraints?.outputDuration !== 'unknown'
127
+ ? 'pass the billed length, usually that of the input video or audio, in seconds, as media_seconds.'
128
+ : `the generated length is known only after the task runs; pass an expected length in pricing_parameters.${name} only when the user gives one.`;
129
+ }
130
+ if (name === 'output_fps')
131
+ return `pass the source video's frame rate in pricing_parameters.${name}, or, if a 30 fps output is acceptable, set model_params.max_fps to "30".`;
132
+ if (/search_count$/.test(name))
133
+ return `the number of searches is known only after the task runs; pass an expected count in pricing_parameters.${name} only when the user gives one.`;
134
+ return `pass measured or expected usage in pricing_parameters.${name}.`;
135
+ }
136
+ /** Token usage is known only once the task has run; name the published rates instead. */
137
+ function tokenHelp(names, rule) {
138
+ const unit = (text) => text === '1k_tokens' ? '1K tokens' : text.replace(/_/g, ' ');
139
+ const rates = rule.components.filter(c => names.some(name => componentReads(c).has(name)))
140
+ .map(c => `${c.id} ${c.tiers.length ? 'from ' : ''}$${c.rate.usd} per ${unit(c.unit)}`);
141
+ return `${names.join(', ')}: billed by the tokens the task actually uses, known only after it runs${rates.length ? ` (public default rates: ${rates.join('; ')})` : ''}.`;
142
+ }
143
+ function helpLines(names, entry, rule, declared) {
144
+ const tokens = names.filter(name => /tokens$/.test(name));
145
+ return [...names.filter(name => !tokens.includes(name)).map(name => `${name}: ${usageHint(name, entry, declared)}`),
146
+ ...(tokens.length ? [tokenHelp(tokens, rule)] : [])];
147
+ }
148
+ /** Every usage value a rule can bill by, with how to give it; get_model lists them before any estimate. */
149
+ export function billingUsageHelp(rule, entry) {
150
+ const declared = new Set((rule.parameters ?? []).map(p => p.name));
151
+ return helpLines([...declared].filter(name => isUsageParameter(entry.id, name)).sort(), entry, rule, declared);
152
+ }
100
153
  function evaluate(node, params) {
101
154
  const nodes = node.args ?? [], at = (i) => evaluate(nodes[i], params), number = (i) => numeric(at(i));
102
155
  switch (node.op) {
@@ -220,8 +273,13 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
220
273
  subtotal_uc: String(charge.n), minimum_charge_applied: cmp(subtotal, minimum) < 0 });
221
274
  }
222
275
  catch (error) {
223
- if (error instanceof QuoteError && error.code === 'quote_usage_required' && error.param)
276
+ if (error instanceof QuoteError && error.code === 'quote_usage_required' && error.param) {
224
277
  missing.add(error.param);
278
+ // The evaluator stops at the first absent usage; name every one this component reads.
279
+ for (const name of componentReads(c))
280
+ if (!Object.hasOwn(params, name))
281
+ missing.add(name);
282
+ }
225
283
  else
226
284
  throw error;
227
285
  }
@@ -233,12 +291,24 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
233
291
  request_hash: requestHash, total_uc: amounts.uc, expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
234
292
  fingerprint: quoteRequestHash(entry.id, { rules: economicRules(rule), parameters: params,
235
293
  exchange_rate_version: body.meta.exchange_rate_version, components, missing: [...missing].sort(), total_uc: amounts.uc }) };
236
- const estimate = { status: missing.size ? components.length ? 'partial' : 'needs_input' : 'estimated', min_usd: Number(amounts.usd), max_usd: Number(amounts.usd),
237
- min_credits: Number(amounts.credits), max_credits: Number(amounts.credits),
294
+ const status = missing.size ? components.length ? 'partial' : 'needs_input' : 'estimated';
295
+ const missingUsage = [...missing].sort(), usageHelp = helpLines(missingUsage, entry, rule, declared);
296
+ const estimate = { status,
297
+ // Nothing could be priced: a zero amount would read as free.
298
+ ...(status === 'needs_input' ? {} : { min_usd: Number(amounts.usd), max_usd: Number(amounts.usd),
299
+ min_credits: Number(amounts.credits), max_credits: Number(amounts.credits) }),
300
+ total_known: status === 'estimated',
238
301
  basis: ['Published full pricing rules evaluated for the supplied generation parameters; exact UC rounding and component minimums.'],
239
- ...(missing.size ? { uncheckable_reason: 'usage' } : {}),
240
- possible_extras: [...missing].map(name => `Additional charge depends on ${name}; supply expected or measured usage in pricing_parameters.`), notes: ['Public default prices; account discounts are not included.',
241
- 'Confirm the estimated cost before generation. Actual billed usage and final charges may differ.'] };
302
+ ...(missing.size ? { uncheckable_reason: 'usage', missing_usage: missingUsage, usage_help: usageHelp } : {}),
303
+ possible_extras: status === 'partial' ? usageHelp.map(line => `Additional charge depends on ${line}`) : [],
304
+ notes: ['Public default prices; account discounts are not included.', status === 'needs_input'
305
+ ? 'No total is quoted until the missing usage is known, and generate_* will not submit before then.'
306
+ : 'Confirm the estimated cost before generation. Actual billed usage and final charges may differ.'] };
307
+ for (const p of rule.parameters ?? []) {
308
+ const assumed = CONSERVATIVE_QUOTE_PARAMETERS[`${entry.id.toLowerCase()} ${p.name}`];
309
+ if (assumed && options.pricingParameters?.[p.name] === undefined)
310
+ estimate.notes.push(assumed.note);
311
+ }
242
312
  if (searchCharges.length) {
243
313
  estimate.search_charges = searchCharges;
244
314
  for (const search of searchCharges) {
@@ -251,9 +321,57 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
251
321
  }
252
322
  return { approval, estimate, amounts, components, parameters: params, rule };
253
323
  }
324
+ /** While the platform limits pricing requests, an estimate may use rules read this recently; generation never does. */
325
+ export const RECENT_RULES_MAX_AGE_MS = 10 * 60_000;
326
+ /** The longest Retry-After a generation waits, once, before its fresh rules read gives up. */
327
+ export const GENERATION_RULES_RETRY_MAX_SECONDS = 5;
328
+ const limited = (error) => error instanceof PricingRulesError && error.code === 'rate_limit_exceeded';
329
+ function pause(ms, signal) {
330
+ return new Promise(resolve => {
331
+ const timer = setTimeout(done, ms);
332
+ function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
333
+ signal?.addEventListener('abort', done, { once: true });
334
+ if (signal?.aborted)
335
+ done();
336
+ });
337
+ }
338
+ async function generationRules(model, signal) {
339
+ try {
340
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
341
+ }
342
+ catch (error) {
343
+ const wait = limited(error) ? error.retryAfter ?? 1 : undefined;
344
+ if (wait === undefined || wait > GENERATION_RULES_RETRY_MAX_SECONDS || signal?.aborted)
345
+ throw error;
346
+ await pause(wait * 1000, signal);
347
+ if (signal?.aborted)
348
+ throw error;
349
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
350
+ }
351
+ }
352
+ /**
353
+ * Generation reads the rules fresh. A hosted estimate (`reuseRules`) reuses them until their fresh_until and, while
354
+ * the platform limits requests, may use rules read in the last 10 minutes; any other estimate reads them fresh. An
355
+ * approval from cached or recent rules can never submit at a changed price: checkRulesApproval refuses it.
356
+ */
254
357
  export async function createRulesEstimate(entry, input, options = {}) {
255
- const { body } = await getPricingRules({ model: entry.id.toLowerCase(), view: 'full' }, { fresh: true });
256
- return calculateRulesEstimate(body, entry, input, options);
358
+ const model = entry.id.toLowerCase();
359
+ if (options.purpose === 'generation')
360
+ return calculateRulesEstimate(await generationRules(model, options.signal), entry, input, options);
361
+ if (!options.reuseRules)
362
+ return calculateRulesEstimate((await getPricingRules({ model, view: 'full' }, { fresh: true })).body, entry, input, options);
363
+ try {
364
+ const { body } = await getPricingRules({ model, view: 'full' }, { reuseUntilFresh: true });
365
+ return calculateRulesEstimate(body, entry, input, options);
366
+ }
367
+ catch (error) {
368
+ const recent = limited(error) ? recentModelRules(model, RECENT_RULES_MAX_AGE_MS) : undefined;
369
+ if (!recent)
370
+ throw error;
371
+ const result = calculateRulesEstimate(recent.body, entry, input, options), readAt = new Date(recent.fetchedAt).toISOString();
372
+ result.estimate.notes.push(`The platform is limiting pricing requests right now, so this estimate uses the published rules read at ${readAt}. generate_* reads the current rules again before submitting and asks for a new approval if the price changed.`);
373
+ return { ...result, rules_read_at: readAt };
374
+ }
257
375
  }
258
376
  export function checkRulesApproval(approval, fresh) {
259
377
  if (Date.parse(approval.expires_at) <= Date.now())
@@ -12,7 +12,8 @@ import { prepareSeedanceInput } from '../services/seedance-input.js';
12
12
  import { API_KEYS_URL, MCP_CONSOLE_URL, MCP_KEY_NAME, TOP_UP_URL } from '../services/http-policy.js';
13
13
  import { trackedLink } from '../services/utm.js';
14
14
  import { currentCredentialMode } from '../request-context.js';
15
- import { MEDIA_SECONDS_DESCRIPTION, MEDIA_SECONDS_MAX, READ_ONLY, dailyLimitOf, errorResult, failure, money, ok } from './shared.js';
15
+ import { MEDIA_SECONDS_DESCRIPTION, MEDIA_SECONDS_MAX, READ_ONLY, dailyLimitOf, errorResult, failure, money, ok, retryText } from './shared.js';
16
+ import { pricingCallLimitReached } from '../services/pricing-call-limit.js';
16
17
  export function registerEstimateCost(server, config) {
17
18
  server.registerTool('estimate_cost', {
18
19
  title: 'Estimate cost',
@@ -23,7 +24,7 @@ export function registerEstimateCost(server, config) {
23
24
  ].join(' '),
24
25
  inputSchema: {
25
26
  model: z.string().min(1).max(128).describe('Model ID, e.g. "seedance-2.0-text-to-video".'),
26
- input: z.record(z.unknown()).optional()
27
+ input: z.record(z.string(), z.unknown()).optional()
27
28
  .describe('The input you plan to pass to the generate tool, e.g. {"prompt":"…","duration":5,"quality":"1080p"}.'),
28
29
  pricing_source: z.enum(['pricing_rules', 'account', 'public_reference']).default('pricing_rules').describe('Use published full pricing rules for public default estimates. The old account/public_reference values are compatibility aliases; neither requests a backend account quote.'),
29
30
  pricing_parameters: QuoteParameters.optional().describe('Measured or explicitly expected usage declared by the pricing policy, such as input_seconds or search_count. Missing enabled-search counts produce a zero-search partial subtotal and per-search rates. Do not invent counts, include user_group/prices/prompts, or treat expected counts as execution limits.'),
@@ -31,6 +32,12 @@ export function registerEstimateCost(server, config) {
31
32
  },
32
33
  annotations: { title: 'Estimate cost', ...READ_ONLY },
33
34
  }, async ({ model, input, media_seconds: mediaSeconds, pricing_source: pricingSource, pricing_parameters: pricingParameters }) => {
35
+ const over = pricingCallLimitReached('estimate_cost');
36
+ if (over)
37
+ return failure(`This account already made ${over.limit} estimate_cost calls in the last minute, the most allowed. Wait ${retryText(over.retryAfterSeconds)}, then estimate again. Nothing was submitted or charged.`, {
38
+ error: { category: 'rate_limited', code: 'pricing_calls_per_minute', retry_after_seconds: over.retryAfterSeconds },
39
+ pricing_source: pricingSource, submission_allowed: false, final_budget_enforced: false, charged: 'no'
40
+ });
34
41
  try {
35
42
  const { catalog, entry } = await resolveModel(model, config, { fresh: true, allowStale: false, skipPricing: true });
36
43
  if (!entry) {
@@ -44,7 +51,7 @@ export function registerEstimateCost(server, config) {
44
51
  validation?.warnings.push(...prepared.warnings);
45
52
  if (validation?.errors.length)
46
53
  return failure('The generation input is invalid; no estimate was created.', { input_valid: false, problems: validation.errors, error: { category: 'invalid_request' }, charged: 'no' });
47
- const rulesEstimate = await createRulesEstimate(entry, values, { mediaSeconds, pricingParameters });
54
+ const rulesEstimate = await createRulesEstimate(entry, values, { mediaSeconds, pricingParameters, reuseRules: config.reusePricingRules === true });
48
55
  const estimate = rulesEstimate.estimate;
49
56
  const lines = [`Estimate for ${entry.id} (${entry.kind}); nothing was submitted or charged.`];
50
57
  if (!validation) {
@@ -68,7 +75,7 @@ export function registerEstimateCost(server, config) {
68
75
  else if (estimate.status === 'token_billed')
69
76
  lines.push('Cost: billed by tokens used; it is only known after the task runs.');
70
77
  else if (estimate.status === 'needs_input')
71
- lines.push('Cost: cannot estimate yet; see the note below.');
78
+ lines.push('Cost: cannot estimate yet. The total depends on usage this request does not give:', ...(estimate.usage_help ?? []).map(line => `- ${line}`));
72
79
  else if (estimate.uncheckable_reason === 'output_duration')
73
80
  lines.push('Cost: the output duration is unknown, so there is no total or upper bound to quote.');
74
81
  else
@@ -79,19 +86,23 @@ export function registerEstimateCost(server, config) {
79
86
  lines.push('May also charge:', ...estimate.possible_extras.map(line => `- ${line}`));
80
87
  for (const note of estimate.notes)
81
88
  lines.push(`Note: ${note}`);
89
+ // Without any priced component there is no total to show or approve: no amounts and no approval record.
90
+ const priced = estimate.status !== 'needs_input';
82
91
  const structured = {
83
92
  model: entry.id,
84
93
  type: entry.kind,
85
94
  pricing_scope: 'public_default',
86
95
  pricing_source: 'pricing_rules',
87
- pricing_quote: rulesEstimate.approval,
88
- amounts: rulesEstimate.amounts,
96
+ ...(priced ? { pricing_quote: rulesEstimate.approval, amounts: rulesEstimate.amounts } : { submission_allowed: false }),
97
+ total_known: estimate.total_known === true,
98
+ ...(estimate.missing_usage ? { missing_usage: estimate.missing_usage } : {}),
89
99
  components: rulesEstimate.components,
90
100
  pricing_parameters: rulesEstimate.parameters,
91
101
  policy_version: rulesEstimate.rule.policy_version,
92
102
  policy_checksum: rulesEstimate.rule.policy_checksum,
93
103
  settlement_basis: rulesEstimate.rule.settlement_basis,
94
- expires_at: rulesEstimate.approval.expires_at,
104
+ ...(priced ? { expires_at: rulesEstimate.approval.expires_at } : {}),
105
+ ...('rules_read_at' in rulesEstimate ? { rules_read_at: rulesEstimate.rules_read_at } : {}),
95
106
  final_budget_enforced: false,
96
107
  input_valid: validation ? validation.errors.length === 0 : null,
97
108
  problems: validation?.errors ?? [],
@@ -149,13 +160,18 @@ export function registerEstimateCost(server, config) {
149
160
  catch {
150
161
  lines.push('Balance: could not be read right now.');
151
162
  }
152
- lines.push(`Estimate valid until ${rulesEstimate.approval.expires_at}.`, 'Public default estimate; account discounts are not included. Confirm this estimated cost before generation. Final charges depend on actual usage.');
163
+ if (priced)
164
+ lines.push(`Estimate valid until ${rulesEstimate.approval.expires_at}.`, 'Public default estimate; account discounts are not included. Confirm this estimated cost before generation. Final charges depend on actual usage.');
165
+ else
166
+ lines.push('No total or approval record was issued. Estimate again with the missing usage before asking the user to approve a generation.');
153
167
  return ok(lines.join('\n'), structured);
154
168
  }
155
169
  catch (error) {
156
170
  if (error instanceof PricingRulesError)
157
- return failure('The model pricing rules could not be verified. No estimate or generation was created.', {
158
- error: { category: 'estimate_unavailable', code: error.code, status: error.status }, pricing_source: pricingSource,
171
+ return failure(error.code === 'rate_limit_exceeded'
172
+ ? `The platform is limiting pricing requests right now, so no estimate was created. Try again in ${retryText(error.retryAfter)}. Nothing was submitted or charged.`
173
+ : 'The model pricing rules could not be verified. No estimate or generation was created.', {
174
+ error: { category: 'estimate_unavailable', code: error.code, status: error.status, ...(error.retryAfter !== undefined ? { retry_after_seconds: error.retryAfter } : {}) }, pricing_source: pricingSource,
159
175
  submission_allowed: false, final_budget_enforced: false, charged: 'no'
160
176
  });
161
177
  if (error instanceof QuoteError)