@thirdfy/agent-cli 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,24 +4,19 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-05-26
+
 ### Added
 
-- `src/runtime/` — organized CLI runtime layer: `main.mjs` (orchestration), `errors.mjs`, `onboardingHints.mjs`, `execution/*`, `actions/selection.mjs`, plus command factories under `src/commands/` (`discovery`, `telemetry`, `credentials`, `agent`, `doctor`, `prompt`). `bin/thirdfy-agent.mjs` remains a thin entrypoint.
-- Maintainer-only operator docs (provider platform audit, Hermes post-publish smoke) moved out of npm-facing `docs/` paths.
-- `npm run validate:provider-parity` — CI guard for earn/capyfi/fx/bridge/trading/hyperliquid/polymarket/bitfinex hints (reads `src/runtime/providerHints.mjs`).
-- `npm run validate:cli-manifest-handlers` and `npm run validate:runtime-boundaries` — manifest handler coverage and import-boundary checks.
-- `npm run validate:release-preflight` — full publish gate (lint, validators, tests, npm pack, smoke); `prepublishOnly` runs it.
-- `npm run validate:live-api-capabilities` — optional post-deploy check when `THIRDFY_API_BASE` is set (`profileDefaults`, DogeOS chain routing).
-- Provider parity script also asserts DogeOS provider ids (`dogeos-barkswap`, `dogeos-laika`, `dogeos-ecosystem`) in CLI selection + MCP.
+- Hyperliquid and Polymarket `recoveryActions` and `decommissionExample` in `providerHints` for fund recovery before runtime delete (pairs with Thirdfy API v3.4.42+).
 
-### Changed
+## [0.2.2] - 2026-05-23
 
-- Thirdfy API `GET /api/v1/agent/cli/capabilities` `profileDefaults.personal` aligned to `agent_wallet` (matches CLI `PROFILE_DEFAULTS`).
-
-### Fixed
+### Changed
 
-- `-V` / `--version` no longer print the full Commander help tree before the version string (early argv handling before `parseAsync`).
-- Commander regression tests for clean `-V` / `--version` output.
+- **npm README** — replaced the multi-version release wall with `## What's new in vX.Y.Z` (current semver only) and a CHANGELOG link; removed maintainer publish instructions from the npm homepage.
+- **`validate:public-docs`** — enforces README/npm surface rules (current version heading, CHANGELOG link, no maintainer publish strings, max inline version highlights).
+- **Cursor rules** — `npm-readme-surface.mdc` plus updates to public-docs and release flow rules; maintainer publish detail stays in `docs/releasing.md` / `docs-dev/publishing.md`.
 
 ## [0.2.1] - 2026-05-23
 
@@ -30,11 +25,19 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 - **Commander.js is now the active router**: `program.parseAsync()` registers all commands via `src/cli/manifest.mjs`, shared option bundles under `src/cli/options/`, and JSON-aware `exitOverride` handling. Handlers and envelopes remain 1:1 with 0.2.0.
 - Removed `dispatch.mjs` and the hybrid `parseArgs()` + `mergeCommanderGlobals()` entry path.
 - Unknown CLI flags now error via Commander (previously ignored by the hand-rolled parser).
+- Thirdfy API `GET /api/v1/agent/cli/capabilities` `profileDefaults.personal` aligned to `agent_wallet` (matches CLI `PROFILE_DEFAULTS`).
 
 ### Added
 
+- `src/runtime/` — organized CLI runtime layer: `main.mjs` (orchestration), `errors.mjs`, `onboardingHints.mjs`, `execution/*`, `actions/selection.mjs`, plus command factories under `src/commands/` (`discovery`, `telemetry`, `credentials`, `agent`, `doctor`, `prompt`). `bin/thirdfy-agent.mjs` remains a thin entrypoint.
+- `npm run validate:provider-parity`, `validate:cli-manifest-handlers`, `validate:runtime-boundaries`, `validate:release-preflight` (also `prepublishOnly`), and optional `validate:live-api-capabilities` when `THIRDFY_API_BASE` is set.
+- Provider parity also asserts DogeOS provider ids (`dogeos-barkswap`, `dogeos-laika`, `dogeos-ecosystem`) in CLI selection + MCP.
 - `test/commander-routing.test.cjs` — `-V`, `--version --json`, unknown command/option envelopes, `help onboarding`.
 
+### Fixed
+
+- `-V` / `--version` no longer print the full Commander help tree before the version string (early argv handling before `parseAsync`).
+
 ### Agent / operator notes
 
 - **No argv path or JSON envelope changes** for documented commands; Hermes/OpenClaw/cron scripts need no changes.

package/README.md

@@ -40,11 +40,14 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## Release notes
+## What's new in v0.2.3
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.2.1** ships full [Commander.js](https://github.com/tj/commander.js) routing (`parseAsync`, manifest-registered subcommands, JSON-aware errors) with **1:1 argv/envelope behavior** vs 0.1.x — Hermes/OpenClaw/cron scripts need no changes; optional Fly pin `@thirdfy/agent-cli@0.2.1` after publish. Unknown flags now error instead of being silently ignored. **v0.1.48** fixes earn provider filtering so generic `deposit_earn_position` / `withdraw_earn_position` rows only appear for matching adapters (not unrelated morpho/vaults-fyi filters). **v0.1.47** adds CapyFi, FX, and bridge provider discovery hints. **v0.1.46** routes `polymarket status` through `get_polymarket_funding_status` with config `agentKey` and defaults dry-run to `place-polymarket-order` (pairs with API **v3.4.37**). **v0.1.45** adds `polymarket status`, `polymarket setup`, and `polymarket dry-run` for agent-scoped setup/geoblock preflight (pairs with API **v3.4.35**). **v0.1.44** adds Aegis provider hints for Base and Unichain earn reads and fail-closed Engine writes (pairs with API **v3.4.28**). **v0.1.43** injects Hyperliquid `userAddress` from the managed execution wallet for solo `agent_wallet` reads when omitted (pairs with API **v3.4.27**). **v0.1.42** persists API `executionWallets` from email login, updates `doctor auth` / onboarding help for agent execution wallet funding vs owner embedded auth wallet, and documents Bridge2 `FUND_AGENT_EXECUTION_WALLET` remediation (pairs with API **v3.4.25**). **v0.1.41** documents Hyperliquid `get_hyperliquid_funding_status` as setup step 0, Bridge2 sender custody, and `deposit_hyperliquid_bridge --estimated-amount-usd` (pairs with API **v3.4.24**). **v0.1.40** fixes email/bootstrap credential persistence when the API returns nested registration payloads, so owner-session onboarding can save the hidden execution identity without exposing a raw agent API key. **v0.1.39** makes `agent_wallet` the fresh solo default, adds framework guidance for Hermes/OpenClaw/Claude Managed Agents, clarifies Gator/ERC-7710 delegation flows, and keeps BYOW/self plus hybrid/thirdfy mode switching explicit. **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
+- **Hyperliquid** and **Polymarket** provider discovery now include `recoveryActions` and `decommissionExample` for fund recovery before runtime delete.
+- Hyperliquid recovery path: `get_hyperliquid_user_state` → `withdraw_hyperliquid_to_arbitrum` → withdraw execution wallet to owner.
+- Polymarket recovery path: `get_polymarket_recovery_status` → `withdraw_polymarket_collateral` → withdraw execution wallet to owner.
+- Pairs with Thirdfy API **v3.4.42+** managed recovery actions and EarnClaw runtime decommission flows.
 
-**Maintainers — npm:** follow [docs/releasing.md](./docs/releasing.md). From a clone with gitignored `.env`, use `npm run publish:npm:local -- --dry-run` then `npm run publish:npm:local`. Or run `npm run release:npm` after exporting tokens in the shell. Never commit npm tokens — use [.env.example](./.env.example) as a template only.
+Older versions: [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 
 ## Quick start
 
@@ -434,29 +437,15 @@ Managed-self execution performs strict wallet preflight and returns deterministi
 - Creator platform (agent registration and keys):
   [thirdfy.com/creator](https://thirdfy.com/creator)
 
-## Development
+## Contributing
+
+From a git clone of this repository:
 
 ```bash
-npm run validate:cli-contract-schemas
+npm ci
+npm run validate:public-docs
 npm test
 npm run smoke:cli
-npm run e2e:self:managed-custody-validation
-npm run e2e:managed:delegation:parity
 ```
 
-## Release
-
-Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [v0.1.39](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.39) — agent-wallet solo default, framework guidance, and delegation UX; [v0.1.38](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.38) — npm README + lockfile metadata alignment; [v0.1.37](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.37) — email OTP login, onboarding help, auth doctor, wallet list, masked `whoami`). **Before every version bump or npm publish:** update this **README** (release notes paragraph, quick start, and command groups) so the npm package page matches what ships; keep `CHANGELOG.md`, [command reference](./docs/command-reference.md), and MCP summaries aligned when discovery or onboarding surfaces change.
-
-```bash
-npm version patch
-npm publish --access public
-git push origin main --follow-tags
-```
-
-Release contract:
-
-- Keep `package.json` version and `CHANGELOG.md` synchronized in the release PR.
-- The git tag must be `vX.Y.Z` and match `package.json` exactly.
-- Push the matching tag so the [Release workflow](.github/workflows/release.yml) creates or aligns the GitHub release entry.
-- If npm already contains that version, the workflow skips republishing and still creates/aligns the GitHub release when triggered by the tag.
+Version history lives in [CHANGELOG.md](./CHANGELOG.md). Maintainer publish steps: [docs/releasing.md](./docs/releasing.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/src/runtime/providerHints.mjs

@@ -61,6 +61,12 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
           'get_hyperliquid_builder_fee_status',
           'get_hyperliquid_referral_status',
         ],
+        recoveryActions: [
+          'get_hyperliquid_user_state',
+          'withdraw_hyperliquid_to_arbitrum',
+        ],
+        decommissionExample:
+          'get_hyperliquid_user_state -> withdraw_hyperliquid_to_arbitrum -> withdraw-to-user on execution wallet',
         credentialType: 'hyperliquid_api_wallet',
         credentialUx:
           'Thirdfy manages Hyperliquid API-wallet setup for normal users. Delegated writes require encrypted privateKey-backed hyperliquid_api_wallet credentials; walletAddress-only records are rejected until Privy walletId-backed Hyperliquid signing ships.',
@@ -168,7 +174,17 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
           'browser_setup:create_or_derive_clob_credentials',
           'browser_setup:deploy_deposit_wallet_and_set_approvals',
         ],
-        statusActions: ['get_polymarket_setup_status'],
+        statusActions: [
+          'get_polymarket_funding_status',
+          'get_polymarket_setup_status',
+          'get_polymarket_recovery_status',
+        ],
+        recoveryActions: [
+          'get_polymarket_recovery_status',
+          'withdraw_polymarket_collateral',
+        ],
+        decommissionExample:
+          'get_polymarket_recovery_status -> withdraw_polymarket_collateral -> withdraw-to-user',
         credentialType: 'polymarket_clob',
         credentialUx:
           'Autonomous agents use an agent-owned Privy wallet and Polymarket deposit wallet first: Thirdfy creates the agent wallet, deploys/approves the deposit wallet, and stores encrypted CLOB credentials once Polymarket key creation is available. User-owned browser setup remains optional for interactive capital.',