@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/dist/cli/wallet.js

@@ -1,6 +1,7 @@
 import { privateKeyToAccount } from "viem/accounts";
 import { resolveAgentWallet } from "../wallet/provider.js";
 import { configError } from "./errors.js";
+import { PRIVY_ENV_VARS, PRIVY_SESSION_ENV_VARS, PRIVY_WALLET_KEY_ENV, resolvePrivyCliWallet, } from "./privy.js";
 /**
  * The ONLY place the CLI resolves a signing wallet.
  *
@@ -12,35 +13,36 @@ import { configError } from "./errors.js";
  *
  * ## Resolution order (first match wins, checked in this order)
  *
- *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
+ *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw testnet key.
  *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
  *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
+ *     broker, either agent-owned (`METRIK_AGENT_PRIVY_WALLET_KEY`) or a
+ *     user-owned broker session. See `./privy.ts`.
  *
- * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
- * one environment configures every surface the same way. It is checked in a
- * FIXED order rather than "whichever is configured", because an environment
- * carrying both is ambiguous about which address funds the stream — and that
- * ambiguity is a fund-moving one. When both are present the private key wins
- * and `resolveCliWallet` says so on stderr rather than silently picking.
+ * The first two match `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures those surfaces the same way. The order is FIXED
+ * rather than "whichever is configured", because an environment carrying two is
+ * ambiguous about which address funds the stream — and that ambiguity is a
+ * fund-moving one. When more than one is present the earlier entry wins and
+ * `resolveCliWallet` says so on stderr rather than silently picking.
  *
- * ## Why CDP is wired and Privy is not
+ * ## What is different about Privy
  *
- * CDP is the only wallet path in this package with live CI evidence
- * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
- * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
- * viem local account, so it drops straight into the CLI's existing
- * `http(rpcUrl)` transport with no other change.
+ * A private key and a CDP account both sign LOCALLY: `privateKeyToAccount()`
+ * and `toAccount(cdpServerAccount)` are viem local accounts, so they drop
+ * straight into the CLI's `http(rpcUrl)` transport with no other change.
  *
- * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
- * account with no `signTransaction`: they sign and broadcast by sending
- * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
- * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
- * that into the CLI is not a matter of reading three more variables — it
- * changes the transport for every fund-moving command, and `metrik invoke`
- * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
- * `assertLocalSigner` below therefore REFUSES a non-local account with that
- * fact, instead of accepting one and failing later inside viem. See
- * `docs/cli.md` § Wallet.
+ * Privy does not. Its account is a JSON-RPC account with no `signTransaction`:
+ * it signs and broadcasts by sending `eth_sendTransaction` /
+ * `eth_signTypedData_v4` to a provider, so the wallet client's TRANSPORT must
+ * be that provider rather than a plain RPC. That is what {@link CliWallet.transport}
+ * carries, and the only reason this file knows Privy exists. The signer check
+ * below is therefore about CAPABILITY, not about locality: it refuses an
+ * account that genuinely cannot sign, and refuses a non-local account only on
+ * the paths that broadcast through `--rpc-url`.
+ *
+ * See `docs/cli.md` § Wallet.
  */
 export const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
 /** Every environment variable the CDP path reads. Named in errors, never printed. */
@@ -50,26 +52,41 @@ export const CDP_ENV_VARS = [
     "CDP_WALLET_SECRET",
     "METRIK_AGENT_CDP_OWNER_NAME",
 ];
+export { PRIVY_ENV_VARS, PRIVY_SESSION_ENV_VARS, PRIVY_WALLET_KEY_ENV, } from "./privy.js";
 const PURPOSE_TEXT = {
     transaction: "signs a transaction",
     capability: "signs an off-chain EIP-712 invocation capability (no transaction is broadcast)",
 };
-const WALLET_HINT = `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), or configure a Coinbase CDP wallet with ` +
-    `${CDP_ENV_VARS.join(", ")}. Both are read from the environment only — never pass a credential as a command-line flag.`;
+const WALLET_HINT = `export ${PRIVATE_KEY_ENV}=0x… (a funded testnet key), configure a Coinbase CDP wallet with ` +
+    `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
+    `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;
 /**
  * Resolves the signing wallet, or throws an actionable configuration error.
  *
- * `note` receives one line when the environment is ambiguous (both wallet
- * sources configured). It is optional so `resolveCliWallet` stays usable from a
- * context with no printer; commands always pass `out.note`.
+ * `note` receives one line when the environment is ambiguous (more than one
+ * wallet source configured). It is optional so `resolveCliWallet` stays usable
+ * from a context with no printer; commands always pass `out.note`.
  */
 export async function resolveCliWallet(env, options = {}) {
     const wallet = await optionalCliWallet(env, options);
     if (wallet === null) {
-        throw configError(`this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: neither ${PRIVATE_KEY_ENV} nor the CDP variables are set`, WALLET_HINT);
+        throw configError(`this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`, WALLET_HINT);
     }
     return wallet;
 }
+/** True for both Privy shapes, which reach their key through a broker. */
+export function isPrivyWalletSource(source) {
+    return source === "privy-autonomous" || source === "privy-session";
+}
+/**
+ * Whether this wallet's ceiling is enforced somewhere the CLI cannot reach.
+ *
+ * The one question every fund-moving command asks before deciding whether to
+ * self-sign a `SpendMandate`. See `./spend-policy.ts`.
+ */
+export function isPolicyEnforced(wallet) {
+    return wallet.readSpendPolicy !== undefined;
+}
 /**
  * The same resolution, but "nothing configured" is not an error. Used by
  * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
@@ -79,14 +96,19 @@ export async function resolveCliWallet(env, options = {}) {
  * A wallet that is PARTIALLY configured is still an error here: "you set three
  * of the four CDP variables" and "you configured no wallet" are different
  * facts, and rendering the first as the second sends the reader looking in the
- * wrong place.
+ * wrong place. The same rule applies to a partial Privy setup.
  */
 export async function optionalCliWallet(env, options = {}) {
     const privateKeyAccount = optionalCliAccount(env);
     const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+    const privyConfigured = PRIVY_ENV_VARS.some((name) => isSet(env[name]));
     if (privateKeyAccount !== null) {
-        if (cdpConfigured) {
-            options.note?.(`warning: both ${PRIVATE_KEY_ENV} and CDP wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the CDP wallet.`);
+        const shadowed = [
+            ...(cdpConfigured ? ["CDP"] : []),
+            ...(privyConfigured ? ["Privy"] : []),
+        ];
+        if (shadowed.length > 0) {
+            options.note?.(`warning: both ${PRIVATE_KEY_ENV} and ${shadowed.join(" and ")} wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the ${shadowed[0]} wallet.`);
         }
         return {
             source: "private-key",
@@ -94,8 +116,29 @@ export async function optionalCliWallet(env, options = {}) {
             description: `${privateKeyAccount.address} (from ${PRIVATE_KEY_ENV})`,
         };
     }
-    if (!cdpConfigured)
+    if (cdpConfigured) {
+        if (privyConfigured) {
+            options.note?.("warning: both CDP and Privy wallet variables are set; using the CDP wallet. Unset the CDP variables to sign with the Privy wallet.");
+        }
+        return await resolveCdpWallet(env);
+    }
+    if (!privyConfigured)
         return null;
+    const privy = await resolvePrivyCliWallet(env, options);
+    // Unreachable: `privyConfigured` is exactly the condition under which
+    // `resolvePrivyCliWallet` returns non-null or throws. Kept so a future change
+    // to either predicate fails loudly here rather than as a null deref.
+    if (privy === null)
+        return null;
+    return {
+        source: privy.source,
+        account: assertCliSigner(privy.account, privy.source),
+        transport: privy.transport,
+        description: privy.description,
+        readSpendPolicy: privy.readSpendPolicy,
+    };
+}
+async function resolveCdpWallet(env) {
     const missing = CDP_ENV_VARS.filter((name) => !isSet(env[name]));
     if (missing.length > 0) {
         throw configError(`the CDP wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`, `a CDP wallet needs all of ${CDP_ENV_VARS.join(", ")}. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others and use ${PRIVATE_KEY_ENV} instead.`);
@@ -130,7 +173,7 @@ export async function optionalCliWallet(env, options = {}) {
     }
     return {
         source: "cdp",
-        account: assertLocalSigner(account, "cdp"),
+        account: assertCliSigner(account, "cdp"),
         description: `${account.address} (CDP account "${ownerName}")`,
     };
 }
@@ -148,17 +191,39 @@ export function optionalCliAccount(env) {
     return privateKeyToAccount(raw);
 }
 /**
- * Every CLI signing path needs a LOCAL signer: fund-moving commands broadcast
- * through `http(--rpc-url)`, which cannot sign, and `invoke` needs a
- * `LocalAccount` to sign the EIP-712 capability. A JSON-RPC account (Privy's
- * adapters) would type-check as an `Account` and then fail somewhere inside
- * viem with a message about a missing method, so it is rejected here with the
- * actual reason.
+ * Whether this wallet source broadcasts through the CLI's own
+ * `http(--rpc-url)` transport, and therefore needs an account that can produce
+ * a signed raw transaction by itself.
+ */
+function broadcastsLocally(source) {
+    return source === "private-key" || source === "cdp";
+}
+/**
+ * Refuses an account that genuinely cannot sign — and nothing else.
+ *
+ * Two distinct capabilities are checked, because two distinct things fail:
+ *
+ *  - `signTypedData` is needed by EVERY command. Fund-moving commands self-sign
+ *    an EIP-712 `SpendMandate`; `invoke` signs an EIP-712
+ *    `InvocationCapability`. Without it the run dies at the first signature
+ *    with a `TypeError` from inside viem.
+ *  - A LOCAL account is needed only where the CLI broadcasts through
+ *    `http(--rpc-url)`, which cannot sign. A Privy account is deliberately NOT
+ *    local: its provider is the transport and performs `eth_sendTransaction`
+ *    itself, so demanding locality there would reject a wallet that works.
+ *
+ * The earlier version of this guard collapsed both into "must be local", which
+ * is why Privy was refused. Deleting the guard outright was not the fix: it
+ * exists so a broken wallet fails here, named, instead of deep inside viem.
  */
-function assertLocalSigner(account, source) {
-    if (account.type === "local")
-        return account;
-    throw configError(`the ${source} wallet returned a ${account.type} account, which cannot sign locally`, "the CLI broadcasts through --rpc-url and signs EIP-712 capabilities in-process, so it needs a local signer.");
+export function assertCliSigner(account, source) {
+    if (typeof account.signTypedData !== "function") {
+        throw configError(`the ${source} wallet (${account.address}) cannot sign EIP-712 typed data`, "every command signs typed data: fund-moving commands self-sign a spend mandate, and `invoke` signs an invocation capability.");
+    }
+    if (broadcastsLocally(source) && account.type !== "local") {
+        throw configError(`the ${source} wallet returned a ${account.type} account, which cannot sign locally`, "this wallet source broadcasts through --rpc-url, which cannot sign, so it needs a local signer.");
+    }
+    return account;
 }
 function isSet(value) {
     return value !== undefined && value.length > 0;

package/dist/cli/wallet.js.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"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"}

package/dist/discovery/rate-band.d.ts

@@ -0,0 +1,74 @@
+import { SignedRateBoundsError, type SignedRateBounds } from "../gateway/signed-rate-bounds.js";
+/**
+ * The buyer-side twin of the gateway's signed-rate check.
+ *
+ * `StreamEscrowV2.openStream` accepts any non-zero `ratePerSecond`; the band a
+ * seller will actually SERVE lives in its operator-signed descriptor
+ * (`commercial.minRatePerSecond` / `maxRatePerSecond`), and the seller's
+ * capability gateway answers every request on an out-of-band stream with
+ * `403 stream-rate-out-of-bounds`. Opening such a stream locks the buyer's
+ * deposit in a stream that can never be served, so every buyer surface that
+ * takes a caller-chosen rate checks it against the SAME band, with the SAME
+ * verification ({@link verifySignedRateBounds}), before anything is broadcast.
+ *
+ * Nothing here is a second signature implementation: the bounds come only out
+ * of `verifySignedRateBounds`, which re-derives the serviceRef from the signed
+ * content and recovers the operator's EIP-712 signature.
+ */
+/** A listing as discovery hands it over: the serviceRef and its signed record. */
+export interface RateBandListing {
+    readonly serviceRef: string;
+    readonly signed: unknown;
+}
+/**
+ * The operator-signed rate band of a verified listing.
+ *
+ * - `null`: the listing is a legacy service BINDING, which carries no
+ *   commercial terms, so the operator signed no band and there is nothing to
+ *   enforce (the gateway enforces none either).
+ * - a {@link SignedRateBounds}: the descriptor verified. Either bound may still
+ *   be `null` when the operator signed only one side, or none.
+ *
+ * Throws {@link SignedRateBoundsError} when the record IS a descriptor but does
+ * not verify, or verifies for a different serviceRef than the listing claims.
+ * Callers must treat that as a refusal: a band that cannot be verified is not a
+ * band that can be assumed absent.
+ */
+export declare function listingRateBand(listing: RateBandListing): Promise<SignedRateBounds | null>;
+/**
+ * The signed band in both units, e.g. `100..10000 atomic/s (0.0001..0.01
+ * USDC/s)`. A one-sided band reads `at least 100 atomic/s (…)` /
+ * `at most 10000 atomic/s (…)`.
+ */
+export declare function describeRateBand(bounds: SignedRateBounds): string;
+/**
+ * `undefined` when `rate` is inside the operator-signed band (bounds are
+ * inclusive, exactly as the gateway applies them), otherwise an actionable
+ * refusal naming the band in atomic units and USDC. `rateLabel` is how the
+ * caller supplied the rate (`--rate`, `ratePerSecondUsdc`).
+ */
+export declare function rateBandRefusal(rate: bigint, bounds: SignedRateBounds, rateLabel: string): string | undefined;
+/**
+ * Outcome of {@link checkListedRateBand}: `ok: false` is a refusal, and its
+ * `message` is safe to hand straight back to the caller.
+ */
+export type ListedRateBandCheck = {
+    readonly ok: true;
+    /** `unlisted`: no verified listing, so no operator-signed band exists. */
+    readonly band: "in-band" | "no-band-signed" | "unlisted";
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Discover the serviceRef's verified listing(s) and check `rate` against every
+ * operator-signed band among them, for a surface that has no listing in hand.
+ *
+ * Fail closed: a registry that cannot be read means a signed band may exist and
+ * is unknown, so it is a refusal — never a pass. A serviceRef with no verified
+ * listing has no signed band to violate, and is allowed (these surfaces never
+ * required a listing to hire).
+ */
+export declare function checkListedRateBand(discover: () => Promise<readonly RateBandListing[]>, serviceRef: string, rate: bigint, rateLabel: string): Promise<ListedRateBandCheck>;
+export { SignedRateBoundsError };
+//# sourceMappingURL=rate-band.d.ts.map

package/dist/discovery/rate-band.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-band.d.ts","sourceRoot":"","sources":["../../src/discovery/rate-band.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,qBAAqB,EAErB,KAAK,gBAAgB,EACtB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AAEH,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgBlC;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAYjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAIpB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,CAAC;CAC1D,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,EACnD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,CAAC,CAqC9B;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/discovery/rate-band.js

@@ -0,0 +1,114 @@
+import { formatUnits } from "viem";
+import { rateOutsideBounds, SignedRateBoundsError, verifySignedRateBounds, } from "../gateway/signed-rate-bounds.js";
+/**
+ * The operator-signed rate band of a verified listing.
+ *
+ * - `null`: the listing is a legacy service BINDING, which carries no
+ *   commercial terms, so the operator signed no band and there is nothing to
+ *   enforce (the gateway enforces none either).
+ * - a {@link SignedRateBounds}: the descriptor verified. Either bound may still
+ *   be `null` when the operator signed only one side, or none.
+ *
+ * Throws {@link SignedRateBoundsError} when the record IS a descriptor but does
+ * not verify, or verifies for a different serviceRef than the listing claims.
+ * Callers must treat that as a refusal: a band that cannot be verified is not a
+ * band that can be assumed absent.
+ */
+export async function listingRateBand(listing) {
+    const signed = listing.signed;
+    if (typeof signed !== "object" ||
+        signed === null ||
+        !("descriptor" in signed)) {
+        return null;
+    }
+    const bounds = await verifySignedRateBounds(signed);
+    if (bounds.serviceRef !== listing.serviceRef.toLowerCase()) {
+        throw new SignedRateBoundsError(`the signed descriptor verifies for serviceRef ${bounds.serviceRef}, not the listed ${listing.serviceRef}`);
+    }
+    return bounds;
+}
+/** `0.0001` for `100n` — USDC has 6 decimals. */
+function usdc(atomic) {
+    return formatUnits(atomic, 6);
+}
+/**
+ * The signed band in both units, e.g. `100..10000 atomic/s (0.0001..0.01
+ * USDC/s)`. A one-sided band reads `at least 100 atomic/s (…)` /
+ * `at most 10000 atomic/s (…)`.
+ */
+export function describeRateBand(bounds) {
+    const { minRatePerSecond: min, maxRatePerSecond: max } = bounds;
+    if (min !== null && max !== null) {
+        return `${min}..${max} atomic/s (${usdc(min)}..${usdc(max)} USDC/s)`;
+    }
+    if (min !== null) {
+        return `at least ${min} atomic/s (${usdc(min)} USDC/s)`;
+    }
+    if (max !== null) {
+        return `at most ${max} atomic/s (${usdc(max)} USDC/s)`;
+    }
+    return "any rate (the operator signed no bounds)";
+}
+/**
+ * `undefined` when `rate` is inside the operator-signed band (bounds are
+ * inclusive, exactly as the gateway applies them), otherwise an actionable
+ * refusal naming the band in atomic units and USDC. `rateLabel` is how the
+ * caller supplied the rate (`--rate`, `ratePerSecondUsdc`).
+ */
+export function rateBandRefusal(rate, bounds, rateLabel) {
+    const outside = rateOutsideBounds(rate, bounds);
+    if (outside === undefined)
+        return undefined;
+    return `the operator signed rates ${describeRateBand(bounds)}; ${rateLabel} ${rate} (${usdc(rate)} USDC/s) would be refused by the service's gateway (${outside}), so the stream could never be served. Nothing was broadcast.`;
+}
+/**
+ * Discover the serviceRef's verified listing(s) and check `rate` against every
+ * operator-signed band among them, for a surface that has no listing in hand.
+ *
+ * Fail closed: a registry that cannot be read means a signed band may exist and
+ * is unknown, so it is a refusal — never a pass. A serviceRef with no verified
+ * listing has no signed band to violate, and is allowed (these surfaces never
+ * required a listing to hire).
+ */
+export async function checkListedRateBand(discover, serviceRef, rate, rateLabel) {
+    let listings;
+    try {
+        listings = await discover();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `refusing to hire: the service registry could not be read (${error instanceof Error ? error.message : String(error)}), so the operator-signed rate band for ${serviceRef} cannot be checked and the stream might never be served. Nothing was spent — retry when the registry answers.`,
+        };
+    }
+    const wanted = serviceRef.toLowerCase();
+    const matches = listings.filter((listing) => listing.serviceRef.toLowerCase() === wanted);
+    if (matches.length === 0)
+        return { ok: true, band: "unlisted" };
+    let signedAny = false;
+    for (const listing of matches) {
+        let bounds;
+        try {
+            bounds = await listingRateBand(listing);
+        }
+        catch (error) {
+            if (error instanceof SignedRateBoundsError) {
+                return {
+                    ok: false,
+                    message: `refusing to hire: the listing's operator-signed rate band could not be verified (${error.message}). Nothing was spent.`,
+                };
+            }
+            throw error;
+        }
+        if (bounds === null)
+            continue;
+        signedAny = true;
+        const refusal = rateBandRefusal(rate, bounds, rateLabel);
+        if (refusal !== undefined) {
+            return { ok: false, message: `refusing to hire: ${refusal}` };
+        }
+    }
+    return { ok: true, band: signedAny ? "in-band" : "no-band-signed" };
+}
+export { SignedRateBoundsError };
+//# sourceMappingURL=rate-band.js.map

package/dist/discovery/rate-band.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-band.js","sourceRoot":"","sources":["../../src/discovery/rate-band.ts"],"names":[],"mappings":"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"}

package/dist/escrow-generation.d.ts

@@ -0,0 +1,81 @@
+import type { Address, Hex } from "viem";
+/**
+ * Escrow-generation-specific rules, driven by the SDK network registry's
+ * `escrow.generation` (metrik-agent#121).
+ *
+ * Today the registry knows only `v2` (`StreamEscrowV2`). `StreamEscrowV3`
+ * changes one rule the agent reasons about: the buyer's no-proof escape hatch.
+ *
+ * - **V2**: `reclaimUnverified` opens at `expiresAt + escapeGraceSeconds`.
+ *   Closing early does NOT bring it forward.
+ * - **V3**: it opens at `min(expiresAt, closedAt) + escapeGraceSeconds`, and the
+ *   escrow exposes `escapeHatchReadyAt(bytes32)` to read it directly. Where a
+ *   chain read is available it is preferred over re-deriving the formula.
+ *
+ * An unknown generation is refused, never guessed: a wrong readiness answer
+ * either sends a buyer a guaranteed revert or tells them to wait when they need
+ * not. (V3 also restricts `recordProven` to the stream's operator or an active
+ * oracle signer; no agent or relay path calls it on a buyer's behalf.)
+ */
+/** Escrow generations whose escape-hatch rule this package implements. */
+export type KnownEscrowGeneration = "v2" | "v3";
+export declare class UnsupportedEscrowGenerationError extends Error {
+    readonly generation: string;
+    constructor(generation: string);
+}
+/**
+ * The generation of `escrow` on `chainId`, from the network registry. An escrow
+ * the registry does not record is treated as V2 — the generation every
+ * unregistered, explicitly configured Metrik deployment speaks today.
+ */
+export declare function escrowGenerationFor(chainId: number, escrow: Address): KnownEscrowGeneration;
+/**
+ * The second the no-proof escape hatch opens, by formula. `closedAt` is `0`
+ * while the stream is open.
+ */
+export declare function escapeHatchReadyAtFormula(generation: string, stream: {
+    readonly expiresAt: bigint;
+    readonly closedAt: bigint;
+}, graceSeconds: bigint): bigint;
+/**
+ * `StreamEscrowV3.escapeHatchReadyAt(bytes32)`. A one-function fragment until
+ * the SDK ships the V3 ABI; replace it with the SDK's export then.
+ */
+export declare const streamEscrowV3EscapeHatchAbi: readonly [{
+    readonly type: "function";
+    readonly name: "escapeHatchReadyAt";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "streamId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+/** The minimal read surface {@link readEscapeHatchReadyAt} needs. */
+export interface EscapeHatchReader {
+    readContract(args: {
+        readonly address: Address;
+        readonly abi: typeof streamEscrowV3EscapeHatchAbi;
+        readonly functionName: "escapeHatchReadyAt";
+        readonly args: readonly [Hex];
+    }): Promise<bigint>;
+}
+/**
+ * The escape-hatch second for one stream: V3 reads the escrow's own view (and
+ * falls back to the V3 formula if that read fails); V2 uses its formula.
+ */
+export declare function readEscapeHatchReadyAt(input: {
+    readonly generation: string;
+    readonly reader: EscapeHatchReader;
+    readonly escrow: Address;
+    readonly streamId: Hex;
+    readonly stream: {
+        readonly expiresAt: bigint;
+        readonly closedAt: bigint;
+    };
+    readonly graceSeconds: bigint;
+}): Promise<bigint>;
+//# sourceMappingURL=escrow-generation.d.ts.map

package/dist/escrow-generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-generation.d.ts","sourceRoot":"","sources":["../src/escrow-generation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAO/B;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,GACd,qBAAqB,CAMvB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACjE,YAAY,EAAE,MAAM,GACnB,MAAM,CAYR;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;EAQ/B,CAAC;AAEX,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,IAAI,EAAE;QACjB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,4BAA4B,CAAC;QAClD,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;QAC5C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;KAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB"}

package/dist/escrow-generation.js

@@ -0,0 +1,76 @@
+import { findDeployment } from "@absol-labs/sdk";
+export class UnsupportedEscrowGenerationError extends Error {
+    generation;
+    constructor(generation) {
+        super(`escrow generation "${generation}" is not one this package knows the escape-hatch rule for (known: v2, v3)`);
+        this.name = "UnsupportedEscrowGenerationError";
+        this.generation = generation;
+    }
+}
+function known(generation) {
+    if (generation === "v2" || generation === "v3")
+        return generation;
+    throw new UnsupportedEscrowGenerationError(generation);
+}
+/**
+ * The generation of `escrow` on `chainId`, from the network registry. An escrow
+ * the registry does not record is treated as V2 — the generation every
+ * unregistered, explicitly configured Metrik deployment speaks today.
+ */
+export function escrowGenerationFor(chainId, escrow) {
+    return known(
+    // The generation of THIS deployment (current or legacy), not of the
+    // network's current escrow.
+    findDeployment(chainId, escrow)?.deployment.escrow.generation ?? "v2");
+}
+/**
+ * The second the no-proof escape hatch opens, by formula. `closedAt` is `0`
+ * while the stream is open.
+ */
+export function escapeHatchReadyAtFormula(generation, stream, graceSeconds) {
+    switch (known(generation)) {
+        case "v2":
+            return stream.expiresAt + graceSeconds;
+        case "v3": {
+            const stop = stream.closedAt > 0n && stream.closedAt < stream.expiresAt
+                ? stream.closedAt
+                : stream.expiresAt;
+            return stop + graceSeconds;
+        }
+    }
+}
+/**
+ * `StreamEscrowV3.escapeHatchReadyAt(bytes32)`. A one-function fragment until
+ * the SDK ships the V3 ABI; replace it with the SDK's export then.
+ */
+export const streamEscrowV3EscapeHatchAbi = [
+    {
+        type: "function",
+        name: "escapeHatchReadyAt",
+        stateMutability: "view",
+        inputs: [{ name: "streamId", type: "bytes32" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+];
+/**
+ * The escape-hatch second for one stream: V3 reads the escrow's own view (and
+ * falls back to the V3 formula if that read fails); V2 uses its formula.
+ */
+export async function readEscapeHatchReadyAt(input) {
+    const generation = known(input.generation);
+    if (generation === "v3") {
+        try {
+            return await input.reader.readContract({
+                address: input.escrow,
+                abi: streamEscrowV3EscapeHatchAbi,
+                functionName: "escapeHatchReadyAt",
+                args: [input.streamId],
+            });
+        }
+        catch {
+            // Fall through to the V3 formula: the same rule the view implements.
+        }
+    }
+    return escapeHatchReadyAtFormula(generation, input.stream, input.graceSeconds);
+}
+//# sourceMappingURL=escrow-generation.js.map

package/dist/escrow-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow-generation.js","sourceRoot":"","sources":["../src/escrow-generation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAyBjD,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IAChD,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CACH,sBAAsB,UAAU,2EAA2E,CAC5G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,KAAK,CAAC,UAAkB;IAC/B,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAClE,MAAM,IAAI,gCAAgC,CAAC,UAAU,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,MAAe;IAEf,OAAO,KAAK;IACV,oEAAoE;IACpE,4BAA4B;IAC5B,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI,CACtE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,MAAiE,EACjE,YAAoB;IAEpB,QAAQ,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1B,KAAK,IAAI;YACP,OAAO,MAAM,CAAC,SAAS,GAAG,YAAY,CAAC;QACzC,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,MAAM,IAAI,GACR,MAAM,CAAC,QAAQ,GAAG,EAAE,IAAI,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,SAAS;gBACxD,CAAC,CAAC,MAAM,CAAC,QAAQ;gBACjB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;YACvB,OAAO,IAAI,GAAG,YAAY,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,oBAAoB;QAC1B,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;CACO,CAAC;AAYX;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAO5C;IACC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC;gBACrC,OAAO,EAAE,KAAK,CAAC,MAAM;gBACrB,GAAG,EAAE,4BAA4B;gBACjC,YAAY,EAAE,oBAAoB;gBAClC,IAAI,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;aACvB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;IACH,CAAC;IACD,OAAO,yBAAyB,CAC9B,UAAU,EACV,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,YAAY,CACnB,CAAC;AACJ,CAAC"}