@bloxwap/agent-cli 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# @bloxwap/agent-cli
+
+## 0.4.0
+
+### Minor Changes
+
+- Enforce trading, funding, and durability invariants: fail closed on retried orders, effective
+  leverage, serialized risk checks, mode and network pins, rotation merges, fresh approvals, quote
+  decimals, deposit terminals, locked deposits, agent error codes, exactly-once fills, journal
+  repair, stale locks, runner liveness, and exact fill linkage.
+
+### Patch Changes
+
+- Publish file locks atomically so concurrent nonce updates stay unique. Missing locks are retried
+  instead of stolen, and the lock file is linked into place only after its record is complete.
+
+## 0.3.0
+
+### Minor Changes
+
+- Support user-owned EOA trading agents (`signerType: eoa` with a local `eoaKeyRef`)
+  alongside user-owned Privy apps. The default Bloxwap builder fee is now zero, with
+  optional non-zero overrides, and the default BLOXWAP referral is applied after
+  agent approval when the account has none. Testnet approval errors now keep the
+  action and upstream rejection, and preflight requires a positive test USDC balance.
+
+## 0.2.0
+
+### Minor Changes
+
+- a04a6c7: Add managed Hyperliquid agents, Relay funding, JSON commands, a persistent runner,
+  risk checks, durable events/audit journals, and the packaged trading skill.
+
+### Patch Changes
+
+- db928e2: Ship license, changelog and repository metadata with the CLI. Verify script-free
+  global npm installs and installed bunx execution on macOS/Linux and Node 22.12/24.
+
+## 0.1.0
+
+Initial implementation of managed-agent trading, funding and persistent runner.
+Use Changesets for subsequent versioning and release notes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Bloxwap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# agent-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An agent-native Hyperliquid trading CLI with JSON input/output, a persistent
+signing runner, user-owned Privy or EOA agents, Relay funding, a packaged agent skill,
+and a paper trading mode against real mainnet market data.
+
+After the first public release, install with `npm i -g @bloxwap/agent-cli` or run
+`bunx @bloxwap/agent-cli --help`. Use Node **22.12+** or Bun;
+`bunx --bun @bloxwap/agent-cli --help` explicitly selects Bun.
+The package has no install lifecycle scripts and supports `--ignore-scripts`.
+Until publication, build a local tarball with `npm run build && npm run pack:cli`
+from the repository root and install that tarball with `npm i -g PATH_TO_TARBALL`.
+
+## Paper trading
+
+Simulate strategies against real mainnet Hyperliquid market data with no
+signing and no funds: `paper reset --yes`, then trade with the global `--paper`
+flag (or `config set mode paper` / `run --paper`). The simulator walks the live
+book, charges Hyperliquid taker/maker plus the optional builder fee (zero by
+default), accrues funding, approximates margin/liquidation, and keeps restartable state under
+`~/.bloxwap/paper/`. `paper summary` reports PnL, fees, funding and trades.
+Envelopes and events carry `mode`/`paper` labels; `config set mode live --yes`
+is the explicit way back to live. See `docs/paper.md`.
+
+## Testnet quickstart
+
+Use your own Privy app or a dedicated EOA agent. No wallet or credentials are
+bundled. Set secrets locally outside the CLI/conversation, then configure only
+their references:
+
+```sh
+npm ci
+npm run build
+# Privy:
+node packages/agent-cli/dist/cli.js config set signerType privy
+node packages/agent-cli/dist/cli.js config set privyAppId YOUR_APP_ID
+node packages/agent-cli/dist/cli.js config set privyAppSecretRef env:BLOXWAP_PRIVY_APP_SECRET
+# Or a user-provided EOA agent (BLOXWAP_EOA_KEY is set locally):
+node packages/agent-cli/dist/cli.js config set signerType eoa
+node packages/agent-cli/dist/cli.js config set eoaKeyRef env:BLOXWAP_EOA_KEY
+
+node packages/agent-cli/dist/cli.js init --network testnet --master-address 0xYOUR_MASTER_ADDRESS
+# Sign the returned agent approval externally and resume init.
+# Init applies the BLOXWAP referral if the account has none.
+node packages/agent-cli/dist/cli.js status --network testnet
+node packages/agent-cli/dist/cli.js run --network testnet --detach
+```
+
+Testnet onboarding requires your selected signer, external master approvals and
+testnet collateral. The EOA must be separate from the master wallet. Never put a
+private key, seed, or app secret in CLI input. Replace all placeholders with your
+own values. Read [custody limits](../../docs/custody.md) before funding.
+
+## Architecture and custody
+
+```mermaid
+flowchart LR
+  Agent[Agent / CLI] -->|private JSON-RPC| Runner[Persistent runner]
+  Runner --> Signer[User-owned Privy or EOA agent]
+  Signer -->|EIP-712 signature| HL[Hyperliquid exchange]
+  Agent --> Relay[Relay funding quote]
+  Master[External master wallet] -->|one-time approvals| HL
+  Runner --> Journal[Events / audit / logs]
+```
+
+Master custody stays external. The user owns the Privy app or local EOA agent key.
+Hyperliquid agent permissions deny withdrawal. Local typed-data and risk checks
+apply to both signer types; Privy policies add remote restrictions for Privy agents.
+
+State: `~/.bloxwap`; config: `~/.bloxwap/config.json`; IPC:
+`~/.bloxwap/run.sock`; env prefix: `BLOXWAP_`. All local state is private to the OS
+user. The default Bloxwap builder address is
+`0x71b09A08257078A4d642F7Dd7315e656c837329a`, with `f=0` (no added fee).
+The default `BLOXWAP` referral is applied during approved onboarding when the
+account has no referral. Optional non-zero builder fees remain configurable and
+require master approval.
+
+## Development and docs
+
+Use Node.js 24+ and run build, lint, typecheck and tests from the workspace root.
+See the [repository README](../../README.md) and [docs app](../../apps/docs/README.md).
+The packaged [SKILL.md](SKILL.md) documents the authorized agent workflow.

package/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: agent-cli
+description: Operate the agent-cli Hyperliquid trading CLI, including managed-agent onboarding, paper trading against real market data, funding, orders, event monitoring, rotation, and normalized error recovery.
+metadata:
+  version: "0.4.0"
+---
+
+Use `agent-cli` for the user's authorized Hyperliquid account operations. Obtain
+command schemas with `agent-cli schema COMMAND`; arguments can be flags or
+`--json '{...}'`, or a JSON object on stdin. Ordinary commands print exactly one
+JSON object: `{ok:true,data,mode,paper}` or
+`{ok:false,code,message,retryable,details,mode,paper}`; `mode` is `"live"` or
+`"paper"` and `paper` is `true` in paper mode.
+Logs/QR appear on stderr. `events --follow` and `logs` explicitly stream JSON lines.
+Use `--network testnet` during testing; never silently change to mainnet.
+
+## Paper first, then fund and go live
+
+Start every strategy in paper mode: `agent-cli --paper ...`, `config set mode
+paper`, or `run --paper`. Paper mode runs against real mainnet Hyperliquid
+public market data (info + WS l2Book/trades/bbo, meta, funding) and never signs
+or submits anything — no Privy session, `approveAgent`, or deposit is needed.
+`order`/`cancel`/`modify`/`leverage` keep the same validation, risk limits,
+builder fee and audit trail; a local simulator fills them (book-walking market
+orders, resting limits, reduce-only, TP/SL, fees, funding, margin/liquidation
+approximation). State is restartable under `~/.bloxwap/paper/`; `paper summary`
+reports PnL/fees/funding, `paper reset --yes` clears it. Envelopes and events
+carry `mode`/`paper`, paper state never mixes with live state, and going live
+requires `config set mode live --yes`. Only after the paper results are proven,
+continue with live onboarding below and real funding.
+
+## Onboarding sequence
+
+1. The user owns all settings and chooses their own Privy app or dedicated EOA
+   agent; no wallet or credentials are bundled. For Privy, set `signerType` to
+   `privy` and configure the app ID and `privyAppSecretRef`. For EOA, set
+   `signerType` to `eoa` and configure `eoaKeyRef`, e.g. `env:BLOXWAP_EOA_KEY`
+   or a mode-0600 `file:` path.
+   The user creates the key and sets the secret outside the conversation on their
+   own machine or runner. Never accept raw keys in CLI input or use the master EOA
+   as the agent. Master-wallet approval always remains in the user's external wallet.
+   The default Bloxwap builder is `0x71b09A08257078A4d642F7Dd7315e656c837329a`,
+   with `f=0` (no builder fee). The default referral code is `BLOXWAP`; override
+   with `config set referralCode` or `BLOXWAP_REFERRAL_CODE`. Optional non-zero
+   builder fees use `config set builder.address` / `config set builder.fee` or
+   `BLOXWAP_BUILDER_ADDRESS` / `BLOXWAP_BUILDER_FEE`.
+2. Run `init --master-address 0x... --network testnet`. Show the returned approval
+   payload/deeplink/QR. The user signs in their master wallet; submit only the
+   resulting signature with `init --signature 0x...`. After agent approval, init
+   applies the configured referral if the account has none and leaves existing
+   referrals unchanged. Builder approval is needed only for a non-zero configured
+   fee. Continue only after `approved:true`.
+3. Run `fund --amount 10 --origin-chain 42161`. Show `qrAscii`/deposit address,
+   origin chain/token, minimum, fees, expected received amount and expiry. On
+   testnet, do not treat the default Arbitrum mainnet chain/token as a test route:
+   use an explicitly supported test chain/token and `originDecimals`, or the
+   credential-gated CI harness with mocked Relay and mocked Hyperliquid orders.
+   If no test route is known, stop funding and report the missing route. The user
+   transfers the quoted origin token. If `signatureSteps` require signatures,
+   show the exact payload and submit each via `deposit` in returned order.
+4. Poll `status` until each active deposit is `settled`, for at most 12 polls
+   or 5 minutes, whichever comes first. Start with 1-second delays, double to a
+   15-second cap, and stop with an explicit pending report if the budget expires.
+   Settlement requires Relay success and a positive Hyperliquid ledger deposit
+   (`userNonFundingLedgerUpdates`), not an unchanged equity balance. Stop on
+   failed, refunded, expired, or abandoned deposits and explain their status.
+   Quotes that never receive funds become `expired` 15 minutes after `expiresAt`.
+   `deposit --abandon` marks an unfinished deposit `abandoned`. Do not place
+   risk-increasing orders while a deposit is awaiting funds or pending. `cancel`
+   and reduce-only orders still run.
+5. Run `run --detach`, then monitor `events --follow --since SEQ`. Persist the
+   last handled sequence; replay after reconnect. An unfilled or rejected order
+   remains incomplete: do not claim the requested trade succeeded. A fill updates the trading
+   plan, an error follows the catalog below, and expiry warnings prompt rotation
+   using external master-wallet approval.
+
+## Completion and approval boundaries
+
+Read this skill and query schemas before acting. Keep a progress record with the
+network, current stage, deposit IDs, last event sequence and order cloid/oid;
+record public IDs only. Missing selected-signer settings, a wallet signature,
+funding route or settled balance is a blocked stage. Report the exact next action
+without requesting any secret in chat or moving to the next stage. Repeat `init`
+to resume persisted approvals rather than creating another agent. Approval and
+revoke payloads include `expiresAt` and are regenerated after 24 hours, or when
+Hyperliquid rejects the nonce; sign the regenerated payload. An `ok:true`
+transport envelope does not imply exchange acceptance. Every live or paper
+`order` carries a `cloid` (generated when omitted) on the success and on the
+error. A mutation timeout or disconnect is `NETWORK_ERROR` with `retryable:
+false` and `details.outcome: "unknown"`. Retry that same `intentId` or `cloid`;
+the CLI reuses the cloid and will not place a second order. Do not mint a new
+cloid for the same intent.
+
+For EOA rotation, the user sets a new local key and supplies only its reference
+with `rotate --eoa-key-ref env:NEW_EOA_KEY`. For either signer, verify
+`swapped:true` before asking the external wallet to sign old agent revocation. Require `oldRevoked:true` before claiming rotation complete.
+`revoke` immediately disables local signing; only `exchangeRevoked:true` confirms
+that the signed exchange revocation was submitted. Inspect `status` to verify the
+agent is absent from exchange approvals. Cancel outstanding orders before final
+revocation, and report any cancellation or cleanup failure explicitly.
+
+## Commands and example envelopes
+
+Examples show representative `data`, not live balances or service promises.
+Full inputs/outputs are discoverable with `schema`; amounts/prices are strings.
+
+| Input | Example output |
+| --- | --- |
+| `--help` | `{"ok":true,"data":{"commands":[{"name":"status","description":"Read account status"}],"globalFlags":["--json","--config","--network","--pretty"]}}` |
+| `schema order` | `{"ok":true,"data":{"input":{"type":"object"},"output":{"oneOf":[]}}}` (actual schemas include properties) |
+| `config get network` | `{"ok":true,"data":"testnet"}` |
+| `config set limits.maxLeverage 5` | `{"ok":true,"data":{"version":1,"limits":{"maxLeverage":5}}}` |
+| `config validate` | `{"ok":true,"data":{"valid":true,"version":1}}` |
+| `init --master-address 0x...` | `{"ok":true,"data":{"approved":false,"requiresSignature":true,"approvals":{"agent":{"typedData":{}}},"qrAscii":"..."}}` |
+| `fund --amount 10 --no-qr` | `{"ok":true,"data":{"depositId":"...","depositAddress":"0x...","expectedReceived":"100000000","builderFeeRate":"0%","builderAddress":"0x71b09A08257078A4d642F7Dd7315e656c837329a","state":"awaiting_funds","qrAscii":null}}` |
+| `deposit --deposit-id ID` | `{"ok":true,"data":{"depositId":"ID","steps":[{"id":"step:0","requiresSignature":true,"payload":{}}]}}` |
+| `deposit --deposit-id ID --step-id step:0 --signature 0x...` | `{"ok":true,"data":{"depositId":"ID","steps":[]}}` |
+| `status` | `{"ok":true,"data":{"balance":{"accountValue":"100"},"agent":{"approved":true,"daysRemaining":"179"},"deposits":[],"policy":{"id":"...","version":"2"},"runner":{"pid":"123"}}}` |
+| `balance` | `{"ok":true,"data":{"accountValue":"100","accountValueUnits":"10000000000","withdrawable":"96","marginUsed":"4"}}` |
+| `market --coin BTC` | `{"ok":true,"data":{"coin":"BTC","asset":"0","szDecimals":"5","maxLeverage":"40","mid":"20000"}}` |
+| `positions` | `{"ok":true,"data":[{"coin":"BTC","size":"0.001","entryPrice":"20000","leverage":"5","marginMode":"cross"}]}` |
+| `orders` | `{"ok":true,"data":[{"coin":"BTC","oid":"123","sz":"0.001","limitPx":"20000","side":"B"}]}` |
+| `order --json '{"coin":"BTC","side":"buy","size":"0.001","price":"20000","tif":"Gtc","cloid":"0x11111111111111111111111111111111"}'` | `{"ok":true,"data":{"result":{"status":"ok","response":{"data":{"statuses":[{"resting":{"oid":123}}]}}},"builderFeeRate":"0%","builderAddress":"0x71b09A08257078A4d642F7Dd7315e656c837329a","cloid":"0x..."}}` |
+| `order --json '{"coin":"BTC","side":"sell","size":"0.001","type":"market","slippage":0.01,"reduceOnly":true}'` | `{"ok":true,"data":{"result":{"status":"ok","response":{"data":{"statuses":[{"filled":{"oid":123}}]}}}}}` |
+| `cancel --oid 123` or `cancel --all` | `{"ok":true,"data":{"cancelled":["123"],"result":{"status":"ok"}}}` |
+| `modify --json '{"modifications":[{"oid":123,"price":"20100","size":"0.001"}]}'` | `{"ok":true,"data":{"status":"ok"}}` |
+| `leverage --coin BTC --leverage 5 --mode isolated` | `{"ok":true,"data":{"status":"ok"}}` |
+| `run --detach` | `{"ok":true,"data":{"pid":123,"startedAt":1700000000000,"network":"testnet"}}` |
+| `events --since 12 --types '["fill"]'` | `{"ok":true,"data":[{"seq":13,"timestamp":"2026-01-01T00:00:00.000Z","type":"fill","data":{"tid":1}}]}` |
+| `events --follow` | `{"seq":13,"timestamp":"2026-01-01T00:00:00.000Z","type":"fill","data":{"tid":1}}` (one line per event) |
+| `logs --follow --level warn` | `{"level":"warn","requestId":"...","message":"Risk rejected","time":"..."}` (JSON lines) |
+| `paper reset --yes` | `{"ok":true,"data":{"paper":true,"mode":"paper","reset":true,"startingBalance":"10000"},"mode":"paper","paper":true}` |
+| `paper summary` | `{"ok":true,"data":{"paper":true,"mode":"paper","equity":"10000","netPnl":"0","feesPaid":"0","fundingPaid":"0","trades":0,"positions":[]}}` |
+| `order --paper --json '{"coin":"BTC","side":"buy","size":"0.001","type":"market"}'` | `{"ok":true,"data":{"result":{"status":"ok","response":{"data":{"statuses":[{"filled":{"oid":1,"totalSz":"0.001","avgPx":"20000","status":"filled"}}]}}},"builderFeeRate":"0%","builderAddress":"0x71b09A08257078A4d642F7Dd7315e656c837329a","cloid":"0x22222222222222222222222222222222"},"mode":"paper","paper":true}` |
+| `run --paper --detach` | `{"ok":true,"data":{"pid":123,"startedAt":1700000000000,"network":"mainnet","paper":true}}` |
+| `rotate` then `rotate --signature 0x...` | `{"ok":true,"data":{"oldAgent":"0x...","newAgent":"0x...","swapped":true,"oldRevoked":false,"revokeApproval":{}}}` |
+| `rotate --revoke-signature 0x...` | `{"ok":true,"data":{"swapped":true,"oldRevoked":true}}` |
+| `revoke --cancel-orders` | `{"ok":true,"data":{"locallyRevoked":true,"exchangeRevoked":false,"requiresSignature":true,"approval":{}}}` |
+| `revoke --signature 0x...` | `{"ok":true,"data":{"locallyRevoked":true,"exchangeRevoked":true}}` |
+| `audit --intent ID` | `{"ok":true,"data":[{"intentId":"ID","stage":"decision","data":{"allowed":true},"previousHash":"...","hash":"..."}]}` |
+| `skill install --target codex` | `{"ok":true,"data":{"target":"codex","path":".../agent-cli/SKILL.md","version":"0.4.0"}}` |
+
+Before an order, query `market --coin BTC` for `mid`, `szDecimals`, asset and
+market leverage ceiling. Compute size/notional with decimal strings/bigints,
+using the user-approved limit or the bounded IOC execution price. A valid schema
+alone does not establish that an order is tradable or within the budget.
+
+Use `--intent-id ID --intent "reason"` on trading actions to connect the user's
+reasoning to the audit. The CLI binds that intent to one cloid. Risk checks use
+the account leverage Hyperliquid will apply and fail closed if it cannot be
+read. Live and paper mutations are serialized per account. `--live` and
+`--paper` select the mode explicitly; a running runner rejects a command whose
+mode does not match the runner or the saved config (`CONFIG_INVALID`) until the
+runner is restarted. Trading, rotate, and revoke reject a network other than
+`approvedNetwork`.
+For TP/SL use `type:"tp"|"sl"` and `triggerPrice` with size/price/reduceOnly;
+market orders use an explicit slippage-bounded IOC, not an unbounded market order.
+
+## Error recovery
+
+| Code | Action |
+| --- | --- |
+| RATE_LIMIT, NETWORK_ERROR | At most 3 read retries with exponential backoff. A mutation with `details.outcome` `"unknown"` is not retryable: retry the same `intentId` or `cloid` only, which the CLI reconciles. Stop if that result is still unknown |
+| NONCE_COLLISION | Retry using a newly issued nonce. A stale approval nonce is not retryable; sign the regenerated payload. A lock held by a live process is `INTERNAL` and is not retryable |
+| DEPOSIT_PENDING | Poll status until settled, expired, or abandoned. `cancel` and reduce-only orders still run. `deposit --abandon` stops a quote you will not fund |
+| RUNNER_NOT_RUNNING | Start runner or use configured direct fallback |
+| INSUFFICIENT_MARGIN | Reduce exposure or request authorized funding |
+| POLICY_REJECTED | Stop and revise intent within limits; do not bypass policy |
+| AGENT_EXPIRED | Rotate with master-wallet approval |
+| AGENT_NOT_APPROVED | Complete init/approval or explain revocation |
+| INVALID_SIZE, INVALID_PRICE | Correct input using market precision |
+| UNKNOWN_MARKET | Refresh metadata; use an allowed market |
+| ORDER_NOT_FOUND | Refresh orders before changing intent. An unknown or expired agent is `AGENT_NOT_APPROVED` or `AGENT_EXPIRED`, not this code |
+| CONFIG_INVALID | Correct configuration/input; never insert secrets |
+| UPSTREAM_ERROR, INTERNAL | Stop, inspect redacted details/logs and report failure |
+
+## Gotchas
+
+HyperCore perps USDC uses **8 decimals**; EVM USDC uses **6**. The quote's origin
+decimals must match `originDecimals` or `fund` returns `CONFIG_INVALID`. Preserve
+strings and bigints. Some deposits require **two distinct signatures**; resume
+stored steps rather than restarting the route. Agent expiry is at most **180 days**.
+Fills in `events.jsonl` are delivered once per exchange `tid`, including
+fills that happen while the runner is down; dedupe by `tid` as well as `seq`.
+Never
+ask for, paste, log or import a master private key or seed. EOA agent keys are
+accepted only through user-configured local references, never command input.
+The agent is trade-only; local limits include markets, size/notional, leverage,
+daily loss and open orders — in paper mode these limits are enforced exactly the
+same way. Privy sees an L1 action hash, so it cannot independently inspect
+notional/action contents; EOA agents have no remote Privy policy. Hyperliquid
+agent permissions and local checks enforce those boundaries for both signers. State is always `~/.bloxwap`, env prefix `BLOXWAP_`; paper
+state is `~/.bloxwap/paper/` and is never read by live commands (or vice
+versa). Envelopes and events always state `mode`/`paper`.
+
+
+## Verification boundaries
+
+Offline skill tests validate the documented command examples against CLI schemas.
+Mocked lifecycle tests exercise resumable approvals, pending funding, events
+and failure handling. These checks do **not** prove a live agent or
+exchange run. The nightly testnet lifecycle uses only a company-owned disposable
+CI master account and separate test Privy app, live Privy and Hyperliquid
+approvals/revocation, and explicitly mocked Relay plus mocked Hyperliquid orders
+that never reach the exchange. The dedicated master account still needs a positive
+test USDC balance because live approvals require prior test collateral.
+The same harness supports a caller-controlled external wallet approval adapter
+on a clean QA runner; its private key stays in that wallet. It never transfers
+real funds. Missing CI credentials fail the job; a skipped or
+mocked test must never be reported as live validation. Record the workflow run,
+commit, lifecycle report, event and audit artifacts before claiming a testnet pass.
+See `docs/agent-workflow.md` and `docs/testnet.md` in the repository for setup.