pyyol 1.9.0 → 1.10.0

package/dist/instrument.js

@@ -16,6 +16,7 @@
 // pass `stream_options: { include_usage: true }` and record manually, or use
 // non-streaming calls for automatic capture.
 import { estimateCost } from "./pricing.js";
+import { fromRequest, issue } from "./scaffold.js";
 import * as providers from "./providers.js";
 import { currentSpan, currentUsage } from "./telemetry.js";
 // [prototype, method, original] for uninstrument().
@@ -35,11 +36,40 @@ export function disableGateway() {
     gateway.key = "";
     gateway.base = "";
 }
-const PROVIDER_PATH = { openai: "/gw/openai/v1", anthropic: "/gw/anthropic" };
-/** The baseURL a provider client should point at, or "" if routing is off/unknown. */
+// Which WIRE FORMAT a provider speaks. This decides the gateway path, and it is the only
+// per-provider knowledge routing needs.
+//
+// WHY NOT A PROVIDER->PATH TABLE. There was one, listing openai and anthropic — not even groq.
+// Every other provider resolved to "" and was therefore NOT ROUTED, silently: no proofs, no
+// Verified badge, and in ranked play decisions that count as unproven. A table naming every
+// provider is always one release behind the ecosystem, so the verified tier was structurally
+// OpenAI-and-Anthropic-only.
+//
+// What actually varies is one bit: does the provider's own SDK append a version segment?
+//
+//   OpenAI-wire clients call {base}/chat/completions   -> the base must end in /v1
+//   Anthropic clients call   {base}/v1/messages        -> the base must NOT
+//   Google clients call      {base}/v1beta/models/...  -> the base must NOT
+//
+// Three cases, with OpenAI-wire the DEFAULT because most of the ecosystem speaks it. A provider
+// nobody has heard of routes correctly on the day it ships.
+const NO_VERSION_SUFFIX = new Set(["anthropic", "google", "vertex"]);
+/**
+ * The baseURL a provider client should point at, or "" when routing is off or the provider
+ * cannot be routed.
+ *
+ * Returns "" for a LOCAL/self-hosted provider, deliberately: the gateway runs on Pyyol's side
+ * and cannot reach a model server on the developer's own machine, so pointing a client at it
+ * would break every call. That play is unverified — and also free, so no cost attribution is
+ * lost either.
+ */
 export function gatewayBaseUrl(provider) {
-    const path = PROVIDER_PATH[provider];
-    return gateway.base && path ? gateway.base + path : "";
+    if (!gateway.base || !provider)
+        return "";
+    if (providers.isSelfHosted(provider))
+        return "";
+    const suffix = NO_VERSION_SUFFIX.has(provider.toLowerCase()) ? "" : "/v1";
+    return `${gateway.base}/gw/${provider}${suffix}`;
 }
 /** The X-Pyyol-* identity headers for the current turn (empty if routing off). */
 export function gatewayHeaders() {
@@ -76,15 +106,14 @@ function detectProvider(client) {
  *  `patchedAs` is the SDK we wrapped (which wire format this is). The client's baseURL
  *  is consulted first and wins. A baseURL pointing at the PYYOL GATEWAY is not used for
  *  attribution — it says the call was proxied, not who served it — so the upstream is
- *  recovered from the gateway path by matching it back against PROVIDER_PATH. */
+ *  recovered by PARSING the gateway path (/gw/<slug>[/v1]) rather than matching a table, so a
+ *  provider added tomorrow is attributed correctly without touching this. */
 export function resolveCallProvider(resource, patchedAs) {
     const base = clientBaseUrl(resource);
     if (base && gateway.base && base.startsWith(gateway.base)) {
-        const tail = base.slice(gateway.base.length);
-        for (const [provider, path] of Object.entries(PROVIDER_PATH)) {
-            if (tail.startsWith(path))
-                return provider;
-        }
+        const parts = base.slice(gateway.base.length).replace(/^\/+|\/+$/g, "").split("/");
+        if (parts.length >= 2 && parts[0] === "gw" && parts[1])
+            return parts[1];
         return patchedAs;
     }
     return providers.resolve({ baseUrl: base, fallback: patchedAs });
@@ -150,104 +179,260 @@ function get(obj, name, dflt) {
     const v = obj[name];
     return v === undefined ? dflt : v;
 }
-/** Pull normalized usage from a provider response, or null if it has none.
- *  Handles OpenAI Chat Completions, Anthropic Messages, and the OpenAI Responses
- *  API; duck-typed so a plain object or an SDK object both work. */
-/** Ollama's native shape: no `usage` object at all, counts at the top level.
- *  Without this an agent running Ollama reported zero tokens forever — it looked
- *  instrumented and measured nothing, and no bill ever arrives to contradict a zero. */
-function extractOllama(resp) {
-    const prompt = get(resp, "prompt_eval_count");
-    const completion = get(resp, "eval_count");
-    if (prompt === undefined && completion === undefined)
-        return null;
-    return {
-        model: get(resp, "model", "") || "",
-        provider: providers.OLLAMA,
-        promptTokens: Math.trunc(prompt || 0),
-        completionTokens: Math.trunc(completion || 0),
-        cachedTokens: 0,
-        reasoningTokens: 0,
-    };
+const MODEL_KEYS = new Set(["model", "modelversion", "modelid", "modelname", "modelslug"]);
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[_\-.]/g, "");
 }
-/** Google Gemini: counts hang off `usageMetadata` (camelCase in the JS SDK). */
-function extractGoogle(resp) {
-    const um = get(resp, "usageMetadata") ?? get(resp, "usage_metadata");
-    if (um == null)
-        return null;
-    const prompt = get(um, "promptTokenCount", get(um, "prompt_token_count", 0)) || 0;
-    const completion = get(um, "candidatesTokenCount", get(um, "candidates_token_count", 0)) || 0;
-    if (!prompt && !completion)
-        return null;
-    return {
-        model: get(resp, "modelVersion", "") || get(resp, "model", "") || "",
-        provider: providers.GOOGLE,
-        promptTokens: Math.trunc(prompt),
-        completionTokens: Math.trunc(completion),
-        cachedTokens: Math.trunc(get(um, "cachedContentTokenCount", get(um, "cached_content_token_count", 0)) || 0),
-        reasoningTokens: Math.trunc(get(um, "thoughtsTokenCount", get(um, "thoughts_token_count", 0)) || 0),
-    };
+function isModelKey(key) {
+    return MODEL_KEYS.has(normalizeKey(key));
 }
-/** Cohere nests counts under `meta.tokens`. */
-function extractCohere(resp) {
-    const tokens = get(get(resp, "meta"), "tokens");
-    if (tokens == null)
+/**
+ * What a response field MEANS, independent of what it is called.
+ *
+ * Ordered most-specific-first: "cache_read_input_tokens" contains both "cache" and "input" and
+ * must read as a cache field, not an input count. Getting that order wrong would make Anthropic's
+ * cache read look like its input total.
+ */
+function classifyUsageKey(key) {
+    const k = key.toLowerCase().replace(/-/g, "_");
+    if (k.includes("cach")) {
+        if (k.includes("creat") || k.includes("writ"))
+            return "cacheWrite";
+        // A MISS is ordinary uncached input, already inside the prompt total that accompanies it
+        // (DeepSeek documents prompt == hit + miss), so counting it would double-bill.
+        if (k.includes("miss"))
+            return null;
+        if (k.includes("read") || k.includes("hit") || k.includes("cached"))
+            return "cacheRead";
+        // A bare cache count with no direction: read is the cheaper and therefore conservative
+        // reading — overstating a discount is worse than understating it.
+        return "cacheRead";
+    }
+    if (k.includes("reasoning") || k.includes("thought"))
+        return "reasoning";
+    if (k.includes("total"))
+        return "total";
+    // Output before input: these are unambiguous, and doing them first keeps the input rules from
+    // having to exclude them.
+    if (k.includes("completion") || k.includes("output") || k.includes("candidates") || k === "eval_count") {
+        return "output";
+    }
+    if (k.includes("prompt"))
+        return "inputPrompt";
+    if (k.includes("input"))
+        return "inputFresh";
+    return null;
+}
+function fieldsOf(node) {
+    if (node === null || node === undefined)
         return null;
-    const prompt = get(tokens, "inputTokens", get(tokens, "input_tokens", 0)) || 0;
-    const completion = get(tokens, "outputTokens", get(tokens, "output_tokens", 0)) || 0;
-    if (!prompt && !completion)
+    if (typeof node !== "object")
         return null;
-    return {
-        model: get(resp, "model", "") || "",
-        provider: "cohere",
-        promptTokens: Math.trunc(prompt),
-        completionTokens: Math.trunc(completion),
-        cachedTokens: 0,
-        reasoningTokens: 0,
-    };
+    if (Array.isArray(node))
+        return null;
+    return node;
 }
-export function extractUsage(resp) {
-    const u = get(resp, "usage");
-    if (u == null) {
-        // Shapes that carry no `usage` at all. Only consulted here, so they can never
-        // hijack a normal OpenAI or Anthropic response.
-        for (const extractor of [extractOllama, extractGoogle, extractCohere]) {
-            const info = extractor(resp);
-            if (info !== null)
-                return info;
+/**
+ * Accumulate every usage-shaped number under `node`, by concept.
+ *
+ * Takes the MAXIMUM per concept rather than the last value seen: responses repeat counts (a
+ * streamed body carries them across frames), and a later zero for a field the provider is not
+ * reporting in that frame would erase a real count already found.
+ */
+function harvestUsage(node, acc, depth = 0) {
+    if (depth > 12)
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            harvestUsage(item, acc, depth + 1);
+        return;
+    }
+    const fields = fieldsOf(node);
+    if (!fields)
+        return;
+    for (const key of Object.keys(fields).sort()) {
+        const value = fields[key];
+        if (isModelKey(key) && typeof value === "string" && value && !acc.model) {
+            acc.model = value;
+            continue;
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            const concept = classifyUsageKey(key);
+            if (concept && value > 0 && value > (acc[concept] ?? 0)) {
+                acc[concept] = Math.trunc(value);
+                acc.found = true;
+            }
+            continue;
+        }
+        harvestUsage(value, acc, depth + 1);
+    }
+}
+const USAGE_CONTAINER_HINTS = ["usage", "tokens", "accounting", "billing"];
+/** Collect every non-scalar value whose key satisfies `match`, in deterministic order. */
+function findByKey(node, match, depth = 0) {
+    if (depth > 12)
+        return [];
+    const out = [];
+    if (Array.isArray(node)) {
+        for (const item of node)
+            out.push(...findByKey(item, match, depth + 1));
+        return out;
+    }
+    const fields = fieldsOf(node);
+    if (!fields)
+        return out;
+    for (const key of Object.keys(fields).sort()) {
+        const v = fields[key];
+        if (v !== null && typeof v === "object") {
+            if (match(key)) {
+                out.push(v); // the envelope is the unit; do not also descend into it
+                continue;
+            }
+            out.push(...findByKey(v, match, depth + 1));
         }
+    }
+    return out;
+}
+function harvestModel(node, acc, depth = 0) {
+    if (depth > 12 || acc.model)
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            harvestModel(item, acc, depth + 1);
+        return;
+    }
+    const fields = fieldsOf(node);
+    if (!fields)
+        return;
+    for (const key of Object.keys(fields).sort()) {
+        if (isModelKey(key) && typeof fields[key] === "string" && fields[key]) {
+            acc.model = fields[key];
+            return;
+        }
+    }
+    for (const key of Object.keys(fields).sort())
+        harvestModel(fields[key], acc, depth + 1);
+}
+/**
+ * Read the CANONICAL usage envelope where one exists, and only scan more widely when there is none.
+ *
+ * WHY PRIORITY RATHER THAN "take the largest match". Once the walk is general, an unrelated number
+ * elsewhere in a response can be read as a token count — a proxy echoing several dialects, or a
+ * provider that left a legacy field in place, produces a body carrying both a real `usage` object
+ * and a stray `prompt_eval_count`. Keeping the largest value would let whichever number happened
+ * to be bigger decide what the developer is charged.
+ *
+ * `usage` is what OpenAI, Anthropic, Bedrock, Mistral and every OpenAI-wire server fill in. The
+ * alternatives are what a provider uses INSTEAD of it, never alongside — so it wins outright.
+ */
+function harvestPreferringEnvelope(resp, acc) {
+    harvestModel(resp, acc);
+    // Tier 1: the canonical envelope, wherever it sits (Anthropic's streaming shape nests it inside
+    // `message`, so this cannot be a top-level-only lookup).
+    const envelopes = findByKey(resp, (k) => normalizeKey(k) === "usage");
+    if (envelopes.length) {
+        for (const e of envelopes)
+            harvestUsage(e, acc);
+        if (acc.found)
+            return;
+    }
+    // Tier 2: a differently-named accounting container (Google's usageMetadata, Cohere's meta.tokens).
+    const containers = findByKey(resp, (k) => {
+        const lk = k.toLowerCase();
+        return USAGE_CONTAINER_HINTS.some((h) => lk.includes(h));
+    });
+    if (containers.length) {
+        for (const c of containers)
+            harvestUsage(c, acc);
+        if (acc.found)
+            return;
+    }
+    // Tier 3: no envelope at all. Ollama natively puts its counts at the TOP LEVEL, and a local model
+    // bills nothing — so a zero there is never contradicted by an invoice, which is exactly why it
+    // went unnoticed. Scan everything rather than report it as free.
+    harvestUsage(resp, acc);
+}
+/**
+ * A vendor label inferred from DISTINCTIVE container names, not from token field names.
+ *
+ * Kept because the label is user-visible and feeds pricing: an open-weight model is free when
+ * self-hosted and billed when a hosted provider serves it, with the same model id either way. Only
+ * markers that genuinely identify one vendor are listed, and this is a LAST-RESORT hint — the
+ * caller's own resolution from the client's baseURL wins wherever it has one.
+ *
+ * A plain `usage` envelope OUTRANKS every marker: a response can carry both, and the envelope the
+ * provider actually filled in is the one that decides.
+ */
+function vendorFromMarkers(resp) {
+    const fields = fieldsOf(resp) ?? {};
+    const keys = new Set(Object.keys(fields).map(normalizeKey));
+    if (keys.has("usage"))
+        return "";
+    if (keys.has("usagemetadata"))
+        return providers.GOOGLE;
+    if (keys.has("promptevalcount") || keys.has("evalcount"))
+        return providers.OLLAMA;
+    const meta = fieldsOf(fields["meta"]);
+    if (meta && meta["tokens"] !== undefined)
+        return "cohere";
+    return "";
+}
+/**
+ * Pull normalized usage from ANY provider response, or null if it carries none.
+ *
+ * Normalizes onto ONE convention: promptTokens is the total billable input, with cache reads and
+ * writes as SUBSETS of it. Providers genuinely disagree and the disagreement is silent, so the rule
+ * follows the WORD USED rather than a vendor list:
+ *
+ *   - a PROMPT-family key names the whole prompt, so cache is already inside it
+ *   - an INPUT-family key names fresh input, so cache is billed on top
+ *
+ * A reported total cross-checks the additive case, so a provider using "input" for a
+ * cache-inclusive total is corrected by its own arithmetic instead of being over-counted.
+ */
+export function extractUsage(resp) {
+    const acc = {};
+    harvestPreferringEnvelope(resp, acc);
+    if (!acc.found)
         return null;
+    const cacheRead = acc.cacheRead ?? 0;
+    const cacheWrite = acc.cacheWrite ?? 0;
+    const completion = acc.output ?? 0;
+    const total = acc.total ?? 0;
+    const inPrompt = acc.inputPrompt ?? 0;
+    const inFresh = acc.inputFresh ?? 0;
+    let prompt;
+    if (inPrompt > 0) {
+        prompt = inPrompt;
+    }
+    else if (inFresh > 0) {
+        prompt = inFresh + cacheRead + cacheWrite;
+        if (total > 0 && prompt > total - completion && total - completion >= inFresh) {
+            prompt = total - completion;
+        }
+    }
+    else {
+        // No input count, but cache counts present: the cache IS the input we know about.
+        prompt = cacheRead + cacheWrite;
+    }
+    // A cache count larger than the prompt total cannot be a subset of it. Raise the total rather
+    // than let pricing clamp the excess away as if it had never been billed.
+    prompt = Math.max(prompt, cacheRead + cacheWrite);
+    let provider = vendorFromMarkers(resp);
+    if (!provider) {
+        if (inPrompt > 0)
+            provider = "openai";
+        else if (inFresh > 0)
+            provider = "anthropic";
     }
-    const model = get(resp, "model", "") || "";
-    let prompt = get(u, "prompt_tokens");
-    let completion = get(u, "completion_tokens");
-    const styleOpenAiChat = prompt !== undefined || completion !== undefined;
-    if (prompt === undefined)
-        prompt = get(u, "input_tokens", 0);
-    if (completion === undefined)
-        completion = get(u, "output_tokens", 0);
-    let cached = 0;
-    let reasoning = 0;
-    const ptd = get(u, "prompt_tokens_details");
-    if (ptd != null)
-        cached = get(ptd, "cached_tokens", 0) || 0;
-    const ctd = get(u, "completion_tokens_details");
-    if (ctd != null)
-        reasoning = get(ctd, "reasoning_tokens", 0) || 0;
-    if (!cached)
-        cached = get(u, "cache_read_input_tokens", 0) || 0;
-    let provider = "";
-    if (styleOpenAiChat)
-        provider = "openai";
-    else if (get(u, "input_tokens") !== undefined)
-        provider = "anthropic";
     return {
-        model,
+        model: acc.model ?? "",
         provider,
-        promptTokens: Math.trunc(prompt || 0),
-        completionTokens: Math.trunc(completion || 0),
-        cachedTokens: Math.trunc(cached || 0),
-        reasoningTokens: Math.trunc(reasoning || 0),
+        promptTokens: Math.trunc(prompt),
+        completionTokens: Math.trunc(completion),
+        cachedTokens: Math.trunc(cacheRead),
+        cachedWriteTokens: Math.trunc(cacheWrite),
+        reasoningTokens: Math.trunc(acc.reasoning ?? 0),
     };
 }
 /** Record usage from a provider response: compute cost, add to the turn
@@ -266,6 +451,7 @@ export function recordResponse(resp, o = {}) {
         promptTokens: info.promptTokens,
         completionTokens: info.completionTokens,
         cachedTokens: info.cachedTokens,
+        cachedWriteTokens: info.cachedWriteTokens,
         reasoningTokens: info.reasoningTokens,
     });
     currentUsage()?.add({
@@ -275,7 +461,9 @@ export function recordResponse(resp, o = {}) {
         completionTokens: info.completionTokens,
         reasoningTokens: info.reasoningTokens,
         cachedTokens: info.cachedTokens,
+        cachedWriteTokens: info.cachedWriteTokens,
         estimatedCost: cost,
+        latencyMs: o.latencyMs ?? 0,
     });
     currentSpan().logModelCall({
         provider,
@@ -290,7 +478,7 @@ export function recordResponse(resp, o = {}) {
 }
 /** @internal Wrap `proto[method]` so its resolved return value is recorded.
  *  Idempotent and fully guarded. Exported for tests. */
-export function patchPrototype(proto, method, provider) {
+export function patchPrototype(proto, method, provider, endpoint = "") {
     if (proto == null)
         return false;
     const orig = proto[method];
@@ -298,6 +486,18 @@ export function patchPrototype(proto, method, provider) {
         return false;
     const wrapped = async function (...args) {
         injectGatewayHeaders(this, args);
+        // Fingerprint the scaffold from the OUTGOING request: the system prompt, tools and
+        // sampling are what the developer wrote, and none of that comes back in the response.
+        // Guarded like every other hook — a fingerprinting problem must never be why a
+        // developer's model call fails.
+        try {
+            const req = (args[0] ?? {});
+            const fp = fromRequest(req, endpoint);
+            currentUsage()?.observeScaffold(fp, fp ? "" : issue(req, endpoint));
+        }
+        catch {
+            // instrumentation must never break the dev's call
+        }
         const start = Date.now();
         const resp = await orig.apply(this, args);
         try {
@@ -327,17 +527,22 @@ async function patchOpenAI() {
     let patched = false;
     const chat = await tryImport("openai/resources/chat/completions");
     if (chat?.Completions?.prototype)
-        patched = patchPrototype(chat.Completions.prototype, "create", "openai") || patched;
+        patched =
+            patchPrototype(chat.Completions.prototype, "create", "openai", "openai.chat.completions") ||
+                patched;
     const responses = await tryImport("openai/resources/responses");
     if (responses?.Responses?.prototype)
-        patched = patchPrototype(responses.Responses.prototype, "create", "openai") || patched;
+        patched =
+            patchPrototype(responses.Responses.prototype, "create", "openai", "openai.responses") || patched;
     return patched;
 }
 async function patchAnthropic() {
     let patched = false;
     const messages = await tryImport("@anthropic-ai/sdk/resources/messages");
     if (messages?.Messages?.prototype)
-        patched = patchPrototype(messages.Messages.prototype, "create", "anthropic") || patched;
+        patched =
+            patchPrototype(messages.Messages.prototype, "create", "anthropic", "anthropic.messages") ||
+                patched;
     return patched;
 }
 /** Auto-capture LLM usage from installed providers. Pass e.g. `["openai"]` to limit

package/dist/movetools.d.ts

@@ -0,0 +1,141 @@
+export declare const TOOL_GOOFSPIEL = "play_card";
+export declare const TOOL_MAFIA = "mafia_action";
+export declare const TOOL_MONOPOLY = "monopoly_action";
+export declare const GAME_GOOFSPIEL = "goofspiel";
+export declare const GAME_MAFIA = "mafia";
+export declare const GAME_MONOPOLY = "monopoly";
+/**
+ * NO_TARGET is the wire convention for "this action names no seat".
+ *
+ * NOT zero, and worth reading twice: seat 0 is a real player. A forgotten target used to act
+ * silently on seat 0, which is why MafiaMove defaults to -1 — and the canonical form has to
+ * agree, or every untargeted action would bind as an action against that player.
+ */
+export declare const NO_TARGET = -1;
+/** The tool name that carries a move for `game`, or "" if the game has no contract. */
+export declare function moveToolName(game: string): string;
+export declare function moveTool(game: string, provider?: string, planRounds?: number): Record<string, unknown>;
+/**
+ * The provider-specific way to REQUIRE the move tool.
+ *
+ * Worth using. Without it a model may answer in prose, and a turn with no tool call is
+ * unverified — the agent keeps playing but earns no completion binding.
+ */
+export declare function moveToolChoice(game: string, provider?: string): unknown;
+/**
+ * The move arguments the model emitted, or null if it emitted no usable move call.
+ *
+ * STRUCTURAL, not per-provider. Every provider that has ever expressed a tool call has
+ * expressed it as a name beside an arguments blob, as SIBLINGS in one object:
+ *
+ *   OpenAI      {"function": {"name": "play_card", "arguments": "{\"card\":7}"}}
+ *   Responses   {"type": "function_call", "name": "play_card", "arguments": "{...}"}
+ *   Anthropic   {"type": "tool_use", "name": "play_card", "input": {"card": 7}}
+ *   Google      {"functionCall": {"name": "play_card", "args": {"card": 7}}}
+ *   Bedrock     {"toolUse": {"name": "play_card", "input": {"card": 7}}}
+ *   Ollama      {"function": {"name": "play_card", "arguments": {"card": 7}}}
+ *
+ * So the walk looks for that structure anywhere in the document and a provider nobody has heard
+ * of works on the day it ships. Enumerating shapes loses by construction: new providers appear
+ * constantly, every self-hosted server has its own dialect, and an unlisted one fails SILENTLY —
+ * the turn is never bound and nobody learns why.
+ *
+ * SAFE because the tool NAME is the discriminator and it is ours. The one near-miss is a response
+ * echoing the tool DEFINITION, which is why "parameters" is NOT accepted as an arguments key: a
+ * JSON Schema yields no card and falls through to null rather than to a wrong move. That
+ * direction matters — a wrong move REJECTS an honest turn, a miss only leaves it unverified.
+ *
+ * Returns the LAST matching call: a model that corrected itself stands behind its final answer.
+ */
+export declare function moveFromResponse(game: string, resp: unknown): Record<string, unknown> | null;
+/** The bound form of a Goofspiel move: the card, and nothing else. */
+export declare function canonGoofspiel(card: number): string;
+/**
+ * The bound form of a Mafia action: the verb and its target seat.
+ *
+ * The PHASE is deliberately excluded — it is server state, not the model's choice, and binding
+ * it would reject an honest turn over a field the model had no say in.
+ *
+ * Negative targets collapse to one token; ZERO DOES NOT. Seat 0 is an ordinary player, and
+ * abstaining is its own action kind rather than a sentinel target, so "no seat" is only ever an
+ * absent or negative field. Collapsing 0 too would let a move against that one player be
+ * substituted for doing nothing.
+ */
+export declare function canonMafia(kind: string, target: number): string;
+/**
+ * The bound form of a Monopoly action: verb, property, amount.
+ *
+ * All three are always rendered, including zeros. Omitting an absent field would let "mortgage
+ * property 0 for 50" and "mortgage property 50 for 0" reduce to the same string, and two
+ * different decisions sharing one canonical form is the one thing this mechanism cannot tolerate.
+ */
+export declare function canonMonopoly(kind: string, property?: number, amount?: number): string;
+/**
+ * Reduce move arguments to the canonical string a bound decision stores.
+ *
+ * null means "nothing bindable here", which callers must treat as an unverified turn and never
+ * as a wrong move.
+ */
+export declare function canonMove(game: string, args: Record<string, unknown> | null): string | null;
+/**
+ * The canonical move the platform will bind for this response, or null.
+ *
+ * The one call worth making in a test: it is exactly what the gateway does, so an agent that
+ * asserts on this locally cannot be surprised by a rejection in a real match.
+ */
+export declare function boundMove(game: string, resp: unknown): string | null;
+/**
+ * The argument that carries a multi-round decision.
+ *
+ * Named once, and it must match the Go gateway and the Python SDK exactly: a mismatch would
+ * not throw, it would silently fall back to single-round binding and quietly restore the
+ * coverage problem range bindings exist to fix.
+ */
+export declare const PLAN_KEY = "plan";
+/**
+ * The most rounds one completion may claim to have decided.
+ *
+ * Bounded because the plan is attacker-supplied — uncapped, a single call could assert a
+ * hundred thousand rounds and become that many database writes. Comfortably above any real
+ * game, so a legitimate agent never meets it.
+ */
+export declare const MAX_SPAN_ROUNDS = 64;
+/** One round a completion decided. */
+export interface RoundMove {
+    round: number;
+    move: string;
+}
+/**
+ * Reduce move arguments to EVERY round they decided.
+ *
+ * # Why a completion may cover more than one round
+ *
+ * Coverage used to count CALLS, so one completion bound one round. An agent that batches — one
+ * call planning three rounds — therefore scored about 33% on real staked tables while playing
+ * entirely model-backed, and cost optimisation is something this platform means to REWARD.
+ * Coverage now means "decisions a model made" rather than "calls made".
+ *
+ * # Why claiming a span is safe
+ *
+ * A span is a COMMITMENT, not a free coverage win. Match-time enforcement is unchanged, so
+ * submitting anything other than the bound move for a covered round is rejected exactly as a
+ * substitution is. An agent that over-claims has only tied its own hands.
+ *
+ * # The one thing a span must never do
+ *
+ * Rounds before `provenRound` are DROPPED. Those turns have already been played, so a binding
+ * over them is coverage nothing will ever check — an agent could retroactively claim turns it
+ * played unbound. Forward claims are self-limiting because they are enforced.
+ *
+ * null means nothing is bindable. A plan naming one round twice returns null WHOLE: two moves
+ * for one slot has no honest reading, and picking either would be guessing for the agent.
+ */
+export declare function canonPlan(game: string, args: Record<string, unknown> | null, provenRound: number): RoundMove[] | null;
+/**
+ * Every round this response will bind, exactly as the gateway will read it.
+ *
+ * Worth calling in a test before shipping a batching agent: if this does not list the round you
+ * are about to play, that turn will not be bound, and if it lists a DIFFERENT move than you
+ * intend to submit, the match will reject it.
+ */
+export declare function boundPlan(game: string, resp: unknown, provenRound: number): RoundMove[] | null;