@thirdfy/agent-cli 0.1.2 → 0.1.4

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)
@@ -34,25 +36,83 @@ npx @thirdfy/agent-cli --help
 export THIRDFY_API_BASE="https://api.thirdfy.com"
 export AGENT_API_KEY="..."
 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 --idempotency-key "swap-001" --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
 ```
 
 ## Auth model
 
 - `AGENT_API_KEY`: execution identity and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
-- `THIRDFY_AUTH_TOKEN`: user-scoped onboarding and account/governance operations (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
+- `THIRDFY_AUTH_TOKEN`: Privy-native owner/account auth (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
+- `THIRDFY_OWNER_SESSION_TOKEN`: wallet-sign owner auth session (`agent register`, `agent key *`)
 
 Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is complete.
 
+### Wallet-sign onboarding path
+
+```bash
+thirdfy-agent agent auth challenge --api-base "$THIRDFY_API_BASE" --agent-key "0xYOUR_AGENT_KEY" --json
+# Sign challenge.message with your wallet, then:
+thirdfy-agent agent auth verify --api-base "$THIRDFY_API_BASE" --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
+```
+
+Use the returned session token:
+
+```bash
+thirdfy-agent agent register --api-base "$THIRDFY_API_BASE" --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
+```
+
+### Idempotency behavior (`run`)
+
+- `run` auto-generates `idempotencyKey` by default when not provided.
+- 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`
-- Onboarding: `agent register`, `agent key rotate`, `agent key revoke`
+- 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;
@@ -113,9 +156,20 @@ async function main() {
     await commandAgentKeyRevoke(context, subFlags, capabilities);
     return;
   }
+  if (commandKey3 === 'agent auth challenge') {
+    await commandAgentAuthChallenge(context, subFlags, capabilities);
+    return;
+  }
+  if (commandKey3 === 'agent auth verify') {
+    await commandAgentAuthVerify(context, subFlags, capabilities);
+    return;
+  }
 
   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;
@@ -228,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',
@@ -236,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,
     },
   });
@@ -243,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,
     },
   });
@@ -268,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,
     },
@@ -483,7 +515,10 @@ async function commandCredentialsStatus(ctx, flags, capabilities) {
 }
 
 async function commandAgentRegister(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent register');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent register: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {
     agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
     name: requireFlag(flags, 'name', 'Missing --name'),
@@ -501,9 +536,10 @@ async function commandAgentRegister(ctx, flags, capabilities) {
   if (flags.strategy) payload.strategy = parseJsonFlag(flags, 'strategy');
   if (flags.apiKeyEnvelopePublicKey) payload.apiKeyEnvelopePublicKey = String(flags.apiKeyEnvelopePublicKey);
 
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/register-with-privy', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const route = ownerHeaders['x-owner-session-token']
+    ? '/api/v1/agent/onboarding/register-with-wallet'
+    : '/api/v1/agent/onboarding/register-with-privy';
+  const response = await apiPost(ctx, route, payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_REGISTERED',
@@ -517,12 +553,13 @@ async function commandAgentRegister(ctx, flags, capabilities) {
 }
 
 async function commandAgentKeyRotate(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key rotate');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent key rotate: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {};
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/rotate', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/rotate', payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_KEY_ROTATED',
@@ -536,12 +573,13 @@ async function commandAgentKeyRotate(ctx, flags, capabilities) {
 }
 
 async function commandAgentKeyRevoke(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key revoke');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent key revoke: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {};
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/revoke', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/revoke', payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_KEY_REVOKED',
@@ -554,6 +592,407 @@ async function commandAgentKeyRevoke(ctx, flags, capabilities) {
   });
 }
 
+async function commandAgentAuthChallenge(ctx, flags, capabilities) {
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    chainId: Number(flags.chainId || 8453),
+  };
+  if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/challenge', payload);
+  printEnvelope({
+    success: true,
+    code: 'OWNER_CHALLENGE_CREATED',
+    message: 'Wallet challenge created',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandAgentAuthVerify(ctx, flags, capabilities) {
+  const payload = {
+    challengeId: requireFlag(flags, 'challengeId', 'Missing --challenge-id'),
+    signature: requireFlag(flags, 'signature', 'Missing --signature'),
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+  };
+  if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/verify', payload);
+  printEnvelope({
+    success: true,
+    code: 'OWNER_VERIFIED',
+    message: 'Wallet challenge verified',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+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'),
@@ -565,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) {
@@ -687,6 +1132,18 @@ function getAuthToken(flags, missingMessage) {
   return authToken;
 }
 
+function buildOwnerAuthHeaders(flags, missingMessage) {
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  const ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  if (!authToken && !ownerSessionToken) {
+    throw new Error(missingMessage);
+  }
+  if (authToken) {
+    return { Authorization: `Bearer ${authToken}` };
+  }
+  return { 'x-owner-session-token': ownerSessionToken };
+}
+
 function extractActions(response) {
   if (Array.isArray(response)) return response;
   if (Array.isArray(response.actions)) return response.actions;
@@ -787,24 +1244,37 @@ 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]
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
-  thirdfy-agent agent register --auth-token <token> --agent-key <key> --name <name> [--json]
-  thirdfy-agent agent key rotate --auth-token <token> [--agent-key <key>] [--json]
-  thirdfy-agent agent key revoke --auth-token <token> [--agent-key <key>] [--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 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 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>] [--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)
   --json             stable machine-readable output
   --verbose          print adapter diagnostics
   --version          print version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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,
   };
 }