pyyol 1.9.0 → 1.10.0

package/dist/cli.d.ts

@@ -15,5 +15,29 @@ export declare function connectionToken(a: Args, c: creds.Credentials | null): {
     token: string;
     usingAgentKey: boolean;
 };
+/** True if the agent's entry file appears to send a system prompt, false if not, null if unknown.
+ *
+ *  A shallow source scan, deliberately: it recognises Anthropic's `system=` and OpenAI's system /
+ *  developer roles. Being approximate is fine because a wrong answer here is a HINT, not a
+ *  decision — the authoritative value is the `scaffold` field on a real decision, which is what the
+ *  unknown case points at.
+ *
+ *  "developer" is included because it is OpenAI's newer name for the system role, and missing it
+ *  would tell a correctly built agent it is ineligible — worse than saying nothing. */
+export declare function scaffoldHint(entry: string | undefined): Promise<boolean | null>;
+/** Report whether this agent will actually earn Verified, and if not, exactly why.
+ *
+ *  Three things decide it and each fails silently on its own: routing (without it the platform sees
+ *  no calls at all), a system prompt (without one the harness cannot be fingerprinted, so the agent
+ *  is excluded from paired model comparison), and coverage (the share of decisions actually proven,
+ *  against the threshold the verified tier requires).
+ *
+ *  An agent can run perfectly and earn nothing. Nothing else in the toolchain says so, and learning
+ *  it from an empty leaderboard row weeks later is the failure this prevents. */
+export declare function printVerifiedReadiness(base: string, c: {
+    accessToken?: string;
+} | null, cfg: {
+    entry?: string;
+} | null): Promise<void>;
 export declare function apiRequest(method: string, url: string, token: string, body: unknown): Promise<[number, any]>;
 export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -918,9 +918,86 @@ async function cmdDoctor(a) {
         allOk = allOk && ok;
         console.log(`  ${ok ? OK : BAD} ${name.padEnd(20)} ${detail}`);
     }
+    // Verified-tier readiness. Separate from the checks above because none of these is a failure of
+    // the agent: it will run, it just will not be RANKED. Conflating the two trains people to ignore
+    // a red mark that sometimes means nothing.
+    //
+    // Mirrors the Python SDK's section deliberately, down to the wording, because a developer must
+    // not get a different answer about their own eligibility depending on which SDK they installed.
+    await printVerifiedReadiness(base, c, cfg);
     console.log("\n" + (allOk ? "✓ ready — `pyyol dev` to practice, `pyyol play <arena>` to compete." : "fix the ✗ items above."));
     return allOk ? 0 : 1;
 }
+/** True if the agent's entry file appears to send a system prompt, false if not, null if unknown.
+ *
+ *  A shallow source scan, deliberately: it recognises Anthropic's `system=` and OpenAI's system /
+ *  developer roles. Being approximate is fine because a wrong answer here is a HINT, not a
+ *  decision — the authoritative value is the `scaffold` field on a real decision, which is what the
+ *  unknown case points at.
+ *
+ *  "developer" is included because it is OpenAI's newer name for the system role, and missing it
+ *  would tell a correctly built agent it is ineligible — worse than saying nothing. */
+export async function scaffoldHint(entry) {
+    if (!entry)
+        return null;
+    const path = String(entry).split(":")[0];
+    try {
+        const { readFileSync } = await import("node:fs");
+        const src = readFileSync(path, "utf8");
+        return ["system:", "system =", '"system"', "'system'", '"developer"', "'developer'"].some((n) => src.includes(n));
+    }
+    catch {
+        return null;
+    }
+}
+/** Report whether this agent will actually earn Verified, and if not, exactly why.
+ *
+ *  Three things decide it and each fails silently on its own: routing (without it the platform sees
+ *  no calls at all), a system prompt (without one the harness cannot be fingerprinted, so the agent
+ *  is excluded from paired model comparison), and coverage (the share of decisions actually proven,
+ *  against the threshold the verified tier requires).
+ *
+ *  An agent can run perfectly and earn nothing. Nothing else in the toolchain says so, and learning
+ *  it from an empty leaderboard row weeks later is the failure this prevents. */
+export async function printVerifiedReadiness(base, c, cfg) {
+    const { gatewayBaseUrl } = await import("./instrument.js");
+    const { explain, ISSUE_NO_SYSTEM_PROMPT } = await import("./scaffold.js");
+    console.log("\nverified tier");
+    const routed = Boolean(gatewayBaseUrl("anthropic") || gatewayBaseUrl("openai"));
+    console.log(`  ${routed ? OK : WARN} ${"gateway routing".padEnd(20)} ` +
+        (routed
+            ? "on — model calls are server-observed"
+            : "off — call pyyol.route(client) after pyyol.instrument(); without it no decision can be " +
+                "proven and this agent cannot appear on the model board"));
+    const hint = await scaffoldHint(cfg?.entry);
+    if (hint === null) {
+        console.log(`  ${WARN} ${"system prompt".padEnd(20)} could not inspect the agent source; run \`pyyol dev\` ` +
+            "and check `scaffold` on a decision in the trace");
+    }
+    else if (hint) {
+        console.log(`  ${OK} ${"system prompt".padEnd(20)} found — the harness can be fingerprinted, so this ` +
+            "agent is eligible for paired model comparison");
+    }
+    else {
+        // The shared explanation, never a paraphrase: the SDKs, the trace and this command have to give
+        // a developer the same sentence about one rule.
+        console.log(`  ${WARN} ${"system prompt".padEnd(20)} none found. ${explain(ISSUE_NO_SYSTEM_PROMPT)}`);
+    }
+    if (base && c?.accessToken) {
+        const [st, body] = await apiGet(`${base}/v1/gw/coverage`, c.accessToken);
+        const b = body;
+        if (st === 200 && b?.decisions) {
+            const cov = Number(b.coverage ?? 0);
+            const mark = cov >= 0.9 ? OK : WARN;
+            console.log(`  ${mark} ${"coverage".padEnd(20)} ${b.bound_decisions ?? 0}/${b.decisions} decisions ` +
+                `proven (${(cov * 100).toFixed(1)}%)` +
+                (cov >= 0.9 ? "" : " — below the 90% the verified tier requires"));
+        }
+        else if (st === 200) {
+            console.log(`  ${WARN} ${"coverage".padEnd(20)} no decisions recorded yet — play a match first`);
+        }
+    }
+}
 async function cmdUpdate() {
     console.log(`pyyol ${SDK_VERSION}`);
     try {

package/dist/index.d.ts

@@ -27,4 +27,6 @@ export { instrument, uninstrument, recordResponse, extractUsage, patchPrototype
 export { route, enableGateway, disableGateway, gatewayBaseUrl, gatewayHeaders } from "./instrument.js";
 export type { ExtractedUsage } from "./instrument.js";
 export { estimateCost, rateFor, isKnown, canonical, PRICING_VERSION } from "./pricing.js";
+export { moveTool, moveToolChoice, moveToolName, moveFromResponse, boundMove, boundPlan, canonPlan, PLAN_KEY, MAX_SPAN_ROUNDS, canonMove, canonGoofspiel, canonMafia, canonMonopoly, NO_TARGET, TOOL_GOOFSPIEL, TOOL_MAFIA, TOOL_MONOPOLY, GAME_GOOFSPIEL, GAME_MAFIA, GAME_MONOPOLY, } from "./movetools.js";
 export type { Rate, CostArgs } from "./pricing.js";
+export { fingerprint as scaffoldFingerprint, fromRequest as scaffoldFromRequest, eligibleForPairing as scaffoldEligibleForPairing, SCAFFOLD_VERSION, } from "./scaffold.js";

package/dist/index.js

@@ -21,3 +21,14 @@ export { Tracer, Span, currentSpan, matchTraceId, currentUsage, UsageAccumulator
 export { instrument, uninstrument, recordResponse, extractUsage, patchPrototype } from "./instrument.js";
 export { route, enableGateway, disableGateway, gatewayBaseUrl, gatewayHeaders } from "./instrument.js";
 export { estimateCost, rateFor, isKnown, canonical, PRICING_VERSION } from "./pricing.js";
+// Structured move tools: how an agent proves its MODEL chose the move it played. Routing
+// through the gateway proves a call happened for a turn; a tool call is what proves the
+// model's answer became the move. See src/movetools.ts.
+export { moveTool, moveToolChoice, moveToolName, moveFromResponse, boundMove, 
+// Range bindings: one completion that decided several rounds. Coverage counts DECISIONS a
+// model made, not calls, so batching no longer costs an agent its verified share.
+boundPlan, canonPlan, PLAN_KEY, MAX_SPAN_ROUNDS, canonMove, canonGoofspiel, canonMafia, canonMonopoly, NO_TARGET, TOOL_GOOFSPIEL, TOOL_MAFIA, TOOL_MONOPOLY, GAME_GOOFSPIEL, GAME_MAFIA, GAME_MONOPOLY, } from "./movetools.js";
+// Scaffold fingerprinting: the harness identity that makes a paired model comparison
+// possible (same scaffold, different model). Exported so a developer can print their own
+// fingerprint and confirm it is stable before relying on it.
+export { fingerprint as scaffoldFingerprint, fromRequest as scaffoldFromRequest, eligibleForPairing as scaffoldEligibleForPairing, SCAFFOLD_VERSION, } from "./scaffold.js";

package/dist/instrument.d.ts

@@ -2,7 +2,15 @@ type Any = any;
 /** Enable gateway routing (called by the runtime in ranked mode; safe in tests). */
 export declare function enableGateway(agentKey: string, baseUrl: string): void;
 export declare function disableGateway(): void;
-/** The baseURL a provider client should point at, or "" if routing is off/unknown. */
+/**
+ * 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 declare function gatewayBaseUrl(provider: string): string;
 /** The X-Pyyol-* identity headers for the current turn (empty if routing off). */
 export declare function gatewayHeaders(): Record<string, string>;
@@ -11,7 +19,8 @@ export declare function gatewayHeaders(): Record<string, string>;
  *  `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 declare function resolveCallProvider(resource: Any, patchedAs: string): string;
 /** Point a provider client at the Pyyol Gateway (sets its baseURL). Explicit, robust
  *  opt-in that operates on the given instance. Returns the client. No-op when routing
@@ -22,9 +31,26 @@ export interface ExtractedUsage {
     provider: string;
     promptTokens: number;
     completionTokens: number;
+    /** Prompt-cache READ tokens. */
     cachedTokens: number;
+    /** Prompt-cache WRITE/creation tokens. Billed at 1.25x input on Anthropic, so an
+     *  agent's most expensive tokens were previously recorded as zero. */
+    cachedWriteTokens: number;
     reasoningTokens: number;
 }
+/**
+ * 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 declare function extractUsage(resp: Any): ExtractedUsage | null;
 /** Record usage from a provider response: compute cost, add to the turn
  *  accumulator, and emit a Lens model_call span. Returns the extracted usage (or
@@ -35,7 +61,7 @@ export declare function recordResponse(resp: Any, o?: {
 }): ExtractedUsage | null;
 /** @internal Wrap `proto[method]` so its resolved return value is recorded.
  *  Idempotent and fully guarded. Exported for tests. */
-export declare function patchPrototype(proto: Any, method: string, provider: string): boolean;
+export declare function patchPrototype(proto: Any, method: string, provider: string, endpoint?: string): boolean;
 /** Auto-capture LLM usage from installed providers. Pass e.g. `["openai"]` to limit
  *  which are patched; default patches all supported providers that are installed.
  *  Returns the list actually instrumented. Safe to call more than once. */