@thirdfy/agent-cli 0.1.48 → 0.2.2

package/src/commands/doctor.mjs

@@ -0,0 +1,320 @@
+import { createRequire } from 'module';
+import { requireFlag } from '../core/args.mjs';
+import { apiGet, requestWithRouteFallback } from '../core/http.mjs';
+import { loadProfileConfig, getProfileConfigPath } from '../core/context.mjs';
+import { DEFAULT_API_BASE, PROFILE_DEFAULTS } from '../core/constants.mjs';
+import { normalizeRunMode, normalizeManagedRunMode } from '../core/runMode.mjs';
+
+const require = createRequire(import.meta.url);
+const { normalizeDelegationStatus } = require('../utils/cli/delegationNormalization.cjs');
+
+export function createDoctorCommands({
+  printEnvelope,
+  extractAgentApiKey,
+  extractAgentKey,
+  maskSecret,
+  resolveAgentApiKey,
+  buildOwnerAuthHeaders,
+  resolveEffectiveUserDid,
+  loadEthers,
+  resolveOwsBinary,
+}) {
+async function commandDoctorSelf(ctx, flags) {
+  const walletAddress = String(flags.walletAddress || process.env.MARKET_MAKER_WALLET_ADDRESS || '').trim();
+  const owsWalletName = String(flags.owsWalletName || process.env.OWS_WALLET_NAME || '').trim();
+  const rpcUrl = String(
+    flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org'
+  ).trim();
+  const passphrasePresent = Boolean(String(process.env.OWS_PASSPHRASE || process.env.OWS_API_KEY || '').trim());
+  const checks = [];
+
+  checks.push({
+    name: 'wallet-address',
+    ok: Boolean(walletAddress),
+    detail: walletAddress || 'missing --wallet-address / MARKET_MAKER_WALLET_ADDRESS',
+  });
+  checks.push({
+    name: 'ows-wallet-name',
+    ok: Boolean(owsWalletName),
+    detail: owsWalletName || 'missing --ows-wallet-name / OWS_WALLET_NAME',
+  });
+  checks.push({
+    name: 'ows-passphrase',
+    ok: passphrasePresent,
+    detail: passphrasePresent ? 'present' : 'missing OWS_PASSPHRASE (or OWS_API_KEY fallback)',
+  });
+
+  try {
+    resolveOwsBinary();
+    checks.push({ name: 'ows-binary', ok: true, detail: 'found' });
+  } catch (error) {
+    checks.push({ name: 'ows-binary', ok: false, detail: error?.message || 'not found' });
+  }
+
+  try {
+    await loadEthers();
+    checks.push({ name: 'ethers-runtime', ok: true, detail: 'loaded' });
+  } catch (error) {
+    checks.push({ name: 'ethers-runtime', ok: false, detail: error?.message || 'missing ethers dependency' });
+  }
+
+  try {
+    const ethers = await loadEthers();
+    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const block = await provider.getBlockNumber();
+    checks.push({ name: 'rpc-connectivity', ok: Number.isFinite(block), detail: `latestBlock=${block}` });
+  } catch (error) {
+    checks.push({ name: 'rpc-connectivity', ok: false, detail: error?.message || 'rpc check failed' });
+  }
+
+  const ok = checks.every((entry) => entry.ok);
+  printEnvelope({
+    success: ok,
+    code: ok ? 'DOCTOR_SELF_OK' : 'DOCTOR_SELF_FAILED',
+    message: ok ? 'Self lane signer diagnostics passed' : 'Self lane signer diagnostics found blocking issues',
+    data: {
+      checks,
+      hints: [
+        'For one-command self execution use: thirdfy-agent run --run-mode self --broadcast ...',
+        'Set --effect-check strict|relaxed|off to control post-trade effect validation behavior.',
+      ],
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      runMode: 'self',
+      rpcUrl,
+    },
+  });
+  if (!ok) process.exit(1);
+}
+
+function buildOnboardingHelp(ctx) {
+  return {
+    title: 'Thirdfy Agent CLI onboarding',
+    summary: 'Use email OTP, wallet-sign, or existing credentials to create owner auth, wallets, and hidden agent execution credentials. Fresh solo profiles default to agent_wallet.',
+    paths: [
+      {
+        id: 'email_otp',
+        recommended: true,
+        description: 'Email OTP first-run flow for humans and agents that can ask the user for a verification code.',
+        commands: [
+          'thirdfy-agent login email user@example.com',
+          'thirdfy-agent login email user@example.com --code <otp> --accept-terms --key-name "My Agent"',
+          'thirdfy-agent whoami',
+          'thirdfy-agent wallet list --json',
+          'thirdfy-agent preflight --run-mode agent_wallet --action <action> --params <json> --json',
+        ],
+        note: 'Email OTP authenticates the owner. Fund the returned agent execution wallet for the target chain; do not fund the owner embedded/login wallet for agent_wallet writes.',
+      },
+      {
+        id: 'wallet_sign',
+        description: 'Headless wallet proof for operators with an EVM signer.',
+        commands: [
+          'thirdfy-agent agent auth challenge --agent-key 0xYOUR_AGENT_KEY --json',
+          'thirdfy-agent login --agent-key 0xYOUR_AGENT_KEY --challenge-id <id> --signature <hex> --json',
+        ],
+      },
+      {
+        id: 'existing_credentials',
+        description: 'Use already-issued owner or agent credentials from a secure secret store.',
+        commands: [
+          'thirdfy-agent login --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"',
+          'thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN"',
+          'thirdfy-agent login --agent-api-key "$THIRDFY_AGENT_API_KEY"',
+        ],
+      },
+      {
+        id: 'mcp_bootstrap',
+        description: 'After owner proof, issue an MCP bootstrap token for agents.',
+        commands: [
+          'thirdfy-agent bootstrap complete --agent-key 0xYOUR_AGENT_KEY --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --lane thirdfy --json',
+        ],
+      },
+    ],
+    nonInteractive: {
+      flag: '--not-interactive or --ni',
+      example:
+        'thirdfy-agent login email user@example.com --code 123456 --accept-terms --ni (place --ni after the subcommand so it is not parsed as a flag value)',
+      rule: 'Commands must fail fast instead of waiting for prompts when required input is missing.',
+    },
+    executionModes: {
+      agent_wallet: 'Solo managed server-wallet execution through /execution-wallet + /execute; no subscriber binding when owner userDid matches. Network gas may be sponsored, but Thirdfy credits/free-quota gates still apply.',
+      self: 'BYOW/OWS local signing through build-tx, wallet sign, and wallet submit.',
+      hybrid: 'Primary self or agent_wallet execution with optional Thirdfy mirror validation.',
+      thirdfy: 'Publisher/fanout execute-intent; requires active subscriber/delegation bindings for writes.',
+      externalDelegation: 'Use delegation create/grant -> sign -> activate -> inspect/balance -> redeem for Gator/ERC-7710 external-wallet authority.',
+    },
+    frameworkGuidance: {
+      hermes:
+        'Hermes agents should receive a pre-provisioned Thirdfy profile/env, run doctor auth/self at startup, use agent_wallet for managed solo writes, fund the agent execution wallet on the target chain, and keep strategy logic separate from CLI secrets.',
+      openclaw:
+        'OpenClaw agents should keep Thirdfy credentials in runtime secrets, use actions discovery before planning, prefer run --run-mode agent_wallet for own-wallet execution, and use thirdfy only for publisher/fanout.',
+      claudeManagedAgents:
+        'Claude Managed Agents should use MCP agentRun/walletExecute for solo managed execution, walletSign/buildTx for BYOW, and executeIntent only for fanout or mirror previews.',
+    },
+    apiBase: ctx.apiBase,
+  };
+}
+
+async function commandDoctorAuth(ctx, _flags) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
+  const runMode = normalizeRunMode(ctx.runMode || config.runMode || 'agent_wallet');
+  const userDid = resolveEffectiveUserDid({});
+  const ownerSessionTokenFromEnv = String(process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  const authTokenFromEnv = String(process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  const agentApiKeyFromEnv = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
+  const checks = [
+    {
+      name: 'owner-auth',
+      ok: Boolean(auth.ownerSessionToken || auth.authToken || ownerSessionTokenFromEnv || authTokenFromEnv),
+      detail: auth.ownerSessionToken
+        ? 'owner session stored'
+        : auth.authToken
+          ? 'auth token stored'
+          : ownerSessionTokenFromEnv
+            ? 'owner session from THIRDFY_OWNER_SESSION_TOKEN'
+            : authTokenFromEnv
+              ? 'auth token from THIRDFY_AUTH_TOKEN'
+              : 'missing owner auth; run `thirdfy-agent login email <email>`',
+    },
+    {
+      name: 'agent-api-key',
+      optional: true,
+      ok: Boolean(agent.apiKey || agentApiKeyFromEnv),
+      detail: agent.apiKey
+        ? 'agent API key stored'
+        : agentApiKeyFromEnv
+          ? 'agent API key from THIRDFY_AGENT_API_KEY'
+          : 'not stored yet (optional until execution); complete onboarding or bootstrap to add one',
+    },
+    {
+      name: 'user-did',
+      optional: runMode !== 'agent_wallet',
+      ok: Boolean(userDid),
+      detail: userDid
+        ? `user DID available (${userDid})`
+        : 'missing user DID; run `thirdfy-agent login email <email>` or set THIRDFY_USER_DID',
+    },
+    {
+      name: 'wallet-profile',
+      ok: Boolean(config.wallets?.primaryEvmWallet || (Array.isArray(config.wallets?.evm) && config.wallets.evm.length)),
+      detail: config.wallets?.primaryEvmWallet
+        || (Array.isArray(config.wallets?.evm) && config.wallets.evm.length
+          ? `${config.wallets.evm.length} linked EVM wallet${config.wallets.evm.length === 1 ? '' : 's'}`
+          : 'missing wallet profile; run email onboarding or wallet-sign proof'),
+    },
+    {
+      name: 'agent-execution-wallets',
+      optional: runMode !== 'agent_wallet',
+      ok: Boolean(config.wallets?.executionWallets && Object.keys(config.wallets.executionWallets).length),
+      detail: config.wallets?.executionWallets && Object.keys(config.wallets.executionWallets).length
+        ? `agent execution wallets available for chains: ${Object.keys(config.wallets.executionWallets).join(', ')}`
+        : 'missing agent execution wallets; run `thirdfy-agent login email <email> --code <otp> --accept-terms --json` or execution-wallet preflight',
+    },
+    {
+      name: 'thirdfy-credits-vs-gas-sponsorship',
+      optional: true,
+      ok: true,
+      detail: 'Thirdfy credits/free quota gate action access; Privy gas sponsorship only pays network gas when chain/action sponsorship is enabled.',
+    },
+  ];
+  const ok = checks.every((entry) => entry.optional || entry.ok);
+  printEnvelope({
+    success: ok,
+    code: ok ? 'DOCTOR_AUTH_OK' : 'DOCTOR_AUTH_NEEDS_SETUP',
+    message: ok ? 'Auth profile is ready' : 'Auth profile needs setup',
+    data: {
+      checks,
+      help: buildOnboardingHelp(ctx),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+  if (!ok) process.exit(1);
+}
+
+async function commandManagedSetup(ctx, flags, capabilities) {
+  const mode = normalizeManagedRunMode(flags.runMode || 'agent_wallet');
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for managed setup'
+  );
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const chainId = Number(flags.chainId || 8453);
+  const tokenAddress = String(flags.tokenAddress || '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913').trim();
+  const maxUsdPerDay = Number(flags.maxUsdPerDay || 1000);
+  const initResponse = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/init-custodial'],
+    body: { chainId },
+    headers: { ...authHeaders },
+  });
+  const grantResponse = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/custodial-grant'],
+    body: {
+      chainId,
+      agentKey,
+      tokenAddress,
+      maxUsdPerDay,
+      periodDuration: Number(flags.periodDuration || 86_400),
+      expirySeconds: Number(flags.expirySeconds || 86_400),
+    },
+    headers: { ...authHeaders },
+  });
+  let readiness = null;
+  let readinessError = null;
+  try {
+    readiness = await apiGet(
+      ctx,
+      `/api/v1/agent/delegation/check?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`,
+      { ...authHeaders }
+    );
+  } catch (error) {
+    readinessError = {
+      message: error?.message || 'Delegation readiness check failed',
+      statusCode: Number(error?.statusCode || 0) || undefined,
+      payload: error?.payload && typeof error.payload === 'object' ? error.payload : undefined,
+    };
+  }
+  const success = initResponse?.success === true && grantResponse?.success === true;
+  printEnvelope({
+    success,
+    code: success ? 'MANAGED_SETUP_READY' : 'MANAGED_SETUP_FAILED',
+    message: success
+      ? readinessError
+        ? `Managed wallet setup completed, but readiness check failed. Run with --run-mode ${mode}.`
+        : `Managed wallet setup completed. Run with --run-mode ${mode}.`
+      : 'Managed wallet setup failed',
+    data: {
+      runMode: mode,
+      init: initResponse,
+      grant: grantResponse,
+      readiness: readiness ? normalizeDelegationStatus(readiness) : null,
+      readinessError,
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      lane: 'managed_easy_wallet',
+      agentKey,
+      chainId,
+      tokenAddress,
+      maxUsdPerDay,
+      upgradeHint:
+        mode === 'agent_wallet'
+          ? 'Use --run-mode self for strict BYOW local-sign, or --run-mode agent_wallet for managed execution.'
+          : null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!success) process.exit(1);
+}
+
+  return {
+    commandDoctorSelf,
+    buildOnboardingHelp,
+    commandDoctorAuth,
+    commandManagedSetup,
+  };
+}

package/src/commands/execute.mjs

@@ -0,0 +1,255 @@
+import { requireFlag } from '../core/args.mjs';
+import { createCliError } from '../core/envelope.mjs';
+import {
+  getEffectiveRunMode,
+  normalizeHybridWalletMode,
+  normalizeRunMode,
+  parseBooleanFlag,
+} from '../core/runMode.mjs';
+import { apiGet } from '../core/http.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../utils/cli/intentNormalization.cjs');
+
+export function createExecuteCommands(deps) {
+  const {
+    resolveActionSelection,
+    prepareActionParamsForFlags,
+    enforceOffchainVenueLaneCompatibility,
+    enforceChainCompatibility,
+    applyHyperliquidAgentWalletAddressDefault,
+    runPreflightByMode,
+    runExecutionByMode,
+    applyExecutionFallbackHints,
+    performSelfBroadcast,
+    executeManagedWalletRun,
+    executeSelfRun,
+    printEnvelope,
+    commandWalletSign,
+    commandWalletExecute,
+  } = deps;
+
+
+async function commandPreflight(ctx, flags, capabilities) {
+  const resolved = await resolveActionSelection(ctx, flags);
+  prepareActionParamsForFlags(flags, resolved.resolvedAction);
+  const runMode = getEffectiveRunMode(ctx, flags);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
+  const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
+  enforceChainCompatibility(capabilities, flags, runMode);
+  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode);
+  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved, { hybridWalletMode, managedPreflight });
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    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,
+    meta: {
+      apiBase: ctx.apiBase,
+      catalog: flags.catalog || null,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      preflightRoute: backendResult.route,
+      runMode,
+      hybridWalletMode,
+      profile: ctx.profile || null,
+      swapInput: flags.__swapInput || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+
+async function commandRun(ctx, flags, capabilities) {
+  const resolved = await resolveActionSelection(ctx, flags);
+  prepareActionParamsForFlags(flags, resolved.resolvedAction);
+  const runMode = getEffectiveRunMode(ctx, flags);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
+  const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
+  enforceChainCompatibility(capabilities, flags, runMode);
+  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode);
+  const skipPreflight = Boolean(flags.skipPreflight);
+  const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
+    skipPreflight,
+    hybridWalletMode,
+    managedPreflight,
+  });
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    runMode,
+    resolvedAction: resolved.resolvedAction,
+  });
+  if (runMode === 'self' && parseBooleanFlag(flags.broadcast, false) && normalized?.success) {
+    const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, normalized);
+    printEnvelope({
+      success: true,
+      code: 'SELF_EXECUTED',
+      message: 'Self-custody execution completed',
+      data: executed,
+      meta: {
+        apiBase: ctx.apiBase,
+        requestedAction: resolved.requestedAction,
+        resolvedAction: resolved.resolvedAction,
+        runMode,
+        profile: ctx.profile || null,
+        skippedPreflight: skipPreflight,
+        swapInput: flags.__swapInput || null,
+        capabilitiesVersion: capabilities?.contractVersion || null,
+      },
+    });
+    return;
+  }
+  printEnvelope({
+    success: normalized.success,
+    code: backendResult.code,
+    message: backendResult.message,
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      idempotencyKey: backendResult.idempotencyKey || null,
+      runMode,
+      hybridWalletMode,
+      profile: ctx.profile || null,
+      skippedPreflight: skipPreflight,
+      swapInput: flags.__swapInput || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+
+async function commandAgentRun(ctx, flags, capabilities) {
+  const signerMethod = String(flags.signerMethod || '').trim().toLowerCase();
+  const strategyIntent = String(flags.strategyIntent || '').trim().toLowerCase();
+  const requestedRunMode = String(flags.runMode || '').trim().toLowerCase();
+  if (signerMethod && !['managed_wallet_server', 'byow', 'fanout_intent'].includes(signerMethod)) {
+    throw createCliError(
+      'SIGNER_METHOD_INVALID',
+      `Unsupported --signer-method "${signerMethod}". Use managed_wallet_server, fanout_intent, or byow.`
+    );
+  }
+  if (signerMethod === 'byow' || requestedRunMode === 'self') {
+    await commandWalletSign(ctx, { ...flags, runMode: 'self' }, capabilities);
+    return;
+  }
+  if (signerMethod === 'fanout_intent') {
+    await commandRun(ctx, { ...flags, runMode: 'thirdfy' }, capabilities);
+    return;
+  }
+  if (signerMethod === 'managed_wallet_server') {
+    await commandWalletExecute(ctx, { ...flags, runMode: 'agent_wallet' }, capabilities);
+    return;
+  }
+  if (requestedRunMode) {
+    const runMode = normalizeRunMode(requestedRunMode);
+    if (runMode === 'self') {
+      await commandWalletSign(ctx, { ...flags, runMode }, capabilities);
+      return;
+    }
+    if (runMode === 'thirdfy' || runMode === 'hybrid') {
+      await commandRun(ctx, { ...flags, runMode }, capabilities);
+      return;
+    }
+    await commandWalletExecute(ctx, { ...flags, runMode: 'agent_wallet' }, capabilities);
+    return;
+  }
+  if (strategyIntent === 'fanout') {
+    await commandRun(ctx, { ...flags, runMode: 'thirdfy' }, capabilities);
+    return;
+  }
+  await commandWalletExecute(ctx, { ...flags, runMode: 'agent_wallet' }, capabilities);
+}
+
+
+async function commandIntentStatus(ctx, flags, capabilities) {
+  const intentId = requireFlag(flags, 'intentId', 'Missing --intent-id');
+  const response = await apiGet(ctx, `/api/v1/agent/execute-intent/status?intentId=${encodeURIComponent(intentId)}`);
+  const normalized = normalizeIntentResponse(response);
+  printEnvelope({
+    success: normalized.success,
+    code: normalized.success ? 'OK' : 'INTENT_STATUS_FAILED',
+    message: normalized.success ? 'Intent status loaded' : 'Intent status failed',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      intentId,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+
+async function commandSelfExec(ctx, flags, capabilities) {
+  const resolved = await resolveActionSelection(ctx, flags);
+  prepareActionParamsForFlags(flags, resolved.resolvedAction);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
+  enforceChainCompatibility(capabilities, flags, 'self');
+  const selfResult = await executeSelfRun(ctx, flags, resolved, {
+    skipPreflight: Boolean(flags.skipPreflight),
+  });
+
+  if (!selfResult?.success) {
+    const blocked = Boolean(selfResult?.preflightBlocked);
+    printEnvelope({
+      success: false,
+      code: blocked ? 'PREFLIGHT_BLOCKED' : 'SELF_EXECUTION_FAILED',
+      message: blocked ? 'Preflight blocked self execution' : 'Self execution preparation failed',
+      data: selfResult || {},
+      meta: {
+        apiBase: ctx.apiBase,
+        runMode: 'self',
+        resolvedAction: resolved.resolvedAction,
+      },
+    });
+    process.exit(1);
+  }
+
+  const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, selfResult);
+
+  printEnvelope({
+    success: true,
+    code: 'SELF_EXECUTED',
+    message: 'Self-custody execution completed',
+    data: executed,
+    meta: {
+      apiBase: ctx.apiBase,
+      runMode: 'self',
+      resolvedAction: resolved.resolvedAction,
+      swapInput: flags.__swapInput || null,
+    },
+  });
+}
+
+  return {
+    commandPreflight,
+    commandRun,
+    commandAgentRun,
+    commandIntentStatus,
+    commandSelfExec,
+  };
+}

package/src/commands/hyperliquid.mjs

@@ -0,0 +1,51 @@
+import { parseJsonFlag } from '../core/args.mjs';
+
+export function createHyperliquidHelpers(deps) {
+  const { getPreparedParams, resolveManagedExecutionPreflight } = deps;
+
+
+function hyperliquidDefaultAddressParamForAction(action) {
+  const canonical = String(action || '').trim().toLowerCase().replace(/_/g, '-');
+  if (
+    canonical === 'get-hyperliquid-open-orders'
+    || canonical === 'get-hyperliquid-user-state'
+    || canonical === 'get-hyperliquid-builder-fee-status'
+    || canonical === 'get-hyperliquid-referral-status'
+  ) {
+    return 'userAddress';
+  }
+  if (
+    canonical === 'get-hyperliquid-setup-status'
+    || canonical === 'get-hyperliquid-funding-status'
+    || canonical === 'get-hyperliquid-onboarding-plan'
+    || canonical === 'prepare-hyperliquid-onboarding'
+  ) {
+    return 'mainWalletAddress';
+  }
+  return null;
+}
+
+
+async function applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode) {
+  if (runMode !== 'agent_wallet') return null;
+  const paramName = hyperliquidDefaultAddressParamForAction(resolved?.resolvedAction);
+  if (!paramName) return null;
+  const params = getPreparedParams(flags);
+  if (String(params?.[paramName] || '').trim()) return null;
+  const preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
+    runMode: 'agent_wallet',
+    requireFundingCheck: false,
+  });
+  if (!preflight.success || !preflight.executionWalletAddress) return preflight;
+  flags.__preparedParams = {
+    ...(params || {}),
+    [paramName]: preflight.executionWalletAddress,
+  };
+  return preflight;
+}
+
+  return {
+    hyperliquidDefaultAddressParamForAction,
+    applyHyperliquidAgentWalletAddressDefault,
+  };
+}

package/src/commands/index.mjs

@@ -0,0 +1,6 @@
+export { createPolymarketCommands, resolveConfigAgentKey } from './polymarket.mjs';
+export { createHyperliquidHelpers } from './hyperliquid.mjs';
+export { createExecuteCommands } from './execute.mjs';
+export { createWalletCommands } from './wallet.mjs';
+export { createDelegationCommands } from './delegation.mjs';
+export { createBootstrapCommands } from './bootstrap.mjs';