@thirdfy/agent-cli 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.18] - 2026-04-21
+
+**npm:** [`@thirdfy/agent-cli@0.1.18`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.18)  
+**Git tag:** `v0.1.18`
+
+### Changed
+
+- **Command reference:** `delegation redeem` documents `--run-mode thirdfy|hybrid|agent_wallet` and clarifies `--hybrid-wallet-mode` for hybrid runs (release PR #16).
+
 ## [0.1.14] - 2026-04-19
 
 **npm:** [`@thirdfy/agent-cli@0.1.14`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.14)  

package/README.md

@@ -138,26 +138,30 @@ thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --challenge-id "
 
 ## Run modes and profiles
 
-`thirdfy-agent` supports one command surface with three run modes:
+`thirdfy-agent` supports one command surface with four 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`)
+- `--run-mode agent_wallet` -> managed wallet execution rail for Claude-friendly hosted execution
 
 | Goal | Recommended mode | Why |
 | --- | --- | --- |
 | BYOW signing and local custody | `self` | Keeps signing and broadcast on your wallet path. |
 | Managed delegated execution | `thirdfy` | Uses delegated governance rail for hosted execution. |
 | Self execution plus governance mirror checks | `hybrid` | Preserves local execution while emitting managed-lane mirrors. |
+| Managed wallet primary + governance mirror checks | `hybrid --hybrid-wallet-mode agent_wallet` | Uses managed wallet as primary hybrid path while still running Thirdfy mirror checks. |
 
 Auth expectations by mode:
 
 - `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
-- `hybrid`: requires execution identity and governed mirror semantics.
+- `hybrid`: requires execution identity and governed mirror semantics (`--hybrid-wallet-mode self|agent_wallet`, default `self`).
 - `thirdfy`: requires execution identity and delegated governance path.
+- `agent_wallet`: requires execution identity and delegated managed-wallet path.
 - custody mode defaults are profile-aware:
   - `managed` default for `thirdfy`
   - `external` default for `self` and `hybrid`
+  - `managed` default for `agent_wallet`
 
 Selection precedence:
 
@@ -192,6 +196,19 @@ thirdfy-agent run \
 
 The default `run --run-mode self` behavior is still unsigned-only (advanced users can sign externally).
 
+Hybrid managed-wallet variant (agent_wallet + Thirdfy mirror):
+
+```bash
+thirdfy-agent run \
+  --agent-api-key "$AGENT_API_KEY" \
+  --run-mode hybrid \
+  --hybrid-wallet-mode agent_wallet \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' \
+  --estimated-amount-usd 25 \
+  --json
+```
+
 Self lane effect-check controls:
 
 ```bash
@@ -273,7 +290,7 @@ Use `create` + `activate` as the default delegated execution lifecycle:
 
 ```bash
 thirdfy-agent delegation create \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --owner-address "0xOWNER_WALLET" \
   --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
@@ -282,7 +299,7 @@ thirdfy-agent delegation create \
 
 # Sign the returned `data.delegation` payload in your wallet, then:
 thirdfy-agent delegation activate \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --wallet-address "0xOWNER_WALLET" \
   --session-account-address "0xSESSION_ACCOUNT" \
@@ -292,25 +309,25 @@ thirdfy-agent delegation activate \
   --json
 
 thirdfy-agent delegation status \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --verify \
   --json
 
 thirdfy-agent delegation inspect \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --verify \
   --json
 
 thirdfy-agent delegation revoke \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --reason "user_revoked" \
   --json
 
 thirdfy-agent delegation balance \
-  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" \
   --agent-key "0xYOUR_AGENT_KEY" \
   --json
 
@@ -323,6 +340,8 @@ thirdfy-agent delegation redeem \
   --json
 ```
 
+`--auth-token "$THIRDFY_AUTH_TOKEN"` remains supported for all delegation commands, but owner-session token is preferred for least-privilege owner operations.
+
 ### MetaMask custodial-compatible lifecycle (new)
 
 ```bash

package/bin/thirdfy-agent.mjs

@@ -23,7 +23,8 @@ const BITFINEX_REQUIRED_SCOPE_PERMISSIONS = {
   funding: { read: 1, write: 1 },
   wallets: { read: 1, write: 1 },
 };
-const RUN_MODES = ['thirdfy', 'self', 'hybrid'];
+const RUN_MODES = ['thirdfy', 'self', 'hybrid', 'agent_wallet'];
+const HYBRID_WALLET_MODES = ['self', 'agent_wallet'];
 const CUSTODY_MODES = ['managed', 'external'];
 const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
 const PROFILE_DEFAULTS = {
@@ -157,6 +158,9 @@ async function main() {
     case 'managed run':
       await commandManagedRun(context, subFlags, capabilities);
       return;
+    case 'managed setup':
+      await commandManagedSetup(context, subFlags, capabilities);
+      return;
     case 'jeff trade':
       await commandRun(context, subFlags, capabilities);
       return;
@@ -549,8 +553,9 @@ async function commandPreflight(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   const runMode = getEffectiveRunMode(ctx, flags);
+  const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
-  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved);
+  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved, { hybridWalletMode });
   const normalized = applyExecutionFallbackHints(backendResult.normalized, {
     flags,
     runMode,
@@ -569,6 +574,7 @@ async function commandPreflight(ctx, flags, capabilities) {
       resolvedAction: resolved.resolvedAction,
       preflightRoute: backendResult.route,
       runMode,
+      hybridWalletMode,
       profile: ctx.profile || null,
       swapInput: flags.__swapInput || null,
       capabilitiesVersion: capabilities?.contractVersion || null,
@@ -581,10 +587,12 @@ async function commandRun(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   const runMode = getEffectiveRunMode(ctx, flags);
+  const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
   const skipPreflight = Boolean(flags.skipPreflight);
   const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
     skipPreflight,
+    hybridWalletMode,
   });
   const normalized = applyExecutionFallbackHints(backendResult.normalized, {
     flags,
@@ -622,6 +630,7 @@ async function commandRun(ctx, flags, capabilities) {
       resolvedAction: resolved.resolvedAction,
       idempotencyKey: backendResult.idempotencyKey || null,
       runMode,
+      hybridWalletMode,
       profile: ctx.profile || null,
       skippedPreflight: skipPreflight,
       swapInput: flags.__swapInput || null,
@@ -952,8 +961,8 @@ async function commandDelegationBalance(ctx, flags, capabilities) {
 
 async function commandDelegationRedeem(ctx, flags, capabilities) {
   const selectedRunMode = getEffectiveRunMode(ctx, flags);
-  if (!['thirdfy', 'hybrid'].includes(selectedRunMode)) {
-    throw createCliError('DELEGATION_REDEEM_MODE_INVALID', 'delegation redeem supports only --run-mode thirdfy|hybrid');
+  if (!['thirdfy', 'hybrid', 'agent_wallet'].includes(selectedRunMode)) {
+    throw createCliError('DELEGATION_REDEEM_MODE_INVALID', 'delegation redeem supports only --run-mode thirdfy|hybrid|agent_wallet');
   }
   const delegatedFlags = {
     ...flags,
@@ -1591,6 +1600,83 @@ async function commandManagedRun(ctx, flags, capabilities) {
   if (!normalized.success) 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);
+}
+
 async function commandProfileInit(ctx, flags) {
   const current = loadProfileConfig();
   const profile = normalizeProfileName(flags.profile || flags.name || 'personal');
@@ -1900,7 +1986,7 @@ function normalizeRunMode(value, flagName = '--run-mode') {
 }
 
 function defaultCustodyModeForRunMode(runMode) {
-  return runMode === 'thirdfy' ? 'managed' : 'external';
+  return runMode === 'thirdfy' || runMode === 'agent_wallet' ? 'managed' : 'external';
 }
 
 function normalizeCustodyMode(value, runModeHint = 'thirdfy') {
@@ -1914,11 +2000,17 @@ function normalizeCustodyMode(value, runModeHint = 'thirdfy') {
 function normalizeManagedRunMode(value) {
   const mode = normalizeRunMode(value || 'thirdfy');
   if (mode === 'self') {
-    throw new Error('Managed lane does not support run-mode=self. Use thirdfy or hybrid.');
+    throw new Error('Managed lane does not support run-mode=self. Use thirdfy, hybrid, or agent_wallet.');
   }
   return mode;
 }
 
+function normalizeHybridWalletMode(value) {
+  const normalized = String(value || '').trim().toLowerCase() || 'self';
+  if (HYBRID_WALLET_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported --hybrid-wallet-mode "${value}". Supported: ${HYBRID_WALLET_MODES.join(', ')}`);
+}
+
 function getProfileConfigPath() {
   return path.join(os.homedir(), '.thirdfy', 'config.json');
 }
@@ -2076,6 +2168,7 @@ function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedActio
   if (
     looksBitfinexAction &&
     runMode !== 'thirdfy' &&
+    runMode !== 'agent_wallet' &&
     (topBlockedReason === 'SELF_MODE_REQUIRES_BUILD_TX' || topBlockedReason === 'HYBRID_MODE_REQUIRES_BUILD_TX')
   ) {
     next.onboardingHint = {
@@ -2094,7 +2187,7 @@ function shouldUseBuildTxPreflight(runMode, resolved) {
   return meta.supportsExecuteIntent === false && meta.supportsBuildTx === true;
 }
 
-async function runPreflightByMode(runMode, ctx, flags, resolved) {
+async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
   const resolvedAction = resolved.resolvedAction;
   if (runMode === 'self') {
     const route = shouldUseBuildTxPreflight(runMode, resolved) ? 'build_tx' : 'execute_intent_validation';
@@ -2115,6 +2208,44 @@ async function runPreflightByMode(runMode, ctx, flags, resolved) {
       normalized,
     };
   }
+  if (runMode === 'hybrid' && options.hybridWalletMode === 'agent_wallet') {
+    const managedPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction,
+      runMode: 'agent_wallet',
+      mirrorOnly: false,
+      hybridWalletMode: 'agent_wallet',
+    });
+    const managedResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', managedPayload);
+    const managedNormalized = normalizeIntentResponse(managedResponse);
+    const mirrorPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction,
+      runMode: 'hybrid',
+      mirrorOnly: true,
+      hybridWalletMode: 'agent_wallet',
+    });
+    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+    const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+    return {
+      message:
+        managedNormalized.success && mirrorNormalized.success
+          ? 'Hybrid preflight completed (agent_wallet + thirdfy mirror)'
+          : 'Hybrid preflight failed (agent_wallet + thirdfy mirror)',
+      route: 'execute_intent_validation_dual',
+      normalized: normalizeIntentResponse({
+        success: Boolean(managedNormalized.success && mirrorNormalized.success),
+        status: mirrorNormalized.status || managedNormalized.status || 'failed',
+        mode: 'hybrid',
+        hybridWalletMode: 'agent_wallet',
+        managed: managedNormalized,
+        mirror: mirrorNormalized,
+        error: managedNormalized.error || mirrorNormalized.error || null,
+      }),
+    };
+  }
   const payload = buildIntentPayload(flags, {
     validationOnly: true,
     forceIdempotency: false,
@@ -2138,8 +2269,8 @@ async function runPreflightByMode(runMode, ctx, flags, resolved) {
 }
 
 async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
-  if (runMode === 'thirdfy') {
-    const normalized = await executeThirdfyRun(ctx, flags, resolved, options);
+  if (runMode === 'thirdfy' || runMode === 'agent_wallet') {
+    const normalized = await executeThirdfyRun(ctx, flags, resolved, options, runMode);
     const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
     return {
       code: normalized.success ? 'RUN_QUEUED' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
@@ -2172,10 +2303,15 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   }
   const normalized = await executeHybridRun(ctx, flags, resolved, options);
   const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+  const hybridWalletMode = normalizeHybridWalletMode(
+    normalized.hybridWalletMode || options?.hybridWalletMode || flags.hybridWalletMode || 'self',
+  );
   return {
     code: normalized.success ? 'HYBRID_READY' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'HYBRID_FAILED',
     message: normalized.success
-      ? 'Hybrid execution prepared (self tx + mirror preflight)'
+      ? hybridWalletMode === 'agent_wallet'
+        ? 'Hybrid execution prepared (agent wallet + mirror preflight)'
+        : 'Hybrid execution prepared (self tx + mirror preflight)'
       : preflightBlocked
         ? 'Preflight blocked hybrid execution'
         : 'Hybrid execution failed',
@@ -2184,15 +2320,16 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   };
 }
 
-async function executeThirdfyRun(ctx, flags, resolved, options) {
+async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'thirdfy') {
   const skipPreflight = Boolean(options?.skipPreflight);
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
       forceIdempotency: false,
       resolvedAction: resolved.resolvedAction,
-      runMode: 'thirdfy',
+      runMode,
       mirrorOnly: false,
+      hybridWalletMode: options?.hybridWalletMode,
     });
     const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
     const preflightNormalized = normalizeIntentResponse(preflight);
@@ -2208,8 +2345,9 @@ async function executeThirdfyRun(ctx, flags, resolved, options) {
     validationOnly: false,
     forceIdempotency: true,
     resolvedAction: resolved.resolvedAction,
-    runMode: 'thirdfy',
+    runMode,
     mirrorOnly: false,
+    hybridWalletMode: options?.hybridWalletMode,
   });
   const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
   const normalized = normalizeIntentResponse(response);
@@ -2261,6 +2399,36 @@ async function executeSelfRun(ctx, flags, resolved, options) {
 }
 
 async function executeHybridRun(ctx, flags, resolved, options) {
+  const hybridWalletMode = normalizeHybridWalletMode(options?.hybridWalletMode || flags.hybridWalletMode || 'self');
+  if (hybridWalletMode === 'agent_wallet') {
+    const managedResult = await executeThirdfyRun(ctx, flags, resolved, options, 'agent_wallet');
+    if (!managedResult.success) {
+      return normalizeIntentResponse({
+        ...managedResult,
+        mode: 'hybrid',
+        hybridWalletMode,
+      });
+    }
+    const mirrorPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: true,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'hybrid',
+      mirrorOnly: true,
+      hybridWalletMode,
+    });
+    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+    const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+    return normalizeIntentResponse({
+      success: Boolean(managedResult.success && mirrorNormalized.success),
+      status: managedResult.status || mirrorNormalized.status || 'queued',
+      mode: 'hybrid',
+      hybridWalletMode,
+      idempotencyKey: managedResult.idempotencyKey || mirrorPayload.idempotencyKey,
+      managed: managedResult,
+      mirror: mirrorNormalized,
+    });
+  }
   const selfResult = await executeSelfRun(ctx, flags, resolved, {
     ...(options || {}),
     runMode: 'hybrid',
@@ -2281,6 +2449,7 @@ async function executeHybridRun(ctx, flags, resolved, options) {
     success: Boolean(selfResult.success && mirrorNormalized.success),
     status: mirrorNormalized.status || 'ready',
     mode: 'hybrid',
+    hybridWalletMode,
     idempotencyKey: mirrorPayload.idempotencyKey,
     self: selfResult,
     mirror: mirrorNormalized,
@@ -2315,6 +2484,7 @@ function buildIntentPayload(flags, options) {
     payload.executionStrategy = {
       runMode: String(options.runMode),
       mirrorOnly: Boolean(options.mirrorOnly),
+      ...(options.hybridWalletMode ? { hybridWalletMode: String(options.hybridWalletMode) } : {}),
     };
   }
   if (options.forceIdempotency) {
@@ -2473,17 +2643,26 @@ function getAuthToken(flags, missingMessage) {
 
 function buildOwnerAuthHeaders(flags, missingMessage) {
   const config = loadProfileConfig();
-  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
-  const ownerSessionToken = String(
-    flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || config?.auth?.ownerSessionToken || ''
-  ).trim();
-  if (!authToken && !ownerSessionToken) {
-    throw new Error(missingMessage);
+  const explicitOwnerSessionToken = String(flags.ownerSessionToken || '').trim();
+  const explicitAuthToken = String(flags.authToken || '').trim();
+  const ownerSessionToken = String(process.env.THIRDFY_OWNER_SESSION_TOKEN || config?.auth?.ownerSessionToken || '').trim();
+  const authToken = String(process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+
+  // Prefer explicit flags first; then prefer owner-session over bearer from env/config
+  // to keep owner operations on least-privilege credentials by default.
+  if (explicitOwnerSessionToken) {
+    return { 'x-owner-session-token': explicitOwnerSessionToken };
+  }
+  if (explicitAuthToken) {
+    return { Authorization: `Bearer ${explicitAuthToken}` };
+  }
+  if (ownerSessionToken) {
+    return { 'x-owner-session-token': ownerSessionToken };
   }
   if (authToken) {
     return { Authorization: `Bearer ${authToken}` };
   }
-  return { 'x-owner-session-token': ownerSessionToken };
+  throw new Error(missingMessage);
 }
 
 function extractActions(response) {
@@ -2969,8 +3148,8 @@ function printHelp() {
 thirdfy-agent ${CLI_VERSION}
 
 Core commands:
-  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid] [--custody-mode managed|external] [--json]
-  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid] [--custody-mode managed|external] [--json]
+  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid|agent_wallet] [--custody-mode managed|external] [--json]
+  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid|agent_wallet] [--custody-mode managed|external] [--json]
   thirdfy-agent profile show [--json]
   thirdfy-agent config set --key <path> --value <value> [--json]
   thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--agent-key <key>] [--run-mode <mode>] [--custody-mode managed|external] [--wallet-address <addr>] [--json]
@@ -2978,19 +3157,20 @@ Core commands:
   thirdfy-agent whoami [--json]
   thirdfy-agent catalogs list [--json]
   thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
-  thirdfy-agent delegation create --auth-token <token> --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
+  thirdfy-agent delegation create [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
   thirdfy-agent delegation init-custodial [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
   thirdfy-agent delegation custodial-grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
-  thirdfy-agent delegation activate --auth-token <token> --agent-key <key> --wallet-address <addr> --session-account-address <addr> --delegation-manager <addr> --delegation <json> --signature <hex> [--json]
-  thirdfy-agent delegation status --auth-token <token> --agent-key <key> [--verify] [--json]
-  thirdfy-agent delegation show --auth-token <token> --agent-key <key> [--verify] [--json]
-  thirdfy-agent delegation inspect --auth-token <token> --agent-key <key> [--verify] [--json]
-  thirdfy-agent delegation balance --auth-token <token> --agent-key <key> [--chain-id <id>] [--json]
-  thirdfy-agent delegation revoke --auth-token <token> --agent-key <key> [--reason <text>] [--chain-id <id>] [--json]
-  thirdfy-agent delegation redeem --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--estimated-amount-usd <usd>] [--json]
+  thirdfy-agent delegation activate [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --wallet-address <addr> --session-account-address <addr> --delegation-manager <addr> --delegation <json> --signature <hex> [--json]
+  thirdfy-agent delegation status [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation show [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation inspect [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--verify] [--json]
+  thirdfy-agent delegation balance [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--chain-id <id>] [--json]
+  thirdfy-agent delegation revoke [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--reason <text>] [--chain-id <id>] [--json]
+  thirdfy-agent delegation redeem --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid|agent_wallet] [--estimated-amount-usd <usd>] [--json]
   thirdfy-agent managed wallet init [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
   thirdfy-agent managed wallet grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
-  thirdfy-agent managed run --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--idempotency-key <key>] [--json]
+  thirdfy-agent managed setup [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--run-mode thirdfy|hybrid|agent_wallet] [--token-address <addr>] [--max-usd-per-day <usd>] [--chain-id <id>] [--json]
+  thirdfy-agent managed run --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid|agent_wallet] [--idempotency-key <key>] [--json]
   thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--verify-permissions] [--skip-permissions-probe] [--bitfinex-base-url <url>] [--json]
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
   thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
@@ -3017,7 +3197,8 @@ Core commands:
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com
   --mcp-base <url>   default: https://mcp.thirdfy.com (bootstrap token issuance)
-  --run-mode <mode>  thirdfy | self | hybrid
+  --run-mode <mode>  thirdfy | self | hybrid | agent_wallet
+  --hybrid-wallet-mode <mode>  self | agent_wallet (only with --run-mode hybrid)
   --custody-mode <mode>  managed | external
   --profile <name>   personal | builder | network
   --env <file>       load env vars from file

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
-    "thirdfy-agent": "./bin/thirdfy-agent.mjs"
+    "thirdfy-agent": "bin/thirdfy-agent.mjs"
   },
   "files": [
     "bin/",

package/src/utils/cli/intentNormalization.cjs

@@ -57,6 +57,8 @@ function normalizeIntentResponse(response) {
     idempotencyKey: response?.idempotencyKey || null,
     mirror: response?.mirror || null,
     self: response?.self || null,
+    managed: response?.managed || null,
+    hybridWalletMode: response?.hybridWalletMode || null,
   };
 }