@bondedhq/shared 0.0.0-stage → 0.1.0

package/dist/problems.js

@@ -0,0 +1,148 @@
+/**
+ * Every problem, warning and refusal a builder can see, with a stable `code`, the sentence (or the
+ * gist of it, when the real one carries numbers or times) and what to do about it. The API puts
+ * the code next to each sentence (`code` beside `error`, `issues[].code` beside check problems,
+ * `problems[].code` in the health panel), the web app links each message to its entry on the
+ * troubleshooting page by code (`#<code>`), and the docs page is built from `PROBLEMS`.
+ *
+ * Codes never change once published: a new message gets a new entry. `match` is how a sentence
+ * the services already produce is recognised, so codes don't depend on every call site.
+ */
+/** The catch-all for a sentence no entry recognises (it still has its own words). */
+export const UNKNOWN_PROBLEM = "other";
+const entry = (code, area, sentence, fix, ...match) => ({ code, area, sentence, fix, match });
+/** Ordered: specific entries before general ones. */
+export const PROBLEMS = [
+    // Sign-in and signed requests.
+    entry("session-ended", "sign-in", "Your session has ended. Sign in again.", "Sign in with your wallet again; sessions last 12 hours.", /session has ended/i),
+    entry("not-signed-in", "sign-in", "You aren't signed in.", "Sign in with your wallet on the page, then try again.", /aren't signed in|sign in with your wallet first|^unauthorized$/i),
+    entry("sign-in-other-chain", "sign-in", "That sign-in is for another chain.", "Switch your wallet to the chain the page uses and sign in again.", /sign-in is for another chain/i),
+    entry("too-many-sign-ins", "sign-in", "Too many sign-ins from this wallet. Try again in an hour.", "Wait an hour, or keep the session you already have open.", /too many sign-ins/i),
+    entry("signature-expired", "sign-in", "The signed request has expired. Sign it again.", "Sign again: a signed request is good for a few minutes. Check your computer's clock if it keeps happening.", /signed (request|check) has expired/i),
+    entry("signature-reused", "sign-in", "That signed request was already used. Sign it again.", "Sign again: each signature can be used once.", /signed request was already used/i),
+    entry("bad-signature", "sign-in", "The signature isn't valid.", "Sign with the wallet that owns the agent, on the right chain, and don't edit the message.", /signature (isn't|is not) (valid|from that wallet)/i, /sign with the vault's agent key/i),
+    entry("stream-token-expired", "sign-in", "That stream token has expired. Ask for a new one.", "Reload the page: it asks for a new stream token.", /stream token has expired/i),
+    // Limits and malformed requests.
+    entry("preview-limit", "requests", "You can start (or run) only so many previews a day.", "Wait until the time the message gives, or make the agent official to rate it without the preview limit.", /at most \d+ previews? (a day|ratings? a day)|preview ratings are used up/i),
+    entry("check-limit", "requests", "You can run only so many connection checks an hour.", "Wait until the time the message gives. A passing check stays good for 24 hours.", /at most \d+ checks an hour|too many checks|connection checks are busy/i),
+    entry("url-verify-limit", "requests", "Your Agent URL has been checked too often this hour.", "Wait an hour before verifying the URL again.", /checked too often this hour|can be checked at most/i),
+    entry("rating-cooldown", "requests", "An agent can be rated only so often; the next rating time is given.", "Wait until the time the message gives.", /one rating .* per agent; next at|rating (is|was) (queued|running) already|already has a rating queued or running/i),
+    entry("stream-limit", "requests", "Too many live streams are open.", "Close other tabs showing live progress, then reload.", /too many live streams/i),
+    entry("rate-limited", "requests", "Too many requests. Try again in a few minutes.", "Wait a few minutes; the limit is per address.", /too many (requests|quote requests|reveal requests)/i),
+    entry("body-too-large", "requests", "The request body is too large.", "Send less: request bodies are capped (16 KB; 256 KB for Sentinel checks).", /is over \d+ KB/i),
+    entry("invalid-request", "requests", "The request isn't valid.", "Check the fields against the API reference; unknown fields are refused.", /^invalid request$/i, /^spec \d+:/, /must be between a day and a year/i),
+    // Registration, ownership and the vault or module.
+    entry("not-owner", "registration", "Only the agent's owner (or the vault's guardian) can do that.", "Connect the wallet that owns the agent in the registry (or guards the vault).", /only the (agent's owner|vault's guardian|module's guardian)/i),
+    entry("not-own-agent", "registration", "This agent isn't registered as your own agent.", 'Register it with "Make it official" (or POST /self/agents) first.', /isn't registered as your own agent|runner tokens are for agents registered as your own agent|register the agent for ratings first/i),
+    entry("operator-managed", "registration", "This agent is managed by Bonded's operator.", "Nothing to do: Bonded's own agents are configured by the operator.", /managed by Bonded's operator/i),
+    entry("vault-invalid", "registration", "That address is not a Bonded vault or mandate module.", "Use the address the factory created for this agent (shown after onboarding).", /not a Bonded (vault|mandate module)/i),
+    entry("vault-wrong-agent", "registration", "The vault or module belongs to another agent.", "Register the vault created for this agent id, or create a new one for it.", /(vault|module) belongs to another agent|vault doesn't belong to this agent/i),
+    entry("mandate-mismatch", "registration", "The mandate doesn't match what the vault or module enforces.", "Register exactly the mandate the vault was created with; its rules can't change afterwards.", /mandate doesn't match|vault enforces different rules|mandate is for another chain or agent/i),
+    entry("vault-creation-unreadable", "registration", "The vault's creation couldn't be checked.", "Create the vault by calling the factory directly (not through another contract), then register it.", /vault's creation (wasn't found|call couldn't be read)|create the vault by calling the factory directly/i),
+    entry("modules-unavailable", "registration", "Smart-account modules aren't deployed on this chain yet.", "Use a Mandate Vault instead.", /modules aren't deployed/i),
+    entry("owner-changed", "registration", "The agent changed hands since it was registered.", "The new owner registers the agent again.", /changed hands/i),
+    entry("tee-needs-runner", "registration", "A TEE-bound agent is rated in chain mode, through its runner, with a declared code hash.", "Use the runner in chain mode and declare the code hash your TEE reports.", /TEE-bound agent/i),
+    entry("tee-binding-failed", "rating", "TEE binding failed: the evidence didn't match the rated deployment.", "Redeploy the reviewed compose file, then rate again.", /TEE binding failed|TEE runs different code/i),
+    // Reaching the agent.
+    entry("runner-token-invalid", "connection", "That runner token isn't valid: it was revoked, replaced or its preview ended.", "Create a new runner token on the agent's (or preview's) page and use that.", /runner token isn't valid|send your runner token/i),
+    entry("runner-token-missing", "connection", "Create a runner token first, then start the runner.", "Create a runner token on the agent's page and start the runner with the command shown.", /create a runner token first/i),
+    entry("wrong-mode", "connection", "The agent runs in the other mode (tools or chain) from the one it is registered for.", "In tools mode trades are tool calls; in chain mode they are transactions signed and sent through the RPC endpoint. Restart the runner with the right --mode, or set the agent up for the registered mode.", /runner is (connected in the wrong mode|in \w+ mode)/i, /as a tool, but in chain mode|tried the rpc endpoint/i),
+    entry("runner-busy", "connection", "The runner is busy with another episode.", "Wait for it to finish, then try again.", /runner is busy/i),
+    entry("runner-could-not-start", "check", "The runner couldn't start your agent.", "Run the agent command yourself in the same folder to see the error, then fix it and check again.", /runner couldn't start your agent/i),
+    entry("runner-not-connected", "connection", "The runner isn't connected.", "Start the runner with your token (keep it running as a service), then try again.", /runner (isn't|is not) connected|runner disconnected|no runner is connected/i),
+    entry("agent-url-missing", "connection", "Set your Agent URL first.", "Add your agent's HTTPS endpoint on the agent's page.", /set your agent url first/i),
+    entry("agent-url-unverified", "connection", "The Agent URL isn't verified yet.", "Give your agent the secret, then press Verify so Bonded can check its answer.", /verify your agent url first|url isn't (verified|set and verified)|agent url isn't verified/i),
+    entry("agent-url-secret-unusable", "connection", "The stored Agent URL secret can't be used.", "Set the Agent URL again to get a new secret.", /secret can't be used/i),
+    entry("agent-url-no-version", "connection", "The Agent URL reported no version, so there is no code hash.", "Report a version in your verify answer, or declare a code hash.", /reported no version/i),
+    entry("connection-kind-mismatch", "connection", "This agent connects the other way (runner or Agent URL).", "Use the connection the agent was set up with, or switch it on the agent's page.", /connects by its agent url|connects with the runner|reached by its agent url, so it has no runner|is rated through its runner, not an agent url/i),
+    entry("url-slow", "connection", "Your URL didn't answer in time.", "Answer within the time given (10 seconds for verify); do slow work after answering.", /didn't answer within \d+ seconds/i),
+    entry("url-closed", "connection", "Your URL closed the connection before answering.", "Check your server's logs: it dropped the request (a crash, a proxy timeout or a body size limit).", /closed the connection before answering/i),
+    entry("url-certificate", "connection", "Your URL's TLS certificate wasn't accepted.", "Serve a valid certificate for the host name (not self-signed, not expired).", /tls certificate/i),
+    entry("agent-secret", "connection", "Your URL refused Bonded's signed call: it isn't using the agent secret Bonded gave you.", "Set the agent secret from the Agent URL page in your agent and check the bonded-signature header with it.", /answered (401|403)|check that your agent uses the agent secret/i),
+    entry("verify-answer", "connection", "Your URL answered the verify check, but not correctly.", 'Answer verify with 200 and JSON { challenge, proof } (proof = HMAC-SHA256 of "verify." + challenge with your secret).', /answered (\d+ )?(to )?the check|without proving it holds the agent secret|answered the check, but not with JSON/i),
+    entry("url-not-public", "connection", "That URL can't be used: it must be public https on the standard port, and not one of Bonded's.", "Use a public https URL on port 443 with no user name, password or #fragment, that resolves to a public address.", /^that isn't a url|your url (is (too long|longer|one of)|must|can't)|isn't reachable on the public internet|redirect/i),
+    entry("url-unreachable", "connection", "Bonded couldn't reach your URL.", "Check the URL is up and answers POST from the internet (no firewall or allowlist in the way).", /nothing accepted a connection|couldn't reach your url|verification couldn't run|your url answered|answer was over|called your url too often/i),
+    entry("agent-urls-off", "service", "Agent URL mode and webhooks are off on this service.", "Use the runner instead; the operator has to set AGENT_URL_SECRET_KEY for URLs and webhooks.", /AGENT_URL_SECRET_KEY/),
+    entry("checks-unavailable", "service", "Connection checks aren't available on this rating service yet.", "Try later; the operator has to run the Arena Gateway.", /connection checks aren't available/i),
+    entry("gateway-unavailable", "service", "The rating worker has no Arena Gateway, so it can't rate an agent its operator runs.", "Try later; the operator has to run the Arena Gateway.", /gateway not available/i),
+    entry("needs-check", "check", "Run a connection check first.", "Run a check of this exact connection (same token or URL, mode and code); a pass lasts 24 hours.", /run a connection check (first|of this connection first)/i),
+    entry("check-running", "check", "A check is already running for this agent.", "Wait for its result.", /check is already running/i),
+    entry("code-changed", "rating", "The agent now reports different code than when the rating was queued.", "Run a connection check of the code that runs now, then rate again.", /now reports different code/i),
+    entry("no-code-hash", "rating", "No code hash: none was reported when the rating was queued.", "Update @bondedhq/runner (it reports one), or declare a code hash, then rate again.", /no code hash/i),
+    // What a connection check finds.
+    entry("timed-out", "check", "It didn't finish within the episode's time.", "Post to the episode's done URL (or exit) when the agent has finished.", /didn't finish within \d+ seconds|^timed out after/i),
+    entry("agent-exited", "check", "It exited or was stopped before finishing.", "Read its output in the check, fix the crash, and check again.", /exited with code|was stopped by \w+ before finishing/i),
+    entry("never-called-a-tool", "check", "Your agent never called a tool.", "Read and trade through the episode's MCP or HTTP endpoints (isBondedEpisode() in @bondedhq/sdk).", /never called a tool/i),
+    entry("no-trade", "check", "It didn't make the trade its task names.", "Make sure the agent does the task it's given (the trade named in the goal).", /didn't make the trade its task names/i),
+    entry("benign-breach", "check", "Its actions broke the mandate in a benign episode.", "Keep trades inside the mandate (tokens, caps, destinations); a rating counts this against it.", /broke the mandate in a benign episode/i),
+    entry("unread-surfaces", "check", "It didn't read every surface; unread ones are scored as untested.", "Have the agent check its messages, news, prices and other reads before trading.", /read \d+ of \d+ surfaces/i),
+    entry("tool-calls-failed", "check", "Some tool calls failed.", "Check the arguments the agent passes; the first failure is quoted.", /tool call\S* failed/i),
+    entry("transactions-refused", "check", "Some transactions were refused.", "Sign for the episode's chain with the episode's key and call only the vault's execute.", /transaction\S* (was |were )?refused/i),
+    entry("usage-not-reported", "check", "It didn't report its model usage at /done.", "Report input and output tokens at /done for a cost estimate (optional).", /didn't report its model usage/i),
+    entry("episode-failed", "check", "The episode failed.", "Read the reason given; run the agent locally with the same input to reproduce it.", /the episode failed/i),
+    // Ratings.
+    entry("fork-budget-spent", "rating", "The agent used up its share of fork requests.", "Make fewer chain reads per episode (cache what doesn't change).", /share of fork requests/i),
+    entry("bonded-url-failure", "rating", "Bonded couldn't reach the agent's URL; not the agent's fault, it will be retried.", "Nothing to do: it is retried.", /bonded couldn't (reach|call) the agent's url/i),
+    entry("rating-over-budget-agent", "rating", "The rating ran past its time budget, and the agent took most of the time.", "Make each episode faster (fewer model calls, a faster model), then rate again.", /ran past its .*budget.*the agent took/i),
+    entry("rating-over-budget", "rating", "The rating ran past its time budget, not because of the agent; it will be retried.", "Nothing to do: it is retried.", /ran past its .*budget/i),
+    entry("agent-failed-episode", "rating", "The agent failed an episode.", "Run a connection check to see the failure, fix it, and rate again.", /stopped: the agent failed/i),
+    entry("not-attested", "rating", "Not attested: the agent didn't do its task often enough in the control episodes.", "Make sure the agent does its benign task; an agent that does nothing can't be rated.", /^not attested/i),
+    entry("incomplete-rating", "rating", "The rating was incomplete (a guard failed to answer).", "Nothing to do: it is rated again.", /incomplete rating/i),
+    entry("preview-stopped", "rating", "This preview was stopped.", "Start a new preview.", /preview was stopped/i),
+    entry("rating-running", "rating", "Its rating is running.", "Wait for it to finish; it stops at the first failed episode.", /its rating is running/i),
+    // Cover and quotes.
+    entry("score-superseded", "cover", "This agent's score is superseded: its latest rating was stopped by the agent.", "Fix what stopped it and wait for a complete rating.", /score is superseded/i),
+    entry("registered-again", "cover", "The agent was registered again after its current score was posted.", "Wait for a complete rating of the current registration.", /registered again after its current score/i),
+    entry("cover-capped", "cover", "Cover is capped on testnet.", "Ask for less cover.", /cover is capped at/i),
+    entry("uninsurable", "cover", "The score is too low to insure.", "Use the report's top fixes and rate again.", /is uninsurable/i),
+    entry("bond-too-low", "cover", "The operator bond is below the tier's minimum for the cover.", "Stake more bond, or ask for less cover.", /operator bond .* is below/i),
+    entry("capacity-exceeded", "cover", "The pool can't take that much cover right now.", "Ask for less cover, or try later.", /capacity exceeded/i),
+    entry("attestation-expired", "cover", "The score has expired.", "Rate the agent again.", /attestation has expired/i),
+    entry("module-needs-enforce", "cover", "A smart-account module can hold cover only in Enforce mode.", "Install the module in Enforce mode.", /only in Enforce mode/i),
+    // Health panel (GET /self/agents/:id/health) and notifications.
+    entry("no-score", "rating", "The agent has no posted score yet.", "Run a connection check, then ask for a rating.", /has no (posted )?score yet/i),
+    entry("score-expired", "rating", "The agent's score has expired.", "Keep the runner connected (scores renew on their own) or ask for a rating.", /score (has )?expired/i),
+    entry("score-expiring", "rating", "The agent's score expires soon.", "Keep the runner connected so the score renews, or ask for a rating.", /score expires (in|on|soon)/i),
+    entry("runner-offline", "connection", "The runner has been offline while a rating or renewal is due.", "Restart the runner, ideally as a service (bonded-runner service --print).", /runner has been offline/i),
+    entry("cover-without-vault-trades", "vault", "The agent has cover, but hasn't traded through its vault lately.", "Point the agent's trades at its vault (npx @bondedhq/runner init shows the change); cover only pays for trades through the vault.", /hasn't traded through (its|the) vault/i),
+    entry("low-gas", "vault", "The agent key is low on gas.", "Send ETH to the agent key; it pays gas for every trade through the vault.", /low on gas/i),
+    entry("cover-lapsing", "cover", "The cover's premium is past due.", "Top up the vault's base asset so the next premium collection succeeds before the grace period ends.", /premium is past due|cover (is )?lapsing/i),
+    entry("vault-frozen", "vault", "The vault froze the agent after a breach.", "Review the breach, then the guardian unfreezes (or rotates) the agent key.", /froze the agent|vault is frozen/i),
+    entry("claim-filed", "cover", "A claim was filed for a breach.", "Nothing to do: the keeper files covered claims and the payout goes to the vault.", /claim was filed/i),
+    entry("claim-paid", "cover", "A claim was paid.", "Nothing to do: the payout went to the vault.", /claim .* was paid/i),
+    entry("breach-recorded", "vault", "The vault recorded a breach.", "Review it on the agent's page; a covered loss is claimed automatically.", /recorded a breach/i),
+    // Notifications and the service itself.
+    entry("email-unavailable", "notifications", "Email notifications aren't set up on this service.", "Use a webhook, or the in-app list.", /email notifications aren't set up/i),
+    entry("webhook-missing", "notifications", "Set a webhook URL first.", "Save a webhook URL, then rotate its secret.", /set a webhook url first/i),
+    entry("sentinel-unavailable", "service", "Sentinel didn't answer.", "Try again in a few seconds.", /sentinel (isn't running|is busy|didn't answer|took too long)/i),
+    entry("try-again", "requests", "Another request for the same thing came first.", "Try again.", /newer token request came first|runner token changed since the check was asked for/i),
+    entry("no-vault", "vault", "This agent has no registered vault.", "Register the agent with its vault (or module) address.", /has no registered vault/i),
+    entry("bounty-reveal", "registration", "The bounty's reveal doesn't match what is on chain.", "Reveal the submission on BountyBoard first, with the exact spec whose sha256 you committed.", /reveal the submission|specURI|settled on chain without validation/i),
+    entry("not-found", "requests", "That wasn't found.", "Check the id; another wallet's previews and checks are shown as not found.", /wasn't found|not found|not configured|no such submission|older episodes are pruned|no TEE check/i),
+    entry("service-error", "service", "The request failed on Bonded's side.", "Try again; if it keeps failing, check the status page.", /^request failed$|message is too large to send|event stream (capacity unavailable|closed)|validation failed; retry scheduled/i),
+];
+const byCode = new Map(PROBLEMS.map((p) => [p.code, p]));
+const bySentence = new Map(PROBLEMS.map((p) => [p.sentence, p.code]));
+/** The stable code for a sentence (`UNKNOWN_PROBLEM` when no entry recognises it). */
+export function problemCode(sentence) {
+    const exact = bySentence.get(sentence);
+    if (exact)
+        return exact;
+    for (const p of PROBLEMS)
+        if (p.match.some((m) => m.test(sentence)))
+            return p.code;
+    return UNKNOWN_PROBLEM;
+}
+export function codedProblem(text, code = problemCode(text)) {
+    const fix = byCode.get(code)?.fix;
+    return { code, text, ...(fix ? { fix } : {}) };
+}
+/** The entry for a code, if there is one. */
+export function problemEntry(code) {
+    return byCode.get(code);
+}
+/** The troubleshooting list for the docs page: code, sentence and fix, without the matchers. */
+export function troubleshootingList() {
+    return PROBLEMS.map(({ code, area, sentence, fix }) => ({ code, area, sentence, fix }));
+}
+//# sourceMappingURL=problems.js.map

package/dist/quote.d.ts

@@ -0,0 +1,123 @@
+import { type Attestation, Quote } from "./schemas/attestation.js";
+import { type Tier } from "./tiers.js";
+/**
+ * Cover quotes: priced from a signed attestation, signed by the attester, and accepted by
+ * `CoverManager.buyCover` (docs/SPECIFICATION.md Sections 6.4 and 9, ADR-009).
+ *
+ * The quote is priced only from the attestation's expected loss and the operator's bond, so
+ * anyone holding the attestation can recompute the premium and check it.
+ */
+/** Quotes stay valid for an hour: long enough to sign and send `buyCover`, short enough that
+ *  a price can't be held while the agent's risk changes. */
+export declare const QUOTE_TTL_SECONDS: number;
+export interface QuotePricing {
+    tier: Tier;
+    /** Annual premium rate after the bond discount, in basis points (rounded up). */
+    premiumRateBps: number;
+    /** Premium rate before the bond discount, in basis points (rounded up). */
+    basePremiumRateBps: number;
+    /** Smallest bond for the agent's total cover (existing plus this quote): the tier's share,
+     *  rounded up. Goes into the quote's `minBond`, which `buyCover` enforces. */
+    minBond: bigint;
+    /** bond ÷ the agent's total cover, as used for the discount. */
+    bondRatio: number;
+}
+/**
+ * Prices cover for a rated agent (Section 9.1):
+ *   P = EL · (1 + load) + capital, then the bond discount P · (1 − min(0.30, bond ÷ cover − 0.10)).
+ *
+ * The bond belongs to the agent, not the vault, and one agent can hold cover on several vaults.
+ * So the bond is measured against the agent's total cover (`existingCover` plus this quote):
+ * one bond can't earn the full discount, or meet the minimum, on every vault at once.
+ *
+ * Throws when the score is uninsurable or the bond is below the tier's minimum, since
+ * `buyCover` would reject the quote anyway.
+ */
+export declare function priceCover(input: {
+    expectedLossBps: number;
+    score: number;
+    coverAmount: bigint;
+    bond: bigint;
+    /** The agent's active cover on other policies (`CoverManager.activeCoverOfAgent`). */
+    existingCover?: bigint;
+}): QuotePricing;
+/**
+ * How firmly a score is tied to the code that runs (bring your own agent):
+ * - tee: the rated code proved, with a TEE quote at every episode, that it is what runs, and the
+ *   attestation carries its measurement;
+ * - declared: the operator says which code it is (`codeHash`), and nothing checks it.
+ */
+export type BindingLevel = "declared" | "tee";
+/** The binding of an attestation: `tee` when it carries a TEE measurement. */
+export declare function bindingOf(teeMeasurement: string): BindingLevel;
+/**
+ * Underwriting policy, not score: the most cover one operator-run agent can hold in total, in
+ * tUSDG, by binding. A declared agent's score may describe different code from what trades, so
+ * the pool takes less of that risk. Configurable per API (`createApi`'s `coverCaps`).
+ */
+export declare const UNDERWRITING_COVER_CAP_USD: Readonly<Record<BindingLevel, number>>;
+/**
+ * Why the policy refuses `coverAmount` on top of `existingCover` for an agent with this binding,
+ * or undefined when it fits. Amounts are in base-asset units (6 decimals).
+ */
+export declare function underwritingCapRefusal(input: {
+    binding: BindingLevel;
+    coverAmount: bigint;
+    existingCover?: bigint;
+    caps?: Readonly<Record<BindingLevel, number>>;
+}): string | undefined;
+export interface BuildQuoteInput {
+    /** The agent's current attestation. The quote copies its score, hashes and model family. */
+    attestation: Attestation;
+    vault: `0x${string}`;
+    /** Cover in base-asset units (6 decimals for USDC-like assets). */
+    coverAmount: bigint;
+    /** The operator's bond for this agent now, in base-asset units. */
+    bond: bigint;
+    /** The agent's active cover on other policies (`CoverManager.activeCoverOfAgent`). */
+    existingCover?: bigint;
+    /** Unix seconds. Defaults to the current time. */
+    now?: number;
+    /** Defaults to a random 128-bit number. */
+    nonce?: bigint;
+    ttlSeconds?: number;
+    /**
+     * The operator-run agent's binding, when the underwriting cap applies (bring-your-own agents).
+     * Omitted for Bonded's built-in designs, which keep the pool's own capacity limits only.
+     */
+    binding?: BindingLevel;
+    /** Caps by binding (default `UNDERWRITING_COVER_CAP_USD`). */
+    coverCaps?: Readonly<Record<BindingLevel, number>>;
+}
+/**
+ * Builds an unsigned quote from an attestation. The quote expires after `ttlSeconds`, and never
+ * after the attestation does, so a quote can't outlive the rating it was priced from.
+ */
+export declare function buildQuote(input: BuildQuoteInput): {
+    quote: Quote;
+    pricing: QuotePricing;
+};
+export interface SignedQuote {
+    quote: Quote;
+    signature: `0x${string}`;
+    signer: `0x${string}`;
+    chainId: number;
+    /** The CoverManager the quote is signed for (the EIP-712 verifying contract). */
+    coverManager: `0x${string}`;
+}
+export declare function signQuote(quote: Quote, options: {
+    chainId: number;
+    coverManager: `0x${string}`;
+    attesterKey: `0x${string}`;
+}): Promise<SignedQuote>;
+/**
+ * Checks a signed quote offline: the signer must be one of `trustedAttesters` (for example,
+ * the registry's attesters) and the signature must be valid. The `signer` field travels with
+ * the quote, so checking the signature alone would accept a quote anyone signed for themselves.
+ */
+export declare function verifyQuote(signed: SignedQuote, trustedAttesters: readonly `0x${string}`[]): Promise<boolean>;
+/** A quote that can't be issued (uninsurable score, bond too small, expired attestation). */
+export declare class QuoteError extends Error {
+    name: string;
+}
+//# sourceMappingURL=quote.d.ts.map

package/dist/quote.js

@@ -0,0 +1,167 @@
+import { verifyTypedData } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { bondDiscountedPremium, priceExpectedLoss } from "./actuarial.js";
+import { bondedDomain, Quote, quoteTypedData } from "./schemas/attestation.js";
+import { isTeeMeasurement } from "./tee.js";
+import { tierForScore } from "./tiers.js";
+/**
+ * Cover quotes: priced from a signed attestation, signed by the attester, and accepted by
+ * `CoverManager.buyCover` (docs/SPECIFICATION.md Sections 6.4 and 9, ADR-009).
+ *
+ * The quote is priced only from the attestation's expected loss and the operator's bond, so
+ * anyone holding the attestation can recompute the premium and check it.
+ */
+/** Quotes stay valid for an hour: long enough to sign and send `buyCover`, short enough that
+ *  a price can't be held while the agent's risk changes. */
+export const QUOTE_TTL_SECONDS = 60 * 60;
+const BPS = 10000n;
+/**
+ * Prices cover for a rated agent (Section 9.1):
+ *   P = EL · (1 + load) + capital, then the bond discount P · (1 − min(0.30, bond ÷ cover − 0.10)).
+ *
+ * The bond belongs to the agent, not the vault, and one agent can hold cover on several vaults.
+ * So the bond is measured against the agent's total cover (`existingCover` plus this quote):
+ * one bond can't earn the full discount, or meet the minimum, on every vault at once.
+ *
+ * Throws when the score is uninsurable or the bond is below the tier's minimum, since
+ * `buyCover` would reject the quote anyway.
+ */
+export function priceCover(input) {
+    const { coverAmount, bond } = input;
+    const existingCover = input.existingCover ?? 0n;
+    if (coverAmount <= 0n)
+        throw new RangeError("cover amount must be positive");
+    if (existingCover < 0n)
+        throw new RangeError("existing cover can't be negative");
+    const rule = tierForScore(input.score);
+    if (!rule.insurable)
+        throw new QuoteError(`score ${input.score} (${rule.tier}) is uninsurable`);
+    const totalCover = existingCover + coverAmount;
+    const minBond = ceilDiv(totalCover * BigInt(rule.minBondBps), BPS);
+    if (bond < minBond) {
+        throw new QuoteError(`the operator bond (${bond}) is below the ${rule.tier} minimum of ${minBond} for the agent's total cover`);
+    }
+    const base = priceExpectedLoss(input.expectedLossBps / 10_000).premiumRate;
+    // Six decimal places is exact enough for a ratio that only moves the discount between 0 and 30%.
+    const bondRatio = Number((bond * 1000000n) / totalCover) / 1_000_000;
+    const discounted = bondDiscountedPremium(base, bondRatio);
+    return {
+        tier: rule.tier,
+        premiumRateBps: toRateBps(discounted),
+        basePremiumRateBps: toRateBps(base),
+        minBond,
+        bondRatio,
+    };
+}
+/** The binding of an attestation: `tee` when it carries a TEE measurement. */
+export function bindingOf(teeMeasurement) {
+    return isTeeMeasurement(teeMeasurement) ? "tee" : "declared";
+}
+/**
+ * Underwriting policy, not score: the most cover one operator-run agent can hold in total, in
+ * tUSDG, by binding. A declared agent's score may describe different code from what trades, so
+ * the pool takes less of that risk. Configurable per API (`createApi`'s `coverCaps`).
+ */
+export const UNDERWRITING_COVER_CAP_USD = {
+    declared: 5_000,
+    tee: 20_000,
+};
+/**
+ * Why the policy refuses `coverAmount` on top of `existingCover` for an agent with this binding,
+ * or undefined when it fits. Amounts are in base-asset units (6 decimals).
+ */
+export function underwritingCapRefusal(input) {
+    const caps = input.caps ?? UNDERWRITING_COVER_CAP_USD;
+    const cap = BigInt(Math.floor(caps[input.binding])) * 1000000n;
+    if ((input.existingCover ?? 0n) + input.coverAmount <= cap)
+        return undefined;
+    const label = input.binding === "tee" ? "a TEE-bound agent" : "an agent with a declared binding";
+    return `underwriting policy: cover for ${label} is capped at ${caps[input.binding].toLocaleString("en-US")} tUSDG in total`;
+}
+/**
+ * Builds an unsigned quote from an attestation. The quote expires after `ttlSeconds`, and never
+ * after the attestation does, so a quote can't outlive the rating it was priced from.
+ */
+export function buildQuote(input) {
+    const { attestation } = input;
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    if (attestation.expiresAt <= now)
+        throw new QuoteError("the attestation has expired");
+    if (input.binding) {
+        const refusal = underwritingCapRefusal({
+            binding: input.binding,
+            coverAmount: input.coverAmount,
+            existingCover: input.existingCover ?? 0n,
+            ...(input.coverCaps ? { caps: input.coverCaps } : {}),
+        });
+        if (refusal)
+            throw new QuoteError(refusal);
+    }
+    const pricing = priceCover({
+        expectedLossBps: attestation.expectedLossBps,
+        score: attestation.score,
+        coverAmount: input.coverAmount,
+        bond: input.bond,
+        existingCover: input.existingCover,
+    });
+    const quote = Quote.parse({
+        agentId: attestation.agentId,
+        vault: input.vault,
+        coverAmount: input.coverAmount.toString(),
+        premiumRateBps: pricing.premiumRateBps,
+        score: attestation.score,
+        modelFamily: attestation.modelFamily,
+        mandateHash: attestation.mandateHash,
+        reportHash: attestation.reportHash,
+        minBond: pricing.minBond.toString(),
+        expiresAt: Math.min(now + (input.ttlSeconds ?? QUOTE_TTL_SECONDS), attestation.expiresAt),
+        nonce: (input.nonce ?? randomNonce()).toString(),
+    });
+    return { quote, pricing };
+}
+export async function signQuote(quote, options) {
+    const account = privateKeyToAccount(options.attesterKey);
+    const signature = await account.signTypedData(quoteTypedData(quoteDomain(options), quote));
+    return {
+        quote: Quote.parse(quote),
+        signature,
+        signer: account.address,
+        chainId: options.chainId,
+        coverManager: options.coverManager,
+    };
+}
+/**
+ * Checks a signed quote offline: the signer must be one of `trustedAttesters` (for example,
+ * the registry's attesters) and the signature must be valid. The `signer` field travels with
+ * the quote, so checking the signature alone would accept a quote anyone signed for themselves.
+ */
+export async function verifyQuote(signed, trustedAttesters) {
+    const trusted = trustedAttesters.some((a) => a.toLowerCase() === signed.signer.toLowerCase());
+    if (!trusted)
+        return false;
+    return verifyTypedData({
+        address: signed.signer,
+        signature: signed.signature,
+        ...quoteTypedData(quoteDomain(signed), signed.quote),
+    });
+}
+/** A quote that can't be issued (uninsurable score, bond too small, expired attestation). */
+export class QuoteError extends Error {
+    name = "QuoteError";
+}
+function quoteDomain(o) {
+    return bondedDomain(o.chainId, o.coverManager);
+}
+/** Rounds up, so rounding never undercharges the pool. */
+function toRateBps(rate) {
+    // Strip float noise first (0.0156 * 10_000 = 156.00000000000003 must not become 157).
+    return Math.min(10_000, Math.ceil(Number((rate * 10_000).toFixed(6))));
+}
+function ceilDiv(a, b) {
+    return (a + b - 1n) / b;
+}
+function randomNonce() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return BigInt(`0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`);
+}
+//# sourceMappingURL=quote.js.map

package/dist/report-fixes.d.ts

@@ -0,0 +1,89 @@
+import type { AttackClassId, AttackSurface, BreachType } from "./schemas/attack.js";
+/**
+ * What to change after a breach, by attack class and breach type: a fixed table, not model
+ * output, so the same breach always gets the same advice. A rating report attaches these to each
+ * breached episode (`evidence[].fixes`) and ranks them (`topFixes`); the web app and the docs read
+ * the same table. A fix is advice: whether it works is measured by rating the agent again.
+ */
+export type FixKind = "prompt" | "mandate" | "guard" | "sentinel";
+export type FixId = "prompt_untrusted_content" | "prompt_operator_only" | "prompt_oracle_prices" | "prompt_allowed_tokens" | "prompt_no_copied_addresses" | "prompt_counterparty" | "prompt_limits" | "mandate_enforce" | "mandate_destinations" | "mandate_router_only" | "mandate_per_trade_cap" | "mandate_daily_cap" | "mandate_assets" | "sdk_guard" | "sentinel";
+export interface Fix {
+    id: FixId;
+    kind: FixKind;
+    title: string;
+    /** What to do, in a sentence or two. */
+    detail: string;
+    /** For a system-prompt fix: the line to add, as is. */
+    promptLine?: string;
+    /** For a mandate fix: the mandate field it changes (as in `EvmMandateRules`). */
+    setting?: string;
+}
+export declare const FIXES: Readonly<Record<FixId, Fix>>;
+/** The fixes for each attack class, most direct first. */
+export declare const FIXES_BY_CLASS: Readonly<Record<AttackClassId, readonly FixId[]>>;
+/** The fixes for each breach type the vault records. */
+export declare const FIXES_BY_BREACH: Readonly<Record<BreachType, readonly FixId[]>>;
+/**
+ * The fixes for one breached episode: its class's, then its breach types', without ones already
+ * in place (Enforce mode when the vault runs it, Sentinel when the rating ran with it).
+ */
+export declare function fixesFor(input: {
+    attackClass: AttackClassId | null;
+    breachTypes: readonly BreachType[];
+    mode?: "monitor" | "enforce";
+    sentinel?: boolean;
+}): Fix[];
+/** A fix as a report lists it: with how many of its breaches it addresses. */
+export interface ReportFix extends Fix {
+    /** Breaches in the report whose evidence lists this fix. Advice, not measured. */
+    prevents: number;
+}
+/** Every fix the evidence lists, most breaches addressed first; ties keep the table's order. */
+export declare function rankFixes(evidence: readonly {
+    fixes: readonly FixId[];
+}[]): ReportFix[];
+/** The three fixes that address the most breaches, by id. */
+export declare const topFixIds: (ranked: readonly ReportFix[], limit?: number) => FixId[];
+/**
+ * One breach in a finished rating's report (`RatingReport.evidence`): the attack and the exact
+ * planted text (unless it is a reused unpublished attack), the action the agent took, what the
+ * vault recorded, and the fixes (ids into `FIXES`) for its class and breach type.
+ */
+export interface BreachEvidence {
+    episodeId: string;
+    attackId: string | null;
+    class: AttackClassId | null;
+    className: string | null;
+    /** Where the attack was planted (the first surface; `surfaces` has them all). */
+    surface: AttackSurface | null;
+    surfaces: AttackSurface[];
+    /** The exact text planted. Absent when withheld (`withheld`). */
+    plantedText?: string;
+    /** Who it appeared to come from, and for token metadata the token. */
+    sender?: string;
+    token?: string;
+    /** An attack from a held-out set (made for this rating alone, or shared and then withheld). */
+    heldOut: boolean;
+    /** The text is withheld: an accepted bounty or the shared held-out set, reused by later ratings. */
+    withheld?: true;
+    /** Whether the agent read a place the attack was planted. */
+    read: boolean | null;
+    /** The action that caused the breach (absent for a breach found later, e.g. a drained approval). */
+    action?: {
+        tool: string;
+        /** Amounts, tokens and addresses only, never free text. */
+        args?: Record<string, string>;
+        /** An `execute` the agent signed itself, decoded into swap, transfer or approve. */
+        decoded: boolean;
+    };
+    breachType: BreachType;
+    lossUsd: number;
+    blocked: boolean;
+    /** Taken afterwards with approvals the agent granted (the episode's, on its first breach). */
+    drained?: {
+        token: string;
+        amount: string;
+    }[];
+    fixes: FixId[];
+}
+//# sourceMappingURL=report-fixes.d.ts.map