otto-intel-mcp 0.1.2 → 0.1.3

package/dist/executable-yield-markets.js

@@ -0,0 +1,154 @@
+/**
+ * Server-owned yield execution registry.
+ *
+ * The dApp's server route and TEA import the exact same records. Discovery can
+ * attach APY data to a record, but it cannot create or mutate execution
+ * eligibility. The canonical commitment is server-only (both consumers run in
+ * Node) and covers the complete registry record, including nested fields.
+ */
+import { createHash } from 'node:crypto';
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+export const BASE_USDC_AAVE_V3_MARKET = deepFreeze({
+    id: 'base-usdc-aave-v3',
+    venue: 'AAVE V3',
+    protocol: 'AAVE',
+    chainId: 8453,
+    chainSlug: 'base',
+    asset: {
+        symbol: 'USDC',
+        group: 'USDC',
+        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        decimals: 6,
+    },
+    protocolTarget: '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5',
+    vaultAddress: '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5',
+    nativeValue: '0',
+    builder: 'aave-native',
+    selectors: {
+        approve: '0x095ea7b3',
+        supply: '0x617ba037',
+        withdraw: '0x69328dec',
+    },
+    // An existing exact allowance lets the SDK omit approve. No other leg is valid.
+    allowedCallSequences: {
+        deposit: [['approve', 'supply'], ['supply']],
+        withdraw: [['withdraw']],
+    },
+    safeBinding: {
+        executionOwner: 'SAFE',
+        depositReceiver: 'SAFE',
+        withdrawReceiver: 'SAFE',
+    },
+    discoveryMarketId: 'aave:8453:0xa238dd80c259a72e81d7e4664a9801593f98d1c5:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+});
+export const BASE_USDC_MORPHO_GAUNTLET_PRIME_MARKET = deepFreeze({
+    id: 'base-usdc-morpho-gauntlet-prime',
+    venue: 'MORPHO · GAUNTLET USDC PRIME',
+    protocol: 'MORPHO',
+    chainId: 8453,
+    chainSlug: 'base',
+    asset: {
+        symbol: 'USDC',
+        group: 'USDC',
+        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        decimals: 6,
+    },
+    protocolTarget: '0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61',
+    vaultAddress: '0xeE8F4eC5672F09119b96Ab6fB59C27E1b7e44b61',
+    vaultShareDecimals: 18,
+    nativeValue: '0',
+    builder: 'morpho-native',
+    selectors: {
+        approve: '0x095ea7b3',
+        deposit: '0x6e553f65',
+        withdraw: '0xb460af94',
+        redeem: '0xba087652',
+    },
+    allowedCallSequences: {
+        deposit: [['approve', 'deposit'], ['deposit']],
+        withdraw: [['withdraw'], ['redeem']],
+    },
+    safeBinding: {
+        executionOwner: 'SAFE',
+        depositReceiver: 'SAFE',
+        withdrawReceiver: 'SAFE',
+    },
+    discoveryMarketId: 'morpho:8453:0xee8f4ec5672f09119b96ab6fb59c27e1b7e44b61:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+});
+export const BASE_USDC_MORPHO_STEAKHOUSE_PRIME_MARKET = deepFreeze({
+    id: 'base-usdc-morpho-steakhouse-prime',
+    venue: 'MORPHO · STEAKHOUSE PRIME USDC',
+    protocol: 'MORPHO',
+    chainId: 8453,
+    chainSlug: 'base',
+    asset: {
+        symbol: 'USDC',
+        group: 'USDC',
+        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        decimals: 6,
+    },
+    protocolTarget: '0xBEEFE94c8aD530842bfE7d8B397938fFc1cb83b2',
+    vaultAddress: '0xBEEFE94c8aD530842bfE7d8B397938fFc1cb83b2',
+    vaultShareDecimals: 18,
+    nativeValue: '0',
+    builder: 'morpho-native',
+    selectors: {
+        approve: '0x095ea7b3',
+        deposit: '0x6e553f65',
+        withdraw: '0xb460af94',
+        redeem: '0xba087652',
+    },
+    allowedCallSequences: {
+        deposit: [['approve', 'deposit'], ['deposit']],
+        withdraw: [['withdraw'], ['redeem']],
+    },
+    safeBinding: {
+        executionOwner: 'SAFE',
+        depositReceiver: 'SAFE',
+        withdrawReceiver: 'SAFE',
+    },
+    discoveryMarketId: 'morpho:8453:0xbeefe94c8ad530842bfe7d8b397938ffc1cb83b2:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+});
+export const EXECUTABLE_YIELD_MARKETS = deepFreeze([
+    BASE_USDC_AAVE_V3_MARKET,
+    BASE_USDC_MORPHO_GAUNTLET_PRIME_MARKET,
+    BASE_USDC_MORPHO_STEAKHOUSE_PRIME_MARKET,
+]);
+function canonicalJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('executable yield registry contains a non-finite number');
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (typeof value === 'object') {
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries
+            .map(([key, nested]) => `${JSON.stringify(key)}:${canonicalJson(nested)}`)
+            .join(',')}}`;
+    }
+    throw new Error('executable yield registry contains a non-canonical value');
+}
+/** SHA-256 commitment over every enumerable field in the complete, canonical registry record. */
+export function getExecutableYieldMarketCommitment(market) {
+    const canonical = canonicalJson(market);
+    const digest = createHash('sha256')
+        .update(`otto:executable-yield-market:v1:${canonical}`, 'utf8')
+        .digest('hex');
+    return `sha256:${digest}`;
+}
+export function getExecutableYieldMarket(marketId) {
+    return EXECUTABLE_YIELD_MARKETS.find((market) => market.id === marketId) ?? null;
+}
+//# sourceMappingURL=executable-yield-markets.js.map

package/dist/execution-delegated-definition.d.ts

@@ -129,6 +129,7 @@ export declare const DELEGATED_SEND_RESULT_SCHEMA: z.ZodObject<{
         policy_name: z.ZodString;
         rules_digest: z.ZodString;
         per_swap_cap_usd: z.ZodLiteral<5000>;
+        user_cap_usd: z.ZodNumber;
     }, z.core.$strict>;
     delegation: z.ZodObject<{
         expires_at: z.ZodString;

package/dist/execution-delegated-definition.js

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { EXECUTION_ENVELOPE_SCHEMA, PREPARE_SWAP_INPUT_SCHEMA, } from './execution-tool-definitions.js';
-import { MODEL_B_PER_SWAP_CAP_USD } from './execution-delegation-policy.js';
+import { MODEL_B_PER_SWAP_CAP_MIN_USD, MODEL_B_PER_SWAP_CAP_USD, } from './execution-delegation-policy.js';
 export const DELEGATED_EXECUTION_TOOL_NAME = 'otto_submit_under_delegation';
 /** Per-request caller authentication rides THIS header — never a tool argument (arguments are logged). */
 export const DELEGATION_AUTH_HEADER = 'x-otto-delegation-auth';
@@ -78,7 +78,18 @@ export const DELEGATED_SEND_RESULT_SCHEMA = z
         policy_id: z.string(),
         policy_name: z.string(),
         rules_digest: z.string().regex(/^[0-9a-f]{64}$/),
+        /** The ENGINE's ceiling — the constant in the one shared project policy. Still a literal. */
         per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+        /**
+         * The cap THIS person chose when they minted, enforced by Otto's server on top of the ceiling.
+         * A bounded integer rather than a literal, because it is the whole point that it can be lower —
+         * but it can never exceed the ceiling, and that bound is here rather than left to the caller.
+         */
+        user_cap_usd: z
+            .number()
+            .int()
+            .min(MODEL_B_PER_SWAP_CAP_MIN_USD)
+            .max(MODEL_B_PER_SWAP_CAP_USD),
     })
         .strict(),
     delegation: z.object({ expires_at: z.string() }).strict(),
@@ -108,7 +119,7 @@ export const DELEGATED_TOOL_ANNOTATIONS = Object.freeze({
 export const DELEGATED_EXECUTION_TOOL_DEFINITION = Object.freeze({
     name: DELEGATED_EXECUTION_TOOL_NAME,
     title: 'Submit an Otto-prepared swap under a CDP end-user delegation',
-    description: `Submit a verified otto_prepare_swap envelope on Base under the end user's CDP delegation. Arguments: { userId, envelope (the otto_prepare_swap result), prepareInput (the exact otto_prepare_swap request, with slippage.minAmountOut) } — validated strictly AFTER the caller is authenticated, so the listed input schema is intentionally permissive. Server-to-server only: the caller presents Otto's delegation secret in the \`${DELEGATION_AUTH_HEADER}\` request header (never in arguments); a call without it is refused before anything is read. Before any send the server confirms, in this order: the Model-B project policy is installed and reads back by name and rules digest; the user's grant is active past the envelope's valid_until; the account is one of that end user's own CDP accounts as CDP reports them; the envelope passes the 13-check verifier for exactly the request that produced it; the plan is inside the fence (allow-listed input token, reviewed spender, gross at or below the ${MODEL_B_PER_SWAP_CAP_USD} USD per-swap cap). Then the three steps (allowance reset, approval, swap) are submitted in order under the delegation, each waited to a sealed canonical block; a halt clears the allowance and reports the read-back. One delegated plan at a time per user. Coinbase's engine bounds the delegated key to Model-B swap shapes through LI.FI up to the per-swap cap; the receiver binding is Otto's server-side check, and the user can revoke at any time.`,
+    description: `Submit a verified otto_prepare_swap envelope on Base under the end user's CDP delegation. Arguments: { userId, envelope (the otto_prepare_swap result), prepareInput (the exact otto_prepare_swap request, with slippage.minAmountOut) } — validated strictly AFTER the caller is authenticated, so the listed input schema is intentionally permissive. Server-to-server only: the caller presents Otto's delegation secret in the \`${DELEGATION_AUTH_HEADER}\` request header (never in arguments); a call without it is refused before anything is read. Before any send the server confirms, in this order: the Model-B project policy is installed and reads back by name and rules digest; the user's grant is active past the envelope's valid_until; the account is one of that end user's own CDP accounts as CDP reports them; the envelope passes the 13-check verifier for exactly the request that produced it; the plan is inside the fence (allow-listed input token, reviewed spender, gross at or below the ${MODEL_B_PER_SWAP_CAP_USD} USD engine ceiling); and the plan is at or below the per-swap cap THIS user chose when they minted, which is recorded against their grant on this server. A delegation with no recorded cap is REFUSED (DELEGATION_CAP_UNRECORDED) rather than defaulted to the ceiling \u2014 mint the permission again to set one. Then the three steps (allowance reset, approval, swap) are submitted in order under the delegation, each waited to a sealed canonical block; a halt clears the allowance and reports the read-back. One delegated plan at a time per user. Coinbase's engine bounds the delegated key to Model-B swap shapes through LI.FI up to the ${MODEL_B_PER_SWAP_CAP_USD} USD ceiling, which is shared by every delegated user and cannot be narrowed per user by the engine; the user's own lower cap and the receiver binding are Otto's server-side checks, and the user can revoke at any time.`,
     inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
     strictInputSchema: SUBMIT_UNDER_DELEGATION_INPUT_SCHEMA,
     outputSchema: DELEGATED_SEND_RESULT_SCHEMA,

package/dist/execution-delegation-admin-definition.d.ts

@@ -1,6 +1,8 @@
 /**
- * execution-delegation-admin-definition.ts — the three header-authed delegation ADMIN tools (PR-1b, seat ruling
- * D10 = (a), 2026-08-29): `otto_delegation_fence`, `otto_delegation_status`, `otto_delegation_revoke`.
+ * execution-delegation-admin-definition.ts — the four header-authed delegation ADMIN tools (PR-1b, seat ruling
+ * D10 = (a), 2026-08-29): `otto_delegation_fence`, `otto_delegation_status`, `otto_delegation_revoke`, and
+ * `otto_delegation_cap` (Founder word `delegate cap choice`, 2026-09-02 — the per-swap cap a person chose,
+ * recorded against the grant they just minted).
  *
  * Same seam and admission as `otto_submit_under_delegation`: they register only with a rig, the caller presents
  * Otto's server secret in the `x-otto-delegation-auth` request header (never in arguments), the registered
@@ -18,7 +20,9 @@ import { DELEGATED_TOOL_TRANSPORT_SCHEMA } from './execution-delegated-definitio
 export declare const DELEGATION_FENCE_TOOL_NAME: "otto_delegation_fence";
 export declare const DELEGATION_STATUS_TOOL_NAME: "otto_delegation_status";
 export declare const DELEGATION_REVOKE_TOOL_NAME: "otto_delegation_revoke";
-export declare const DELEGATION_ADMIN_TOOL_NAMES: readonly ["otto_delegation_fence", "otto_delegation_status", "otto_delegation_revoke"];
+/** Records the per-swap cap the person chose, against the grant they just minted. */
+export declare const DELEGATION_CAP_TOOL_NAME: "otto_delegation_cap";
+export declare const DELEGATION_ADMIN_TOOL_NAMES: readonly ["otto_delegation_fence", "otto_delegation_status", "otto_delegation_revoke", "otto_delegation_cap"];
 /** The one PUBLIC delegation tool: the fence's public promise (present / name / digest / cap) — never user or grant data. */
 export declare const DELEGATION_FENCE_STATUS_TOOL_NAME: "otto_delegation_fence_status";
 export declare const DELEGATION_FENCE_INPUT_SCHEMA: z.ZodObject<{}, z.core.$strict>;
@@ -49,9 +53,74 @@ export declare const DELEGATION_STATUS_RESULT_SCHEMA: z.ZodObject<{
     delegation: z.ZodObject<{
         active: z.ZodBoolean;
         expires_at: z.ZodOptional<z.ZodString>;
+        per_swap_cap_usd: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     revocation_requested_here: z.ZodBoolean;
+    ruleset_version: z.ZodNumber;
+    mint_enabled: z.ZodBoolean;
 }, z.core.$strict>;
+/**
+ * 🔴 TWO PHASES, BECAUSE THE RECORD NOW COMES BEFORE THE GRANT.
+ *
+ * Rounds 1 and 2 recorded a cap against a grant that already existed, and the codex gate broke both the
+ * same way: an expiry is the only thing a send can learn about a live grant, so two grants that share one
+ * are indistinguishable at enforcement however the row is keyed. Round 3 removes the collision instead of
+ * describing it.
+ *
+ *   `reserve` — the SERVER picks a whole-second instant at or BEFORE the person's chosen duration that no
+ *     durable row for this user occupies, writes the cap against it, and answers with the instant. The
+ *     caller then mints with `mint_expires_at`, which is that instant plus a one-millisecond filler CDP
+ *     truncates away (a bare `.000Z` is refused upstream — see `mintExpiryFor`).
+ *   `confirm` — after the mint, the server re-reads the grant from CDP and refuses unless the instant CDP
+ *     reports IS the reserved one. On a mismatch the fresh grant is REVOKED: a permission whose expiry
+ *     does not match the row it was reserved against is one nothing may act under.
+ *
+ * The user is still never named by the caller — both phases resolve the identity from the access token.
+ */
+export declare const DELEGATION_CAP_RESERVE_INPUT_SCHEMA: z.ZodObject<{
+    phase: z.ZodLiteral<"reserve">;
+    accessToken: z.ZodString;
+    perSwapCapUsd: z.ZodNumber;
+    requestedDays: z.ZodNumber;
+    mintKey: z.ZodString;
+}, z.core.$strict>;
+export declare const DELEGATION_CAP_CONFIRM_INPUT_SCHEMA: z.ZodObject<{
+    phase: z.ZodLiteral<"confirm">;
+    accessToken: z.ZodString;
+    mintKey: z.ZodString;
+}, z.core.$strict>;
+export declare const DELEGATION_CAP_INPUT_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    phase: z.ZodLiteral<"reserve">;
+    accessToken: z.ZodString;
+    perSwapCapUsd: z.ZodNumber;
+    requestedDays: z.ZodNumber;
+    mintKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    phase: z.ZodLiteral<"confirm">;
+    accessToken: z.ZodString;
+    mintKey: z.ZodString;
+}, z.core.$strict>], "phase">;
+export declare const DELEGATION_CAP_RESULT_SCHEMA: z.ZodObject<{
+    phase: z.ZodEnum<{
+        reserve: "reserve";
+        confirm: "confirm";
+    }>;
+    user_id: z.ZodString;
+    expires_at: z.ZodString;
+    mint_expires_at: z.ZodOptional<z.ZodString>;
+    per_swap_cap_usd: z.ZodNumber;
+    state: z.ZodEnum<{
+        legacy: "legacy";
+        reserved: "reserved";
+        confirmed_active: "confirmed_active";
+        superseded: "superseded";
+        revoked: "revoked";
+        expired: "expired";
+    }>;
+    ruleset_version: z.ZodNumber;
+    recorded: z.ZodBoolean;
+}, z.core.$strict>;
+export type DelegationCapResult = z.infer<typeof DELEGATION_CAP_RESULT_SCHEMA>;
 export declare const DELEGATION_REVOKE_INPUT_SCHEMA: z.ZodUnion<readonly [z.ZodObject<{
     accessToken: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -73,6 +142,9 @@ export declare const DELEGATION_FENCE_STATUS_RESULT_SCHEMA: z.ZodObject<{
     present: z.ZodBoolean;
     policy_name: z.ZodString;
     per_swap_cap_usd: z.ZodLiteral<5000>;
+    per_swap_cap_min_usd: z.ZodLiteral<1>;
+    ruleset_version: z.ZodNumber;
+    mint_enabled: z.ZodBoolean;
     project_id: z.ZodOptional<z.ZodString>;
     rules_digest: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodEnum<{
@@ -86,12 +158,15 @@ export type DelegationFenceStatusResult = z.infer<typeof DELEGATION_FENCE_STATUS
 export declare const DELEGATION_FENCE_STATUS_TOOL_DEFINITION: Readonly<{
     name: "otto_delegation_fence_status";
     title: "Read the Model-B delegation fence (public promise: present, name, rules digest, per-swap cap)";
-    description: "PUBLIC and read-only, no header: whether the Model-B project policy that fences every delegated send is installed and v-current on this server, with its versioned name, rules digest, the per-swap cap in USD, and Otto's PUBLIC CDP project id (a UUID — the authority an agent binds its mint to). Exposes ONLY the fence's public promise — never an end user, a grant, an address or a policy's contents. An agent about to mint a delegation (otto-execute delegate) reads this first, mints to the published project_id and no other, and refuses to mint when the fence is not present; the server enforces fence-before-authority on every delegated send regardless. Arguments: {}.";
+    description: "PUBLIC and read-only, no header: whether the Model-B project policy that fences every delegated send is installed and v-current on this server, with its versioned name, rules digest, the per-swap cap ceiling in USD (shared by every delegated user — a person may choose any whole-dollar cap from per_swap_cap_min_usd up to it, enforced server-side and recorded against their own grant), and Otto's PUBLIC CDP project id (a UUID — the authority an agent binds its mint to). Exposes ONLY the fence's public promise — never an end user, a grant, an address or a policy's contents. An agent about to mint a delegation (otto-execute delegate) reads this first, mints to the published project_id and no other, and refuses to mint when the fence is not present; the server enforces fence-before-authority on every delegated send regardless. Arguments: {}.";
     inputSchema: z.ZodObject<{}, z.core.$strict>;
     outputSchema: z.ZodObject<{
         present: z.ZodBoolean;
         policy_name: z.ZodString;
         per_swap_cap_usd: z.ZodLiteral<5000>;
+        per_swap_cap_min_usd: z.ZodLiteral<1>;
+        ruleset_version: z.ZodNumber;
+        mint_enabled: z.ZodBoolean;
         project_id: z.ZodOptional<z.ZodString>;
         rules_digest: z.ZodOptional<z.ZodString>;
         reason: z.ZodOptional<z.ZodEnum<{
@@ -152,7 +227,7 @@ export declare const DELEGATION_FENCE_TOOL_DEFINITION: Readonly<{
 export declare const DELEGATION_STATUS_TOOL_DEFINITION: Readonly<{
     name: "otto_delegation_status";
     title: "Read one end user's delegation status (token-bound)";
-    description: `Read back, for the end user identified by a CDP access token, their CDP accounts, whether the Model-B fence is present, and whether an active delegation reads back (with its expiry). Arguments: { accessToken } \u2014 the server resolves the user from the token; a client-sent user id is refused. Output is bound to that user; nothing about any other user is returned. ${string}`;
+    description: `Read back, for the end user identified by a CDP access token, their CDP accounts, whether the Model-B fence is present, and whether an active delegation reads back (with its expiry and the per-swap cap recorded for it). Arguments: { accessToken } \u2014 the server resolves the user from the token; a client-sent user id is refused. delegation.per_swap_cap_usd is the number THIS user chose at mint time; it is ABSENT when no cap is recorded for the grant, which means the delegated send will refuse it \u2014 say so rather than showing the shared ceiling. fence.per_swap_cap_usd is that shared ceiling and is never a per-user number. Output is bound to that user; nothing about any other user is returned. ${string}`;
     inputSchema: z.ZodObject<{}, z.core.$loose>;
     strictInputSchema: z.ZodObject<{
         accessToken: z.ZodString;
@@ -169,8 +244,11 @@ export declare const DELEGATION_STATUS_TOOL_DEFINITION: Readonly<{
         delegation: z.ZodObject<{
             active: z.ZodBoolean;
             expires_at: z.ZodOptional<z.ZodString>;
+            per_swap_cap_usd: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
         revocation_requested_here: z.ZodBoolean;
+        ruleset_version: z.ZodNumber;
+        mint_enabled: z.ZodBoolean;
     }, z.core.$strict>;
     annotations: Readonly<{
         readOnlyHint: true;
@@ -206,3 +284,46 @@ export declare const DELEGATION_REVOKE_TOOL_DEFINITION: Readonly<{
         openWorldHint: true;
     }>;
 }>;
+export declare const DELEGATION_CAP_TOOL_DEFINITION: Readonly<{
+    name: "otto_delegation_cap";
+    title: "Reserve the expiry a delegation is minted with, record the chosen per-swap cap against it, then confirm the mint";
+    description: `TWO PHASES, both header authed, both resolving the end user from the access token. { phase: "reserve", accessToken, perSwapCapUsd, requestedDays, mintKey } picks a whole-second expiry instant at or BEFORE the requested duration that no durable row for this user already occupies, writes the chosen cap (whole USD, 1\u20265000) against it, and answers { expires_at, mint_expires_at, per_swap_cap_usd, recorded }. Call createDelegation with mint_expires_at EXACTLY as given \u2014 it is the reserved instant plus a one-millisecond filler, because CDP refuses an expiry ending .000 and truncates the filler away \u2014 and with mintKey as the idempotencyKey. Then { phase: "confirm", accessToken, mintKey } re-reads the grant from CDP and refuses (DELEGATION_CAP_GRANT_CHANGED) unless the instant CDP reports IS the reserved one, revoking the fresh grant when it is not. Why this shape: Coinbase issues no grant id and a send can learn nothing about a live grant except its expiry, so the expiry is made an identity BY CONSTRUCTION \u2014 reserved server-side, recorded before the mint, asserted after it. Until a reservation exists, otto_submit_under_delegation refuses that delegation (DELEGATION_CAP_UNRECORDED) rather than falling back to the 5000 USD ceiling. A reservation is IMMUTABLE per mint key \u2014 pressing again returns the same instant and the cap already in force, so raising a cap means minting a new permission (which the user is told replaces the old one). Coinbase's engine cannot hold this number: end-user accounts are fenced by ONE project-scope policy shared by every delegated user, so a lower per-user cap is enforced by Otto's server alone. ${string}`;
+    inputSchema: z.ZodObject<{}, z.core.$loose>;
+    strictInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        phase: z.ZodLiteral<"reserve">;
+        accessToken: z.ZodString;
+        perSwapCapUsd: z.ZodNumber;
+        requestedDays: z.ZodNumber;
+        mintKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        phase: z.ZodLiteral<"confirm">;
+        accessToken: z.ZodString;
+        mintKey: z.ZodString;
+    }, z.core.$strict>], "phase">;
+    outputSchema: z.ZodObject<{
+        phase: z.ZodEnum<{
+            reserve: "reserve";
+            confirm: "confirm";
+        }>;
+        user_id: z.ZodString;
+        expires_at: z.ZodString;
+        mint_expires_at: z.ZodOptional<z.ZodString>;
+        per_swap_cap_usd: z.ZodNumber;
+        state: z.ZodEnum<{
+            legacy: "legacy";
+            reserved: "reserved";
+            confirmed_active: "confirmed_active";
+            superseded: "superseded";
+            revoked: "revoked";
+            expired: "expired";
+        }>;
+        ruleset_version: z.ZodNumber;
+        recorded: z.ZodBoolean;
+    }, z.core.$strict>;
+    annotations: Readonly<{
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: true;
+        openWorldHint: true;
+    }>;
+}>;

package/dist/execution-delegation-admin-definition.js

@@ -1,6 +1,8 @@
 /**
- * execution-delegation-admin-definition.ts — the three header-authed delegation ADMIN tools (PR-1b, seat ruling
- * D10 = (a), 2026-08-29): `otto_delegation_fence`, `otto_delegation_status`, `otto_delegation_revoke`.
+ * execution-delegation-admin-definition.ts — the four header-authed delegation ADMIN tools (PR-1b, seat ruling
+ * D10 = (a), 2026-08-29): `otto_delegation_fence`, `otto_delegation_status`, `otto_delegation_revoke`, and
+ * `otto_delegation_cap` (Founder word `delegate cap choice`, 2026-09-02 — the per-swap cap a person chose,
+ * recorded against the grant they just minted).
  *
  * Same seam and admission as `otto_submit_under_delegation`: they register only with a rig, the caller presents
  * Otto's server secret in the `x-otto-delegation-auth` request header (never in arguments), the registered
@@ -14,16 +16,26 @@
  * proxy exposes only the token variant (asserted in PR-2).
  */
 import { z } from 'zod';
-import { MODEL_B_PER_SWAP_CAP_USD } from './execution-delegation-policy.js';
+import { MODEL_B_DELEGATION_EXPIRY_MAX_DAYS, MODEL_B_DELEGATION_EXPIRY_MIN_DAYS, MODEL_B_PER_SWAP_CAP_MIN_USD, MODEL_B_PER_SWAP_CAP_USD, } from './execution-delegation-policy.js';
 import { DELEGATION_AUTH_HEADER, DELEGATED_TOOL_TRANSPORT_SCHEMA, } from './execution-delegated-definition.js';
+import { CAP_RECORD_STATES, MINT_KEY_PATTERN } from './execution-delegation-cap-store.js';
 export const DELEGATION_FENCE_TOOL_NAME = 'otto_delegation_fence';
 export const DELEGATION_STATUS_TOOL_NAME = 'otto_delegation_status';
 export const DELEGATION_REVOKE_TOOL_NAME = 'otto_delegation_revoke';
+/** Records the per-swap cap the person chose, against the grant they just minted. */
+export const DELEGATION_CAP_TOOL_NAME = 'otto_delegation_cap';
 export const DELEGATION_ADMIN_TOOL_NAMES = Object.freeze([
     DELEGATION_FENCE_TOOL_NAME,
     DELEGATION_STATUS_TOOL_NAME,
     DELEGATION_REVOKE_TOOL_NAME,
+    DELEGATION_CAP_TOOL_NAME,
 ]);
+/** A chosen per-swap cap, as every schema on this surface bounds it: whole USD, 1 … the engine ceiling. */
+const PER_SWAP_CAP_SCHEMA = z
+    .number()
+    .int()
+    .min(MODEL_B_PER_SWAP_CAP_MIN_USD)
+    .max(MODEL_B_PER_SWAP_CAP_USD);
 /** The one PUBLIC delegation tool: the fence's public promise (present / name / digest / cap) — never user or grant data. */
 export const DELEGATION_FENCE_STATUS_TOOL_NAME = 'otto_delegation_fence_status';
 const END_USER_ID_PATTERN = /^[a-zA-Z0-9-]{1,100}$/;
@@ -67,9 +79,117 @@ export const DELEGATION_STATUS_RESULT_SCHEMA = z
         /** Active = reads back from CDP, not expired, and no revocation was requested on this server. */
         active: z.boolean(),
         expires_at: z.string().optional(),
+        /**
+         * The per-swap cap recorded for THIS grant — the number the person chose when they minted.
+         * ABSENT when none is recorded, and that absence is load-bearing: a delegated send for a grant
+         * with no recorded cap refuses, so the surface reading this must say the permission is not usable
+         * rather than quietly showing the ceiling.
+         */
+        per_swap_cap_usd: PER_SWAP_CAP_SCHEMA.optional(),
     })
         .strict(),
     revocation_requested_here: z.boolean(),
+    /**
+     * The cap-ruleset version THIS worker implements. The page and the agent CLI refuse to reserve or
+     * mint against a server reporting less than the version they were built for — a rolling deploy runs
+     * two binaries at once and the Coinbase fence is identical on both, so the fence cannot tell them
+     * apart and this is what does.
+     */
+    ruleset_version: z.number().int().min(1),
+    /**
+     * Whether a NEW permission can be created on this worker at all (the staged-deploy gate). It never
+     * gates this read and never gates revoke: pausing the creation of authority must not pause its
+     * withdrawal, and a permission that already stands keeps working under its own cap.
+     */
+    mint_enabled: z.boolean(),
+})
+    .strict();
+/* ── cap (round 3: RESERVE an expiry and record the cap against it, then CONFIRM the mint) ── */
+/**
+ * 🔴 TWO PHASES, BECAUSE THE RECORD NOW COMES BEFORE THE GRANT.
+ *
+ * Rounds 1 and 2 recorded a cap against a grant that already existed, and the codex gate broke both the
+ * same way: an expiry is the only thing a send can learn about a live grant, so two grants that share one
+ * are indistinguishable at enforcement however the row is keyed. Round 3 removes the collision instead of
+ * describing it.
+ *
+ *   `reserve` — the SERVER picks a whole-second instant at or BEFORE the person's chosen duration that no
+ *     durable row for this user occupies, writes the cap against it, and answers with the instant. The
+ *     caller then mints with `mint_expires_at`, which is that instant plus a one-millisecond filler CDP
+ *     truncates away (a bare `.000Z` is refused upstream — see `mintExpiryFor`).
+ *   `confirm` — after the mint, the server re-reads the grant from CDP and refuses unless the instant CDP
+ *     reports IS the reserved one. On a mismatch the fresh grant is REVOKED: a permission whose expiry
+ *     does not match the row it was reserved against is one nothing may act under.
+ *
+ * The user is still never named by the caller — both phases resolve the identity from the access token.
+ */
+export const DELEGATION_CAP_RESERVE_INPUT_SCHEMA = z
+    .object({
+    phase: z.literal('reserve'),
+    accessToken: ACCESS_TOKEN_SCHEMA,
+    perSwapCapUsd: PER_SWAP_CAP_SCHEMA,
+    /**
+     * How long the person asked for. The server turns it into an instant itself — a caller-supplied expiry
+     * would put the choice of the enforcement key back in the browser, and it is the server choosing it
+     * that makes the key unique.
+     */
+    requestedDays: z
+        .number()
+        .int()
+        .min(MODEL_B_DELEGATION_EXPIRY_MIN_DAYS)
+        .max(MODEL_B_DELEGATION_EXPIRY_MAX_DAYS),
+    /**
+     * The `idempotencyKey` the caller WILL pass to `createDelegation`. It makes the reservation itself
+     * retry-safe: pressing again after a lost response returns the same instant rather than consuming a
+     * second one. It is NOT the enforcement key — `(userId, expiry)` is.
+     */
+    mintKey: z.string().regex(MINT_KEY_PATTERN, 'must be the mint idempotency key'),
+})
+    .strict();
+export const DELEGATION_CAP_CONFIRM_INPUT_SCHEMA = z
+    .object({
+    phase: z.literal('confirm'),
+    accessToken: ACCESS_TOKEN_SCHEMA,
+    /** Which reservation this mint was for. The reserved instant is read from the store, never from the caller. */
+    mintKey: z.string().regex(MINT_KEY_PATTERN, 'must be the mint idempotency key'),
+})
+    .strict();
+export const DELEGATION_CAP_INPUT_SCHEMA = z.discriminatedUnion('phase', [
+    DELEGATION_CAP_RESERVE_INPUT_SCHEMA,
+    DELEGATION_CAP_CONFIRM_INPUT_SCHEMA,
+]);
+export const DELEGATION_CAP_RESULT_SCHEMA = z
+    .object({
+    phase: z.enum(['reserve', 'confirm']),
+    user_id: z.string().regex(END_USER_ID_PATTERN),
+    /**
+     * The RESERVED whole-second instant — the enforcement key. On `confirm` it is also what CDP reports for
+     * the live grant, because the call refuses otherwise.
+     */
+    expires_at: z.string(),
+    /**
+     * What to hand `createDelegation`: the reserved instant plus the one-millisecond filler. Present on
+     * `reserve` only — by `confirm` the mint has already happened.
+     */
+    mint_expires_at: z.string().optional(),
+    /**
+     * The cap IN FORCE at that instant, read back from the binding index — not necessarily the number the
+     * caller asked for.
+     */
+    per_swap_cap_usd: PER_SWAP_CAP_SCHEMA,
+    /**
+     * Where this permission is in its lifecycle. `reserved` authorises NOTHING — only `confirmed_active`
+     * does, and only while it is the one the send gate reads back.
+     */
+    state: z.enum(CAP_RECORD_STATES),
+    /** The cap ruleset this record requires; a worker that implements an older one refuses it. */
+    ruleset_version: z.number().int().min(1),
+    /**
+     * True when THIS call wrote the transition. False when it had already happened for this mint key:
+     * a reservation is immutable and a confirmation is one-shot, so the fields above are what already
+     * stands, and a caller wanting a different number mints a new permission.
+     */
+    recorded: z.boolean(),
 })
     .strict();
 /* ── revoke ── */
@@ -97,7 +217,21 @@ export const DELEGATION_FENCE_STATUS_RESULT_SCHEMA = z
     .object({
     present: z.boolean(),
     policy_name: z.string(),
+    /**
+     * The ENGINE's ceiling, shared by every delegated user — never one person's cap. A public tool has no
+     * user, so it can only ever publish this number and the floor below it.
+     */
     per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+    /** The floor of the range a person may choose at mint time; their choice is enforced server-side. */
+    per_swap_cap_min_usd: z.literal(MODEL_B_PER_SWAP_CAP_MIN_USD),
+    /** The cap-ruleset version this worker implements; a client built for a newer one refuses to mint. */
+    ruleset_version: z.number().int().min(1),
+    /**
+     * Whether this worker will create a NEW permission at all. Published so the page and the CLI can say
+     * so before a person signs in, rather than discovering it at the reserve. Permissions that already
+     * stand keep working, and revoke always works.
+     */
+    mint_enabled: z.boolean(),
     /** Otto's PUBLIC CDP project id (a UUID): the authority the agent CLI binds its mint to. */
     project_id: z
         .string()
@@ -114,7 +248,7 @@ export const DELEGATION_FENCE_STATUS_RESULT_SCHEMA = z
 export const DELEGATION_FENCE_STATUS_TOOL_DEFINITION = Object.freeze({
     name: DELEGATION_FENCE_STATUS_TOOL_NAME,
     title: 'Read the Model-B delegation fence (public promise: present, name, rules digest, per-swap cap)',
-    description: `PUBLIC and read-only, no header: whether the Model-B project policy that fences every delegated send is installed and v-current on this server, with its versioned name, rules digest, the per-swap cap in USD, and Otto's PUBLIC CDP project id (a UUID — the authority an agent binds its mint to). Exposes ONLY the fence's public promise — never an end user, a grant, an address or a policy's contents. An agent about to mint a delegation (otto-execute delegate) reads this first, mints to the published project_id and no other, and refuses to mint when the fence is not present; the server enforces fence-before-authority on every delegated send regardless. Arguments: {}.`,
+    description: `PUBLIC and read-only, no header: whether the Model-B project policy that fences every delegated send is installed and v-current on this server, with its versioned name, rules digest, the per-swap cap ceiling in USD (shared by every delegated user \u2014 a person may choose any whole-dollar cap from per_swap_cap_min_usd up to it, enforced server-side and recorded against their own grant), and Otto's PUBLIC CDP project id (a UUID — the authority an agent binds its mint to). Exposes ONLY the fence's public promise — never an end user, a grant, an address or a policy's contents. An agent about to mint a delegation (otto-execute delegate) reads this first, mints to the published project_id and no other, and refuses to mint when the fence is not present; the server enforces fence-before-authority on every delegated send regardless. Arguments: {}.`,
     inputSchema: DELEGATION_FENCE_STATUS_INPUT_SCHEMA,
     outputSchema: DELEGATION_FENCE_STATUS_RESULT_SCHEMA,
     annotations: Object.freeze({
@@ -142,7 +276,7 @@ export const DELEGATION_FENCE_TOOL_DEFINITION = Object.freeze({
 export const DELEGATION_STATUS_TOOL_DEFINITION = Object.freeze({
     name: DELEGATION_STATUS_TOOL_NAME,
     title: "Read one end user's delegation status (token-bound)",
-    description: `Read back, for the end user identified by a CDP access token, their CDP accounts, whether the Model-B fence is present, and whether an active delegation reads back (with its expiry). Arguments: { accessToken } — the server resolves the user from the token; a client-sent user id is refused. Output is bound to that user; nothing about any other user is returned. ${AUTH_SENTENCE}`,
+    description: `Read back, for the end user identified by a CDP access token, their CDP accounts, whether the Model-B fence is present, and whether an active delegation reads back (with its expiry and the per-swap cap recorded for it). Arguments: { accessToken } — the server resolves the user from the token; a client-sent user id is refused. delegation.per_swap_cap_usd is the number THIS user chose at mint time; it is ABSENT when no cap is recorded for the grant, which means the delegated send will refuse it — say so rather than showing the shared ceiling. fence.per_swap_cap_usd is that shared ceiling and is never a per-user number. Output is bound to that user; nothing about any other user is returned. ${AUTH_SENTENCE}`,
     inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
     strictInputSchema: DELEGATION_STATUS_INPUT_SCHEMA,
     outputSchema: DELEGATION_STATUS_RESULT_SCHEMA,
@@ -167,4 +301,19 @@ export const DELEGATION_REVOKE_TOOL_DEFINITION = Object.freeze({
         openWorldHint: true,
     }),
 });
+export const DELEGATION_CAP_TOOL_DEFINITION = Object.freeze({
+    name: DELEGATION_CAP_TOOL_NAME,
+    title: "Reserve the expiry a delegation is minted with, record the chosen per-swap cap against it, then confirm the mint",
+    description: `TWO PHASES, both header authed, both resolving the end user from the access token. { phase: "reserve", accessToken, perSwapCapUsd, requestedDays, mintKey } picks a whole-second expiry instant at or BEFORE the requested duration that no durable row for this user already occupies, writes the chosen cap (whole USD, ${MODEL_B_PER_SWAP_CAP_MIN_USD}…${MODEL_B_PER_SWAP_CAP_USD}) against it, and answers { expires_at, mint_expires_at, per_swap_cap_usd, recorded }. Call createDelegation with mint_expires_at EXACTLY as given — it is the reserved instant plus a one-millisecond filler, because CDP refuses an expiry ending .000 and truncates the filler away — and with mintKey as the idempotencyKey. Then { phase: "confirm", accessToken, mintKey } re-reads the grant from CDP and refuses (DELEGATION_CAP_GRANT_CHANGED) unless the instant CDP reports IS the reserved one, revoking the fresh grant when it is not. Why this shape: Coinbase issues no grant id and a send can learn nothing about a live grant except its expiry, so the expiry is made an identity BY CONSTRUCTION — reserved server-side, recorded before the mint, asserted after it. Until a reservation exists, otto_submit_under_delegation refuses that delegation (DELEGATION_CAP_UNRECORDED) rather than falling back to the ${MODEL_B_PER_SWAP_CAP_USD} USD ceiling. A reservation is IMMUTABLE per mint key — pressing again returns the same instant and the cap already in force, so raising a cap means minting a new permission (which the user is told replaces the old one). Coinbase's engine cannot hold this number: end-user accounts are fenced by ONE project-scope policy shared by every delegated user, so a lower per-user cap is enforced by Otto's server alone. ${AUTH_SENTENCE}`,
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    strictInputSchema: DELEGATION_CAP_INPUT_SCHEMA,
+    outputSchema: DELEGATION_CAP_RESULT_SCHEMA,
+    annotations: Object.freeze({
+        readOnlyHint: false,
+        destructiveHint: false,
+        // Idempotent by construction: the record is immutable, so a repeat returns what is already there.
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+});
 //# sourceMappingURL=execution-delegation-admin-definition.js.map