@thirdfy/agent-cli 0.1.48 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.48",
+  "version": "0.2.1",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -8,21 +8,31 @@
   },
   "files": [
     "bin/",
+    "src/core/",
+    "src/commands/",
+    "src/cli/",
+    "src/runtime/",
     "src/utils/cli/",
     "src/contracts/cli/schemas/",
     "scripts/validate-cli-contract-schemas.mjs",
+    "scripts/validate-npm-pack.mjs",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.cjs\"",
-    "lint": "node --check ./bin/thirdfy-agent.mjs",
+    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/actions/*.mjs",
+    "validate:cli-manifest-handlers": "node ./scripts/validate-cli-manifest-handlers.mjs",
+    "validate:runtime-boundaries": "node ./scripts/validate-runtime-boundaries.mjs",
+    "validate:npm-pack": "node ./scripts/validate-npm-pack.mjs",
     "release:npm": "node ./scripts/release-npm.mjs",
     "publish:npm:local": "bash ./scripts/local-npm-publish.sh",
     "validate:public-docs": "node ./scripts/validate-public-docs.mjs",
     "validate:cli-contract-schemas": "node ./scripts/validate-cli-contract-schemas.mjs",
+    "validate:provider-parity": "node ./scripts/validate-provider-parity.mjs",
     "validate:actions": "node ./scripts/e2e/validate-actions.mjs",
+    "e2e:local-api:smoke": "node ./scripts/e2e/local-api-smoke.mjs",
     "e2e:base:simulate": "node ./scripts/e2e/base-simulate.mjs",
     "e2e:base:real": "node ./scripts/e2e/base-realtx.mjs",
     "e2e:delegation:discovery": "node ./scripts/e2e/delegation-discovery.mjs",
@@ -33,8 +43,10 @@
     "e2e:managed:delegation:parity": "node ./scripts/e2e/managed-custodial-lifecycle.mjs",
     "e2e:delegation:prod:certify": "node ./scripts/e2e/prod-delegation-certify.mjs",
     "e2e:report:last": "node ./scripts/e2e/report-last.mjs",
-    "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
-    "prepublishOnly": "npm run validate:public-docs && npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
+    "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs -V && node ./bin/thirdfy-agent.mjs --version --json",
+    "validate:release-preflight": "npm run lint && npm run validate:public-docs && npm run validate:cli-contract-schemas && npm run validate:provider-parity && npm run validate:cli-manifest-handlers && npm run validate:runtime-boundaries && npm run test && npm run validate:npm-pack && npm run smoke:cli",
+    "validate:live-api-capabilities": "node ./scripts/validate-live-api-capabilities.mjs",
+    "prepublishOnly": "npm run validate:release-preflight"
   },
   "keywords": [
     "thirdfy",
@@ -57,6 +69,7 @@
   "homepage": "https://github.com/thirdfy/agent-cli#readme",
   "dependencies": {
     "@open-wallet-standard/core": "^1.3.0",
+    "commander": "^12.1.0",
     "ethers": "^6.16.0"
   }
 }

package/scripts/validate-npm-pack.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const requiredPaths = [
+  'bin/thirdfy-agent.mjs',
+  'src/core/index.mjs',
+  'src/core/constants.mjs',
+  'src/core/envelope.mjs',
+  'src/utils/cli/intentNormalization.cjs',
+  'src/contracts/cli/schemas/preflight.response.schema.json',
+];
+
+const repoRoot = path.resolve(fileURLToPath(new URL('.', import.meta.url)), '..');
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'thirdfy-agent-pack-'));
+
+execSync('npm pack --pack-destination .', { cwd: repoRoot, stdio: 'pipe' });
+const packed = fs.readdirSync(repoRoot).find((name) => name.endsWith('.tgz'));
+if (!packed) {
+  console.error('npm pack did not produce a tarball');
+  process.exit(1);
+}
+
+const extractDir = path.join(tmpDir, 'package');
+fs.mkdirSync(extractDir, { recursive: true });
+const tarballPath = path.join(repoRoot, packed);
+execSync(`tar -xzf ${JSON.stringify(tarballPath)} -C ${JSON.stringify(extractDir)}`, {
+  stdio: 'pipe',
+});
+fs.unlinkSync(tarballPath);
+
+const packageRoot = path.join(extractDir, 'package');
+const missing = requiredPaths.filter((rel) => !fs.existsSync(path.join(packageRoot, rel)));
+if (missing.length) {
+  console.error('npm pack tarball missing required paths:');
+  for (const rel of missing) console.error(`  - ${rel}`);
+  process.exit(1);
+}
+
+console.log('npm pack validation OK');

package/src/cli/errors.mjs

@@ -0,0 +1,103 @@
+/**
+ * JSON-aware Commander exitOverride wiring.
+ */
+
+function resolveJsonMode(program, getJsonMode) {
+  if (typeof getJsonMode === 'function' && getJsonMode()) return true;
+  if (process.argv.includes('--json')) return true;
+  try {
+    return Boolean(program.opts()?.json);
+  } catch {
+    return false;
+  }
+}
+
+export function configureCommanderErrors(program, deps) {
+  const { getJsonMode, printEnvelope, CLI_VERSION, getApiBase, collectRootFlags } = deps;
+
+  program.exitOverride((err) => {
+    const jsonMode = resolveJsonMode(program, getJsonMode);
+
+    if (err.code === 'commander.help' || err.code === 'commander.helpDisplayed') {
+      const rootFlags = typeof collectRootFlags === 'function' ? collectRootFlags(program) : {};
+      if (!rootFlags.version) {
+        program.outputHelp();
+      }
+      throw err;
+    }
+
+    if (err.code === 'commander.unknownCommand') {
+      if (jsonMode) {
+        printEnvelope({
+          success: false,
+          code: 'UNKNOWN_COMMAND',
+          message: err.message || 'Unknown command',
+          data: {},
+          meta: { version: CLI_VERSION, apiBase: getApiBase() },
+        });
+      }
+      throw err;
+    }
+
+    const optionErrors = new Set([
+      'commander.unknownOption',
+      'commander.optionMissingArgument',
+      'commander.missingMandatoryOptionValue',
+      'commander.missingArgument',
+    ]);
+
+    if (optionErrors.has(err.code)) {
+      if (jsonMode) {
+        printEnvelope({
+          success: false,
+          code: 'CLI_ARG_ERROR',
+          message: err.message || 'Invalid CLI arguments',
+          data: { commanderCode: err.code },
+          meta: { version: CLI_VERSION, apiBase: getApiBase() },
+        });
+      }
+      throw err;
+    }
+
+    throw err;
+  });
+
+  program.showHelpAfterError(!resolveJsonMode(program, getJsonMode));
+
+  return program;
+}
+
+/** Parse root version/json/api-base from argv without full Commander parse (avoids help noise). */
+export function collectVersionFlagsFromArgv(argv = process.argv) {
+  const flags = {};
+  if (argv.includes('-V') || argv.includes('--version')) flags.version = true;
+  if (argv.includes('--json')) flags.json = true;
+  const apiIdx = argv.indexOf('--api-base');
+  if (apiIdx >= 0 && argv[apiIdx + 1]) flags.apiBase = argv[apiIdx + 1];
+  const envIdx = argv.indexOf('--env');
+  if (envIdx >= 0 && argv[envIdx + 1]) flags.env = argv[envIdx + 1];
+  return flags;
+}
+
+export async function handleRootOnlyFlows(program, deps, flagsOverride = null) {
+  const { collectRootFlags, prepareContextFromFlags, printEnvelope, CLI_VERSION, getApiBase } = deps;
+  const flags = flagsOverride || collectRootFlags(program);
+
+  if (flags.version) {
+    prepareContextFromFlags(flags);
+    if (flags.json) {
+      printEnvelope({
+        success: true,
+        code: 'OK',
+        message: 'thirdfy-agent version',
+        data: { version: CLI_VERSION },
+        meta: { apiBase: getApiBase() },
+      });
+    } else {
+      process.stdout.write(`${CLI_VERSION}\n`);
+    }
+    return true;
+  }
+
+  return false;
+}

package/src/cli/flags.mjs

@@ -0,0 +1,66 @@
+/**
+ * Merge Commander opts from root + leaf command into legacy flags shape used by handlers.
+ */
+
+function walkAncestors(command) {
+  const chain = [];
+  let current = command;
+  while (current) {
+    chain.unshift(current);
+    current = current.parent;
+  }
+  return chain;
+}
+
+function mergeOpts(commands) {
+  const merged = {};
+  for (const cmd of commands) {
+    Object.assign(merged, cmd.opts());
+  }
+  return merged;
+}
+
+export function collectRootFlags(program) {
+  return normalizeFlags(program.opts());
+}
+
+export function collectLegacyFlags(rootProgram, actionCommand, extra = {}) {
+  const chain = actionCommand ? walkAncestors(actionCommand) : [rootProgram];
+  const opts = { ...mergeOpts(chain), ...extra };
+  return normalizeFlags(opts);
+}
+
+function normalizeFlags(opts) {
+  const flags = { ...opts };
+
+  if (flags.version) flags.version = true;
+  if (flags.help) flags.help = true;
+  if (flags.json) flags.json = true;
+  if (flags.verbose) flags.verbose = true;
+  if (flags.broadcast) flags.broadcast = true;
+  if (flags.skipPreflight) flags.skipPreflight = true;
+  if (flags.allowWalletMismatch) flags.allowWalletMismatch = true;
+  if (flags.verify) flags.verify = true;
+  if (flags.includeOnchain) flags.includeOnchain = true;
+  if (flags.onchain) flags.includeOnchain = true;
+  if (flags.acceptTerms) flags.acceptTerms = true;
+  if (flags.all) flags.all = true;
+  if (flags.clearAgentKey) flags.clearAgentKey = true;
+  if (flags.noBootstrapAgent) flags.noBootstrapAgent = true;
+  if (flags.rotateAgentKey) flags.rotateAgentKey = true;
+  if (flags.notInteractive) flags.notInteractive = true;
+  if (flags.ni) flags.ni = true;
+
+  // Commander action args
+  if (flags.address !== undefined) {
+    flags.address = String(flags.address).trim();
+  }
+  if (Array.isArray(flags.query)) {
+    const tokens = flags.query.filter(Boolean).map(String);
+    flags.prompt = tokens.join(' ').trim();
+  } else if (flags.query !== undefined) {
+    flags.prompt = String(flags.query).trim();
+  }
+
+  return flags;
+}

package/src/cli/help.mjs

@@ -0,0 +1,89 @@
+export function printHelp({ version }) {
+  const help = `
+thirdfy-agent ${version}
+
+Core commands:
+  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid|agent_wallet] [--custody-mode managed|external] [--json]
+  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid|agent_wallet] [--custody-mode managed|external] [--json]
+  thirdfy-agent profile show [--json]
+  thirdfy-agent config set --key <path> --value <value> [--json]
+  thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--agent-key <key>] [--run-mode <mode>] [--custody-mode managed|external] [--wallet-address <addr>] [--json]
+  thirdfy-agent login email <address> [--code <otp>] [--accept-terms] [--key-name <name>] [--agent-key <key>] [--not-interactive|--ni] [--json]
+  thirdfy-agent logout [--all] [--clear-agent-key] [--json]
+  thirdfy-agent whoami [--json]
+  thirdfy-agent help onboarding [--json]
+  thirdfy-agent catalogs list [--json]
+  thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
+  thirdfy-agent data summary --agent-key <key> [--chain-id <id>] [--network <id>] [--category trading|yield|prediction] [--limit <n>] [--json]
+  thirdfy-agent analytics portfolio --agent-key <key> [--network base-mainnet] [--category trading|yield|prediction] [--json]
+  thirdfy-agent analytics leaderboard [--category trading|yield|prediction] [--network base-mainnet] [--window 24h|7d|30d|all] [--metric roiPct|pnlUsd|aprPct|currentValueUsd] [--json]
+  thirdfy-agent track actions --agent-key <key> [--limit <n>] [--json]
+  thirdfy-agent track events --agent-key <key> [--limit <n>] [--json]
+  thirdfy-agent track action --agent-api-key <key> --action <name> [--category <name>] [--source agent|external_mcp|operator|thirdfy|custom] [--provider <id>] [--protocol <id>] [--namespace <name>] [--action-type supported|custom] [--status observed|planned|skipped|submitted|confirmed|failed|blocked] [--chain-id <id>] [--params <json>] [--json]
+  thirdfy-agent delegation create [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
+  thirdfy-agent delegation init-custodial [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
+  thirdfy-agent delegation custodial-grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
+  thirdfy-agent delegation activate [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --wallet-address <addr> --session-account-address <addr> --delegation-manager <addr> --delegation <json> --signature <hex> [--json]
+  thirdfy-agent delegation status [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation show [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation inspect [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation balance [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--chain-id <id>] [--json]
+  thirdfy-agent delegation revoke [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--reason <text>] [--chain-id <id>] [--json]
+  thirdfy-agent delegation redeem --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid|agent_wallet] [--estimated-amount-usd <usd>] [--json]
+  thirdfy-agent managed wallet init [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
+  thirdfy-agent managed wallet grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
+  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]
+  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--permission-profile funding|spot] [--credential-ref <ref>] [--verify-permissions] [--skip-permissions-probe] [--bitfinex-base-url <url>] [--json]
+  thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
+  thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
+  thirdfy-agent agent auth verify --challenge-id <id> --signature <hex> --agent-key <key> [--wallet-address <addr>] [--json]
+  thirdfy-agent bootstrap begin --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
+  thirdfy-agent bootstrap complete --agent-key <key> [--proof-type session_token|wallet_signature] [--lane self|hybrid|thirdfy|agent_wallet] [--owner-session-token <token> | --auth-token <token> | --challenge-id <id> --signature <hex>] [--name <agent-name>] [--mcp-base <url>] [--json]
+  thirdfy-agent onboarding begin ...      # alias of bootstrap begin
+  thirdfy-agent onboarding complete ...   # alias of bootstrap complete
+  thirdfy-agent developer bootstrap --agent-key <key> --name <name> [--owner-session-token <token> | --challenge-id <id> --signature <hex>] [--json]
+  thirdfy-agent agent register --agent-key <key> --name <name> [--auth-token <token> | --owner-session-token <token>] [--json]
+  thirdfy-agent agent key rotate [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
+  thirdfy-agent agent key revoke [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
+  thirdfy-agent preflight --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
+  thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--broadcast] [--idempotency-key <key>] [--json]
+  thirdfy-agent self-exec --agent-api-key <key> --action <id> --params <json> --wallet-address <addr> --ows-wallet-name <name> [--rpc-url <url>] [--effect-check strict|relaxed|off] [--json]
+  thirdfy-agent doctor self [--wallet-address <addr>] [--ows-wallet-name <name>] [--rpc-url <url>] [--json]
+  thirdfy-agent doctor auth [--json]
+  thirdfy-agent jeff preflight --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
+  thirdfy-agent jeff trade --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
+  thirdfy-agent jeff status --intent-id <id> [--json]
+  thirdfy-agent prompt "<natural language prompt>" [--json]
+  thirdfy-agent intent-status --intent-id <id> [--json]
+  thirdfy-agent credits balance --auth-token <token> [--json]
+
+Global flags:
+  --api-base <url>   default: https://api.thirdfy.com
+  --mcp-base <url>   default: https://mcp.thirdfy.com (bootstrap token issuance)
+  --run-mode <mode>  thirdfy | self | hybrid | agent_wallet
+  --hybrid-wallet-mode <mode>  self | agent_wallet (only with --run-mode hybrid)
+  --custody-mode <mode>  managed | external
+  --profile <name>   personal | builder | network
+  --env <file>       load env vars from file
+  --timeout <ms>     request timeout
+  --params <json>    for swap: amountInRaw + tokenInDecimals, or amountInHuman + tokenInDecimals, or legacy human amountIn (decimal string)
+  --broadcast        with run --run-mode self, sign and broadcast using OWS
+  --user-did <did>   required for managed wallet server execution paths
+  --allow-wallet-mismatch  bypass strict funded-wallet vs execution-wallet guard
+  --effect-check <mode>  self-exec check mode: strict | relaxed | off (default: relaxed)
+  --owner-session-token <token>  owner session token (or THIRDFY_OWNER_SESSION_TOKEN)
+  --not-interactive, --ni  fail fast when required login input is missing
+  --json             stable machine-readable output
+  --verbose          print adapter diagnostics
+  --version          print version
+`.trim();
+  process.stdout.write(`${help}\n`);
+}