@thirdfy/agent-cli 0.1.46 → 0.2.1

package/src/cli/manifest.mjs

@@ -0,0 +1,422 @@
+/**
+ * Commander command manifest — mirrors former dispatch.mjs routing.
+ * @typedef {'offline'|'online'} CapabilityTier
+ * @typedef {object} ManifestEntry
+ * @property {string[]} path - command path segments
+ * @property {string} handler - key on handlers object
+ * @property {CapabilityTier} [tier='offline']
+ * @property {string[]} [aliases] - alternate paths (same handler/options)
+ * @property {string[]} [options] - option bundle names from options/index.mjs
+ * @property {string} [description]
+ * @property {object} [args] - Commander arguments, e.g. { email: '<address>' }
+ * @property {string} [trackKind] - for commandTrackList: 'actions' | 'events'
+ * @property {boolean} [jeffAlias] - maps jeff * to root handlers
+ */
+
+/** @type {ManifestEntry[]} */
+export const CLI_MANIFEST = [
+  // profile / config
+  {
+    path: ['profile', 'init'],
+    handler: 'commandProfileInit',
+    options: ['bootstrap'],
+    description: 'Initialize CLI profile and run mode defaults',
+  },
+  {
+    path: ['profile', 'use'],
+    handler: 'commandProfileUse',
+    options: ['bootstrap'],
+    description: 'Switch active profile and run mode',
+  },
+  {
+    path: ['profile', 'show'],
+    handler: 'commandProfileShow',
+    description: 'Show persisted profile configuration',
+  },
+  {
+    path: ['config', 'set'],
+    handler: 'commandConfigSet',
+    options: ['bootstrap'],
+    description: 'Set a nested config value',
+  },
+  {
+    path: ['config', 'get'],
+    handler: 'commandProfileShow',
+    description: 'Show persisted profile configuration (alias of profile show)',
+  },
+  // auth
+  {
+    path: ['login'],
+    handler: 'commandLogin',
+    options: ['auth', 'bootstrap'],
+    description: 'Login with auth token, owner session, or agent API key',
+  },
+  {
+    path: ['login', 'email'],
+    handler: 'commandLoginEmail',
+    options: ['auth', 'bootstrap'],
+    description: 'Privy email OTP login',
+    args: { address: '<address>' },
+  },
+  { path: ['logout'], handler: 'commandLogout', options: ['bootstrap'], description: 'Logout and clear local credentials' },
+  { path: ['whoami'], handler: 'commandWhoami', description: 'Show masked local identity' },
+  { path: ['doctor', 'self'], handler: 'commandDoctorSelf', options: ['wallet'], description: 'Self-mode wallet diagnostics' },
+  { path: ['doctor', 'auth'], handler: 'commandDoctorAuth', description: 'Auth and onboarding diagnostics' },
+  {
+    path: ['help', 'onboarding'],
+    handler: 'commandHelpOnboarding',
+    description: 'Structured onboarding help (JSON envelope)',
+  },
+  {
+    path: ['onboarding', 'help'],
+    handler: 'commandHelpOnboarding',
+    description: 'Structured onboarding help (JSON envelope)',
+  },
+  { path: ['wallet', 'list'], handler: 'commandWalletList', description: 'List configured wallets' },
+  // polymarket (offline wrappers)
+  {
+    path: ['polymarket', 'status'],
+    handler: 'commandPolymarketStatus',
+    options: ['auth', 'polymarket'],
+    description: 'Polymarket funding/setup status',
+  },
+  {
+    path: ['polymarket', 'setup'],
+    handler: 'commandPolymarketSetup',
+    options: ['auth', 'execution', 'polymarket'],
+    description: 'Polymarket onboarding preflight',
+  },
+  {
+    path: ['polymarket', 'dry-run'],
+    handler: 'commandPolymarketDryRun',
+    options: ['auth', 'execution', 'polymarket'],
+    description: 'Polymarket dry-run preflight',
+  },
+  // online
+  {
+    path: ['agent', 'run'],
+    handler: 'commandAgentRun',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Run agent action via managed/self paths',
+  },
+  {
+    path: ['managed', 'setup'],
+    handler: 'commandManagedSetup',
+    tier: 'online',
+    options: ['auth', 'delegation', 'bootstrap'],
+    description: 'Managed wallet + delegation setup',
+  },
+  {
+    path: ['jeff', 'trade'],
+    handler: 'commandRun',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Execute intent (jeff alias)',
+  },
+  {
+    path: ['jeff', 'preflight'],
+    handler: 'commandPreflight',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Governance preflight (jeff alias)',
+  },
+  {
+    path: ['jeff', 'status'],
+    handler: 'commandIntentStatus',
+    tier: 'online',
+    options: ['execution'],
+    description: 'Intent status (jeff alias)',
+  },
+  { path: ['catalogs', 'list'], handler: 'commandCatalogsList', tier: 'online', description: 'List action catalogs' },
+  {
+    path: ['credits', 'balance'],
+    handler: 'commandCreditsBalance',
+    tier: 'online',
+    options: ['auth'],
+    description: 'Credits balance',
+  },
+  {
+    path: ['data', 'summary'],
+    handler: 'commandDataSummary',
+    tier: 'online',
+    options: ['auth', 'tracking', 'chains'],
+    description: 'Agent data summary',
+  },
+  {
+    path: ['track', 'actions'],
+    handler: 'commandTrackList',
+    tier: 'online',
+    options: ['auth', 'tracking'],
+    trackKind: 'actions',
+    description: 'List tracked actions',
+  },
+  {
+    path: ['track', 'events'],
+    handler: 'commandTrackList',
+    tier: 'online',
+    options: ['auth', 'tracking'],
+    trackKind: 'events',
+    description: 'List tracked events',
+  },
+  {
+    path: ['track', 'action'],
+    handler: 'commandTrackAction',
+    tier: 'online',
+    options: ['auth', 'execution', 'tracking'],
+    description: 'Record a tracked action',
+  },
+  {
+    path: ['delegation', 'create'],
+    handler: 'commandDelegationCreate',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Create delegation',
+  },
+  {
+    path: ['delegation', 'grant'],
+    handler: 'commandDelegationCreate',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Create delegation (alias)',
+  },
+  {
+    path: ['delegation', 'init-custodial'],
+    handler: 'commandDelegationInitCustodial',
+    tier: 'online',
+    options: ['auth', 'delegation', 'chains'],
+    description: 'Initialize custodial session account',
+  },
+  {
+    path: ['delegation', 'custodial-grant'],
+    handler: 'commandDelegationCustodialGrant',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Custodial delegation grant',
+  },
+  {
+    path: ['delegation', 'activate'],
+    handler: 'commandDelegationActivate',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Activate delegation on-chain',
+  },
+  {
+    path: ['delegation', 'status'],
+    handler: 'commandDelegationStatus',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Delegation status',
+  },
+  {
+    path: ['delegation', 'show'],
+    handler: 'commandDelegationStatus',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Delegation status (alias)',
+  },
+  {
+    path: ['delegation', 'inspect'],
+    handler: 'commandDelegationInspect',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Delegation inspect',
+  },
+  {
+    path: ['delegation', 'balance'],
+    handler: 'commandDelegationBalance',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Delegation balance',
+  },
+  {
+    path: ['delegation', 'revoke'],
+    handler: 'commandDelegationRevoke',
+    tier: 'online',
+    options: ['auth', 'delegation'],
+    description: 'Revoke delegation',
+  },
+  {
+    path: ['delegation', 'redeem'],
+    handler: 'commandDelegationRedeem',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Redeem via delegation',
+  },
+  {
+    path: ['credentials', 'upsert'],
+    handler: 'commandCredentialsUpsert',
+    tier: 'online',
+    options: ['auth', 'credentials'],
+    description: 'Upsert CEX credentials',
+  },
+  {
+    path: ['credentials', 'status'],
+    handler: 'commandCredentialsStatus',
+    tier: 'online',
+    options: ['auth', 'credentials'],
+    description: 'CEX credential status',
+  },
+  {
+    path: ['agent', 'register'],
+    handler: 'commandAgentRegister',
+    tier: 'online',
+    options: ['auth', 'bootstrap', 'agent'],
+    description: 'Register agent',
+  },
+  {
+    path: ['developer', 'bootstrap'],
+    handler: 'commandDeveloperBootstrap',
+    tier: 'online',
+    options: ['auth', 'bootstrap'],
+    description: 'Developer bootstrap flow',
+  },
+  {
+    path: ['bootstrap', 'begin'],
+    handler: 'commandBootstrapBegin',
+    tier: 'online',
+    options: ['auth', 'bootstrap'],
+    description: 'Begin agent bootstrap',
+  },
+  {
+    path: ['onboarding', 'begin'],
+    handler: 'commandBootstrapBegin',
+    tier: 'online',
+    options: ['auth', 'bootstrap'],
+    description: 'Begin agent bootstrap (alias)',
+  },
+  {
+    path: ['bootstrap', 'complete'],
+    handler: 'commandBootstrapComplete',
+    tier: 'online',
+    options: ['auth', 'bootstrap'],
+    description: 'Complete agent bootstrap',
+  },
+  {
+    path: ['onboarding', 'complete'],
+    handler: 'commandBootstrapComplete',
+    tier: 'online',
+    options: ['auth', 'bootstrap'],
+    description: 'Complete agent bootstrap (alias)',
+  },
+  // three-deep
+  {
+    path: ['agent', 'key', 'rotate'],
+    handler: 'commandAgentKeyRotate',
+    tier: 'online',
+    options: ['auth'],
+    description: 'Rotate agent API key',
+  },
+  {
+    path: ['agent', 'key', 'revoke'],
+    handler: 'commandAgentKeyRevoke',
+    tier: 'online',
+    options: ['auth'],
+    description: 'Revoke agent API key',
+  },
+  {
+    path: ['agent', 'auth', 'challenge'],
+    handler: 'commandAgentAuthChallenge',
+    tier: 'online',
+    options: ['auth'],
+    description: 'Agent wallet auth challenge',
+  },
+  {
+    path: ['agent', 'auth', 'verify'],
+    handler: 'commandAgentAuthVerify',
+    tier: 'online',
+    options: ['auth'],
+    description: 'Agent wallet auth verify',
+  },
+  {
+    path: ['managed', 'wallet', 'init'],
+    handler: 'commandDelegationInitCustodial',
+    tier: 'online',
+    options: ['auth', 'delegation', 'chains'],
+    description: 'Initialize managed wallet (custodial)',
+  },
+  {
+    path: ['managed', 'wallet', 'grant'],
+    handler: 'commandDelegationCustodialGrant',
+    tier: 'online',
+    options: ['auth', 'delegation', 'chains'],
+    description: 'Managed wallet grant',
+  },
+  {
+    path: ['wallet', 'execute'],
+    handler: 'commandWalletExecute',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Execute via wallet API',
+  },
+  {
+    path: ['wallet', 'sign'],
+    handler: 'commandWalletSign',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Sign via wallet API',
+  },
+  {
+    path: ['wallet', 'submit'],
+    handler: 'commandWalletSubmit',
+    tier: 'online',
+    options: ['wallet'],
+    description: 'Submit signed transaction',
+  },
+  {
+    path: ['analytics', 'portfolio'],
+    handler: 'commandAnalyticsPortfolio',
+    tier: 'online',
+    options: ['auth', 'tracking', 'analytics', 'chains'],
+    description: 'Portfolio analytics',
+  },
+  {
+    path: ['analytics', 'leaderboard'],
+    handler: 'commandAnalyticsLeaderboard',
+    tier: 'online',
+    options: ['tracking', 'analytics'],
+    description: 'Leaderboard analytics',
+  },
+  // root commands
+  {
+    path: ['prompt'],
+    handler: 'commandPrompt',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Natural language prompt (experimental)',
+    args: { query: '[query...]' },
+  },
+  {
+    path: ['actions'],
+    handler: 'commandActions',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'List allowed actions',
+  },
+  {
+    path: ['preflight'],
+    handler: 'commandPreflight',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Governance preflight',
+  },
+  { path: ['run'], handler: 'commandRun', tier: 'online', options: ['auth', 'execution'], description: 'Execute intent' },
+  {
+    path: ['self-exec'],
+    handler: 'commandSelfExec',
+    tier: 'online',
+    options: ['auth', 'execution', 'wallet'],
+    description: 'Self-custody execute with OWS',
+  },
+  {
+    path: ['intent-status'],
+    handler: 'commandIntentStatus',
+    tier: 'online',
+    options: ['execution'],
+    description: 'Poll intent status',
+  },
+];
+
+export function manifestPathKey(path) {
+  return path.join(' ');
+}

package/src/cli/options/agent.mjs

@@ -0,0 +1,9 @@
+export function attachAgentRegisterOptions(cmd) {
+  return cmd
+    .option('--bio <text>', 'agent bio')
+    .option('--website <url>', 'agent website')
+    .option('--github <handle>', 'agent github')
+    .option('--tags <csv>', 'agent tags csv')
+    .option('--strategy <json>', 'agent strategy JSON')
+    .option('--api-key-envelope-public-key <key>', 'API key envelope public key');
+}

package/src/cli/options/analytics.mjs

@@ -0,0 +1,5 @@
+export function attachAnalyticsOptions(cmd) {
+  return cmd
+    .option('--window <window>', '24h|7d|30d|all')
+    .option('--metric <metric>', 'roiPct|pnlUsd|aprPct|currentValueUsd');
+}

package/src/cli/options/auth.mjs

@@ -0,0 +1,10 @@
+export function attachAuthOptions(cmd) {
+  return cmd
+    .option('--auth-token <token>', 'Thirdfy auth token')
+    .option('--owner-session-token <token>', 'owner session token')
+    .option('--agent-api-key <key>', 'agent API key')
+    .option('--agent-key <key>', 'agent key')
+    .option('--wallet-address <addr>', 'wallet address')
+    .option('--challenge-id <id>', 'wallet challenge id')
+    .option('--signature <hex>', 'wallet signature hex');
+}

package/src/cli/options/bootstrap.mjs

@@ -0,0 +1,19 @@
+export function attachBootstrapOptions(cmd) {
+  return cmd
+    .option('--proof-type <type>', 'session_token|wallet_signature')
+    .option('--lane <mode>', 'bootstrap lane alias for run-mode')
+    .option('--key <path>', 'config key path')
+    .option('--value <value>', 'config value')
+    .option('--name <name>', 'profile or agent name')
+    .option('--email <address>', 'email address')
+    .option('--code <otp>', 'email OTP code')
+    .option('--otp <otp>', 'email OTP alias')
+    .option('--accept-terms', 'accept terms for email login')
+    .option('--key-name <name>', 'Privy key name')
+    .option('-ni, --not-interactive', 'fail fast when required login input is missing')
+    .option('--no-bootstrap-agent', 'skip agent bootstrap on email login')
+    .option('--rotate-agent-key', 'rotate agent key')
+    .option('--login-attempt-id <id>', 'email login attempt id')
+    .option('--all', 'logout all sessions')
+    .option('--clear-agent-key', 'clear stored agent key on logout');
+}

package/src/cli/options/chains.mjs

@@ -0,0 +1,3 @@
+export function attachChainOptions(cmd) {
+  return cmd.option('--chain-id <id>', 'chain id');
+}

package/src/cli/options/credentials.mjs

@@ -0,0 +1,15 @@
+export function attachCredentialsOptions(cmd) {
+  return cmd
+    .option('--venue <id>', 'credential venue')
+    .option('--api-key <key>', 'exchange API key')
+    .option('--api-secret <secret>', 'exchange API secret')
+    .option('--permission-profile <profile>', 'funding|spot')
+    .option('--credential-ref <ref>', 'credential reference')
+    .option('--credential-type <type>', 'credential type')
+    .option('--verify-permissions', 'verify exchange permissions')
+    .option('--skip-permissions-probe', 'skip permissions probe')
+    .option('--bitfinex-base-url <url>', 'Bitfinex API base URL')
+    .option('--passphrase <value>', 'exchange passphrase')
+    .option('--metadata <json>', 'credential metadata JSON')
+    .option('--policy <json>', 'credential policy JSON');
+}

package/src/cli/options/delegation.mjs

@@ -0,0 +1,22 @@
+export function attachDelegationOptions(cmd) {
+  return cmd
+    .option('--owner-address <addr>', 'owner address')
+    .option('--session-account-address <addr>', 'session account address')
+    .option('--token-address <addr>', 'token address')
+    .option('--max-usd-per-day <usd>', 'max USD per day')
+    .option('--period-duration <sec>', 'period duration seconds')
+    .option('--expiry-seconds <sec>', 'expiry seconds')
+    .option('--delegation-manager <addr>', 'delegation manager address')
+    .option('--delegation <json>', 'delegation JSON')
+    .option('--permission <json>', 'permission JSON')
+    .option('--permission-type <type>', 'permission type')
+    .option('--permission-data <json>', 'permission data JSON')
+    .option('--model-a-constraints <json>', 'model A constraints JSON')
+    .option('--permissions-expiry <value>', 'permissions expiry')
+    .option('--permissions-context <value>', 'permissions context')
+    .option('--session-account-type <type>', 'session account type')
+    .option('--verify', 'verify on-chain')
+    .option('--include-onchain', 'include on-chain data')
+    .option('--onchain', 'alias for include on-chain')
+    .option('--reason <text>', 'revoke reason');
+}

package/src/cli/options/execution.mjs

@@ -0,0 +1,24 @@
+export function attachExecutionOptions(cmd) {
+  return cmd
+    .option('--action <id>', 'action id')
+    .option('--params <json>', 'action params JSON')
+    .option('--catalog <id>', 'actions catalog id')
+    .option('--provider <id>', 'provider filter')
+    .option('--chain-id <id>', 'chain id')
+    .option('--idempotency-key <key>', 'idempotency key')
+    .option('--estimated-amount-usd <usd>', 'estimated amount USD')
+    .option('--broadcast', 'with run --run-mode self, sign and broadcast using OWS')
+    .option('--skip-preflight', 'skip preflight')
+    .option('--user-did <did>', 'user DID for managed paths')
+    .option('--allow-wallet-mismatch', 'bypass strict funded-wallet vs execution-wallet guard')
+    .option('--execution-scope <scope>', 'execution scope')
+    .option('--signer-method <method>', 'managed_wallet_server|byow|fanout_intent')
+    .option('--strategy-intent <intent>', 'single_wallet|fanout')
+    .option('--intent-id <id>', 'intent id')
+    .option('--execution-wallet-address <addr>', 'expected execution wallet')
+    .option('--effect-check <mode>', 'self-exec: strict|relaxed|off')
+    .option('--effect-check-retries <n>', 'effect check retries')
+    .option('--effect-check-wait-ms <ms>', 'effect check wait ms')
+    .option('--effect-token-in <addr>', 'effect check token in')
+    .option('--effect-token-out <addr>', 'effect check token out');
+}

package/src/cli/options/global.mjs

@@ -0,0 +1,16 @@
+/** Root-program globals only (also inherited by subcommands via opts merge). */
+export function attachGlobalOptions(program) {
+  program
+    .option('-V, --version', 'print version number')
+    .option('--api-base <url>', 'Thirdfy API base URL')
+    .option('--mcp-base <url>', 'MCP base URL for bootstrap token issuance')
+    .option('--timeout <ms>', 'HTTP timeout in milliseconds')
+    .option('--env <file>', 'load environment variables from file')
+    .option('--json', 'stable machine-readable envelopes')
+    .option('--verbose', 'print adapter diagnostics')
+    .option('--run-mode <mode>', 'thirdfy | self | hybrid | agent_wallet')
+    .option('--hybrid-wallet-mode <mode>', 'self | agent_wallet (hybrid only)')
+    .option('--custody-mode <mode>', 'managed | external')
+    .option('--profile <name>', 'personal | builder | network');
+  return program;
+}

package/src/cli/options/index.mjs

@@ -0,0 +1,37 @@
+import { attachGlobalOptions } from './global.mjs';
+import { attachAuthOptions } from './auth.mjs';
+import { attachExecutionOptions } from './execution.mjs';
+import { attachDelegationOptions } from './delegation.mjs';
+import { attachTrackingOptions } from './tracking.mjs';
+import { attachWalletOptions } from './wallet.mjs';
+import { attachBootstrapOptions } from './bootstrap.mjs';
+import { attachCredentialsOptions } from './credentials.mjs';
+import { attachAnalyticsOptions } from './analytics.mjs';
+import { attachPolymarketOptions } from './polymarket.mjs';
+import { attachAgentRegisterOptions } from './agent.mjs';
+import { attachChainOptions } from './chains.mjs';
+
+const BUNDLES = {
+  auth: attachAuthOptions,
+  execution: attachExecutionOptions,
+  delegation: attachDelegationOptions,
+  tracking: attachTrackingOptions,
+  wallet: attachWalletOptions,
+  bootstrap: attachBootstrapOptions,
+  credentials: attachCredentialsOptions,
+  analytics: attachAnalyticsOptions,
+  polymarket: attachPolymarketOptions,
+  agent: attachAgentRegisterOptions,
+  chains: attachChainOptions,
+};
+
+/** @param {import('commander').Command} cmd */
+export function attachOptionBundles(cmd, bundleNames = []) {
+  for (const name of bundleNames) {
+    const fn = BUNDLES[name];
+    if (fn) fn(cmd);
+  }
+  return cmd;
+}
+
+export { attachGlobalOptions, BUNDLES };

package/src/cli/options/polymarket.mjs

@@ -0,0 +1,3 @@
+export function attachPolymarketOptions(cmd) {
+  return cmd.option('--amount-pusd <n>', 'Polymarket pUSD amount');
+}

package/src/cli/options/tracking.mjs

@@ -0,0 +1,18 @@
+export function attachTrackingOptions(cmd) {
+  return cmd
+    .option('--limit <n>', 'result limit')
+    .option('--network <id>', 'network id')
+    .option('--network-id <id>', 'network id')
+    .option('--chain-type <type>', 'chain type')
+    .option('--category <name>', 'category')
+    .option('--status <status>', 'track status')
+    .option('--source <source>', 'track source')
+    .option('--protocol <id>', 'protocol id')
+    .option('--namespace <name>', 'namespace')
+    .option('--action-type <type>', 'action type')
+    .option('--event-id <id>', 'event id')
+    .option('--amount-usd <usd>', 'amount USD')
+    .option('--tx-hash <hash>', 'transaction hash')
+    .option('--decision <json>', 'decision JSON')
+    .option('--proof <json>', 'proof JSON');
+}

package/src/cli/options/wallet.mjs

@@ -0,0 +1,7 @@
+export function attachWalletOptions(cmd) {
+  return cmd
+    .option('--signed-tx-hex <hex>', 'signed transaction hex')
+    .option('--signed-tx <hex>', 'signed transaction hex alias')
+    .option('--rpc-url <url>', 'RPC URL')
+    .option('--ows-wallet-name <name>', 'OWS wallet name');
+}

package/src/cli/program.mjs

@@ -0,0 +1,5 @@
+import { buildCliProgram } from './register.mjs';
+
+export { buildCliProgram };
+export { collectRootFlags, collectLegacyFlags } from './flags.mjs';
+export { configureCommanderErrors, handleRootOnlyFlows, collectVersionFlagsFromArgv } from './errors.mjs';