otto-intel-mcp 0.1.0

package/dist/execution-delegated-definition.js

@@ -0,0 +1,116 @@
+/**
+ * execution-delegated-definition.ts — the ONE execution tool that submits: `otto_submit_under_delegation`.
+ * Kept apart from the prepare-only `EXECUTION_TOOL_DEFINITIONS` on purpose: it registers only when the
+ * hosted service holds Otto's CDP developer credentials, it is not read-only, and its caller is
+ * authenticated per request by a header the arguments never carry.
+ */
+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';
+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';
+const END_USER_ID_PATTERN = /^[a-zA-Z0-9-]{1,100}$/;
+const EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
+const HEX_PATTERN = /^0x(?:[0-9a-fA-F]{2})*$/;
+export const SUBMIT_UNDER_DELEGATION_INPUT_SCHEMA = z
+    .object({
+    userId: z
+        .string()
+        .regex(END_USER_ID_PATTERN, 'must be a CDP end-user id')
+        .describe('The CDP end user whose delegation submits the plan. The server reads the user and its accounts from CDP; the caller never binds an address on its own.'),
+    envelope: EXECUTION_ENVELOPE_SCHEMA.describe('The otto_prepare_swap envelope, exactly as returned.'),
+    prepareInput: PREPARE_SWAP_INPUT_SCHEMA.describe("The EXACT otto_prepare_swap request that produced the envelope (binds intent_digest). slippage.minAmountOut is REQUIRED here: it is the user's own floor, enforced on-chain by the router and re-checked by the verifier."),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.prepareInput.slippage.minAmountOut === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['prepareInput', 'slippage', 'minAmountOut'],
+            message: 'required for a delegated send: the caller must state the minimum acceptable output',
+        });
+    }
+    if (value.prepareInput.accountProfile.kind !== 'eoa') {
+        context.addIssue({
+            code: 'custom',
+            path: ['prepareInput', 'accountProfile', 'kind'],
+            message: 'a CDP end-user account is an EOA',
+        });
+    }
+    if (value.prepareInput.chainId !== 8453 || value.envelope.payload.chain_id !== 8453) {
+        context.addIssue({
+            code: 'custom',
+            path: ['prepareInput', 'chainId'],
+            message: 'delegated sends are Base mainnet (8453) only',
+        });
+    }
+});
+/**
+ * What the tool REGISTERS as its input schema: permissive on purpose. The MCP SDK validates the registered
+ * schema BEFORE the handler runs, which would answer an unauthenticated caller with the exact validation
+ * failure — a schema oracle in front of the caller check. Registering a passthrough object moves ALL
+ * validation behind the header check: the handler parses `SUBMIT_UNDER_DELEGATION_INPUT_SCHEMA` itself,
+ * strictly, after the caller is accepted. The strict schema stays exported for consumers.
+ */
+export const DELEGATED_TOOL_TRANSPORT_SCHEMA = z.object({}).passthrough();
+const SENT_STEP_SCHEMA = z
+    .object({
+    index: z.number().int().min(0).max(2),
+    kind: z.enum(['approve_reset', 'approve', 'call']),
+    to: z.string().regex(EVM_ADDRESS_PATTERN),
+    transaction_hash: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
+    status: z.literal('success'),
+    block_number: z.string().regex(/^\d+$/),
+    gas_used: z.string().regex(/^\d+$/),
+})
+    .strict();
+export const DELEGATED_SEND_RESULT_SCHEMA = z
+    .object({
+    status: z.literal('sent'),
+    user_id: z.string().regex(END_USER_ID_PATTERN),
+    address: z.string().regex(EVM_ADDRESS_PATTERN),
+    chain_id: z.literal(8453),
+    artifact_id: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/),
+    steps: z.array(SENT_STEP_SCHEMA).length(3),
+    fence: z
+        .object({
+        policy_id: z.string(),
+        policy_name: z.string(),
+        rules_digest: z.string().regex(/^[0-9a-f]{64}$/),
+        per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+    })
+        .strict(),
+    delegation: z.object({ expires_at: z.string() }).strict(),
+    /** True when this response is the stored result of an EARLIER submission of the same artifact (nothing was re-sent). */
+    replayed: z.boolean().optional(),
+    verification: z
+        .object({
+        checks: z.array(z.string()).min(12),
+        gross: z.string().regex(/^\d+$/),
+        min_amount_out: z.string().regex(/^\d+$/),
+        otto_fee_atomic: z.string().regex(/^\d+$/),
+        otto_fee_recipient: z.string().regex(EVM_ADDRESS_PATTERN),
+        fee_config_version: z.string(),
+        receiver: z.string().regex(EVM_ADDRESS_PATTERN),
+        call_data_digest: z.string().regex(HEX_PATTERN).optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** Not read-only, not idempotent: every accepted call moves the end user's funds through the delegation. */
+export const DELEGATED_TOOL_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+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.`,
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    strictInputSchema: SUBMIT_UNDER_DELEGATION_INPUT_SCHEMA,
+    outputSchema: DELEGATED_SEND_RESULT_SCHEMA,
+});
+//# sourceMappingURL=execution-delegated-definition.js.map

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

@@ -0,0 +1,208 @@
+/**
+ * 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`.
+ *
+ * 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
+ * transport schema is permissive and the strict schema is parsed only AFTER the header is accepted (no schema
+ * oracle in front of the caller check — `execution-delegated-definition.ts` states why).
+ *
+ * IDENTITY INVARIANT (seat ruling, 21:4x CEST): `status` and the user path of `revoke` never take a client-sent
+ * id — they take the end user's CDP ACCESS TOKEN and the server resolves the userId itself through
+ * `cdp.endUser.validateAccessToken`. A bare `userId` on `status` is refused by the strict schema. The SUPPORT path
+ * of `revoke` (`{ userId, support_reason }`) exists for an operator holding the server secret; the dApp's public
+ * proxy exposes only the token variant (asserted in PR-2).
+ */
+import { z } from 'zod';
+import { DELEGATED_TOOL_TRANSPORT_SCHEMA } from './execution-delegated-definition.js';
+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"];
+/** 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>;
+export declare const DELEGATION_FENCE_RESULT_SCHEMA: z.ZodObject<{
+    status: z.ZodLiteral<"present">;
+    action: z.ZodEnum<{
+        unchanged: "unchanged";
+        created: "created";
+        updated: "updated";
+    }>;
+    policy_id: z.ZodString;
+    policy_name: z.ZodString;
+    rules_digest: z.ZodString;
+    per_swap_cap_usd: z.ZodLiteral<5000>;
+}, z.core.$strict>;
+export declare const DELEGATION_STATUS_INPUT_SCHEMA: z.ZodObject<{
+    accessToken: z.ZodString;
+}, z.core.$strict>;
+export declare const DELEGATION_STATUS_RESULT_SCHEMA: z.ZodObject<{
+    user_id: z.ZodString;
+    addresses: z.ZodArray<z.ZodString>;
+    fence: z.ZodObject<{
+        present: z.ZodBoolean;
+        policy_name: z.ZodString;
+        per_swap_cap_usd: z.ZodLiteral<5000>;
+        rules_digest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    delegation: z.ZodObject<{
+        active: z.ZodBoolean;
+        expires_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    revocation_requested_here: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const DELEGATION_REVOKE_INPUT_SCHEMA: z.ZodUnion<readonly [z.ZodObject<{
+    accessToken: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    userId: z.ZodString;
+    support_reason: z.ZodString;
+}, z.core.$strict>]>;
+export declare const DELEGATION_REVOKE_RESULT_SCHEMA: z.ZodObject<{
+    user_id: z.ZodString;
+    revoked: z.ZodLiteral<true>;
+    reads_back: z.ZodLiteral<false>;
+    path: z.ZodEnum<{
+        user: "user";
+        support: "support";
+    }>;
+}, z.core.$strict>;
+export type DelegationFenceResult = z.infer<typeof DELEGATION_FENCE_RESULT_SCHEMA>;
+export declare const DELEGATION_FENCE_STATUS_INPUT_SCHEMA: z.ZodObject<{}, z.core.$strict>;
+export declare const DELEGATION_FENCE_STATUS_RESULT_SCHEMA: z.ZodObject<{
+    present: z.ZodBoolean;
+    policy_name: z.ZodString;
+    per_swap_cap_usd: z.ZodLiteral<5000>;
+    project_id: z.ZodOptional<z.ZodString>;
+    rules_digest: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        absent: "absent";
+        ambiguous: "ambiguous";
+        name_mismatch: "name_mismatch";
+        digest_mismatch: "digest_mismatch";
+    }>>;
+}, z.core.$strict>;
+export type DelegationFenceStatusResult = z.infer<typeof DELEGATION_FENCE_STATUS_RESULT_SCHEMA>;
+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: {}.";
+    inputSchema: z.ZodObject<{}, z.core.$strict>;
+    outputSchema: z.ZodObject<{
+        present: z.ZodBoolean;
+        policy_name: z.ZodString;
+        per_swap_cap_usd: z.ZodLiteral<5000>;
+        project_id: z.ZodOptional<z.ZodString>;
+        rules_digest: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            absent: "absent";
+            ambiguous: "ambiguous";
+            name_mismatch: "name_mismatch";
+            digest_mismatch: "digest_mismatch";
+        }>>;
+    }, z.core.$strict>;
+    annotations: Readonly<{
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+        openWorldHint: true;
+    }>;
+}>;
+export type DelegationStatusResult = z.infer<typeof DELEGATION_STATUS_RESULT_SCHEMA>;
+export type DelegationRevokeResult = z.infer<typeof DELEGATION_REVOKE_RESULT_SCHEMA>;
+export interface DelegationAdminToolDefinition<TStrict extends z.ZodTypeAny, TOut extends z.ZodTypeAny> {
+    readonly name: (typeof DELEGATION_ADMIN_TOOL_NAMES)[number];
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: typeof DELEGATED_TOOL_TRANSPORT_SCHEMA;
+    readonly strictInputSchema: TStrict;
+    readonly outputSchema: TOut;
+    readonly annotations: {
+        readonly readOnlyHint: boolean;
+        readonly destructiveHint: boolean;
+        readonly idempotentHint: boolean;
+        readonly openWorldHint: boolean;
+    };
+}
+export declare const DELEGATION_FENCE_TOOL_DEFINITION: Readonly<{
+    name: "otto_delegation_fence";
+    title: "Ensure the Model-B project policy (the delegation fence) is installed and reads back as v-current";
+    description: `Idempotent ensure-by-digest of the ONE CDP project-scope policy that fences every delegated send, then a read-back. Writes only when no project policy exists (creates it) or when the existing one is Otto's own lineage with stale rules (updates it in place). REFUSES BY NAME if a different project-scope policy is installed \u2014 it is never overwritten or deleted. Never downgrades a newer fence. An OPS action: at most one ensure runs project-wide at a time, never during a rolling deploy, never from the dApp (the mint gate reads fence.present from otto_delegation_status). Arguments: {}. Output: the policy id, versioned name, rules digest and the per-swap cap; the tool fails unless the fence reads back present under the written id. ${string}`;
+    inputSchema: z.ZodObject<{}, z.core.$loose>;
+    strictInputSchema: z.ZodObject<{}, z.core.$strict>;
+    outputSchema: z.ZodObject<{
+        status: z.ZodLiteral<"present">;
+        action: z.ZodEnum<{
+            unchanged: "unchanged";
+            created: "created";
+            updated: "updated";
+        }>;
+        policy_id: z.ZodString;
+        policy_name: z.ZodString;
+        rules_digest: z.ZodString;
+        per_swap_cap_usd: z.ZodLiteral<5000>;
+    }, z.core.$strict>;
+    annotations: Readonly<{
+        readOnlyHint: false;
+        destructiveHint: false;
+        idempotentHint: true;
+        openWorldHint: true;
+    }>;
+}>;
+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}`;
+    inputSchema: z.ZodObject<{}, z.core.$loose>;
+    strictInputSchema: z.ZodObject<{
+        accessToken: z.ZodString;
+    }, z.core.$strict>;
+    outputSchema: z.ZodObject<{
+        user_id: z.ZodString;
+        addresses: z.ZodArray<z.ZodString>;
+        fence: z.ZodObject<{
+            present: z.ZodBoolean;
+            policy_name: z.ZodString;
+            per_swap_cap_usd: z.ZodLiteral<5000>;
+            rules_digest: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        delegation: z.ZodObject<{
+            active: z.ZodBoolean;
+            expires_at: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        revocation_requested_here: z.ZodBoolean;
+    }, z.core.$strict>;
+    annotations: Readonly<{
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+        openWorldHint: true;
+    }>;
+}>;
+export declare const DELEGATION_REVOKE_TOOL_DEFINITION: Readonly<{
+    name: "otto_delegation_revoke";
+    title: "Revoke one end user's delegation, developer-side, confirmed by read-back";
+    description: `Revoke the end user's delegation from Otto's side and confirm by read-back that it no longer exists; from then on this server submits nothing for that user (fail-closed, even if the read-back had failed). Arguments: EITHER { accessToken } (the user path \u2014 the server resolves the user from the token) OR { userId, support_reason } (the support path, for an operator holding the server secret; the reason is logged, the token never is). ${string}`;
+    inputSchema: z.ZodObject<{}, z.core.$loose>;
+    strictInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+        accessToken: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        userId: z.ZodString;
+        support_reason: z.ZodString;
+    }, z.core.$strict>]>;
+    outputSchema: z.ZodObject<{
+        user_id: z.ZodString;
+        revoked: z.ZodLiteral<true>;
+        reads_back: z.ZodLiteral<false>;
+        path: z.ZodEnum<{
+            user: "user";
+            support: "support";
+        }>;
+    }, z.core.$strict>;
+    annotations: Readonly<{
+        readOnlyHint: false;
+        destructiveHint: true;
+        idempotentHint: true;
+        openWorldHint: true;
+    }>;
+}>;

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

@@ -0,0 +1,170 @@
+/**
+ * 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`.
+ *
+ * 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
+ * transport schema is permissive and the strict schema is parsed only AFTER the header is accepted (no schema
+ * oracle in front of the caller check — `execution-delegated-definition.ts` states why).
+ *
+ * IDENTITY INVARIANT (seat ruling, 21:4x CEST): `status` and the user path of `revoke` never take a client-sent
+ * id — they take the end user's CDP ACCESS TOKEN and the server resolves the userId itself through
+ * `cdp.endUser.validateAccessToken`. A bare `userId` on `status` is refused by the strict schema. The SUPPORT path
+ * of `revoke` (`{ userId, support_reason }`) exists for an operator holding the server secret; the dApp's public
+ * 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 { DELEGATION_AUTH_HEADER, DELEGATED_TOOL_TRANSPORT_SCHEMA, } from './execution-delegated-definition.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';
+export const DELEGATION_ADMIN_TOOL_NAMES = Object.freeze([
+    DELEGATION_FENCE_TOOL_NAME,
+    DELEGATION_STATUS_TOOL_NAME,
+    DELEGATION_REVOKE_TOOL_NAME,
+]);
+/** 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}$/;
+const EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
+/** A CDP end-user access token: opaque, bounded, never logged, never echoed. */
+const ACCESS_TOKEN_SCHEMA = z.string().min(16).max(8192);
+/* ── fence ── */
+export const DELEGATION_FENCE_INPUT_SCHEMA = z.object({}).strict();
+export const DELEGATION_FENCE_RESULT_SCHEMA = z
+    .object({
+    status: z.literal('present'),
+    /** What this call did: nothing (already v-current), created it, or updated our own stale lineage in place. */
+    action: z.enum(['unchanged', 'created', 'updated']),
+    policy_id: z.string(),
+    policy_name: z.string(),
+    rules_digest: z.string().regex(/^[0-9a-f]{64}$/),
+    per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+})
+    .strict();
+/* ── status ── */
+export const DELEGATION_STATUS_INPUT_SCHEMA = z
+    .object({ accessToken: ACCESS_TOKEN_SCHEMA })
+    .strict();
+export const DELEGATION_STATUS_RESULT_SCHEMA = z
+    .object({
+    user_id: z.string().regex(END_USER_ID_PATTERN),
+    addresses: z.array(z.string().regex(EVM_ADDRESS_PATTERN)),
+    fence: z
+        .object({
+        present: z.boolean(),
+        policy_name: z.string(),
+        per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+        rules_digest: z
+            .string()
+            .regex(/^[0-9a-f]{64}$/)
+            .optional(),
+    })
+        .strict(),
+    delegation: z
+        .object({
+        /** Active = reads back from CDP, not expired, and no revocation was requested on this server. */
+        active: z.boolean(),
+        expires_at: z.string().optional(),
+    })
+        .strict(),
+    revocation_requested_here: z.boolean(),
+})
+    .strict();
+/* ── revoke ── */
+export const DELEGATION_REVOKE_INPUT_SCHEMA = z.union([
+    z.object({ accessToken: ACCESS_TOKEN_SCHEMA }).strict(),
+    z
+        .object({
+        userId: z.string().regex(END_USER_ID_PATTERN),
+        support_reason: z.string().min(8).max(200),
+    })
+        .strict(),
+]);
+export const DELEGATION_REVOKE_RESULT_SCHEMA = z
+    .object({
+    user_id: z.string().regex(END_USER_ID_PATTERN),
+    revoked: z.literal(true),
+    /** The grant no longer reads back from CDP (the revoke is confirmed by read-back, never inferred). */
+    reads_back: z.literal(false),
+    path: z.enum(['user', 'support']),
+})
+    .strict();
+/* ── fence status (public, read-only, no header) ── */
+export const DELEGATION_FENCE_STATUS_INPUT_SCHEMA = z.object({}).strict();
+export const DELEGATION_FENCE_STATUS_RESULT_SCHEMA = z
+    .object({
+    present: z.boolean(),
+    policy_name: z.string(),
+    per_swap_cap_usd: z.literal(MODEL_B_PER_SWAP_CAP_USD),
+    /** Otto's PUBLIC CDP project id (a UUID): the authority the agent CLI binds its mint to. */
+    project_id: z
+        .string()
+        .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+        .optional(),
+    rules_digest: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+    /** Why it is not present — a class, never a policy's contents. */
+    reason: z.enum(['absent', 'ambiguous', 'name_mismatch', 'digest_mismatch']).optional(),
+})
+    .strict();
+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: {}.`,
+    inputSchema: DELEGATION_FENCE_STATUS_INPUT_SCHEMA,
+    outputSchema: DELEGATION_FENCE_STATUS_RESULT_SCHEMA,
+    annotations: Object.freeze({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+});
+const AUTH_SENTENCE = `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. The listed input schema is intentionally permissive — the strict schema is validated after the caller is authenticated.`;
+export const DELEGATION_FENCE_TOOL_DEFINITION = Object.freeze({
+    name: DELEGATION_FENCE_TOOL_NAME,
+    title: 'Ensure the Model-B project policy (the delegation fence) is installed and reads back as v-current',
+    description: `Idempotent ensure-by-digest of the ONE CDP project-scope policy that fences every delegated send, then a read-back. Writes only when no project policy exists (creates it) or when the existing one is Otto's own lineage with stale rules (updates it in place). REFUSES BY NAME if a different project-scope policy is installed — it is never overwritten or deleted. Never downgrades a newer fence. An OPS action: at most one ensure runs project-wide at a time, never during a rolling deploy, never from the dApp (the mint gate reads fence.present from otto_delegation_status). Arguments: {}. Output: the policy id, versioned name, rules digest and the per-swap cap; the tool fails unless the fence reads back present under the written id. ${AUTH_SENTENCE}`,
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    strictInputSchema: DELEGATION_FENCE_INPUT_SCHEMA,
+    outputSchema: DELEGATION_FENCE_RESULT_SCHEMA,
+    annotations: Object.freeze({
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+});
+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}`,
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    strictInputSchema: DELEGATION_STATUS_INPUT_SCHEMA,
+    outputSchema: DELEGATION_STATUS_RESULT_SCHEMA,
+    annotations: Object.freeze({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+});
+export const DELEGATION_REVOKE_TOOL_DEFINITION = Object.freeze({
+    name: DELEGATION_REVOKE_TOOL_NAME,
+    title: "Revoke one end user's delegation, developer-side, confirmed by read-back",
+    description: `Revoke the end user's delegation from Otto's side and confirm by read-back that it no longer exists; from then on this server submits nothing for that user (fail-closed, even if the read-back had failed). Arguments: EITHER { accessToken } (the user path — the server resolves the user from the token) OR { userId, support_reason } (the support path, for an operator holding the server secret; the reason is logged, the token never is). ${AUTH_SENTENCE}`,
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    strictInputSchema: DELEGATION_REVOKE_INPUT_SCHEMA,
+    outputSchema: DELEGATION_REVOKE_RESULT_SCHEMA,
+    annotations: Object.freeze({
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    }),
+});
+//# sourceMappingURL=execution-delegation-admin-definition.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * execution-delegation-admin.ts — the three delegation ADMIN tools on the hosted MCP (PR-1b, seat ruling D10 = (a)).
+ *
+ *   otto_delegation_fence   — the ONLY writer of the Model-B project policy: ensure-by-digest + read-back.
+ *   otto_delegation_status  — one user's grant/fence read-back, bound to the user a CDP access token resolves to.
+ *   otto_delegation_revoke  — developer-side revoke with read-back, fail-closed under the rig lock.
+ *
+ * Every tool: the request header FIRST (constant-time, before parsing or any CDP read — the same seam as
+ * `otto_submit_under_delegation`), then the strict schema, then the reads. Nothing here logs a token, the
+ * header, or a credential; refusals are machine-readable codes.
+ *
+ * FENCE RULES (gate r1 of this PR sharpened them; each is mutation-proved in the tests):
+ *   CARDINALITY — Coinbase allows exactly one project-scope policy. A read-back with MORE than one is an
+ *     anomalous snapshot and refuses (`DELEGATION_FENCE_AMBIGUOUS`) before any other judgement — nothing is
+ *     written, nothing is blessed as present on the strength of "one of them matches".
+ *   LINEAGE — a project policy is OURS only when its description matches the ANCHORED pattern
+ *     `^OTTO model b swap fence v<N>$` (`modelBLineageVersion`). Ours with N == this binary's version and the
+ *     v-current rules → `unchanged`. Ours with N ≤ this version and stale rules → updated IN PLACE. Ours with
+ *     N > this version → refused (`DELEGATION_FENCE_NEWER`): a running older binary never downgrades a newer
+ *     fence (rollback is a governed manual act). Anything else — the proof kit's `OTTO PROBE …`, a hand-installed
+ *     policy, no description, the prefix in the middle, a suffix — is FOREIGN: refused by name
+ *     (`DELEGATION_FENCE_FOREIGN`, naming the description + rules-digest prefix); never overwritten, never deleted.
+ *   WRITE ONCE — a create that Coinbase refuses as a duplicate (`already_exists` / 409: someone created a policy
+ *     between the snapshot and the write) is never retried and never turned into an update from this path: the
+ *     tool re-reads once and judges what is there.
+ *   BEFORE AN UPDATE — the policy is re-read BY ID immediately before the write and must still be exactly the
+ *     snapshot (same description, same rules digest); any change → refused, nothing written. `@coinbase/cdp-sdk`
+ *     1.54.0 offers no conditional update (`UpdatePolicyOptions` = { id, policy, idempotencyKey } — no revision,
+ *     no ETag), so the window between that re-read and the write cannot be closed by code. It is closed by the
+ *     OPERATIONAL PREMISE, stated here, in the tool description and in the README: AT MOST ONE ENSURE WRITES
+ *     PROJECT-WIDE AT A TIME, ACROSS VERSIONS — the ensure is an OPS action run by one operator, never during a
+ *     rolling deploy (two versions of this tool running at once are two writers, and the older one would win a
+ *     race and downgrade); the dApp never invokes it (PR-2's mint gate reads `fence.present` from
+ *     `otto_delegation_status`); nobody edits the policy in the CDP portal while an ensure runs. Under that
+ *     premise the re-read is exact; without it, "never overwrite foreign" and "never downgrade" narrow to
+ *     "…what was foreign / newer one round-trip ago".
+ *   READ-BACK BOUND TO THE WRITE — after a write, the proof is a read-back of exactly one project policy whose
+ *     id IS the id that was written (the created id, or the updated id) and which reads back as v-current. A
+ *     matching record under another id (a stale cache, a ghost) is not proof; a bounded poll covers the engine's
+ *     asynchronous propagation, then the tool fails closed (`DELEGATION_FENCE_ABSENT`).
+ *
+ * IDENTITY. `status` and the user path of `revoke` resolve the userId from `cdp.endUser.validateAccessToken`;
+ * a client-sent id is refused by the strict schema. The support path of `revoke` takes `{ userId,
+ * support_reason }` from an operator holding the server secret; the reason is written to the structured log
+ * through the boot redactor (URLs and configured secret values never land in the log), the token never is.
+ */
+import { type DelegationFenceResult, type DelegationFenceStatusResult, type DelegationRevokeResult, type DelegationStatusResult } from './execution-delegation-admin-definition.js';
+import { type DelegationCaller } from './execution-delegation.js';
+import type { ExecutionToolRuntime } from './execution-tools.js';
+/** Read-back after a write: the engine propagates asynchronously (the proof kit waited 3 s flat). */
+export interface FenceReadBackWait {
+    readonly pollMs?: number;
+    readonly maxPolls?: number;
+}
+/** `otto_delegation_fence` — ensure-by-digest + read-back bound to the write; the only writer of the project policy. */
+export declare function ensureDelegationFence(runtime: ExecutionToolRuntime, rawInput: unknown, caller: DelegationCaller, wait?: FenceReadBackWait): Promise<DelegationFenceResult>;
+/**
+ * `otto_delegation_fence_status` — PUBLIC, read-only, no caller check: the fence's public promise. Nothing here
+ * names a user, a grant, an address or a policy's contents; `reason` is a class from `readBackModelBFence`.
+ */
+export declare function readDelegationFenceStatus(runtime: ExecutionToolRuntime): Promise<DelegationFenceStatusResult>;
+/** `otto_delegation_status` — one user's read-back, bound to the token's user. */
+export declare function readDelegationStatus(runtime: ExecutionToolRuntime, rawInput: unknown, caller: DelegationCaller): Promise<DelegationStatusResult>;
+/** What the support path writes to the structured log: the user id and the REDACTED reason — never a token. */
+export interface SupportActionSink {
+    write(entry: {
+        readonly action: 'delegation_revoke';
+        readonly userId: string;
+        readonly reason: string;
+        readonly ts: string;
+    }): void;
+}
+/** `otto_delegation_revoke` — developer-side revoke, read-back inside the rig lock, fail-closed afterwards. */
+export declare function revokeDelegation(runtime: ExecutionToolRuntime, rawInput: unknown, caller: DelegationCaller, supportSink?: SupportActionSink): Promise<DelegationRevokeResult>;