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