otto-execute 0.1.0

package/dist/delegate.d.ts

@@ -0,0 +1,117 @@
+/**
+ * otto-execute/delegate — the AGENT path to a Model-B delegation, headless from the agent's own process
+ * (PR-2a; Founder word `agent delegate cli`, 2026-08-29). Sign in as the end user by email OTP, mint a
+ * time-boxed CDP delegation to Otto's project, read it back, revoke it — all END-USER-SIDE: no Otto
+ * credential is ever in this process, and the delegation can only be minted by the signed-in user (the API
+ * requires the user's Bearer token plus an `X-Wallet-Auth` JWT signed by a Temporary Wallet Secret that
+ * lives inside `@coinbase/cdp-core`).
+ *
+ * THIS PATH IS NOT DOCUMENTED OR SUPPORTED BY COINBASE AND CAN BREAK ON AN SDK UPDATE; the browser page is
+ * the supported path. `@coinbase/cdp-core` ships browser + react-native bundles only, so Node resolves the
+ * WEB bundle and runs it with exactly two shims installed here before the SDK loads: an in-memory
+ * `localStorage` (sign-in needs it) and a `window = { crypto }` alias (the delegation leg spells WebCrypto as
+ * `window.crypto`; Node 22's `globalThis.crypto` is the same WebCrypto the SDK's native build uses). Nothing
+ * else is aliased — no `document`, no `location`. The dependency is PINNED (`@coinbase/cdp-core` 0.0.120 —
+ * the version proven live at Sitting B, 2026-08-29); a canary test drives the real web build on Node against
+ * a loopback fake of the CDP API, and the alias breaking is a NAMED refusal (`CDP_CORE_NODE_PATH_BROKEN`),
+ * never a silent failure. A Node client sends no Origin, so Coinbase's domain allowlist does not apply to
+ * it — a policy/support risk with Coinbase, not a fund or user risk: the secret stays on the user's own
+ * device and the human still consents via the OTP.
+ *
+ * FENCE BEFORE AUTHORITY holds on this path too: `readPublicFenceStatus` asks the hosted MCP's PUBLIC
+ * `otto_delegation_fence_status` (no header — the fence's public promise, never user data) and the CLI
+ * refuses to mint when the fence is not present, or when the MCP cannot be reached (fail-closed). The server
+ * enforces the same on every delegated send regardless.
+ *
+ * Kept on its OWN entry (`otto-execute/delegate`): the root export never loads cdp-core; the SDK is loaded
+ * lazily inside `initEndUserSdk` and a consumer without the optional peers (`@coinbase/cdp-core`, pinned, and
+ * `react` — the web build imports `zustand/react`) gets a named refusal (`CDP_CORE_NOT_INSTALLED`).
+ */
+export declare const CDP_CORE_PINNED_VERSION: "0.0.120";
+export declare const DEFAULT_OTTO_MCP_URL: "https://mcp.ottoai.services/mcp";
+/**
+ * The endpoints the delegate path talks to. In production they are FIXED: the fence is Otto's default MCP and
+ * the SDK is Coinbase's own endpoint — neither is a caller's to redirect (no flag, no environment variable).
+ * The ONLY override is an in-process global (`__ottoDelegateTestEndpoints__`) that the test harness installs
+ * through a `--import` preload a production invocation never loads; forging it needs code execution inside this
+ * process, which already subsumes it. So a caller who controls only the environment or argv can point neither
+ * the fence read nor the OTP's SDK endpoint anywhere.
+ */
+export interface DelegateEndpoints {
+    readonly mcpUrl: string;
+    readonly apiBasePath?: string;
+}
+export declare const DELEGATE_TEST_ENDPOINTS_KEY: "__ottoDelegateTestEndpoints__";
+export declare function resolveDelegateEndpoints(): DelegateEndpoints;
+export declare const FENCE_STATUS_TOOL_NAME: "otto_delegation_fence_status";
+export declare const UNSUPPORTED_PATH_NOTE: "this path is not documented or supported by Coinbase and can break on an SDK update; the browser page is the supported path";
+export declare const DELEGATE_REFUSAL_CODES: readonly ["CDP_CORE_NOT_INSTALLED", "CDP_CORE_NODE_PATH_BROKEN", "PROJECT_ID_REQUIRED", "EMAIL_INVALID", "OTP_INVALID", "NO_EVM_ACCOUNT", "EXPIRY_INVALID", "DELEGATION_FENCE_ABSENT", "FENCE_MISMATCH", "FENCE_UNREACHABLE", "STORAGE_NOT_EPHEMERAL", "WINDOW_NOT_OURS", "CREDENTIAL_IN_ENVIRONMENT", "UNKNOWN_OPTION", "FENCE_SOURCE_NOT_OTTO", "SDK_ENDPOINT_NOT_COINBASE", "REVOKE_NOT_CONFIRMED", "NOT_SIGNED_IN"];
+export type DelegateRefusalCode = (typeof DELEGATE_REFUSAL_CODES)[number];
+export declare class DelegateRefusal extends Error {
+    readonly code: DelegateRefusalCode;
+    constructor(code: DelegateRefusalCode, message: string);
+}
+export declare function isDelegateRefusal(error: unknown): error is DelegateRefusal;
+/**
+ * Mask a message before it is printed: URLs → `<url>` and any environment VALUE ≥ 8 chars → `<NAME>` (longest
+ * first, so a value that contains another is masked whole). Applied to every error the CLI prints, so a
+ * verbatim SDK error can never carry a secret or an endpoint to stdout/stderr.
+ */
+export declare function redactSecrets(text: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The SDK's web build reaching a browser global it expected (`window`, `document`, `navigator`, …) is the
+ * signature of the unsupported path breaking under an SDK change: a NAMED refusal, never a raw
+ * ReferenceError. Anything else is rethrown as itself.
+ */
+export declare function nodePathGuard<T>(run: () => Promise<T>): Promise<T>;
+export interface EndUserSdkOptions {
+    /** TESTS ONLY: point the SDK at a loopback fake of the CDP API (its `/platform`-shaped base). */
+    readonly apiBasePath?: string;
+}
+/**
+ * Boot cdp-core for Otto's CDP project (a PUBLIC project id). Idempotent per process. Returns nothing on
+ * purpose: the SDK module type must not appear in this package's declarations, or a consumer WITHOUT the
+ * optional `@coinbase/cdp-core` peer fails `tsc` on `otto-execute/delegate` (the isolated-install smoke
+ * compiles a consumer with `skipLibCheck: false` to keep it that way).
+ */
+export declare function initEndUserSdk(projectId: string | undefined, options?: EndUserSdkOptions): Promise<void>;
+export interface SignedInEndUser {
+    readonly userId: string;
+    readonly address: `0x${string}`;
+}
+/**
+ * Email OTP sign-in. `readOtp` is the caller's prompt (the CLI reads it muted from the terminal); the code
+ * is consulted once, never echoed, never written.
+ */
+export declare function signInWithEmailOtp(email: string, readOtp: () => Promise<string>): Promise<SignedInEndUser>;
+export interface MintedDelegation {
+    readonly expiresAt: string;
+    readonly days: number;
+}
+/** Mint the delegation for the signed-in user, with the ruled expiry bounds (default 90 days, max 180). */
+export declare function mintDelegation(requestedDays: unknown, nowMs?: number): Promise<MintedDelegation>;
+/** The signed-in user's own delegation as CDP reports it, or `undefined` when none is active. */
+export declare function readDelegationAsUser(): Promise<{
+    readonly expiresAt: string;
+} | undefined>;
+/** End-user-side revoke ("the user pulls the plug"), confirmed by read-back. */
+export declare function revokeDelegationAsUser(): Promise<{
+    readonly readsBack: boolean;
+}>;
+export interface PublicFenceStatus {
+    readonly present: boolean;
+    readonly policy_name: string;
+    readonly per_swap_cap_usd: number;
+    /** Otto's PUBLIC CDP project id (a UUID) — the authority the CLI binds its mint to. Always required. */
+    readonly project_id: string;
+    readonly rules_digest?: string;
+    readonly reason?: string;
+}
+export interface FenceReadOptions {
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/** Ask the hosted MCP's PUBLIC `otto_delegation_fence_status`. Any failure to get an answer is FENCE_UNREACHABLE (fail-closed). */
+export declare function readPublicFenceStatus(mcpUrl?: string, options?: FenceReadOptions): Promise<PublicFenceStatus>;
+/** Refuse to proceed unless the fence reads back present. */
+export declare function assertFencePresent(status: PublicFenceStatus): void;

package/dist/delegate.js

@@ -0,0 +1,394 @@
+/**
+ * otto-execute/delegate — the AGENT path to a Model-B delegation, headless from the agent's own process
+ * (PR-2a; Founder word `agent delegate cli`, 2026-08-29). Sign in as the end user by email OTP, mint a
+ * time-boxed CDP delegation to Otto's project, read it back, revoke it — all END-USER-SIDE: no Otto
+ * credential is ever in this process, and the delegation can only be minted by the signed-in user (the API
+ * requires the user's Bearer token plus an `X-Wallet-Auth` JWT signed by a Temporary Wallet Secret that
+ * lives inside `@coinbase/cdp-core`).
+ *
+ * THIS PATH IS NOT DOCUMENTED OR SUPPORTED BY COINBASE AND CAN BREAK ON AN SDK UPDATE; the browser page is
+ * the supported path. `@coinbase/cdp-core` ships browser + react-native bundles only, so Node resolves the
+ * WEB bundle and runs it with exactly two shims installed here before the SDK loads: an in-memory
+ * `localStorage` (sign-in needs it) and a `window = { crypto }` alias (the delegation leg spells WebCrypto as
+ * `window.crypto`; Node 22's `globalThis.crypto` is the same WebCrypto the SDK's native build uses). Nothing
+ * else is aliased — no `document`, no `location`. The dependency is PINNED (`@coinbase/cdp-core` 0.0.120 —
+ * the version proven live at Sitting B, 2026-08-29); a canary test drives the real web build on Node against
+ * a loopback fake of the CDP API, and the alias breaking is a NAMED refusal (`CDP_CORE_NODE_PATH_BROKEN`),
+ * never a silent failure. A Node client sends no Origin, so Coinbase's domain allowlist does not apply to
+ * it — a policy/support risk with Coinbase, not a fund or user risk: the secret stays on the user's own
+ * device and the human still consents via the OTP.
+ *
+ * FENCE BEFORE AUTHORITY holds on this path too: `readPublicFenceStatus` asks the hosted MCP's PUBLIC
+ * `otto_delegation_fence_status` (no header — the fence's public promise, never user data) and the CLI
+ * refuses to mint when the fence is not present, or when the MCP cannot be reached (fail-closed). The server
+ * enforces the same on every delegated send regardless.
+ *
+ * Kept on its OWN entry (`otto-execute/delegate`): the root export never loads cdp-core; the SDK is loaded
+ * lazily inside `initEndUserSdk` and a consumer without the optional peers (`@coinbase/cdp-core`, pinned, and
+ * `react` — the web build imports `zustand/react`) gets a named refusal (`CDP_CORE_NOT_INSTALLED`).
+ */
+import { boundedDelegationExpiry, MODEL_B_PER_SWAP_CAP_USD, MODEL_B_POLICY_DIGEST_V1, MODEL_B_POLICY_NAME_V1, } from './vendor/otto-intel-mcp/execution-index.js';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const CDP_CORE_PINNED_VERSION = '0.0.120';
+export const DEFAULT_OTTO_MCP_URL = 'https://mcp.ottoai.services/mcp';
+export const DELEGATE_TEST_ENDPOINTS_KEY = '__ottoDelegateTestEndpoints__';
+export function resolveDelegateEndpoints() {
+    const injected = globalThis[DELEGATE_TEST_ENDPOINTS_KEY];
+    const mcpUrl = typeof injected?.mcpUrl === 'string' ? injected.mcpUrl : DEFAULT_OTTO_MCP_URL;
+    const apiBasePath = typeof injected?.apiBasePath === 'string' ? injected.apiBasePath : undefined;
+    return apiBasePath ? { mcpUrl, apiBasePath } : { mcpUrl };
+}
+export const FENCE_STATUS_TOOL_NAME = 'otto_delegation_fence_status';
+export const UNSUPPORTED_PATH_NOTE = 'this path is not documented or supported by Coinbase and can break on an SDK update; the browser page is the supported path';
+export const DELEGATE_REFUSAL_CODES = [
+    /** `@coinbase/cdp-core` (the optional peer, pinned) is not installed. */
+    'CDP_CORE_NOT_INSTALLED',
+    /** The pinned web build no longer runs on Node with the two shims — the SDK reached a browser global. */
+    'CDP_CORE_NODE_PATH_BROKEN',
+    'PROJECT_ID_REQUIRED',
+    'EMAIL_INVALID',
+    'OTP_INVALID',
+    /** Sign-in succeeded but the end user has no EVM account (the project must create an EOA on login). */
+    'NO_EVM_ACCOUNT',
+    'EXPIRY_INVALID',
+    /** The hosted MCP reports the Model-B fence is not present — nothing is minted. */
+    'DELEGATION_FENCE_ABSENT',
+    /** The public fence read answered `present` but the name/digest/cap/project_id are not Otto's v1 — never coerced. */
+    'FENCE_MISMATCH',
+    /** The hosted MCP could not be reached or did not answer the public fence read — nothing is minted (fail-closed). */
+    'FENCE_UNREACHABLE',
+    /** A pre-existing localStorage that this process did not install (persistent web storage) — key material could hit disk. */
+    'STORAGE_NOT_EPHEMERAL',
+    /** A pre-existing `window` that is not exactly this process's `{ crypto }` alias — an unexpected browser global. */
+    'WINDOW_NOT_OURS',
+    /** An Otto credential or the server secret (or any 64-hex value) is present in this process's environment. */
+    'CREDENTIAL_IN_ENVIRONMENT',
+    /** An unrecognized CLI flag (including the OTP families `--otp/--code/--token`) — the OTP must never enter argv. */
+    'UNKNOWN_OPTION',
+    /** `--mcp`/`OTTO_MCP_URL` points at a non-Otto, non-loopback host — the fence source is not trusted. */
+    'FENCE_SOURCE_NOT_OTTO',
+    /** `OTTO_DELEGATE_CDP_BASE_PATH` redirects the SDK endpoint to a non-loopback host — refused (tests use loopback only). */
+    'SDK_ENDPOINT_NOT_COINBASE',
+    /** A revoke that did not take: the grant still reads back — a non-zero refusal, never a success. */
+    'REVOKE_NOT_CONFIRMED',
+    'NOT_SIGNED_IN',
+];
+export class DelegateRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DelegateRefusal';
+    }
+}
+export function isDelegateRefusal(error) {
+    return error instanceof DelegateRefusal;
+}
+function refuse(code, message) {
+    throw new DelegateRefusal(code, message);
+}
+/**
+ * Mask a message before it is printed: URLs → `<url>` and any environment VALUE ≥ 8 chars → `<NAME>` (longest
+ * first, so a value that contains another is masked whole). Applied to every error the CLI prints, so a
+ * verbatim SDK error can never carry a secret or an endpoint to stdout/stderr.
+ */
+export function redactSecrets(text, env = process.env) {
+    let out = text.replace(/https?:\/\/[^\s'"]+/gi, '<url>');
+    const values = Object.entries(env)
+        .map(([name, value]) => ({ name, value: (value ?? '').trim() }))
+        .filter((e) => e.value.length >= 8)
+        .sort((a, b) => b.value.length - a.value.length);
+    for (const { name, value } of values) {
+        if (out.includes(value))
+            out = out.split(value).join(`<${name}>`);
+    }
+    return out;
+}
+/* ------------------------------------------------------------------ *
+ * The two shims — installed before the SDK loads, idempotent, nothing else touched.
+ * ------------------------------------------------------------------ */
+/** The in-memory shim THIS process installed — identity, so a foreign (persistent) localStorage is refused. */
+let ourLocalStorage;
+function installLocalStorageShim() {
+    const existing = globalThis.localStorage;
+    if (existing !== undefined) {
+        // Idempotent for our own shim; anything else (e.g. Node `--experimental-webstorage
+        // --localstorage-file`, which writes to disk) is refused so no session/key material can persist.
+        if (existing === ourLocalStorage)
+            return;
+        refuse('STORAGE_NOT_EPHEMERAL', 'a localStorage this process did not install is present (persistent web storage can write SDK session/key material to disk); run the delegate path without --experimental-webstorage/--localstorage-file');
+    }
+    const store = new Map();
+    const shim = {
+        get length() {
+            return store.size;
+        },
+        clear: () => store.clear(),
+        getItem: (key) => (store.has(key) ? store.get(key) : null),
+        key: (index) => Array.from(store.keys())[index] ?? null,
+        removeItem: (key) => void store.delete(key),
+        setItem: (key, value) => void store.set(key, String(value)),
+    };
+    ourLocalStorage = shim;
+    Object.defineProperty(globalThis, 'localStorage', { value: shim, configurable: true });
+}
+/**
+ * A pre-existing `window` is trusted ONLY when its sole own key is `crypto`, held as a DATA property whose
+ * value is IDENTICALLY Node's own `globalThis.crypto`. Requiring a data property (not an accessor) closes the
+ * getter TOCTOU where `window.crypto` returns the genuine object on the validating read and an interceptor on
+ * the SDK's later read. (A Proxy that lies on getOwnPropertyDescriptor requires in-process code execution to
+ * install — which already subsumes this process — so it is out of scope.)
+ */
+function windowIsOurs(win) {
+    const keys = Reflect.ownKeys(win);
+    if (keys.length !== 1 || keys[0] !== 'crypto')
+        return false;
+    const descriptor = Object.getOwnPropertyDescriptor(win, 'crypto');
+    return !!descriptor && 'value' in descriptor && descriptor.value === globalThis.crypto;
+}
+function installWindowCryptoAlias() {
+    const existing = globalThis.window;
+    if (existing !== undefined) {
+        if (windowIsOurs(existing))
+            return;
+        refuse('WINDOW_NOT_OURS', 'a pre-existing `window` that is not exactly this process’s { crypto } alias is present; refusing so the SDK cannot reach an unexpected browser global');
+    }
+    if (!globalThis.crypto?.subtle) {
+        refuse('CDP_CORE_NODE_PATH_BROKEN', 'Node WebCrypto (globalThis.crypto.subtle) is required for the headless end-user leg');
+    }
+    Object.defineProperty(globalThis, 'window', {
+        value: Object.freeze({ crypto: globalThis.crypto }),
+        configurable: true,
+    });
+}
+/**
+ * The SDK's web build reaching a browser global it expected (`window`, `document`, `navigator`, …) is the
+ * signature of the unsupported path breaking under an SDK change: a NAMED refusal, never a raw
+ * ReferenceError. Anything else is rethrown as itself.
+ */
+export async function nodePathGuard(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (isNodePathBreak(error)) {
+            refuse('CDP_CORE_NODE_PATH_BROKEN', `the pinned @coinbase/cdp-core ${CDP_CORE_PINNED_VERSION} web build reached a browser global on Node (${error.message}); ${UNSUPPORTED_PATH_NOTE}`);
+        }
+        throw error;
+    }
+}
+function isNodePathBreak(error, depth = 0) {
+    if (!(error instanceof Error) || depth > 8)
+        return false;
+    const browserGlobal = /\b(window|document|navigator|location|self|indexedDB|sessionStorage)\b/;
+    if (error instanceof ReferenceError && browserGlobal.test(error.message))
+        return true;
+    if (error instanceof TypeError &&
+        /Cannot read propert(y|ies) of undefined/.test(error.message) &&
+        (browserGlobal.test(error.message) ||
+            /reading '(crypto|subtle|getRandomValues|createElement|addEventListener|querySelector|cookie|userAgent)'/.test(error.message)))
+        return true;
+    // The SDK wraps failures ("Something went wrong.") — the break, if any, is in the cause chain.
+    return isNodePathBreak(error.cause, depth + 1);
+}
+let core;
+async function loadCdpCore() {
+    try {
+        return (await import('@coinbase/cdp-core'));
+    }
+    catch (error) {
+        // An import-time failure that reaches a browser global is the unsupported path breaking, NOT an
+        // absent peer — classify it first so it is not mislabeled `CDP_CORE_NOT_INSTALLED`.
+        if (isNodePathBreak(error)) {
+            refuse('CDP_CORE_NODE_PATH_BROKEN', `the pinned @coinbase/cdp-core ${CDP_CORE_PINNED_VERSION} web build reached a browser global at import on Node (${error.message}); ${UNSUPPORTED_PATH_NOTE}`);
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        return refuse('CDP_CORE_NOT_INSTALLED', `the delegate entry needs its optional peers — @coinbase/cdp-core@${CDP_CORE_PINNED_VERSION} and react (cdp-core's web build imports zustand/react) — and one is not installed (${reason})`);
+    }
+}
+/**
+ * Boot cdp-core for Otto's CDP project (a PUBLIC project id). Idempotent per process. Returns nothing on
+ * purpose: the SDK module type must not appear in this package's declarations, or a consumer WITHOUT the
+ * optional `@coinbase/cdp-core` peer fails `tsc` on `otto-execute/delegate` (the isolated-install smoke
+ * compiles a consumer with `skipLibCheck: false` to keep it that way).
+ */
+export async function initEndUserSdk(projectId, options = {}) {
+    if (core)
+        return;
+    const id = projectId?.trim() ?? '';
+    if (!/^[0-9a-f-]{36}$/i.test(id)) {
+        refuse('PROJECT_ID_REQUIRED', 'a CDP project id (UUID) is required: --project-id or OTTO_CDP_PROJECT_ID (a public identifier)');
+    }
+    installLocalStorageShim();
+    installWindowCryptoAlias();
+    const mod = await loadCdpCore();
+    await nodePathGuard(() => mod.initialize({
+        projectId: id,
+        ethereum: { createOnLogin: 'eoa' },
+        disableAnalytics: true,
+        ...(options.apiBasePath ? { basePath: options.apiBasePath } : {}),
+    }));
+    core = mod;
+}
+function sdk() {
+    if (!core)
+        refuse('NOT_SIGNED_IN', 'initEndUserSdk has not run in this process');
+    return core;
+}
+/**
+ * Email OTP sign-in. `readOtp` is the caller's prompt (the CLI reads it muted from the terminal); the code
+ * is consulted once, never echoed, never written.
+ */
+export async function signInWithEmailOtp(email, readOtp) {
+    const address = email.trim();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address))
+        refuse('EMAIL_INVALID', 'a valid email is required');
+    const mod = sdk();
+    // A fresh sign-in each time: the SDK refuses a second sign-in while a session is live in the process.
+    if (await nodePathGuard(() => mod.isSignedIn()))
+        await nodePathGuard(() => mod.signOut());
+    const { flowId } = await nodePathGuard(() => mod.signInWithEmail({ email: address }));
+    const otp = (await readOtp()).trim();
+    if (!/^[0-9]{4,10}$/.test(otp))
+        refuse('OTP_INVALID', 'that does not look like an OTP code; request a fresh one');
+    const { user } = await nodePathGuard(() => mod.verifyEmailOTP({ flowId, otp }));
+    const account = user.evmAccounts?.[0];
+    if (!account) {
+        refuse('NO_EVM_ACCOUNT', 'sign-in succeeded but the end user has no EVM account; the project must create an EVM EOA on login');
+    }
+    return Object.freeze({ userId: user.userId, address: account });
+}
+/** Mint the delegation for the signed-in user, with the ruled expiry bounds (default 90 days, max 180). */
+export async function mintDelegation(requestedDays, nowMs = Date.now()) {
+    let bounded;
+    try {
+        bounded = boundedDelegationExpiry(requestedDays, nowMs);
+    }
+    catch (error) {
+        return refuse('EXPIRY_INVALID', error instanceof Error ? error.message : String(error));
+    }
+    const mod = sdk();
+    const minted = await nodePathGuard(() => mod.createDelegation({ expiresAt: bounded.expiresAt }));
+    return Object.freeze({ expiresAt: minted.expiresAt, days: bounded.days });
+}
+/** The signed-in user's own delegation as CDP reports it, or `undefined` when none is active. */
+export async function readDelegationAsUser() {
+    const mod = sdk();
+    try {
+        const grant = await nodePathGuard(() => mod.getDelegation());
+        return Object.freeze({ expiresAt: String(grant.expiresAt ?? '') });
+    }
+    catch (error) {
+        const e = error;
+        if (e.statusCode === 404 ||
+            ['delegation_not_found', 'delegation_revoked', 'delegation_expired'].includes(e.errorType ?? ''))
+            return undefined;
+        throw error;
+    }
+}
+/** End-user-side revoke ("the user pulls the plug"), confirmed by read-back. */
+export async function revokeDelegationAsUser() {
+    const mod = sdk();
+    await nodePathGuard(() => mod.revokeDelegation());
+    const after = await readDelegationAsUser();
+    return Object.freeze({ readsBack: after !== undefined });
+}
+/**
+ * The hosted MCP may answer JSON or, per its `Accept`, a `text/event-stream` frame. Read the JSON either way:
+ * for SSE, concatenate the `data:` lines of the (single) event and parse that. Never throws — an unparseable
+ * body returns `undefined`, which the caller turns into FENCE_UNREACHABLE (fail-closed).
+ */
+function parseRpcBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const data = text
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice(5).trimStart())
+            .join('');
+        if (data === '')
+            return undefined;
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Ask the hosted MCP's PUBLIC `otto_delegation_fence_status`. Any failure to get an answer is FENCE_UNREACHABLE (fail-closed). */
+export async function readPublicFenceStatus(mcpUrl = DEFAULT_OTTO_MCP_URL, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+    let reply;
+    try {
+        const response = await fetchImpl(mcpUrl, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json, text/event-stream',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: { name: FENCE_STATUS_TOOL_NAME, arguments: {} },
+            }),
+            // A 3xx would take the read to a host the caller's guard never vetted; refuse rather than follow it,
+            // so the host the CLI trusted is the host that actually answers (fail-closed → FENCE_UNREACHABLE).
+            redirect: 'error',
+            signal: controller.signal,
+        });
+        if (response.status !== 200) {
+            refuse('FENCE_UNREACHABLE', `the hosted MCP answered HTTP ${response.status} to the public fence read; nothing is minted`);
+        }
+        reply = parseRpcBody(await response.text());
+    }
+    catch (error) {
+        if (isDelegateRefusal(error))
+            throw error;
+        refuse('FENCE_UNREACHABLE', `the hosted MCP could not be reached for the public fence read (${error instanceof Error ? error.name : 'error'}); nothing is minted`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const result = reply
+        ?.result;
+    const status = result?.structuredContent;
+    if (!result || result.isError || !status || typeof status.present !== 'boolean') {
+        refuse('FENCE_UNREACHABLE', 'the hosted MCP did not answer the public fence read with a fence status; nothing is minted');
+    }
+    // The authority binding: a UUID project id must be published (present OR absent) or there is nothing to
+    // mint to — fail-closed. Never coerced.
+    const projectId = typeof status.project_id === 'string' ? status.project_id : '';
+    if (!UUID_PATTERN.test(projectId)) {
+        refuse('FENCE_UNREACHABLE', 'the public fence read carried no CDP project id (a UUID) to bind the mint to; nothing is minted');
+    }
+    // When the fence reads back PRESENT, its promise must be Otto's v1 EXACTLY — name, rules digest and cap.
+    // Anything else is a fence that is not the one this build knows: FENCE_MISMATCH, never coerced to authority.
+    if (status.present === true) {
+        if (status.policy_name !== MODEL_B_POLICY_NAME_V1 ||
+            status.rules_digest !== MODEL_B_POLICY_DIGEST_V1 ||
+            status.per_swap_cap_usd !== MODEL_B_PER_SWAP_CAP_USD) {
+            refuse('FENCE_MISMATCH', `the public fence read answered present but not as "${MODEL_B_POLICY_NAME_V1}" with the v1 rules digest and the ${MODEL_B_PER_SWAP_CAP_USD} USD cap; nothing is minted`);
+        }
+    }
+    return Object.freeze({
+        present: status.present,
+        policy_name: String(status.policy_name ?? ''),
+        per_swap_cap_usd: Number(status.per_swap_cap_usd ?? 0),
+        project_id: projectId,
+        ...(typeof status.rules_digest === 'string' ? { rules_digest: status.rules_digest } : {}),
+        ...(typeof status.reason === 'string' ? { reason: status.reason } : {}),
+    });
+}
+/** Refuse to proceed unless the fence reads back present. */
+export function assertFencePresent(status) {
+    if (!status.present) {
+        refuse('DELEGATION_FENCE_ABSENT', `the Model-B fence is not present on the hosted MCP (${status.reason ?? 'absent'}); nothing is minted — the operator installs it first`);
+    }
+}
+//# sourceMappingURL=delegate.js.map

package/dist/eoa-signer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * eoa-signer.ts — the bring-your-own-EOA capability provider (spec §2 SigningAdapter, §9 handshakes).
+ *
+ * Provides `send_evm_transaction` (one signed tx per plan step, in order; nonce/gas/serialization are
+ * adapter-owned per spec §6) and `sign_x402_payment` (challenge → signed `x_payment`, exactly the
+ * hosted MCP's existing retry protocol). The key never leaves this process; it is read from the
+ * environment once (env.ts registers it with the output guard) or generated in-process for a
+ * dry run and discarded. On this path the USER's key both signs and submits.
+ *
+ * Dry run = sign, never broadcast: every step is signed with placeholder nonce/gas, parsed back, and
+ * the parsed {to, value, data} must equal the verified plan step byte-for-byte, and the signature
+ * must recover to this account. That proves "what the signer signs is what the adapter verified"
+ * without touching a chain.
+ */
+import { type Address, type Hex, type PublicClient } from 'viem';
+import { type SealedWaitOptions } from './chain.js';
+import { type ValidatedX402Challenge, type X402Table } from './x402-table.js';
+import { type SigningCapability, type VerifiedStep, type VerifiedSwap } from './verify.js';
+import type { SentStep } from './vendor/otto-intel-mcp/adapter-index.js';
+export declare const EOA_CAPABILITIES: readonly SigningCapability[];
+export declare const CHAIN_ID: 8453;
+/**
+ * The INDEPENDENT per-payment ceiling applied to every x402 signature, stated here rather than
+ * inherited from `@x402/core`'s default (which is the same `$1`, but is the SDK's number to change,
+ * not ours). Every live table row is $0.001–$0.002, so this has ~500x of headroom over real traffic;
+ * it exists to bound a table that is wrong, not to bound normal use. Raising it is a deliberate edit.
+ */
+export declare const PER_PAYMENT_SPEND_CAP: "$1";
+export interface DryRunSignedStep {
+    readonly index: number;
+    readonly kind: VerifiedStep['kind'];
+    readonly to: Address;
+    readonly signed_bytes: number;
+    readonly recovered_signer: Address;
+    readonly decoded_matches_plan: true;
+    readonly broadcast: false;
+}
+export type { SentStep };
+export interface SignedX402Payment {
+    /** The `x_payment` value: base64 x402 v2 PaymentPayload (the hosted MCP forwards it as `X-Payment`). */
+    readonly header: string;
+    readonly payload: Record<string, unknown>;
+}
+/** A plan step failed after an approval was live; the adapter tried to clear the allowance. */
+export declare class PlanHaltedError extends Error {
+    readonly failedStep: number;
+    readonly allowanceCleared: boolean;
+    readonly clearTransactionHash?: Hex | undefined;
+    constructor(message: string, failedStep: number, allowanceCleared: boolean, clearTransactionHash?: Hex | undefined);
+}
+export declare class EoaSigner {
+    private readonly account;
+    private readonly rpcUrl;
+    readonly address: Address;
+    readonly capabilities: readonly SigningCapability[];
+    readonly chainId: 8453;
+    private constructor();
+    static fromPrivateKey(privateKey: Hex, rpcUrl?: string): EoaSigner;
+    /** A throwaway in-process key for dry runs. Never printed, never persisted, gone with the process. */
+    static ephemeral(): EoaSigner;
+    publicClient(): PublicClient;
+    /**
+     * `send_evm_transaction`, dry: sign every step, decode back, recover — broadcast nothing. `clock` is
+     * either a fixed instant (deterministic tests) or a clock FUNCTION read afresh before every signature
+     * (the default, `Date.now`), so an artifact that expires between two signatures is caught.
+     */
+    signPlanDryRun(plan: VerifiedSwap, clock?: number | (() => number)): Promise<DryRunSignedStep[]>;
+    /**
+     * Nonce / fee / gas round trips first, then `beforeSign` (the plan's freshness + binding re-check,
+     * AFTER those round trips and immediately before the signature), then sign and broadcast. Resolves
+     * only with the SEALED, CANONICAL receipt (`waitForSealedReceipt`): the next step's gas estimate and
+     * any read-back must see this transaction, and a Flashblocks preconfirmation alone guarantees neither
+     * that they do nor that the transaction survived sealing.
+     */
+    private submit;
+    /**
+     * `send_evm_transaction`, live: one tx per step, in order, the plan re-checked before every step AND
+     * again immediately before each signature (after the nonce / fee / gas round trips, so an artifact
+     * that expires during preparation is never signed). The plan halts at the first step that does not
+     * succeed; after ANY failure a bounded `approve(spender, 0)` is attempted and its real outcome —
+     * confirmed by an allowance read-back — is reported, so no allowance outlives the halted plan unnoticed.
+     */
+    sendPlan(plan: VerifiedSwap, pub?: PublicClient, sealedWait?: SealedWaitOptions): Promise<SentStep[]>;
+    private halt;
+    /**
+     * `sign_x402_payment`: turn a table-validated challenge into the signed `x_payment` value.
+     * Validation and hand-off are two moments. Immediately before signing, the document is validated
+     * AGAIN against the static table and must resolve to the same row and the same bound fields as the
+     * earlier validation; the requirement selector accepts only a candidate matching that ROW; and the
+     * produced payload's `accepted` requirement and authorization are checked against the ROW (not
+     * against anything the challenge supplied) before the header is returned.
+     */
+    signX402Payment(paymentRequired: unknown, validated: ValidatedX402Challenge, table?: X402Table, nowSeconds?: number): Promise<SignedX402Payment>;
+}