@volter/twin-xai 0.1.0

package/dist/src/xai-budget.js

@@ -0,0 +1,139 @@
+// xAI's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed bindings
+// `liveXaiExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling window,
+// reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger — lives ONCE
+// in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's header for
+// the full rationale AND for the honest list of what the guard does not guarantee (an injected clock
+// or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ──────────────────────────────────────────────────────────────────────────
+// A ~4.5-day Figma token lockout (2026-07-25) came from a burst of raw vendor calls made OUTSIDE any
+// guarded client. `liveXaiExecute` was exactly that shape: this pack's one construction site for a
+// real client, and a BARE `fetch` with the credential attached as `Authorization: Bearer` and
+// NOTHING in front of it — no ceiling, no cooldown, no ledger. `scripts/rate-budget-coverage.test.ts`
+// is the gate that found it; this module is the fix.
+//
+// ── HOW THE CEILING WAS CHOSEN: xAI PUBLISHES NO SCALAR LIMIT AT ALL ─────────────────────────
+// This is a DISCLAIMER, not a model of a limit, and it is a stronger disclaimer than gemini's.
+//
+// xAI's public documentation states no rate limit anywhere that could bind this connector: neither
+// the API reference (docs.x.ai/docs/api-reference), nor the models page (docs.x.ai/docs/models,
+// which carries pricing and capability tables but no RPM/RPS/TPM figures), nor the overview or
+// quickstart pages publish a requests-per-minute, requests-per-second or tokens-per-minute number,
+// and none of them even direct the reader to a dashboard where one could be read. (The URL commonly
+// cited for this, docs.x.ai/docs/consumption-and-rate-limits, returns 404.)
+//
+// So there is no vendor figure to size against, and the rule for that case is to SAY SO and pin to
+// the kernel's austere fallback rather than borrow an adjacent-but-different number. Copying, say,
+// OpenAI's tier limits because xAI's API is OpenAI-chat-compatible would be exactly the fabrication
+// this rule exists to prevent — protocol compatibility is not quota compatibility.
+//
+// Therefore: 60 weighted units per 60s at a default weight of 2 — EXACTLY `DEFAULT_RATE_BUDGET`.
+// 30 calls a minute, one every two seconds. Comfortably above any real pull (the whole pull surface
+// is TWO calls: the flat catalog and the rich one) and far below the shape that causes lockouts.
+// Nothing here is more permissive than the fallback.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN: THEY ARE FLAT, DELIBERATELY ─────────────────────────────────
+// There are NO pricing rules, and their absence is a decision rather than an omission.
+//
+// `XaiExecute` is typed `method: 'GET'` — the pull surface is read-only catalogs
+// (`/v1/models`, `/v1/language-models`) and the push surface REFUSES LOUDLY for every operation,
+// because the xAI API has no client-writable resources. So no caller of this execute can reach the
+// token-billed inference endpoints (`POST /v1/chat/completions`, `/v1/messages`), and there is no
+// endpoint in reach that is credibly dearer than another.
+//
+// Inventing a ratio anyway — pricing some GET at 4 "to be safe" — would be a made-up number wearing
+// the costume of a vendor fact, which is precisely what the anti-fabrication rule forbids. Every
+// call therefore costs the same 2, and nothing is free.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'xai';
+/** Rolling window, in ms. The fallback's, because xAI publishes no per-minute figure to match. */
+export const XAI_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 60/60s at the default weight of 2 = 30 calls a minute —
+ * the kernel's austere fallback exactly, adopted deliberately because xAI publishes no scalar limit.
+ */
+export const XAI_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const XAI_BUDGET_MAX_RETRY_AFTER_S = 300;
+/**
+ * Per-call cost. FLAT by design — see the header: the execute is GET-only over read-only catalogs,
+ * so no reachable endpoint is credibly dearer than another, and inventing a ratio would be a
+ * fabricated vendor fact. `other` is the only weight, and it is never zero.
+ */
+export const XAI_CALL_WEIGHTS = {
+    /** Every call. xAI publishes no per-endpoint cost, and this execute reaches only catalog reads. */
+    other: 2,
+};
+/**
+ * THE PACK'S DECLARATION — pure data, the only xAI-specific thing in the whole budget.
+ *
+ * `rules` is EMPTY on purpose (see the header). Also exported as `pack.rateBudget` (see index.ts),
+ * so `registerPack` arms it too.
+ */
+export const XAI_RATE_BUDGET = {
+    windowMs: XAI_BUDGET_WINDOW_MS,
+    ceiling: XAI_BUDGET_CEILING,
+    defaultWeight: XAI_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: XAI_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [],
+    reason: 'xAI publishes NO scalar rate limit anywhere in its public documentation that could bind this ' +
+        'connector: neither the API reference (docs.x.ai/docs/api-reference), nor the models page (which ' +
+        'carries pricing and capability tables but no RPM/RPS/TPM figures), nor the overview or quickstart ' +
+        'pages state a requests-per-minute, requests-per-second or tokens-per-minute number, and none even ' +
+        'points at a dashboard where one could be read (the commonly-cited consumption-and-rate-limits URL ' +
+        '404s). With no vendor figure to model, this pins to the kernel\'s austere fallback rather than ' +
+        'borrowing OpenAI\'s tier limits on the strength of xAI\'s OpenAI-compatible protocol — protocol ' +
+        'compatibility is not quota compatibility. 60 weighted units / 60s at 2 per call = 30 calls a ' +
+        'minute, identical to DEFAULT_RATE_BUDGET and no more permissive than it. Pricing is FLAT and that ' +
+        'is deliberate: XaiExecute is typed GET-only over read-only catalogs and the push surface refuses ' +
+        'loudly, so no caller can reach a token-billed inference endpoint and no reachable endpoint is ' +
+        'credibly dearer than another; inventing a ratio would be a made-up number dressed as vendor fact.',
+};
+// Declared at module load, so merely importing this module (which `xai-connector.ts` does) is enough
+// to arm the real ceiling. Here the declaration and the kernel's DEFAULT_RATE_BUDGET happen to be
+// numerically identical, so the usual "the fallback is not uniformly tighter" hazard does not bite —
+// but `RateBudget` still reads its policy live, and constructing through the subclass below (which
+// imports this module) is what keeps the ordering a non-issue in general.
+declareRateBudget(VENDOR, XAI_RATE_BUDGET);
+/** Split a connector path (which may carry its own query string) into pathname + parsed query. */
+export function splitXaiPath(path) {
+    const q = path.indexOf('?');
+    if (q < 0)
+        return { pathname: path, query: {} };
+    const query = {};
+    for (const [k, v] of new URLSearchParams(path.slice(q + 1)))
+        query[k] = v;
+    return { pathname: path.slice(0, q), query };
+}
+/**
+ * Price one call. Keyed off the request the connector is ABOUT to make. With no rules declared every
+ * call takes `defaultWeight` — which is the point: an unclassified endpoint must never be free.
+ */
+export function xaiCallWeight(method, path) {
+    const { pathname, query } = splitXaiPath(path);
+    return rateBudgetWeight(VENDOR, `${(method || 'GET').toUpperCase()} ${pathname}`, query);
+}
+/** Where xAI's ledger lives. API-key-keyed and cwd-independent by default (the limit, whatever it
+ *  is, is per key, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting instead. */
+export function xaiBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * xAI's budget — the shared kernel guard bound to this vendor's declaration. A real subclass, not an
+ * alias, so the guard check in `liveXaiExecute` still means "a budget that accounts against XAI's
+ * ledger under XAI's ceiling": another vendor's `RateBudget` (with its own, possibly larger,
+ * ceiling) is NOT assignable there.
+ */
+export class XaiBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as XaiBudgetError } from '@volter/world-core';

package/dist/src/xai-capabilities.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const XAI_CAPABILITIES: CapabilitySpec[];
+export declare const XAI_AREAS: readonly ["api_key", "chat", "cli_proxy", "completions_legacy", "conformance", "connector", "deferred", "errors", "images", "messages_compat", "models", "oauth", "responses", "search", "streaming", "tokenize", "tools", "ui"];
+export declare function xaiCapabilities(): Promise<CapabilityReport>;