@volter/twin-moonshot 0.1.0

package/dist/src/moonshot-budget.js

@@ -0,0 +1,142 @@
+// The client-side rate budget — the fail-closed backstop `liveMoonshotExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Moonshot's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings, exactly as every other pack does.
+//
+// THE GROUNDING (platform.kimi.ai/docs/pricing/limits, read 2026-09-16): Moonshot publishes a
+// per-tier table whose LOWEST published row (Tier 0, deposit ≥ $1) is concurrency 1, RPM 3,
+// TPM 500,000, TPD 1,500,000. RPM 3 is an order of magnitude UNDER the kernel's undeclared
+// fallback (30 calls/min), so the declaration buys resolution DOWNWARD from the fallback, never
+// headroom: the ceiling is pinned at the kernel fallback in units, and the INFERENCE rules price
+// the model-facing endpoints at a weight that keeps the real RPM-3 worst case inside the window.
+// The tier table scales up to Tier 5 (RPM 300), but no caller's tier is knowable here — the
+// budget protects the LOWEST tier by construction, and a higher tier is only ever under-spent.
+// Web-search endpoints (POST /v1/tools/search, /v1/tools/search_pro, /v1/tools/fetch) are
+// metered on their OWN QPS (QPS 1 at Tier 0), independent of the inference RPM — they get their
+// own rule so a search sweep cannot be priced as a cheap read.
+//
+// THE 429 SHAPE (same limits page): a real 429 carries `X-RateLimit-Limit` /
+// `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers. `recordCall` reads the standard
+// `retry-after` backstop plus these.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'moonshot';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const MOONSHOT_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback. Moonshot DOES publish an RPM scalar (3 at Tier 0),
+ * but it is a CALL ceiling, not a weight-unit ceiling; pricing every call 2 keeps the fallback
+ * shape and lets the inference rules spend the allowance where the vendor actually meters it.
+ */
+export const MOONSHOT_BUDGET_CEILING = 60;
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const MOONSHOT_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const MOONSHOT_CALL_WEIGHTS = {
+    /** Model-facing inference: /v1/chat/completions, /v1/responses, /anthropic/v1/messages.
+     *  At 60/6 that is at most 10 inference calls a window — inside Tier 0's RPM 3×window shape
+     *  for a single burst while leaving room for the interleaved reads a real client issues. */
+    inference: 6,
+    /** The web-search tool endpoints — Moonshot meters them on their OWN QPS (1 at Tier 0),
+     *  independent of inference RPM. Priced like inference so a sweep cannot ride the read weight. */
+    webSearch: 6,
+    /** Everything else: models, files, batches, balance, token counting, signature verify. */
+    other: 2,
+};
+/** THE PACK'S DECLARATION — pure data, the only Moonshot-specific thing in the whole budget. */
+export const MOONSHOT_RATE_BUDGET = {
+    windowMs: MOONSHOT_BUDGET_WINDOW_MS,
+    ceiling: MOONSHOT_BUDGET_CEILING,
+    defaultWeight: MOONSHOT_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: MOONSHOT_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        // Anchored on Moonshot's REAL paths. Inference is token-metered (TPM 500,000 at Tier 0
+        // dwarfs RPM 3 as the binding constraint on real traffic), so model-facing POSTs cost 6.
+        { match: '^POST /v1/chat/completions$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+        { match: '^POST /v1/responses$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+        { match: '^POST /anthropic/v1/messages$', weight: MOONSHOT_CALL_WEIGHTS.inference },
+        // Web-search tools: own QPS pool at the vendor, priced at inference weight here.
+        { match: '^POST /v1/tools/search$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+        { match: '^POST /v1/tools/search_pro$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+        { match: '^POST /v1/tools/fetch$', weight: MOONSHOT_CALL_WEIGHTS.webSearch },
+    ],
+    reason: 'Moonshot publishes a per-tier limit table (platform.kimi.ai/docs/pricing/limits, read ' +
+        '2026-09-16): Tier 0 (deposit ≥ $1) is concurrency 1, RPM 3, TPM 500,000, TPD 1,500,000, ' +
+        'Web Search QPS 1; Tier 5 (≥ $3000) is 100/300/5M/Unlimited/50. A 429 carries ' +
+        'X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset. Because the LOWEST published ' +
+        'RPM (3) is far under the kernel fallback of 30 calls/min, the ceiling is pinned AT the ' +
+        'fallback (60 units / 60s, defaultWeight 2) and the declaration spends it downward: the three ' +
+        'model-facing inference endpoints (POST /v1/chat/completions, POST /v1/responses, ' +
+        'POST /anthropic/v1/messages) cost 6 each — at most 10 land in a window — because those calls ' +
+        'are token-metered (TPM) at the vendor and one call spends far more of a real account\'s ' +
+        'allowance than a list poll. The web-search tool endpoints get their own 6-weight rule ' +
+        'because Moonshot meters them on a SEPARATE QPS pool (1 at Tier 0), so a search sweep must ' +
+        'not be priceable as a cheap read. The per-tier judgment call is the strict direction: the ' +
+        'budget protects Tier 0 by construction and only ever under-spends a higher tier. The window ' +
+        'bounds the 60s AVERAGE and does not pace; a `retry-after` read off a real 429 is the ' +
+        'persisted cooldown backstop.',
+};
+// Declared at module load, so merely importing this module (which `moonshot-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, MOONSHOT_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about Moonshot. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function moonshotCallWeight(method, path) {
+    const { bare, query } = moonshotSplitQuery(path);
+    // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+    // `execute('post', …)` really does issue a POST and must be priced as one.
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+/**
+ * `/v1/chat/completions?a=1` -> `{ bare: '/v1/chat/completions', query: { a: '1' } }`. Rules
+ * match the path; NORMALIZED, because the anchored rules are otherwise trivially evaded: `fetch`
+ * upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE that a
+ * `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor while
+ * most routers treat it as the same endpoint.
+ */
+function moonshotSplitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    // Collapse REPEATED slashes as well as a trailing one: `//v1/chat/completions` reaches the
+    // same endpoint on most routers but misses a `^POST /v1/...$` rule, which would price an
+    // inference call as a 2-unit read.
+    const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where Moonshot's ledger lives. Token-keyed and cwd-independent by default (Moonshot's limits
+ *  are per ACCOUNT, so a cwd-scoped ledger would hand the same key a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function moonshotBudgetPath(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.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * Moonshot's budget — the shared kernel guard bound to this vendor's declaration. A real
+ * subclass, not an alias, so `budget instanceof MoonshotBudget` in `liveMoonshotExecute` means
+ * "a budget that accounts against MOONSHOT's ledger under MOONSHOT's ceiling".
+ */
+export class MoonshotBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({
+            ...opts,
+            // Field-per-line so the mutation gate can neuter the vendor binding: a budget whose
+            // `vendor` is not 'moonshot' accounts against another vendor's ledger, and the ceiling
+            // verify reads `err.vendor` off the refusal — the neuter must redden THAT assertion.
+            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 MoonshotBudgetError } from '@volter/world-core';
+/** Re-exported so a caller can age a window out against the DECLARED window, not a hard-coded 60_000. */
+export { MOONSHOT_BUDGET_WINDOW_MS as MOONSHOT_RATE_BUDGET_WINDOW_MS };

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

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const MOONSHOT_CAPABILITIES: CapabilitySpec[];
+export declare const MOONSHOT_AREAS: readonly ["auth", "balance", "batches", "chat", "conformance", "connector", "errors", "files", "messages", "models", "rate_limits", "responses", "signatures", "streaming", "tokens", "tools"];
+export declare function moonshotCapabilities(): Promise<CapabilityReport>;