@thirdfy/agent-cli 0.1.3 → 0.1.5

package/README.md

@@ -8,6 +8,8 @@ Use it to:
 - run governance preflight checks
 - queue execute-intent requests with idempotency
 - poll intent status with stable JSON output for automation
+- choose execution topology with one switch: `thirdfy`, `self`, or `hybrid`
+- configure profile-driven defaults (`personal`, `builder`, `network`)
 
 If you want the full developer docs, start here:
 - [Thirdfy Agent CLI docs](https://docs.thirdfy.com/api/thirdfy-agent-cli)
@@ -37,6 +39,7 @@ export THIRDFY_AUTH_TOKEN="..."
 export THIRDFY_OWNER_SESSION_TOKEN="..."
 
 thirdfy-agent actions --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --json
+thirdfy-agent profile init --profile personal --json
 thirdfy-agent preflight --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
 thirdfy-agent run --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
 thirdfy-agent intent-status --api-base "$THIRDFY_API_BASE" --intent-id "<intentId>" --json
@@ -70,10 +73,45 @@ thirdfy-agent agent register --api-base "$THIRDFY_API_BASE" --owner-session-toke
 - For deterministic retries across workers/restarts, pass your own stable `--idempotency-key`.
 - `preflight` does not force idempotency keys.
 
+## Run modes and profiles
+
+`thirdfy-agent` supports one command surface with three run modes:
+
+- `--run-mode thirdfy` -> Thirdfy-governed execute-intent rail (default for `profile=network`)
+- `--run-mode self` -> self-custody rail (`build-tx` flow; default for `profile=personal`)
+- `--run-mode hybrid` -> self-custody + governance mirror metadata (default for `profile=builder`)
+
+Selection precedence:
+
+1. `--run-mode`
+2. `THIRDFY_RUN_MODE`
+3. saved profile config (`~/.thirdfy/config.json`)
+4. profile default
+
+Profile commands:
+
+```bash
+thirdfy-agent profile init --profile personal --json
+thirdfy-agent profile use --profile builder --run-mode hybrid --json
+thirdfy-agent whoami --json
+```
+
+`profile use --profile <name>` resets run mode to that profile default unless `--run-mode` is explicitly provided.
+
+## Jeff shorthand rail
+
+Jeff-friendly aliases map directly to core commands:
+
+- `thirdfy-agent jeff preflight ...` -> alias of `preflight`
+- `thirdfy-agent jeff trade ...` -> alias of `run`
+- `thirdfy-agent jeff status --intent-id ...` -> alias of `intent-status`
+- `thirdfy-agent prompt "<text>"` -> captures prompt intent and suggests deterministic execution commands
+
 ## Command groups
 
 - Discovery: `catalogs list`, `actions`
-- Execution: `preflight`, `run`, `intent-status`
+- Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
+- Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`
 - Governance readiness: `delegation upsert`, `delegation status`, `credentials upsert`, `credentials status`
 - Account: `credits balance`

package/bin/thirdfy-agent.mjs

@@ -2,6 +2,7 @@
 
 import { randomUUID } from 'crypto';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { createRequire } from 'module';
 
@@ -16,6 +17,12 @@ const {
 const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
+const RUN_MODES = ['thirdfy', 'self', 'hybrid'];
+const PROFILE_DEFAULTS = {
+  personal: 'self',
+  builder: 'hybrid',
+  network: 'thirdfy',
+};
 const catalogCache = new Map();
 
 const rawArgv = process.argv.slice(2);
@@ -59,6 +66,11 @@ main().catch((error) => {
 });
 
 async function main() {
+  const profileState = resolveProfileState(globalFlags);
+  context.profile = profileState.profile;
+  context.runMode = profileState.runMode;
+  context.profileConfigPath = profileState.configPath;
+
   if (globalFlags.version) {
     printEnvelope({
       success: true,
@@ -75,12 +87,43 @@ async function main() {
     return;
   }
 
-  const capabilities = await negotiateCapabilities(context);
   const commandKey = parsed.positionals.slice(0, 2).join(' ');
   const commandKey3 = parsed.positionals.slice(0, 3).join(' ');
   const subFlags = parsed.flags;
 
+  // Pure local profile/config commands should work offline.
+  switch (commandKey) {
+    case 'profile init':
+      await commandProfileInit(context, subFlags);
+      return;
+    case 'profile use':
+      await commandProfileUse(context, subFlags);
+      return;
+    case 'profile show':
+      await commandProfileShow(context, subFlags);
+      return;
+    case 'config get':
+      await commandProfileShow(context, subFlags);
+      return;
+    case 'whoami':
+      await commandProfileShow(context, subFlags);
+      return;
+    default:
+      break;
+  }
+
+  const capabilities = await negotiateCapabilities(context);
+
   switch (commandKey) {
+    case 'jeff trade':
+      await commandRun(context, subFlags, capabilities);
+      return;
+    case 'jeff preflight':
+      await commandPreflight(context, subFlags, capabilities);
+      return;
+    case 'jeff status':
+      await commandIntentStatus(context, subFlags, capabilities);
+      return;
     case 'catalogs list':
       await commandCatalogsList(context, subFlags, capabilities);
       return;
@@ -124,6 +167,9 @@ async function main() {
 
   const rootCommand = parsed.positionals[0];
   switch (rootCommand) {
+    case 'prompt':
+      await commandPrompt(context, subFlags, capabilities, parsed.positionals.slice(1));
+      return;
     case 'actions':
       await commandActions(context, subFlags, capabilities);
       return;
@@ -236,6 +282,9 @@ async function commandCatalogsList(ctx, flags, capabilities) {
 async function commandActions(ctx, flags, capabilities) {
   const policyAware = Boolean(flags.agentApiKey);
   const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  const effectiveRunMode = getEffectiveRunMode(ctx, flags);
+  const chainIdFilter = Number(flags.chainId || 0) || undefined;
+  const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
   printEnvelope({
     success: true,
     code: 'OK',
@@ -244,6 +293,9 @@ async function commandActions(ctx, flags, capabilities) {
     meta: {
       apiBase: ctx.apiBase,
       policyAware,
+      runMode: effectiveRunMode,
+      profile: ctx.profile || null,
+      chainCompatibility: chainSupport,
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
@@ -251,23 +303,22 @@ async function commandActions(ctx, flags, capabilities) {
 
 async function commandPreflight(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
-  const payload = buildIntentPayload(flags, {
-    validationOnly: true,
-    forceIdempotency: false,
-    resolvedAction: resolved.resolvedAction,
-  });
-  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
-  const normalized = normalizeIntentResponse(response);
+  const runMode = getEffectiveRunMode(ctx, flags);
+  enforceChainCompatibility(capabilities, flags, runMode);
+  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved.resolvedAction);
+  const normalized = backendResult.normalized;
   printEnvelope({
     success: normalized.success,
     code: normalized.success ? 'PREFLIGHT_OK' : 'PREFLIGHT_FAILED',
-    message: normalized.success ? 'Preflight completed' : 'Preflight failed',
+    message: backendResult.message,
     data: normalized,
     meta: {
       apiBase: ctx.apiBase,
       catalog: flags.catalog || null,
       requestedAction: resolved.requestedAction,
       resolvedAction: resolved.resolvedAction,
+      runMode,
+      profile: ctx.profile || null,
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
@@ -276,52 +327,25 @@ async function commandPreflight(ctx, flags, capabilities) {
 
 async function commandRun(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
+  const runMode = getEffectiveRunMode(ctx, flags);
+  enforceChainCompatibility(capabilities, flags, runMode);
   const skipPreflight = Boolean(flags.skipPreflight);
-  if (!skipPreflight) {
-    const preflightPayload = buildIntentPayload(flags, {
-      validationOnly: true,
-      forceIdempotency: false,
-      resolvedAction: resolved.resolvedAction,
-    });
-    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
-    const preflightNormalized = normalizeIntentResponse(preflight);
-    const blockedCount = preflightNormalized.blocked || 0;
-    if (!preflightNormalized.success || blockedCount > 0) {
-      printEnvelope({
-        success: false,
-        code: 'PREFLIGHT_BLOCKED',
-        message: 'Preflight blocked execution',
-        data: preflightNormalized,
-        meta: {
-          apiBase: ctx.apiBase,
-          catalog: flags.catalog || null,
-          requestedAction: resolved.requestedAction,
-          resolvedAction: resolved.resolvedAction,
-          skippedPreflight: false,
-        },
-      });
-      process.exit(1);
-      return;
-    }
-  }
-
-  const payload = buildIntentPayload(flags, {
-    validationOnly: false,
-    forceIdempotency: true,
-    resolvedAction: resolved.resolvedAction,
+  const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
+    skipPreflight,
   });
-  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
-  const normalized = normalizeIntentResponse(response);
+  const normalized = backendResult.normalized;
   printEnvelope({
     success: normalized.success,
-    code: normalized.success ? 'RUN_QUEUED' : 'RUN_FAILED',
-    message: normalized.success ? 'Execution intent queued' : 'Execution failed',
+    code: backendResult.code,
+    message: backendResult.message,
     data: normalized,
     meta: {
       apiBase: ctx.apiBase,
       requestedAction: resolved.requestedAction,
       resolvedAction: resolved.resolvedAction,
-      idempotencyKey: payload.idempotencyKey || null,
+      idempotencyKey: backendResult.idempotencyKey || null,
+      runMode,
+      profile: ctx.profile || null,
       skippedPreflight: skipPreflight,
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
@@ -609,6 +633,366 @@ async function commandAgentAuthVerify(ctx, flags, capabilities) {
   });
 }
 
+async function commandPrompt(ctx, flags, capabilities, promptTokens) {
+  const prompt = String(flags.prompt || promptTokens.join(' ') || '').trim();
+  if (!prompt) {
+    throw new Error('Missing prompt text. Use: thirdfy-agent prompt "<text>"');
+  }
+  // Jeff rail: deterministic wrapper around existing run contract.
+  printEnvelope({
+    success: true,
+    code: 'PROMPT_RECEIVED',
+    message: 'Prompt captured; execute with `jeff trade` or `run` using --run-mode.',
+    data: {
+      prompt,
+      suggestedCommands: [
+        'thirdfy-agent jeff trade --run-mode self --agent-api-key ... --action ... --params ...',
+        'thirdfy-agent jeff trade --run-mode hybrid --agent-api-key ... --action ... --params ...',
+      ],
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      profile: ctx.profile || null,
+      runMode: getEffectiveRunMode(ctx, flags),
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandProfileInit(ctx, flags) {
+  const profile = normalizeProfileName(flags.profile || flags.name || 'personal');
+  const runMode = normalizeRunMode(flags.runMode || PROFILE_DEFAULTS[profile]);
+  persistProfileConfig({
+    profile,
+    runMode,
+  });
+  ctx.profile = profile;
+  ctx.runMode = runMode;
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_INITIALIZED',
+    message: 'Profile initialized',
+    data: {
+      profile,
+      runMode,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+async function commandProfileUse(ctx, flags) {
+  const current = loadProfileConfig();
+  const profile = normalizeProfileName(flags.profile || flags.name || current.profile || 'personal');
+  // `profile use` intentionally re-applies profile defaults unless caller pins a mode.
+  const runMode = normalizeRunMode(flags.runMode || PROFILE_DEFAULTS[profile]);
+  persistProfileConfig({
+    profile,
+    runMode,
+  });
+  ctx.profile = profile;
+  ctx.runMode = runMode;
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_UPDATED',
+    message: 'Profile updated',
+    data: {
+      profile,
+      runMode,
+      defaults: PROFILE_DEFAULTS,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+async function commandProfileShow(ctx, _flags) {
+  const config = loadProfileConfig();
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_OK',
+    message: 'Profile configuration loaded',
+    data: {
+      profile: ctx.profile || config.profile || 'personal',
+      runMode: ctx.runMode || config.runMode || 'thirdfy',
+      profileDefaults: PROFILE_DEFAULTS,
+      configPath: getProfileConfigPath(),
+      config,
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+function resolveProfileState(flags) {
+  const persisted = loadProfileConfig();
+  const profile = normalizeProfileName(flags.profile || process.env.THIRDFY_PROFILE || persisted.profile || 'personal');
+  const runMode = normalizeRunMode(
+    flags.runMode ||
+      process.env.THIRDFY_RUN_MODE ||
+      persisted.runMode ||
+      PROFILE_DEFAULTS[profile] ||
+      'thirdfy'
+  );
+  return {
+    profile,
+    runMode,
+    configPath: getProfileConfigPath(),
+  };
+}
+
+function normalizeProfileName(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized in PROFILE_DEFAULTS) return normalized;
+  throw new Error(`Unsupported profile "${value}". Supported: ${Object.keys(PROFILE_DEFAULTS).join(', ')}`);
+}
+
+function normalizeRunMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return 'thirdfy';
+  if (RUN_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported --run-mode "${value}". Supported: ${RUN_MODES.join(', ')}`);
+}
+
+function getProfileConfigPath() {
+  return path.join(os.homedir(), '.thirdfy', 'config.json');
+}
+
+function loadProfileConfig() {
+  try {
+    const raw = fs.readFileSync(getProfileConfigPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function persistProfileConfig(config) {
+  const configPath = getProfileConfigPath();
+  const dirPath = path.dirname(configPath);
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}
+
+function getEffectiveRunMode(ctx, flags) {
+  if (flags.runMode) return normalizeRunMode(flags.runMode);
+  return normalizeRunMode(ctx.runMode || 'thirdfy');
+}
+
+function resolveChainSupport(capabilities, chainId, runMode) {
+  const chains = Array.isArray(capabilities?.chains) ? capabilities.chains : [];
+  if (!chainId) return { chainId: null, supported: null };
+  const match = chains.find((entry) => Number(entry.chainId) === Number(chainId));
+  if (!match) {
+    return { chainId, supported: false, reason: 'chain_not_advertised_by_api' };
+  }
+  const lanes = Array.isArray(match.supportedExecutionLanes) ? match.supportedExecutionLanes : [];
+  return {
+    chainId,
+    supported: lanes.includes(runMode),
+    runMode,
+    chainKey: match.chainKey || null,
+    displayName: match.displayName || null,
+  };
+}
+
+function enforceChainCompatibility(capabilities, flags, runMode) {
+  const chainId = Number(flags.chainId || 0) || undefined;
+  if (!chainId) return;
+  if (!capabilities || !Array.isArray(capabilities.chains)) return;
+  const support = resolveChainSupport(capabilities, chainId, runMode);
+  if (support?.supported === false) {
+    throw new Error(
+      `Chain ${chainId} is not advertised as compatible with run-mode=${runMode}. Check \`thirdfy-agent actions --chain-id ${chainId}\`.`
+    );
+  }
+}
+
+async function runPreflightByMode(runMode, ctx, flags, resolvedAction) {
+  if (runMode === 'self') {
+    const normalized = await executeSelfRun(
+      ctx,
+      flags,
+      { resolvedAction },
+      { skipPreflight: false }
+    );
+    const blockedByGovernance = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      message: blockedByGovernance
+        ? 'Self preflight blocked by governance'
+        : normalized.success
+          ? 'Self preflight completed (unsigned transaction ready)'
+          : 'Self preflight failed',
+      normalized,
+    };
+  }
+  const payload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: false,
+    resolvedAction,
+    runMode,
+    mirrorOnly: runMode === 'hybrid',
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  return {
+    message: normalized.success
+      ? runMode === 'hybrid'
+        ? 'Hybrid mirror preflight completed'
+        : 'Preflight completed'
+      : runMode === 'hybrid'
+        ? 'Hybrid mirror preflight failed'
+        : 'Preflight failed',
+    normalized,
+  };
+}
+
+async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
+  if (runMode === 'thirdfy') {
+    const normalized = await executeThirdfyRun(ctx, flags, resolved, options);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success ? 'RUN_QUEUED' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
+      message: normalized.success
+        ? 'Execution intent queued'
+        : preflightBlocked
+          ? 'Preflight blocked execution'
+          : 'Execution failed',
+      idempotencyKey: normalized.idempotencyKey || null,
+      normalized,
+    };
+  }
+  if (runMode === 'self') {
+    const normalized = await executeSelfRun(ctx, flags, resolved, options);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success
+        ? 'SELF_UNSIGNED_TX_READY'
+        : preflightBlocked
+          ? 'PREFLIGHT_BLOCKED'
+          : 'SELF_EXECUTION_FAILED',
+      message: normalized.success
+        ? 'Unsigned transaction prepared for self-custody execution'
+        : preflightBlocked
+          ? 'Preflight blocked self execution'
+          : 'Self-custody execution failed',
+      idempotencyKey: null,
+      normalized,
+    };
+  }
+  const normalized = await executeHybridRun(ctx, flags, resolved, options);
+  const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+  return {
+    code: normalized.success ? 'HYBRID_READY' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'HYBRID_FAILED',
+    message: normalized.success
+      ? 'Hybrid execution prepared (self tx + mirror preflight)'
+      : preflightBlocked
+        ? 'Preflight blocked hybrid execution'
+        : 'Hybrid execution failed',
+    idempotencyKey: normalized.idempotencyKey || null,
+    normalized,
+  };
+}
+
+async function executeThirdfyRun(ctx, flags, resolved, options) {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'thirdfy',
+      mirrorOnly: false,
+    });
+    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflightNormalized = normalizeIntentResponse(preflight);
+    const blockedCount = preflightNormalized.blocked || 0;
+    if (!preflightNormalized.success || blockedCount > 0) {
+      preflightNormalized.success = false;
+      preflightNormalized.error = preflightNormalized.error || 'Preflight blocked execution';
+      preflightNormalized.preflightBlocked = true;
+      return preflightNormalized;
+    }
+  }
+  const payload = buildIntentPayload(flags, {
+    validationOnly: false,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+    runMode: 'thirdfy',
+    mirrorOnly: false,
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  normalized.idempotencyKey = payload.idempotencyKey;
+  return normalized;
+}
+
+async function executeSelfRun(ctx, flags, resolved, options) {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'self',
+      mirrorOnly: false,
+    });
+    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflightNormalized = normalizeIntentResponse(preflight);
+    const blockedCount = preflightNormalized.blocked || 0;
+    if (!preflightNormalized.success || blockedCount > 0) {
+      preflightNormalized.success = false;
+      preflightNormalized.error = preflightNormalized.error || 'Preflight blocked self execution';
+      preflightNormalized.preflightBlocked = true;
+      return preflightNormalized;
+    }
+  }
+  const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
+  const buildTx = await apiPost(ctx, '/api/v1/agent/build-tx', buildTxPayload);
+  return normalizeIntentResponse({
+    ...buildTx,
+    status: buildTx?.status || 'ready',
+    mode: buildTx?.mode || 'self',
+    unsignedTx: buildTx?.unsignedTx || null,
+    estimatedGas: buildTx?.estimatedGas || null,
+  });
+}
+
+async function executeHybridRun(ctx, flags, resolved, options) {
+  const selfResult = await executeSelfRun(ctx, flags, resolved, options);
+  if (!selfResult.success) return selfResult;
+
+  const mirrorPayload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+    runMode: 'hybrid',
+    mirrorOnly: true,
+  });
+  const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+  const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+  return normalizeIntentResponse({
+    success: Boolean(selfResult.success && mirrorNormalized.success),
+    status: mirrorNormalized.status || 'ready',
+    mode: 'hybrid',
+    idempotencyKey: mirrorPayload.idempotencyKey,
+    self: selfResult,
+    mirror: mirrorNormalized,
+  });
+}
+
+function buildBuildTxPayload(flags, resolvedAction) {
+  const payload = {
+    agentApiKey: requireFlag(flags, 'agentApiKey', 'Missing --agent-api-key'),
+    action: String(resolvedAction || requireFlag(flags, 'action', 'Missing --action')).trim(),
+    params: parseJsonFlag(flags, 'params'),
+  };
+  if (flags.chainId) payload.chainId = Number(flags.chainId);
+  if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+  return payload;
+}
+
 function buildIntentPayload(flags, options) {
   const payload = {
     agentApiKey: requireFlag(flags, 'agentApiKey', 'Missing --agent-api-key'),
@@ -620,6 +1004,12 @@ function buildIntentPayload(flags, options) {
   if (flags.estimatedAmountUsd) payload.estimatedAmountUsd = Number(flags.estimatedAmountUsd);
   if (flags.userDid) payload.userDid = String(flags.userDid);
   if (options.validationOnly) payload.executionLane = 'validation_only';
+  if (options.runMode) {
+    payload.executionStrategy = {
+      runMode: String(options.runMode),
+      mirrorOnly: Boolean(options.mirrorOnly),
+    };
+  }
   if (options.forceIdempotency) {
     payload.idempotencyKey = String(flags.idempotencyKey || `cli:${payload.action}:${Date.now()}:${randomUUID()}`);
   } else if (flags.idempotencyKey) {
@@ -704,15 +1094,29 @@ async function resolveActionSelection(ctx, flags) {
     return { requestedAction, resolvedAction: requestedAction };
   }
 
-  const exact = keyed.filter(
-    (entry) => entry.key.toLowerCase() === requestedLower || entry.aliases.some((a) => a.toLowerCase() === requestedLower)
-  );
-  if (exact.length === 1) {
-    return { requestedAction, resolvedAction: exact[0].key };
+  // Prefer direct action id matches over alias matches.
+  // This keeps UX simple for commands like `--action swap` when another action aliases to "swap".
+  const exactKey = keyed.filter((entry) => entry.key.toLowerCase() === requestedLower);
+  if (exactKey.length === 1) {
+    return { requestedAction, resolvedAction: exactKey[0].key };
+  }
+  if (exactKey.length > 1) {
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(
+        exactKey.map((v) => v.key)
+      )}.`
+    );
+  }
+
+  const exactAlias = keyed.filter((entry) => entry.aliases.some((a) => a.toLowerCase() === requestedLower));
+  if (exactAlias.length === 1) {
+    return { requestedAction, resolvedAction: exactAlias[0].key };
   }
-  if (exact.length > 1) {
+  if (exactAlias.length > 1) {
     throw new Error(
-      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(exact.map((v) => v.key))}.`
+      `Ambiguous --action "${requestedAction}". Alias matches multiple actions: ${formatActionList(
+        exactAlias.map((v) => v.key)
+      )}.`
     );
   }
 
@@ -854,8 +1258,12 @@ function printHelp() {
 thirdfy-agent ${CLI_VERSION}
 
 Core commands:
+  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid] [--json]
+  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid] [--json]
+  thirdfy-agent profile show [--json]
+  thirdfy-agent whoami [--json]
   thirdfy-agent catalogs list [--json]
-  thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--json]
+  thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
   thirdfy-agent delegation upsert --user-did <did> --agent-key <key> --wallet-address <addr> [--json]
   thirdfy-agent delegation status --auth-token <token> --agent-key <key> [--verify] [--json]
   thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
@@ -865,13 +1273,19 @@ Core commands:
   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> [--json]
-  thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--idempotency-key <key>] [--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>] [--idempotency-key <key>] [--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
+  --run-mode <mode>  thirdfy | self | hybrid
+  --profile <name>   personal | builder | network
   --env <file>       load env vars from file
   --timeout <ms>     request timeout
   --owner-session-token <token>  owner session token (or THIRDFY_OWNER_SESSION_TOKEN)

package/package.json

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

package/src/utils/cli/intentNormalization.cjs

@@ -30,6 +30,12 @@ function normalizeIntentResponse(response) {
     results,
     blockedByReason: summarizeBlockedReasons(results),
     error: response?.error || null,
+    mode: response?.mode || null,
+    unsignedTx: response?.unsignedTx || null,
+    estimatedGas: response?.estimatedGas || null,
+    idempotencyKey: response?.idempotencyKey || null,
+    mirror: response?.mirror || null,
+    self: response?.self || null,
   };
 }