@thirdfy/agent-cli 0.1.44 → 0.1.45

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.45] - 2026-05-22
+
+### Added
+
+- Polymarket operator commands: `polymarket status` (wraps `get_polymarket_setup_status` with balance/geoblock flags), `polymarket setup` (onboarding plan + next-step guide), and `polymarket dry-run` (preflight for `place_polymarket_order`). Pairs with thirdfy-api-v2 **v3.4.35** EU egress readiness fields.
+
+### Changed
+
+- [`docs/command-reference.md`](./docs/command-reference.md) documents the new Polymarket commands and agent-scoped setup status params.
+- Polymarket commands default `--run-mode` via `flags.runMode` (`agent_wallet` when omitted) and use `parseBooleanFlag` for `--include-balance` / `--include-geoblock`.
+- `polymarket setup --json` emits a single JSON envelope by embedding setup guidance in the preflight payload.
+- Polymarket provider hints list `get_polymarket_onboarding_plan` in read/setup actions so `actions --provider polymarket --json` discovers the setup command's underlying action.
+
 ## [0.1.44] - 2026-05-20
 
 ### Added

package/README.md

@@ -42,7 +42,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **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`.
+Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **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`.
 
 **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.
 
@@ -294,6 +294,7 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 
 - Discovery: `catalogs list`, `actions` (optional `--provider`, `--chain-id`; see [`docs/command-reference.md`](./docs/command-reference.md) for trading vs earn vs prediction providers and case-insensitive matching)
 - Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
+- Polymarket: `polymarket status`, `polymarket setup`, `polymarket dry-run`
 - Managed signer execution: `wallet execute`, `wallet sign`, `wallet submit`, `agent run`
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `login email`, `help onboarding`, `doctor auth`, `wallet list`, `bootstrap begin`, `bootstrap complete`, `onboarding begin`, `onboarding complete`, `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`, `developer bootstrap`

package/bin/thirdfy-agent.mjs

@@ -219,6 +219,15 @@ async function main() {
     case 'wallet list':
       await commandWalletList(context, subFlags);
       return;
+    case 'polymarket status':
+      await commandPolymarketStatus(context, subFlags);
+      return;
+    case 'polymarket setup':
+      await commandPolymarketSetup(context, subFlags);
+      return;
+    case 'polymarket dry-run':
+      await commandPolymarketDryRun(context, subFlags);
+      return;
     default:
       break;
   }
@@ -594,6 +603,7 @@ function getTradingProviderHint(providerId) {
         'get_polymarket_prices',
         'get_polymarket_price_history',
         'get_polymarket_setup_status',
+        'get_polymarket_onboarding_plan',
         'get_polymarket_order',
         'get_polymarket_user_orders',
       ],
@@ -603,7 +613,7 @@ function getTradingProviderHint(providerId) {
         'get_polymarket_market or get_polymarket_markets',
         'get_polymarket_order_book',
         'get_polymarket_prices or get_polymarket_price_history',
-        'get_polymarket_setup_status before place_polymarket_order',
+        'get_polymarket_setup_status and get_polymarket_onboarding_plan before place_polymarket_order',
       ],
       orderManagementActions: [
         'place_polymarket_order',
@@ -613,6 +623,7 @@ function getTradingProviderHint(providerId) {
       ],
       setupActions: [
         'get_polymarket_setup_status',
+        'get_polymarket_onboarding_plan',
         'agent_wallet_setup:ensure_agent_wallet_deposit_wallet',
         'agent_wallet_setup:deploy_deposit_wallet_and_set_approvals',
         'agent_wallet_setup:create_or_derive_clob_credentials',
@@ -1267,12 +1278,25 @@ async function commandPreflight(ctx, flags, capabilities) {
     runMode,
     resolvedAction: resolved.resolvedAction,
   });
+  const data = flags.__polymarketSetupGuide
+    ? {
+        ...normalized,
+        setupGuide: {
+          message:
+            'Review onboarding plan output above. Run agent-wallet setup via API when liveOrderReady is false. Fund pUSD on deposit wallet before live orders.',
+          nextCommands: [
+            'thirdfy-agent polymarket status --agent-key <key> --json',
+            'thirdfy-agent preflight --action get_polymarket_setup_status --params \'{"agentKey":"<key>","includeGeoblock":true}\' --json',
+          ],
+        },
+      }
+    : normalized;
   const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
   printEnvelope({
     success: normalized.success,
     code: normalized.success ? 'PREFLIGHT_OK' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'PREFLIGHT_FAILED',
     message: backendResult.message,
-    data: normalized,
+    data,
     meta: {
       apiBase: ctx.apiBase,
       catalog: flags.catalog || null,
@@ -4863,6 +4887,46 @@ function printEnvelope(payload) {
   process.stdout.write(`${JSON.stringify(payload.data || {}, null, 2)}\n`);
 }
 
+async function commandPolymarketStatus(ctx, flags) {
+  const params = {
+    includeBalance: parseBooleanFlag(flags.includeBalance, true),
+    includeGeoblock: parseBooleanFlag(flags.includeGeoblock, true),
+  };
+  if (flags.agentKey) params.agentKey = String(flags.agentKey);
+  if (flags.amountPusd) params.amountPusd = String(flags.amountPusd);
+  const capabilities = await negotiateCapabilities(ctx);
+  flags.action = 'get_polymarket_setup_status';
+  flags.params = JSON.stringify(params);
+  if (!flags.runMode) flags.runMode = 'agent_wallet';
+  await commandPreflight(ctx, flags, capabilities);
+}
+
+async function commandPolymarketSetup(ctx, flags) {
+  const capabilities = await negotiateCapabilities(ctx);
+  flags.action = 'get_polymarket_onboarding_plan';
+  flags.params = flags.params || JSON.stringify({ agentKey: flags.agentKey || undefined });
+  if (!flags.runMode) flags.runMode = 'agent_wallet';
+  flags.__polymarketSetupGuide = true;
+  await commandPreflight(ctx, flags, capabilities);
+}
+
+async function commandPolymarketDryRun(ctx, flags) {
+  if (!flags.action) flags.action = 'place_polymarket_order';
+  if (!flags.params) {
+    printEnvelope({
+      success: false,
+      code: 'MISSING_PARAMS',
+      message: 'Provide --params for place_polymarket_order dry-run (tokenID, price, size, side)',
+      data: {},
+      meta: { apiBase: ctx.apiBase },
+    });
+    process.exit(1);
+  }
+  const capabilities = await negotiateCapabilities(ctx);
+  if (!flags.runMode) flags.runMode = 'agent_wallet';
+  await commandPreflight(ctx, flags, capabilities);
+}
+
 function printHelp() {
   const help = `
 thirdfy-agent ${CLI_VERSION}
@@ -4900,6 +4964,9 @@ Core commands:
   thirdfy-agent managed setup [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--run-mode thirdfy|hybrid|agent_wallet] [--token-address <addr>] [--max-usd-per-day <usd>] [--chain-id <id>] [--json]
   thirdfy-agent wallet execute --agent-api-key <key> --user-did <did> --action <id> --params <json> [--chain-id <id>] [--idempotency-key <key>] [--wallet-address <expected>] [--allow-wallet-mismatch] [--json]
   thirdfy-agent wallet list [--json]
+  thirdfy-agent polymarket status [--agent-key <key>] [--amount-pusd <n>] [--json]
+  thirdfy-agent polymarket setup [--agent-key <key>] [--params <json>] [--json]
+  thirdfy-agent polymarket dry-run --params <json> [--action place_polymarket_order] [--json]
   thirdfy-agent wallet sign --agent-api-key <key> --action <id> --params <json> [--chain-id <id>] [--json]
   thirdfy-agent wallet submit --signed-tx-hex <hex> [--chain-id <id>] [--rpc-url <url>] [--json]
   thirdfy-agent agent run --agent-api-key <key> --action <id> --params <json> [--signer-method managed_wallet_server|byow|fanout_intent] [--strategy-intent single_wallet|fanout] [--run-mode <mode>] [--user-did <did>] [--json]

package/package.json

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