otto-execute 0.1.0 → 0.1.2

package/README.md

@@ -1,151 +1,137 @@
 # otto-execute
 
-The **user's side** of Otto Model B.
-
-> **Agent path to a delegation — `otto-execute delegate`** (`otto-execute/delegate` entry): sign in as the end user by email OTP (typed on the terminal, never echoed, never written), mint a time-boxed CDP delegation to Otto's project (default 90 days, max 180), read it back, revoke it — all from the agent's own process, end-user-side (no Otto credential is ever in it). Before minting it reads the hosted MCP's PUBLIC `otto_delegation_fence_status` and refuses when the Model-B fence is not present (and fails closed when the MCP cannot be reached). **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` is an optional peer PINNED to `0.0.120` (the version proven live); a canary test drives its real web build on Node against a loopback fake on every dependency bump, and the shim breaking is a named refusal (`CDP_CORE_NODE_PATH_BROKEN`), never a silent failure. The fence source (Otto's MCP, `https://mcp.ottoai.services/mcp`) and the CDP SDK endpoint are **fixed** — no flag or environment variable redirects either, and the mint binds to the public project id the fence itself publishes (there is no `--project-id`). The command also refuses to run with any Otto credential or 64-hex value in its environment, and keeps the OTP out of argv by every spelling. **Threat model:** the residual after all of the above is a **platform universal**, not a property of this CLI — a caller who controls the process environment has pre-entry arbitrary code execution in ANY Node program (via `NODE_OPTIONS=--import=…`, `LD_PRELOAD`, or PATH-shadowing the `node` binary), so environment control is equivalent to process control. **An attacker with environment control of your shell already owns your OTP and every CLI on the machine.** Run the delegate path only in an environment you trust.
-
-Otto's hosted MCP (`otto-intel-mcp`, `https://mcp.ottoai.services`) constructs transactions
-**prepare-only**: `otto_prepare_swap` returns an unsigned, digest-committed envelope carrying a LI.FI
-swap with Otto's fee attribution baked in. Nothing in it is signed. This package is what **your**
-signer runs before and while signing one:
-
-1. **Verify** — integrity (the constructor's own schema / digest / commitment / freshness / binding
-   assertions), then **your intent** (input token and exact amount, the deposit legs pulling exactly
-   that, the output token, and your own positive minimum output), then policy (reviewed router,
-   `_receiver` == you, the fee leg decoded independently and matched to the ruled 10 bps to Otto's
-   recipient through a reviewed FeeForwarder deployment, aggregate under the cap). Twelve named checks
-   (+ `intent_digest` when you pass the exact request you sent). A verified plan is deep-frozen and
-   registered by identity; signers additionally require the plan to be bound to THEIR address and chain, to
-   cover their capabilities, and to be fresh at signing time — re-checked before every live step.
-2. **Sign / submit** —
-   - **BYO/EOA** (`EoaSigner`): your key signs **and** submits, one ordered transaction per step,
-     halting and clearing a live allowance on any uncertain failure (the clear is confirmed by an
-     `allowance` read-back, never inferred from a receipt). Freshness and binding are re-asserted
-     immediately before every signature, after the nonce / fee / gas round trips. `signPlanDryRun`
-     signs, decodes back and recovers without broadcasting.
-   - **CDP-delegated** (`CdpDelegatedSigner`, from the `otto-execute/cdp` entry): you have already signed
-     in and minted a time-boxed delegation; Otto's server submits your own transactions under it —
-     user-authenticated, Otto-governed (project policy), Otto-revocable. No raw-submission surface exists
-     on the signer; submission, allowance clearing and revocation are serialized on one lock per rig.
-   - **x402** (`validateX402Challenge` + `EoaSigner.signX402Payment`): a 402 is validated against an
-     exact-match table (resource, recipient, exact amount, exact 300 s window, pinned EIP-712 domain),
-     revalidated immediately before signing, and the produced authorization is checked against the
-     table row. The `table` parameter is public on purpose: it defaults to the built-in `X402_TABLE`
-     (Otto's routes), and a caller may pass a narrower or newer table — the per-payment spend cap below
-     bounds what any table can authorize, so a wrong table cannot sign for more than `$1`.
-
-Otto never holds your keys or funds on either path.
-
-## Install
+The user's side of Otto's execution seam. [Otto Intel MCP](https://www.npmjs.com/package/otto-intel-mcp) builds a swap as an unsigned, digest-committed **envelope** for an address you supply; `otto-execute` checks that envelope against **your own intent**, then signs and submits it with **your** key (or under a delegation you minted). CLI and library, one install.
+
+- npm: `npm install otto-execute` — 19 packages including itself (`@x402/core`, `@x402/evm`, `viem`, `zod`), 0 `npm audit` findings.
+- Docs: https://docs.useotto.xyz/acp-swarm/execution-seam
+- Requires Node 22 or newer.
+
+## Quick start (under a minute)
+
+**1. Get an envelope** — ask the hosted MCP (`https://mcp.ottoai.services`, free) for a swap on your address:
+
+```json
+{
+  "name": "otto_prepare_swap",
+  "arguments": {
+    "accountProfile": { "kind": "eoa", "address": "0xYourAddress", "chainId": 8453 },
+    "chainId": 8453,
+    "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    "toToken": "0x4200000000000000000000000000000000000006",
+    "fromAmount": "1000000",
+    "slippage": { "maxBps": 50, "minAmountOut": "200000000000000" },
+    "client_ref": "my-trade-1"
+  }
+}
+```
+
+Any MCP client works (connection snippets: the [otto-intel-mcp README](https://www.npmjs.com/package/otto-intel-mcp)); the tool result is one text part containing JSON — save that JSON object (it starts with `schema_version`, `artifact_id`, …) as `envelope.json`. It is valid for **5 minutes** from construction (`valid_until`; the hosted server's window — the tool description states it), and `submit` re-checks freshness before each of its three signatures, so don't pace on the window: verify, then submit, or fetch a fresh envelope. v1 builds Base (chain 8453) swaps.
+
+**2. Write your intent** — what *you* meant, in atomic token units (USDC has 6 decimals: `1000000` = 1 USDC; WETH has 18: `200000000000000` = 0.0002 WETH). `minAmountOut` is your own floor from a price source you trust:
+
+```json
+{ "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "toToken": "0x4200000000000000000000000000000000000006", "fromAmount": "1000000", "minAmountOut": "200000000000000" }
+```
+
+**3. Verify, sign, submit:**
 
 ```bash
-npm install otto-execute
+npx otto-execute verify --envelope envelope.json --intent intent.json --account 0xYourAddress      # no key needed
+OTTO_EXECUTE_PRIVATE_KEY=0x… npx otto-execute sign   --envelope envelope.json --intent intent.json   # dry run: signs + decodes back, broadcasts nothing
+OTTO_EXECUTE_PRIVATE_KEY=0x… npx otto-execute submit --envelope envelope.json --intent intent.json --i-understand-mainnet
+```
+
+`verify` on a real envelope prints (captured 2026-09-02):
+
+```json
+{
+  "verified": {
+    "account": "0xF7270569486Ae94945360107721273C60dFdD825",
+    "checks": ["schema", "payload_digest", "commitment", "freshness", "account_binding", "capabilities", "chain", "plan_shape", "approvals", "swap_decode", "min_output", "fee_attribution"],
+    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    "output_token": "0x4200000000000000000000000000000000000006",
+    "gross": "1000000",
+    "otto_fee": "1000",
+    "min_amount_out": "415211826902997",
+    "fee_distributions": [
+      { "recipient": "0xC06ebbefD94032B85424D51906e2A335EFAe264B", "amount": "1500" },
+      { "recipient": "0x0E84dDEdAaE6A779c462C22a59F301EC31B6b808", "amount": "1000" }
+    ],
+    "valid_until": "2026-09-02T09:00:49.613Z",
+    "seconds_remaining": 287,
+    "artifact_id": "01M1GN9T3DH6470V0Y8968QXRX"
+  }
+}
 ```
 
-That installs this package plus `@x402/core`, `@x402/evm`, `viem` and `zod` — 18 packages. The parts of
-`otto-intel-mcp` this package runs at runtime (`otto-intel-mcp/execution`, `/adapter`, `/adapter-cdp` —
-the envelope schema, the verifier, the signing adapters) are **vendored** into `dist/vendor/otto-intel-mcp/`
-at build time as file-for-file copies of the published `otto-intel-mcp` release, so a consumer does not
-install that package (it is also an MCP server and would cost ~240 packages). The copy is byte-verified:
-`dist/vendor/otto-intel-mcp/VENDORED.json` records the version, the registry integrity hash and a sha256 per
-file; `npm run vendor:check` re-derives it (and runs in `prepack`). A change in the seam is therefore a
-visible `otto-intel-mcp` version bump + re-vendor here, never silent drift. `@coinbase/cdp-sdk` stays an
-optional peer, loaded only by the `otto-execute/cdp` entry.
+`seconds_remaining` is the budget you have left to `submit` (the whole plan must clear before `valid_until`).
 
-Working on it inside the monorepo:
+A plan that does not hold is refused by name, exit code 2 — for example an envelope past its window:
 
-```bash
-cd services/otto-execute && npm ci
-npm run verify          # typecheck → build (tsc + vendor-seam) → tests; the prepublishOnly gate
-npm run fixtures:check  # monorepo-only: the committed envelope fixtures still match the sibling constructor
-npm run smoke:install   # pack + clean install outside the repo + a real verify + the consumer package count
+```json
+{ "refused": { "code": "STALE_ARTIFACT", "message": "[STALE_ARTIFACT] execution artifact has expired" } }
 ```
 
-The test suite is **hermetic**: it resolves `otto-intel-mcp/*` from `node_modules` (the published package,
-an exact devDependency) and runs on captured envelope fixtures under `test/fixtures/envelopes/` — genuine
-`otto_prepare_swap` outputs built by the constructor's own code over its real LI.FI captures and committed by
-`scripts/capture-envelopes.ts` (the one file that touches `../otto-intel-mcp`, run only in the monorepo).
-
-**Sealed-state rule (Base Flashblocks).** A receipt can arrive from a preconfirmation while `latest` — the
-state gas estimates and reads run against — still predates it, and a preconfirmation is not final (a
-Flashblock reorg = a preconfirmed transaction omitted from the sealed block). Both signers therefore count a
-transaction as mined ONLY once `waitForSealedReceipt` has refetched its receipt and the sealed canonical
-block at that height carries the receipt's block hash — before the next estimate and before the allowance
-read-back after a clear; if that never happens within the bound, the step fails closed. Observed live
-2026-08-28: an approve preconfirmed, the swap call estimated against `latest`, `TRANSFER_FROM_FAILED` on an
-allowance already granted. The wait is what a user's wallet observes.
-
-`@coinbase/cdp-sdk` is an OPTIONAL peer: only the CDP-delegated signer needs it, and that signer lives on its
-own entry — `import { CdpDelegatedSigner } from 'otto-execute/cdp'`. The root entry (`otto-execute`: verifier,
-BYO/EOA signer, x402 table) and the CLI never resolve the SDK; `test/root-without-cdp.test.ts` loads the root
-with the peer made unresolvable to prove it. The dev-only `.npmrc` (`legacy-peer-deps`) is **gone**: it existed
-only because the SDK's optional `@x402` peers want `^2.19` while this package pinned `2.16.0`, and the
-reconcile to `2.23.0` satisfies that range natively — `npm install` now succeeds with no flag.
-
-> **`@x402/*` reconciled to 2.23.0 (2026-09-01)**, matching what `otto-intel-mcp@0.1.0` ships, so one
-> `@x402/core` instance serves both packages.
->
-> **`spendControls` is set explicitly, and KEPT.** `@x402/core` ≥ 2.23 seeds `spendControls = {}` in the
-> bare `x402Client` constructor, which the SDK reads as *default assets only, capped at `$1` per payment*.
-> `signX402Payment` states that cap in our own source (`PER_PAYMENT_SPEND_CAP = '$1'`) instead of inheriting
-> it, so the number is visible here and a future SDK default cannot move it silently.
->
-> It is deliberately **not** disabled. The table checks more *fields*, but it is **not an independent
-> authority**: `table` is a parameter, and even the default table's `amount_atomic` values are hand-edited
-> constants that nothing else cross-checks. A price typo (`5000` → `5000000`) leaves the table agreeing with
-> itself perfectly, and only a cap derived from the requirement amount rather than from the table stands
-> between that typo and a signature for 1000× the intended amount. Field coverage is not a second opinion.
->
-> The SDK's rejection is translated into this package's own vocabulary as
-> **`X402_SPEND_LIMIT_EXCEEDED`** — a distinct condition from `X402_AMOUNT_EXCEEDED` (which means the
-> *challenge* disagreed with the table; this one means the *table* asked for more than the budget). Only
-> that rejection is translated; every other error rethrows untouched.
->
-> Three tests pin it, mutation-proved in both directions: a `$5` typo row is never signed (flip the cap to
-> `false` and it signs; delete the translation and a raw SDK error escapes instead of an `X402Refusal`), a
-> live-priced row still signs through the same path, and a challenge that disagrees with the table is still
-> `X402_AMOUNT_EXCEEDED`.
-
-## Library
+Exit codes: 0 verified/sent, 2 refused, 1 usage or I/O error. Keys come from the environment only (`OTTO_EXECUTE_PRIVATE_KEY`); a key-looking value in argv aborts; `sign` and `submit` take the account from the key, so `--account` is for `verify` only. `submit` sends up to three transactions and needs a little ETH on Base for gas; `--rpc <https url>` sets your own Base RPC (default: the public Base RPC — fine for `verify`/`sign`, pass your own for `submit`). `--prepare-input p.json` (the exact `arguments` you sent) adds the `intent_digest` check.
+
+## Quick start (library)
 
 ```ts
+import { readFileSync } from 'node:fs';
 import { verifySwapEnvelope, defaultAdapterPolicy, EoaSigner } from 'otto-execute';
 
-const signer = EoaSigner.fromPrivateKey(process.env.MY_KEY as `0x${string}`, RPC_URL);
-const verified = verifySwapEnvelope(envelopeFromMcp, {
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const WETH = '0x4200000000000000000000000000000000000006';
+const envelope = JSON.parse(readFileSync('envelope.json', 'utf8')); // the otto_prepare_swap result
+
+const signer = EoaSigner.fromPrivateKey(process.env.OTTO_EXECUTE_PRIVATE_KEY as `0x${string}`, 'https://your-base-rpc');
+const verified = verifySwapEnvelope(envelope, {
   profile: { kind: 'eoa', address: signer.address, chainId: 8453 },
-  intent: { fromToken: USDC, toToken: WETH, fromAmount: 2_000_000n, minAmountOut: myOwnFloor },
+  intent: { fromToken: USDC, toToken: WETH, fromAmount: 1_000_000n, minAmountOut: 200_000_000_000_000n },
   capabilities: signer.capabilities,
   policy: defaultAdapterPolicy(8453),
-  prepareInput: theExactInputISentToOttoPrepareSwap, // optional: binds intent_digest to your request
+  // prepareInput: theArgumentsYouSent,  // optional: also binds intent_digest to your exact request
 });
 await signer.signPlanDryRun(verified); // proves what would be signed; broadcasts nothing
-await signer.sendPlan(verified); // Base mainnet, real funds
+await signer.sendPlan(verified);       // Base mainnet
 ```
 
-`minAmountOut` is **yours**: derive it from a price source you trust. It is also the on-chain fence
-for the swap's internal DEX legs (LI.FI's router reverts unless you receive at least it), so it must
-be positive.
+`minAmountOut` is yours to derive and must be positive: it is also the on-chain floor for the swap's DEX legs (LI.FI's router reverts unless you receive at least it).
 
-## CLI
+## What you get
 
-```bash
-otto-execute verify --envelope e.json --intent intent.json --account 0x…           # no key needed
-OTTO_EXECUTE_PRIVATE_KEY=0x… otto-execute sign   --envelope e.json --intent intent.json   # dry: sign + decode back
-OTTO_EXECUTE_PRIVATE_KEY=0x… otto-execute submit --envelope e.json --intent intent.json --i-understand-mainnet
-otto-execute x402 --challenge c.json            # validate a 402 against the table
-OTTO_EXECUTE_PRIVATE_KEY=0x… otto-execute x402 --challenge c.json --sign   # emit x_payment
-```
+| Command / API | Does |
+| --- | --- |
+| `verify` · `verifySwapEnvelope()` | Re-checks the envelope's own assertions (schema, payload digest, commitment, freshness, account binding), then **your intent** (input token + exact amount, every deposit leg pulling exactly that, the output token, your minimum output), then policy (reviewed router, receiver = you, every distribution leg decoded independently and matched to the reviewed, versioned set through a reviewed FeeForwarder deployment, aggregate under the cap). Twelve named checks; a verified plan is frozen and registered by identity. |
+| `sign` · `signPlanDryRun()` | Signs every step with your key, decodes each back and recovers the signer — nothing is broadcast. |
+| `submit` · `sendPlan()` | Sends the steps in order (allowance reset → approval → swap), each waited to a sealed Base block; on any uncertain failure it halts and clears the live allowance, confirmed by an allowance read-back. Freshness and binding are re-checked immediately before every signature. |
+| `x402 --challenge c.json [--sign]` · `validateX402Challenge()` + `signX402Payment()` | For the hosted MCP's **paid intelligence tools** (the constructors are free): when a tool answers `payment_required`, save that object as `c.json`; this validates it against an exact-match table of Otto's routes (resource, recipient, amount, 300 s window, EIP-712 domain) and, with `--sign`, prints the `x_payment` string — retry the same tool with it in the `x_payment` argument. A per-payment cap of `$1` is enforced regardless of the table. |
+| `delegate --email you@example.com [--expires-days 90]` · `otto-execute/delegate` | Mints a time-boxed CDP delegation (default 90 days, max 180) to Otto's public project so Otto's server can submit your own swaps under it; `delegation status\|revoke` read it back / revoke it. Reads the public `otto_delegation_fence_status` first and refuses when the fence is absent. Runs end-user-side: sign-in by email OTP typed on the terminal; no Otto credential in the process. Not a Coinbase-supported path — it drives the pinned `@coinbase/cdp-core` 0.0.120 web build on Node and can break on an SDK update (a canary test names the break). |
+| `otto-execute/cdp` · `CdpDelegatedSigner` | Library only: the same verify → submit over a delegation you minted with `delegate` (needs the optional `@coinbase/cdp-sdk` peer; the CLI's `submit` is the EOA path). |
+
+Every refusal is a named code (`AdapterRefusal` / `X402Refusal` / `DelegateRefusal`), never upstream error text.
+
+## File shapes
+
+- `envelope.json` — the `otto_prepare_swap` result, verbatim.
+- `intent.json` — `{ fromToken, toToken, fromAmount, minAmountOut }`, addresses `0x` + 40 hex, amounts as strings in atomic units.
+- `--prepare-input p.json` — the exact `arguments` object you sent to `otto_prepare_swap` (optional; adds the `intent_digest` check).
+- `x402 --challenge c.json` — the `payment_required` object a hosted tool returned.
+
+## Design notes (for reviewers)
 
-Keys come from the environment only; a key value found in argv aborts. Refusals exit 2 with
-`{ "refused": { "code", "message" } }`.
+- **Vendored seam.** The parts of `otto-intel-mcp` this package runs (`/execution`, `/adapter`, `/adapter-cdp`) are copied file-for-file from the published `otto-intel-mcp` release into `dist/vendor/` at build time; `dist/vendor/otto-intel-mcp/VENDORED.json` records the version, the registry integrity hash and a sha256 per file, re-derived by `npm run vendor:check` in `prepack`. A seam change is a visible version bump + re-vendor, never silent drift.
+- **Sealed-state rule (Base Flashblocks).** A receipt can arrive from a preconfirmation while `latest` still predates it, and a preconfirmation can be reorged. Both signers count a transaction as mined only once the sealed canonical block at that height carries the receipt's block hash — before the next estimate and before the allowance read-back. Observed live 2026-08-28.
+- **`spendControls` kept on.** `@x402/core` ≥ 2.23 caps a payment at `$1` by default; this package states that cap explicitly (`PER_PAYMENT_SPEND_CAP`) and translates the SDK's rejection to `X402_SPEND_LIMIT_EXCEEDED`. The `table` parameter of `validateX402Challenge` is public and defaults to `X402_TABLE`; whatever table a caller passes, the cap bounds what can be signed.
+- **Optional peers.** `@coinbase/cdp-sdk` (the `/cdp` entry) and `@coinbase/cdp-core` (the `/delegate` entry) are optional; the root entry and the CLI's verify/sign/submit/x402 never load them, and a consumer without them typechecks (`test/root-without-cdp.test.ts`, and the isolated-install smoke compiles a consumer with `skipLibCheck: false`).
+- **Hermetic tests.** `npm test` runs on captured genuine envelopes (`test/fixtures/envelopes/`, built by the constructor's own code over its real LI.FI captures) and resolves `otto-intel-mcp/*` from `node_modules`; `scripts/capture-envelopes.ts` (monorepo-only) re-captures and `npm run fixtures:check` fails when they are stale. The 24-row mutation matrix (`MUTATION_CASES`) is the one the Model-B proof kit shipped with, which consumes this package.
+- Not in this package by design: a DEX allowlist (the on-chain minimum-output bind is the fence); bridge / Polymarket / Hyperliquid adapters (their constructors are live on the MCP; adapters follow).
 
-## What is proven, and where
+Working in the monorepo: `npm ci && npm run verify` (typecheck → build incl. vendoring → tests), `npm run smoke:install` (pack + clean install outside the repo + real verify + TypeScript consumer compile + package count), `npm run pack:audit` (the privacy gate, also in `prepack`).
 
-The consistency matrix (`MUTATION_CASES`, 24 rows) and the tests are the ones the Model-B proof kit
-(`scripts/probes/model-b-proof/`, PR #1918, codex gate GO r5/5) shipped with; the kit now consumes this
-package. Live sittings run from the kit's runbook (`docs/0826_model_b_proof_runbook.md`).
+## Links
 
-Not in this package by design: an allowlist of DEX contracts (the on-chain minimum-output bind is the
-fence), user-side revocation claims (exists per CDP's API; unobserved), bridge / Polymarket / Hyperliquid
-adapters (their constructors are merged; consumers follow).
+- Execution seam docs (the envelope field by field, the checks, delegation): https://docs.useotto.xyz/acp-swarm/execution-seam
+- Otto Intel MCP (the constructors + intelligence tools): https://www.npmjs.com/package/otto-intel-mcp · https://docs.useotto.xyz/acp-swarm/otto-intel-mcp
+- Otto AI: https://useotto.xyz · X: [@useOttoAI](https://x.com/useOttoAI)
+- Changelog: 0.1.2 — `verify` prints `seconds_remaining` (the submit budget) and `secondsRemaining()` is exported; envelope window documented as 5 minutes; 0.1.1 — README rewritten for first-time users and agents (quick start, captured real output, file shapes); 0.1.0 — first release.

package/dist/cli.js

@@ -18,6 +18,7 @@ import { readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { getAddress } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
+import { secondsRemaining } from './window.js';
 import { DEFAULT_OTTO_MCP_URL, DelegateRefusal, UNSUPPORTED_PATH_NOTE, assertFencePresent, initEndUserSdk, isDelegateRefusal, mintDelegation, readDelegationAsUser, readPublicFenceStatus, redactSecrets, resolveDelegateEndpoints, revokeDelegationAsUser, signInWithEmailOtp, } from './delegate.js';
 import { EoaSigner } from './eoa-signer.js';
 import { isAdapterRefusal } from './refusal.js';
@@ -381,6 +382,8 @@ async function main() {
         min_amount_out: verified.minAmountOut,
         fee_distributions: verified.fees.distributions,
         valid_until: verified.artifact.valid_until,
+        // The budget left to submit the WHOLE plan (freshness is re-checked before every signature).
+        seconds_remaining: secondsRemaining(verified.artifact.valid_until),
         artifact_id: verified.artifact.artifact_id,
     };
     if (command === 'verify') {

package/dist/index.d.ts

@@ -14,3 +14,4 @@ export { waitForSealedReceipt, type SealedClient, type SealedWaitOptions } from
 export { EOA_CAPABILITIES, EoaSigner, PlanHaltedError, type DryRunSignedStep, type SentStep, type SignedX402Payment, } from './eoa-signer.js';
 export { BASE_USDC, OTTO_X402_PAY_TO, X402_REFUSAL_CODES, X402_TABLE, X402_TABLE_VERSION, X402Refusal, canonicalResourceUrl, requirementMatchesRow, validateX402Challenge, type PaymentRequirementLike, type ValidatedX402Challenge, type X402ExpectedRow, type X402RefusalCode, type X402Table, } from './x402-table.js';
 export { FOREIGN_ADDRESS, FOREIGN_TOKEN, MUTATION_CASES, applyMutation, recommit, recommitCommitmentOnly, recommitPayloadOnly, type CatchingLayer, type MutationCase, type MutationContext, } from './mutations.js';
+export { secondsRemaining } from './window.js';

package/dist/index.js

@@ -16,4 +16,5 @@ export { EOA_CAPABILITIES, EoaSigner, PlanHaltedError, } from './eoa-signer.js';
 // optional `@coinbase/cdp-sdk` peer (loaded lazily); this root never references the SDK at all.
 export { BASE_USDC, OTTO_X402_PAY_TO, X402_REFUSAL_CODES, X402_TABLE, X402_TABLE_VERSION, X402Refusal, canonicalResourceUrl, requirementMatchesRow, validateX402Challenge, } from './x402-table.js';
 export { FOREIGN_ADDRESS, FOREIGN_TOKEN, MUTATION_CASES, applyMutation, recommit, recommitCommitmentOnly, recommitPayloadOnly, } from './mutations.js';
+export { secondsRemaining } from './window.js';
 //# sourceMappingURL=index.js.map

package/dist/window.d.ts

@@ -0,0 +1,10 @@
+/**
+ * window.ts — the freshness budget a caller has left on an envelope. The constructor stamps
+ * `valid_until` (5 minutes from construction on the hosted server by default; the tool description
+ * states the exact window) and the verifier and both signers refuse a stale envelope before every
+ * signature — so the WHOLE plan (allowance reset → approval → swap, each waited to a sealed block)
+ * must clear before `valid_until`. `verify` prints this so a user sees the budget instead of
+ * discovering it as STALE_ARTIFACT mid-plan.
+ */
+/** Whole seconds until `validUntil` (an ISO-8601 instant), never negative; `NaN` in → 0. */
+export declare function secondsRemaining(validUntil: string, nowMs?: number): number;

package/dist/window.js

@@ -0,0 +1,16 @@
+/**
+ * window.ts — the freshness budget a caller has left on an envelope. The constructor stamps
+ * `valid_until` (5 minutes from construction on the hosted server by default; the tool description
+ * states the exact window) and the verifier and both signers refuse a stale envelope before every
+ * signature — so the WHOLE plan (allowance reset → approval → swap, each waited to a sealed block)
+ * must clear before `valid_until`. `verify` prints this so a user sees the budget instead of
+ * discovering it as STALE_ARTIFACT mid-plan.
+ */
+/** Whole seconds until `validUntil` (an ISO-8601 instant), never negative; `NaN` in → 0. */
+export function secondsRemaining(validUntil, nowMs = Date.now()) {
+    const until = Date.parse(validUntil);
+    if (!Number.isFinite(until))
+        return 0;
+    return Math.max(0, Math.floor((until - nowMs) / 1000));
+}
+//# sourceMappingURL=window.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "otto-execute",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The user's side of Otto Model B: verify a prepare-only execution artifact from the Otto Intel MCP against your own intent and the ruled attribution, then sign and submit it with your own key (or under a delegation you minted). Otto never holds your keys or funds.",
   "license": "MIT",
   "homepage": "https://docs.useotto.xyz",