@evolinkai/cli 0.12.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.
@@ -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)
@@ -10,7 +10,7 @@ import { ApprovedRulesEstimate, createRulesEstimate, checkRulesApproval, rulesBu
10
10
  import { PricingRulesError } from '../services/pricing-rules-client.js';
11
11
  import { CLIENT_REQUEST_ID_PATTERN, monotonicNow, newRunId, remainingMs } from '../services/http-policy.js';
12
12
  import { formatUsd } from '../services/error-handler.js';
13
- import { MEDIA_SECONDS_DESCRIPTION, MEDIA_SECONDS_MAX, PAID, errorResult, failure, money, ok, progressReporter, usdOf } from './shared.js';
13
+ import { MEDIA_SECONDS_DESCRIPTION, MEDIA_SECONDS_MAX, PAID, errorResult, failure, money, ok, progressReporter, retryText, usdOf } from './shared.js';
14
14
  import { RESULT_DELIVERY_GUIDANCE, TERMINAL_STATUSES, describeTask, waitForTask } from './task-format.js';
15
15
  import { PAID_GENERATION_GUIDANCE } from '../tool-guidance.js';
16
16
  import { currentRequestCredentials } from '../request-context.js';
@@ -51,7 +51,7 @@ function rangeText(estimate) {
51
51
  /** Why max_cost_usd could not be checked, and what the assistant can do next. */
52
52
  function uncheckedCap(estimate, pricingWarning) {
53
53
  if (estimate.uncheckable_reason === 'usage')
54
- return ['published pricing rules need additional billing usage to calculate a complete estimate', `Provide the missing expected or measured usage in pricing_parameters. ${estimate.possible_extras.join(' ')}`];
54
+ return ['published pricing rules need additional billing usage to calculate a complete estimate', `Provide the missing expected or measured usage. ${(estimate.usage_help ?? estimate.possible_extras).join(' ')}`];
55
55
  if (estimate.uncheckable_reason === 'output_duration') {
56
56
  return ['the generated output duration is not fixed, so the declared seconds cannot establish an upper bound', 'Use an explicit duration if the model accepts it; otherwise ask the user whether to proceed without a cap.'];
57
57
  }
@@ -91,7 +91,7 @@ function registerGenerate(server, config, kind) {
91
91
  model: z.string().min(1).max(128).describe(`${kind[0].toUpperCase()}${kind.slice(1)} model ID from search_models.`),
92
92
  // The cap is checked in the handler: a schema limit makes the SDK answer with a bare validation error.
93
93
  prompt: z.string().optional().describe(`Shortcut for input.prompt; up to ${PROMPT_SHORTCUT_MAX.toLocaleString('en-US')} characters (get_model lists the model's own limit).`),
94
- input: z.record(z.unknown()).optional()
94
+ input: z.record(z.string(), z.unknown()).optional()
95
95
  .describe('Model parameters exactly as listed by get_model, e.g. {"prompt":"…","quality":"1080p"}. Do not put model or callback_url here.'),
96
96
  client_request_id: z.string().regex(CLIENT_REQUEST_ID_PATTERN).optional()
97
97
  .describe('Optional idempotency key (16–96 characters: letters, digits, . _ -). Reuse the same value only to retry the same request after a network error or timeout.'),
@@ -165,7 +165,8 @@ function registerGenerate(server, config, kind) {
165
165
  // media_seconds only prices the request; the body below is built from input alone.
166
166
  if (args.account_quote)
167
167
  throw new QuoteError('quote_refresh_required', 'Refresh the legacy account estimate with estimate_cost and obtain user approval.');
168
- const rulesEstimate = await createRulesEstimate(entry, effectiveInput, { mediaSeconds: args.media_seconds, pricingParameters: args.pricing_parameters });
168
+ const rulesEstimate = await createRulesEstimate(entry, effectiveInput, { mediaSeconds: args.media_seconds, pricingParameters: args.pricing_parameters,
169
+ purpose: 'generation', signal: extra.signal });
169
170
  if (args.pricing_quote)
170
171
  checkRulesApproval(args.pricing_quote, rulesEstimate);
171
172
  const estimate = rulesEstimate.estimate;
@@ -186,8 +187,14 @@ function registerGenerate(server, config, kind) {
186
187
  });
187
188
  }
188
189
  }
189
- if (estimate.status === 'needs_input')
190
- throw new QuoteError('quote_usage_required', 'No charge can be estimated yet; supply the missing pricing usage before submission.');
190
+ if (estimate.status === 'needs_input') {
191
+ return failure([`No total can be estimated for ${entry.id} yet, so nothing was submitted or charged. The total depends on:`,
192
+ ...(estimate.usage_help ?? []).map(line => `- ${line}`),
193
+ 'Estimate again with this usage and get the user\'s approval before generating.'].join('\n'), {
194
+ error: { category: 'estimate_unavailable', code: 'quote_usage_required' },
195
+ missing_usage: estimate.missing_usage, usage_help: estimate.usage_help, charged: 'no', submission_state: 'not_submitted'
196
+ });
197
+ }
191
198
  clientRequestId = args.client_request_id ?? newRunId();
192
199
  const body = { ...effectiveInput, model: entry.id };
193
200
  const submitted = await submitTask(config, {
@@ -269,7 +276,12 @@ function registerGenerate(server, config, kind) {
269
276
  }
270
277
  catch (error) {
271
278
  if (error instanceof PricingRulesError)
272
- return failure('The pricing rules could not be verified. Nothing was submitted or charged.', { error: { category: 'estimate_unavailable', code: error.code }, charged: 'no', submission_state: 'not_submitted' });
279
+ return failure(error.code === 'rate_limit_exceeded'
280
+ ? `The platform is limiting pricing requests right now, so the price could not be checked and nothing was submitted or charged. Try again in ${retryText(error.retryAfter)}.`
281
+ : 'The pricing rules could not be verified. Nothing was submitted or charged.', {
282
+ error: { category: 'estimate_unavailable', code: error.code, ...(error.retryAfter !== undefined ? { retry_after_seconds: error.retryAfter } : {}) },
283
+ charged: 'no', submission_state: 'not_submitted'
284
+ });
273
285
  if (error instanceof QuoteError)
274
286
  return failure(`${error.message} Nothing was submitted or charged.`, { error: { category: 'estimate_unavailable', code: error.code }, charged: 'no', submission_state: 'not_submitted' });
275
287
  // clientRequestId is set right before the submit, so it also tells whether a request may have gone out.
@@ -4,6 +4,8 @@ import { z } from 'zod';
4
4
  import { modelParamsMeta } from '../data/model-params.js';
5
5
  import { resolveModel, suggestModels } from '../services/model-catalog.js';
6
6
  import { billedByMediaLength, formatPrice } from '../services/pricing-client.js';
7
+ import { cachedPricingRules } from '../services/pricing-rules-client.js';
8
+ import { billingUsageHelp } from '../services/pricing-rules-estimate.js';
7
9
  import { formatUsd } from '../services/error-handler.js';
8
10
  import { trackedLink } from '../services/utm.js';
9
11
  import { READ_ONLY, errorResult, failure, ok } from './shared.js';
@@ -37,6 +39,15 @@ export function describeParam(name, spec, indent = '') {
37
39
  }
38
40
  return lines;
39
41
  }
42
+ /**
43
+ * The rules name the usage a total needs. Only the full list the catalog has just cached for the prices is read, so
44
+ * get_model asks the platform for nothing more; without it, estimate_cost still reports missing usage itself.
45
+ */
46
+ function billingUsage(entry) {
47
+ const body = cachedPricingRules({ view: 'full' });
48
+ const rule = body && 'models' in body ? body.models.find(model => model.model_id === entry.id.toLowerCase()) : undefined;
49
+ return rule?.policy_source === 'published' && rule.pricing_status === 'available' ? billingUsageHelp(rule, entry) : [];
50
+ }
40
51
  function priceLine(price) {
41
52
  const minimum = price.min_charge_usd !== undefined ? ` (minimum $${formatUsd(price.min_charge_usd)} per task)` : '';
42
53
  const factors = price.multipliers ? ` (resolution factors ${Object.entries(price.multipliers).map(([k, v]) => `${k} ×${v}`).join(', ')})` : '';
@@ -142,6 +153,11 @@ export function registerGetModel(server, config) {
142
153
  else {
143
154
  lines.push(catalog.pricingWarning ?? 'Pricing data is unavailable in this catalog.');
144
155
  }
156
+ const usage = billingUsage(entry);
157
+ if (usage.length) {
158
+ lines.push('Billing usage (estimate_cost needs these for a total and names any that are missing):', ...usage.map(line => `- ${line}`));
159
+ structured.billing_usage = usage;
160
+ }
145
161
  if (catalog.pricingWarning)
146
162
  structured.pricing_warning = catalog.pricingWarning;
147
163
  return ok(lines.join('\n'), structured);
@@ -3,16 +3,24 @@
3
3
  import { currentRequestCredentials } from '../request-context.js';
4
4
  import { RequestTimeoutError } from '../services/http-policy.js';
5
5
  import { getPricingRules, PricingRulesError, PricingRulesQuery } from '../services/pricing-rules-client.js';
6
- import { failure, ok, READ_ONLY } from './shared.js';
7
- export function registerPricingRules(server) {
6
+ import { pricingCallLimitReached } from '../services/pricing-call-limit.js';
7
+ import { failure, ok, READ_ONLY, retryText } from './shared.js';
8
+ export function registerPricingRules(server, config) {
8
9
  server.registerTool('get_pricing_rules', {
9
10
  title: 'Read public pricing rules',
10
11
  description: 'Read schema-2 public default pricing rules, decimal-string rates including fractional UC, minimum charges, tiers and optional full expressions. Free and anonymous upstream. The returned price_selection, when present, identifies route-priority prices or legacy minimum configuration prices. Coverage follows the returned published policies and supported legacy text adapters, including media when available. These are public reference rates, not account prices, live availability, a task quote, a bill or a final spending cap. Do not substitute these rules for media estimate_cost or assume empty media results are free.',
11
12
  inputSchema: PricingRulesQuery.shape,
12
13
  annotations: { title: 'Read public pricing rules', ...READ_ONLY },
13
14
  }, async (input) => {
15
+ const over = pricingCallLimitReached('get_pricing_rules');
16
+ if (over)
17
+ return failure(`This account already made ${over.limit} get_pricing_rules calls in the last minute, the most allowed. Wait ${retryText(over.retryAfterSeconds)}, then try again. No quote or spending limit was established.`, {
18
+ error: { category: 'rate_limited', code: 'pricing_calls_per_minute', retryable: true, retry_after: over.retryAfterSeconds },
19
+ charged: 'no', quote_established: false, final_budget_enforced: false
20
+ });
14
21
  try {
15
- const { body, source } = await getPricingRules(input);
22
+ // Hosted: rules stay valid until their own fresh_until, and a burst of lookups must not spend the shared per-IP limit.
23
+ const { body, source } = await getPricingRules(input, config.reusePricingRules ? { reuseUntilFresh: true } : {});
16
24
  const models = 'model' in body ? [body.model] : body.models;
17
25
  const selection = body.meta.price_selection ?? 'configured_minimum';
18
26
  const warnings = [
@@ -46,7 +54,8 @@ export function registerPricingRules(server) {
46
54
  return failure(safeError.status === 404
47
55
  ? 'No public pricing rules are published for this model and filters. This does not mean the model is free or unavailable.'
48
56
  : safeError.code === 'interrupted' ? 'Public pricing rules lookup was interrupted. No quote or spending limit was established.'
49
- : safeError.message, { error: { category: safeError.code === 'interrupted' ? 'interrupted'
57
+ : safeError.code === 'rate_limit_exceeded' ? `The platform is limiting pricing requests right now. Try again in ${retryText(safeError.retryAfter)}. No quote or spending limit was established.`
58
+ : safeError.message, { error: { category: safeError.code === 'interrupted' ? 'interrupted'
50
59
  : safeError.status === 404 ? 'not_found' : safeError.status === 429 ? 'rate_limit' : 'server_error',
51
60
  code: safeError.code, status: safeError.status,
52
61
  retryable: safeError.status === 429 || safeError.status >= 500
@@ -7,9 +7,12 @@ import { trackedLink } from '../services/utm.js';
7
7
  import { MODEL_SELECTION_GUIDANCE, modelPreference } from '../services/model-recommendations.js';
8
8
  import { referenceInputs } from '../services/model-capabilities.js';
9
9
  import { READ_ONLY, errorResult, ok } from './shared.js';
10
+ // Assistant-facing text is English by default; a catalog name in Chinese, Japanese or Korean is left out and the ID shown.
11
+ const CJK = /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af\uff00-\uffef]/;
12
+ const english = (text) => text && !CJK.test(text) ? text : undefined;
10
13
  export function modelTitle(entry) {
11
14
  const title = entry.spec?.title?.replace(/\s+(interface|api)$/i, '').trim();
12
- return title || entry.title || entry.priced?.description?.slice(0, 120) || undefined;
15
+ return title || english(entry.title) || english(entry.priced?.description?.slice(0, 120)) || undefined;
13
16
  }
14
17
  /** Every term must appear somewhere; matches in the model ID count most. */
15
18
  export function scoreModel(entry, terms) {
@@ -171,6 +171,10 @@ export function progressReporter(extra, totalSeconds) {
171
171
  }).catch(() => undefined);
172
172
  };
173
173
  }
174
+ /** "N seconds" from a Retry-After, or about a minute (the platform's limit window) when it gave none. */
175
+ export function retryText(seconds) {
176
+ return seconds === undefined ? 'about a minute' : `${seconds} second${seconds === 1 ? '' : 's'}`;
177
+ }
174
178
  export function sleep(ms, signal) {
175
179
  return new Promise(resolve => {
176
180
  if (signal?.aborted) {
@@ -1,4 +1,4 @@
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
  /** Version reported in serverInfo and in the X-Evo-Client-Version header. */
4
- export const MCP_VERSION = '1.10.0';
4
+ export const MCP_VERSION = '1.11.0';