@vxil/sdk 0.37.1 → 0.38.1
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/dist/index.d.ts +91 -16
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -483,13 +483,16 @@ export interface UsageCurrent {
|
|
|
483
483
|
requests: {
|
|
484
484
|
/** requests recorded this month (0 until the meter has rows). */
|
|
485
485
|
used: number;
|
|
486
|
-
/** the plan's
|
|
486
|
+
/** the plan's daily API-call cap × 30 (a month's worth, kept for older
|
|
487
|
+
* clients); null = no fixed cap. The enforced limit is daily, on every
|
|
488
|
+
* plan: the `api_calls` lane of `daily_caps` (429 daily_limit_reached
|
|
489
|
+
* past it until 00:00 UTC). */
|
|
487
490
|
quota: number | null;
|
|
488
491
|
/** max(quota − used, 0); null when quota is null. */
|
|
489
492
|
remaining: number | null;
|
|
490
|
-
/** the PLAN's hard-cap policy — true only on the free tier
|
|
491
|
-
*
|
|
492
|
-
*
|
|
493
|
+
/** the PLAN's hard-cap policy flag — true only on the free tier. Not a
|
|
494
|
+
* live "the next request will 429" signal: every plan refuses calls past
|
|
495
|
+
* its daily limit, and no plan is ever billed for overage. */
|
|
493
496
|
enforced: boolean;
|
|
494
497
|
};
|
|
495
498
|
/** month-to-date per-feature metered detail. Aggregated periodically — it
|
|
@@ -1519,6 +1522,12 @@ export interface AiUsage {
|
|
|
1519
1522
|
* need no adjustment — these are for your own visibility. */
|
|
1520
1523
|
cache_creation_input_tokens?: number;
|
|
1521
1524
|
cache_read_input_tokens?: number;
|
|
1525
|
+
/** Thinking / reasoning tokens, present only when the provider reports them
|
|
1526
|
+
* (Gemini, and Anthropic when it sends a breakdown). Already INSIDE
|
|
1527
|
+
* `output_tokens` — a breakdown, never added again. Like the cache counts,
|
|
1528
|
+
* these are on the generation record and the `?since=` usage frame too, and
|
|
1529
|
+
* never change metering. */
|
|
1530
|
+
thinking_tokens?: number;
|
|
1522
1531
|
}
|
|
1523
1532
|
/** One tool invocation the model asked for (tool-use passthrough — vxil relays,
|
|
1524
1533
|
* YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
|
|
@@ -1541,6 +1550,13 @@ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
|
|
|
1541
1550
|
* with `ai.templates.put`) → `features.ai.defaults.mediaResolution` → the
|
|
1542
1551
|
* model's own default. */
|
|
1543
1552
|
export type AiMediaResolution = 'low' | 'medium' | 'high';
|
|
1553
|
+
/** Anthropic effort for `ai.generate` / `stream` / `generateAsync` (`effort`):
|
|
1554
|
+
* how much the model thinks and spends before it answers. Sent to Anthropic
|
|
1555
|
+
* only, as `output_config.effort` — every other provider ignores it; omitted →
|
|
1556
|
+
* `features.ai.defaults.effort` → the model's own default. A level a model does
|
|
1557
|
+
* not accept is the provider's own error. Thinking tokens are billed as output
|
|
1558
|
+
* tokens. Never derived from `thinking_level`. */
|
|
1559
|
+
export type AiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
1544
1560
|
/** A prior conversation turn for the tool-calling round-trip: assistant turns
|
|
1545
1561
|
* carry the tool_calls they made; `role:'tool'` turns carry one call's result
|
|
1546
1562
|
* (`tool_call_id` correlates it; `name` is the tool's name). */
|
|
@@ -1582,8 +1598,9 @@ export interface AiStreamHandle {
|
|
|
1582
1598
|
/** Frames delivered over the ai-<generation_id> realtime channel and the
|
|
1583
1599
|
* ?since= replay buffer (the WS envelope is { event, data } — `event` is the
|
|
1584
1600
|
* frame type; replayed frames carry it as `type`). `title` arrives early when
|
|
1585
|
-
* the stream was requested with title/title_template;
|
|
1586
|
-
* frame carries done:true
|
|
1601
|
+
* the stream was requested with title/title_template; the terminal frame —
|
|
1602
|
+
* usage, or the error frame — carries done:true, so narrow a usage frame with
|
|
1603
|
+
* `'usage' in frame`, not `frame.done`. */
|
|
1587
1604
|
export type AiStreamFrame = {
|
|
1588
1605
|
type?: 'token';
|
|
1589
1606
|
seq: number;
|
|
@@ -1596,10 +1613,38 @@ export type AiStreamFrame = {
|
|
|
1596
1613
|
type?: 'usage';
|
|
1597
1614
|
seq: number;
|
|
1598
1615
|
done: true;
|
|
1616
|
+
/** the provider's own finish word (only `tool_use` is normalised), or
|
|
1617
|
+
* `schema_mismatch` when a structured answer failed its schema */
|
|
1599
1618
|
finish: string;
|
|
1600
1619
|
usage: AiUsage;
|
|
1601
1620
|
tool_calls?: AiToolCall[];
|
|
1621
|
+
/** the structured-output repair fixed the answer */
|
|
1622
|
+
repaired?: boolean;
|
|
1623
|
+
/** the stored answer was cut at 262,144 characters (vxil's storage cut,
|
|
1624
|
+
* not a token cut) */
|
|
1625
|
+
truncated?: boolean;
|
|
1626
|
+
}
|
|
1627
|
+
/** The terminal failure frame. Live on `ai-<generation_id>`: `{ done,
|
|
1628
|
+
* message }` from a stream, `{ seq: 1, done, message, error_class }` from a
|
|
1629
|
+
* job-lane run — never a hint. Replayed by `?since=` for a failed job-lane
|
|
1630
|
+
* generation, with `hint` (the provider's own error text, up to 200
|
|
1631
|
+
* characters) for API-key callers only — never for an end-user session. */
|
|
1632
|
+
| {
|
|
1633
|
+
type?: 'error';
|
|
1634
|
+
seq?: number;
|
|
1635
|
+
done: true;
|
|
1636
|
+
message: string;
|
|
1637
|
+
error_class?: string | null;
|
|
1638
|
+
hint?: string;
|
|
1602
1639
|
};
|
|
1640
|
+
/** The request's `repair` (`ai.generate` / `generateAsync`, with a response
|
|
1641
|
+
* schema): `false` = no repair call — an invalid answer is
|
|
1642
|
+
* `output_schema_mismatch` after ONE call. Omitted / `true` = one repair call
|
|
1643
|
+
* when it can help; never after a refusal, a safety stop, a length cut or an
|
|
1644
|
+
* empty answer, which keep the provider's own finish word (`refusal`,
|
|
1645
|
+
* `max_tokens`, `MAX_TOKENS`, `length`, `content_filter`, …) on the record
|
|
1646
|
+
* and the frame, and in the sync 422's `details.finish`. */
|
|
1647
|
+
export type AiRepair = boolean;
|
|
1603
1648
|
/** The live-only `token_expiring` event (never seq'd, never replayed): fired
|
|
1604
1649
|
* ~30s before each 300s connect-token window ends on a long stream. Re-mint
|
|
1605
1650
|
* via ai.remintToken() and reconnect with ?since=<last seen seq>. */
|
|
@@ -1649,13 +1694,20 @@ export interface AiGenerationRecord {
|
|
|
1649
1694
|
provider: string;
|
|
1650
1695
|
model: string;
|
|
1651
1696
|
template: string | null;
|
|
1652
|
-
|
|
1653
|
-
|
|
1654
|
-
|
|
1655
|
-
|
|
1697
|
+
/** input / output, plus `cache_creation_input_tokens`,
|
|
1698
|
+
* `cache_read_input_tokens` and `thinking_tokens` when Anthropic or
|
|
1699
|
+
* Gemini report them (cache counts: Anthropic; thinking: either; absent
|
|
1700
|
+
* otherwise, never 0) — summed over the first call and the repair */
|
|
1701
|
+
usage: AiUsage;
|
|
1656
1702
|
cached: boolean;
|
|
1703
|
+
/** the structured-output repair call fixed the answer (optional: a server
|
|
1704
|
+
* before 2026-11 does not send it) */
|
|
1705
|
+
repaired?: boolean;
|
|
1657
1706
|
created_at: string;
|
|
1658
1707
|
settled_at: string | null;
|
|
1708
|
+
/** `finish` is the provider's own word (only `tool_use` is normalised) or
|
|
1709
|
+
* `schema_mismatch`; `truncated` is vxil's 262,144-character storage cut,
|
|
1710
|
+
* not a token cut */
|
|
1659
1711
|
result: {
|
|
1660
1712
|
text: string;
|
|
1661
1713
|
finish: string;
|
|
@@ -1665,11 +1717,23 @@ export interface AiGenerationRecord {
|
|
|
1665
1717
|
* user was erased) · `not_recorded` (not settled yet, or a sync/stream
|
|
1666
1718
|
* generation) */
|
|
1667
1719
|
result_state: 'stored' | 'purged' | 'not_recorded';
|
|
1668
|
-
/** a job-lane generation's
|
|
1669
|
-
*
|
|
1670
|
-
*
|
|
1671
|
-
*
|
|
1672
|
-
|
|
1720
|
+
/** a job-lane generation's execution attempts — one per attempt, timing
|
|
1721
|
+
* its FIRST provider call (the repair's own time is `repair_ms`), with the
|
|
1722
|
+
* upstream HTTP status and error class — oldest first, at most 10 kept. A
|
|
1723
|
+
* retried attempt shows up here with the status the model provider
|
|
1724
|
+
* answered. Empty on a sync/stream generation and before the first call
|
|
1725
|
+
* returned */
|
|
1726
|
+
attempts?: AiGenerationAttempt[];
|
|
1727
|
+
}
|
|
1728
|
+
/** One execution attempt on GET /v1/ai/generations/{id}. */
|
|
1729
|
+
export interface AiGenerationAttempt extends GenerationProviderAttempt {
|
|
1730
|
+
/** the structured-output repair call's time, in ms, on the settling
|
|
1731
|
+
* attempt when a repair ran */
|
|
1732
|
+
repair_ms?: number;
|
|
1733
|
+
/** on a failed or released attempt: the provider's own error text, up to
|
|
1734
|
+
* 200 characters (vxil never adds the prompt). API-key callers only —
|
|
1735
|
+
* never on an end-user session's read */
|
|
1736
|
+
hint?: string;
|
|
1673
1737
|
}
|
|
1674
1738
|
/** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
|
|
1675
1739
|
export interface JobGenerationQueuedEventPayload {
|
|
@@ -7096,6 +7160,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7096
7160
|
thinking_level?: AiThinkingLevel;
|
|
7097
7161
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7098
7162
|
media_resolution?: AiMediaResolution;
|
|
7163
|
+
/** Anthropic effort — see AiEffort. */
|
|
7164
|
+
effort?: AiEffort;
|
|
7099
7165
|
tools?: Array<{
|
|
7100
7166
|
name: string;
|
|
7101
7167
|
description?: string;
|
|
@@ -7112,6 +7178,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7112
7178
|
* still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
|
|
7113
7179
|
* over the template's stored schema. */
|
|
7114
7180
|
response_schema?: Record<string, unknown>;
|
|
7181
|
+
/** See AiRepair: `false` = no repair call on an invalid structured answer. */
|
|
7182
|
+
repair?: AiRepair;
|
|
7115
7183
|
images?: string[];
|
|
7116
7184
|
/** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
|
|
7117
7185
|
* URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
|
|
@@ -7158,6 +7226,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7158
7226
|
thinking_level?: AiThinkingLevel;
|
|
7159
7227
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7160
7228
|
media_resolution?: AiMediaResolution;
|
|
7229
|
+
/** Anthropic effort — see AiEffort. */
|
|
7230
|
+
effort?: AiEffort;
|
|
7161
7231
|
tools?: Array<{
|
|
7162
7232
|
name: string;
|
|
7163
7233
|
description?: string;
|
|
@@ -7197,6 +7267,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7197
7267
|
thinking_level?: AiThinkingLevel;
|
|
7198
7268
|
/** Gemini per-image / per-page token budget — see AiMediaResolution. */
|
|
7199
7269
|
media_resolution?: AiMediaResolution;
|
|
7270
|
+
/** Anthropic effort — see AiEffort. */
|
|
7271
|
+
effort?: AiEffort;
|
|
7200
7272
|
tools?: Array<{
|
|
7201
7273
|
name: string;
|
|
7202
7274
|
description?: string;
|
|
@@ -7207,8 +7279,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7207
7279
|
/** JSON Schema the completion must satisfy — same contract as
|
|
7208
7280
|
* `generate`; the validated answer lands in the replay buffer (a
|
|
7209
7281
|
* schema-mismatch delivers finish:'schema_mismatch' on the terminal
|
|
7210
|
-
* usage frame
|
|
7282
|
+
* usage frame, or the provider's own word when the answer could not be
|
|
7283
|
+
* repaired). */
|
|
7211
7284
|
response_schema?: Record<string, unknown>;
|
|
7285
|
+
/** See AiRepair: `false` = no repair call on an invalid structured answer. */
|
|
7286
|
+
repair?: AiRepair;
|
|
7212
7287
|
images?: string[];
|
|
7213
7288
|
/** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
|
|
7214
7289
|
* URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
|
package/package.json
CHANGED