@thirdfy/agent-cli 0.4.0 → 0.4.2

package/src/runtime/execution/runners/createExecutionRunners.mjs

@@ -0,0 +1,315 @@
+import { ACTION_PREFLIGHT_VENUE_FIELDS, isApiActionBlock } from '../actionPreflight.mjs';
+import { normalizeHybridWalletMode } from '../../../core/runMode.mjs';
+import { apiPost } from '../../../core/http.mjs';
+import { actionNameForApi } from '../../actions/selection.mjs';
+import { isReadOnlyAction } from './managedResponse.mjs';
+import { createFallbackHints } from './fallbackHints.mjs';
+import { createManagedPreflight } from './managedPreflight.mjs';
+import { createThirdfyLane } from './thirdfyLane.mjs';
+import { createSelfLane } from './selfLane.mjs';
+import { createAgentWalletLane } from './agentWalletLane.mjs';
+import { createHybridLane } from './hybridLane.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../../../utils/cli/intentNormalization.cjs');
+
+/** Execution runners: the preflight and the run for each run mode, wired from the lane files. */
+export function createExecutionRunners(deps) {
+  const {
+    buildIntentPayload,
+    shouldUseBuildTxPreflight,
+  } = deps;
+  const { applyExecutionFallbackHints } = createFallbackHints(deps);
+  const { shouldUseManagedReadFastPath, resolveManagedExecutionPreflight } = createManagedPreflight(deps);
+  const { executeThirdfyRun, runReadOnlyActionViaIntentRail } = createThirdfyLane(deps);
+  const { executeSelfRun, performSelfBroadcast, resolveEffectCheckResult, submitSignedTx } = createSelfLane(deps, { runReadOnlyActionViaIntentRail });
+  const { executeManagedWalletRun } = createAgentWalletLane(deps, { shouldUseManagedReadFastPath, resolveManagedExecutionPreflight, runReadOnlyActionViaIntentRail });
+  const { executeHybridRun } = createHybridLane(deps, { runReadOnlyActionViaIntentRail, executeManagedWalletRun, executeSelfRun });
+
+async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
+  const resolvedAction = resolved.resolvedAction;
+  if (runMode === 'agent_wallet') {
+    const preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
+      runMode,
+      // Reads carry no transaction; keep funding optional so preflight matches run.
+      requireFundingCheck: !isReadOnlyAction(resolved),
+      preflightSeed: options.managedPreflight,
+      // Ask the API to check policy and venue readiness for this action, not just the wallet.
+      evaluateAction: true,
+    });
+    const normalized = normalizeIntentResponse({
+      success: preflight.success,
+      status: preflight.success ? 'ready' : 'failed',
+      mode: 'agent_wallet',
+      executionWalletAddress: preflight.executionWalletAddress || null,
+      signerMethod: preflight.signerMethod || 'managed_wallet_server',
+      blockedReason: preflight.blockedReason || null,
+      blockedStage: preflight.blockedStage || null,
+      error: preflight.success ? null : preflight.error || 'Managed wallet preflight failed',
+      preflightBlocked: !preflight.success,
+      fundingTokenBalance: preflight.fundingTokenBalance || null,
+      executionWalletPreflight: preflight,
+    });
+    normalized.executionWalletAddress = preflight.executionWalletAddress || null;
+    normalized.signerMethod = preflight.signerMethod || 'managed_wallet_server';
+    normalized.executionWalletPreflight = preflight;
+    normalized.fundingTokenBalance = preflight.fundingTokenBalance || null;
+    normalized.policyEvaluated = preflight.policyEvaluated === true;
+    for (const key of [...ACTION_PREFLIGHT_VENUE_FIELDS, 'executionVenue']) {
+      if (preflight[key] != null) normalized[key] = preflight[key];
+    }
+    // Only an API refusal of the action is `blocked`; CLI-local checks keep `failed`.
+    const apiBlocked = isApiActionBlock(preflight);
+    if (apiBlocked) normalized.status = 'blocked';
+    return {
+      message: preflight.success
+        ? 'Managed wallet preflight completed'
+        : preflight.blockedStage === 'venue_readiness'
+          ? 'Managed wallet preflight blocked: venue not ready'
+          : apiBlocked
+            ? 'Managed wallet preflight blocked by policy'
+            : 'Managed wallet preflight failed',
+      route: 'execution_wallet_preflight',
+      normalized,
+    };
+  }
+  if (runMode === 'self') {
+    // Reads have no unsigned tx to prepare. Keep preflight on validation-only execute-intent so
+    // operators dry-running self mode do not trigger a real catalog read (run still uses the read rail).
+    if (isReadOnlyAction(resolved)) {
+      const payload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        apiAction: actionNameForApi(resolved),
+        runMode: 'self',
+        mirrorOnly: false,
+      });
+      const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', payload);
+      const normalized = normalizeIntentResponse(response);
+      const blockedCount = normalized.blocked || 0;
+      if (!normalized.success || blockedCount > 0) {
+        normalized.success = false;
+        normalized.error = normalized.error || 'Preflight blocked self execution';
+        normalized.preflightBlocked = true;
+      }
+      return {
+        message: normalized.success
+          ? 'Self preflight completed'
+          : normalized.preflightBlocked
+            ? 'Self preflight blocked by governance'
+            : 'Self preflight failed',
+        route: 'execute_intent_validation',
+        normalized,
+      };
+    }
+    const route = shouldUseBuildTxPreflight(runMode, resolved) ? 'build_tx' : 'execute_intent_validation';
+    const normalized = await executeSelfRun(
+      ctx,
+      flags,
+      resolved,
+      { skipPreflight: route === 'build_tx' }
+    );
+    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',
+      route,
+      normalized,
+    };
+  }
+  if (runMode === 'hybrid') {
+    // Reads have nothing to mirror and need no wallet. Keep preflight on validation-only
+    // execute-intent so dry-runs do not trigger a real catalog read (run still uses the read rail).
+    if (isReadOnlyAction(resolved)) {
+      const payload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        apiAction: actionNameForApi(resolved),
+        runMode: 'hybrid',
+        mirrorOnly: false,
+        hybridWalletMode: options.hybridWalletMode,
+      });
+      const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', payload);
+      const normalized = normalizeIntentResponse(response);
+      const blockedCount = normalized.blocked || 0;
+      if (!normalized.success || blockedCount > 0) {
+        normalized.success = false;
+        normalized.error = normalized.error || 'Preflight blocked hybrid execution';
+        normalized.preflightBlocked = true;
+      }
+      return {
+        message: normalized.success
+          ? 'Hybrid preflight completed'
+          : normalized.preflightBlocked
+            ? 'Hybrid preflight blocked by governance'
+            : 'Hybrid preflight failed',
+        route: 'execute_intent_validation',
+        normalized,
+      };
+    }
+    if (options.hybridWalletMode === 'agent_wallet') {
+      const managedPayload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        apiAction: actionNameForApi(resolved),
+        runMode: 'agent_wallet',
+        mirrorOnly: false,
+        hybridWalletMode: 'agent_wallet',
+      });
+      const managedResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', managedPayload);
+      const managedNormalized = normalizeIntentResponse(managedResponse);
+      const mirrorPayload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        apiAction: actionNameForApi(resolved),
+        runMode: 'hybrid',
+        mirrorOnly: true,
+        hybridWalletMode: 'agent_wallet',
+      });
+      const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/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,
+    resolvedAction,
+    apiAction: actionNameForApi(resolved),
+    runMode,
+    mirrorOnly: runMode === 'hybrid',
+  });
+  const response = await apiPost({ ...ctx, writeAction: false }, '/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',
+    route: 'execute_intent_validation',
+    normalized,
+  };
+}
+
+async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
+  if (runMode === 'thirdfy') {
+    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',
+      message: normalized.success
+        ? 'Execution intent queued'
+        : preflightBlocked
+          ? 'Preflight blocked execution'
+          : 'Execution failed',
+      idempotencyKey: normalized.idempotencyKey || null,
+      normalized,
+    };
+  }
+  if (runMode === 'agent_wallet') {
+    const normalized = await executeManagedWalletRun(ctx, flags, resolved, options);
+    const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    return {
+      code: normalized.success ? 'WALLET_EXECUTED' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
+      message: normalized.success
+        ? 'Managed wallet execution completed'
+        : preflightBlocked
+          ? 'Managed wallet preflight blocked execution'
+          : 'Managed wallet 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);
+    const readOnlySuccess =
+      normalized.success && normalized.routeFallback === 'execute_intent_read_only';
+    return {
+      code: normalized.success
+        ? readOnlySuccess
+          ? 'SELF_READ_COMPLETED'
+          : 'SELF_UNSIGNED_TX_READY'
+        : preflightBlocked
+          ? 'PREFLIGHT_BLOCKED'
+          : 'SELF_EXECUTION_FAILED',
+      message: normalized.success
+        ? readOnlySuccess
+          ? 'Read-only action completed via delegated execute-intent'
+          : '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);
+  const hybridWalletMode = normalizeHybridWalletMode(
+    normalized.hybridWalletMode || options?.hybridWalletMode || flags.hybridWalletMode || 'self',
+  );
+  const readOnlySuccess =
+    normalized.success && normalized.routeFallback === 'execute_intent_read_only';
+  return {
+    code: normalized.success
+      ? readOnlySuccess
+        ? 'HYBRID_READ_COMPLETED'
+        : 'HYBRID_READY'
+      : preflightBlocked
+        ? 'PREFLIGHT_BLOCKED'
+        : 'HYBRID_FAILED',
+    message: normalized.success
+      ? readOnlySuccess
+        ? 'Read-only action completed via delegated execute-intent'
+        : 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',
+    idempotencyKey: normalized.idempotencyKey || null,
+    normalized,
+  };
+}
+
+  return {
+    applyExecutionFallbackHints,
+    runPreflightByMode,
+    runExecutionByMode,
+    executeThirdfyRun,
+    executeManagedWalletRun,
+    executeSelfRun,
+    executeHybridRun,
+    resolveManagedExecutionPreflight,
+    performSelfBroadcast,
+    resolveEffectCheckResult,
+    submitSignedTx,
+  };
+}

package/src/runtime/execution/runners/fallbackHints.mjs

@@ -0,0 +1,54 @@
+/** Hints added to a failed execution answer (Bitfinex onboarding and similar next steps). */
+export function createFallbackHints(deps) {
+  const {
+    buildBitfinexOnboardingCommand,
+    inferBitfinexPermissionProfileFromAction,
+  } = deps;
+
+function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedAction }) {
+  if (!normalized || typeof normalized !== 'object') return normalized;
+  const next = { ...normalized };
+  const reasons = new Set();
+  const topBlockedReason = String(next.blockedReason || '').trim();
+  if (topBlockedReason) reasons.add(topBlockedReason);
+  const blockedByReason = next.blockedByReason && typeof next.blockedByReason === 'object' ? next.blockedByReason : {};
+  for (const key of Object.keys(blockedByReason)) {
+    if (String(key || '').trim()) reasons.add(String(key).trim());
+  }
+  const resolvedActionLower = String(resolvedAction || '').trim().toLowerCase();
+  const looksBitfinexAction = resolvedActionLower.includes('bitfinex');
+  const permissionProfile = inferBitfinexPermissionProfileFromAction(resolvedActionLower);
+  const cexCredentialMissingSignals = new Set([
+    'CEX_CREDENTIAL_NOT_FOUND',
+    'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+    'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
+    'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
+  ]);
+  const hasMissingCredentialSignal = Array.from(reasons).some((code) => cexCredentialMissingSignals.has(code));
+  if (looksBitfinexAction && hasMissingCredentialSignal) {
+    next.onboardingHint = {
+      type: 'bitfinex_credentials',
+      message:
+        'Bitfinex credentials are missing for this delegated account. Onboard credentials first, then retry the same command.',
+      command: buildBitfinexOnboardingCommand(permissionProfile),
+    };
+  }
+  if (
+    looksBitfinexAction &&
+    runMode !== 'thirdfy' &&
+    runMode !== 'agent_wallet' &&
+    (topBlockedReason === 'SELF_MODE_REQUIRES_BUILD_TX' || topBlockedReason === 'HYBRID_MODE_REQUIRES_BUILD_TX')
+  ) {
+    next.onboardingHint = {
+      ...(next.onboardingHint || {}),
+      runMode: 'thirdfy',
+      runModeMessage: 'Bitfinex actions require delegated execute-intent rail. Re-run with --run-mode thirdfy.',
+    };
+  }
+  return next;
+}
+
+  return {
+    applyExecutionFallbackHints,
+  };
+}

package/src/runtime/execution/runners/hybridLane.mjs

@@ -0,0 +1,88 @@
+import { normalizeHybridWalletMode } from '../../../core/runMode.mjs';
+import { apiPost } from '../../../core/http.mjs';
+import { actionNameForApi } from '../../actions/selection.mjs';
+import { isReadOnlyAction } from './managedResponse.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../../../utils/cli/intentNormalization.cjs');
+
+/** The hybrid lane: the managed wallet or self signing, per the hybrid wallet mode. */
+export function createHybridLane(deps, lanes) {
+  const {
+    buildIntentPayload,
+  } = deps;
+  const { runReadOnlyActionViaIntentRail, executeManagedWalletRun, executeSelfRun } = lanes;
+
+async function executeHybridRun(ctx, flags, resolved, options) {
+  const hybridWalletMode = normalizeHybridWalletMode(options?.hybridWalletMode || flags.hybridWalletMode || 'self');
+  // Reads have nothing to mirror and need no wallet, whichever hybrid wallet mode is selected.
+  // Answering from the read rail also keeps the payload at the top level, instead of nesting it under
+  // `managed` where callers that read `results` cannot find it.
+  if (isReadOnlyAction(resolved)) {
+    const readResult = await runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, null, 'hybrid');
+    readResult.hybridWalletMode = hybridWalletMode;
+    return readResult;
+  }
+  if (hybridWalletMode === 'agent_wallet') {
+    const managedResult = await executeManagedWalletRun(ctx, { ...flags, runMode: 'agent_wallet' }, resolved, options);
+    if (!managedResult.success) {
+      return normalizeIntentResponse({
+        ...managedResult,
+        mode: 'hybrid',
+        hybridWalletMode,
+      });
+    }
+    const mirrorPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: true,
+      resolvedAction: resolved.resolvedAction,
+      apiAction: actionNameForApi(resolved),
+      runMode: 'hybrid',
+      mirrorOnly: true,
+      hybridWalletMode,
+    });
+    const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/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',
+    blockedReasonCode: 'HYBRID_MODE_REQUIRES_BUILD_TX',
+  });
+  if (!selfResult.success) return selfResult;
+
+  const mirrorPayload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+    apiAction: actionNameForApi(resolved),
+    runMode: 'hybrid',
+    mirrorOnly: true,
+  });
+  const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', mirrorPayload);
+  const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+  return normalizeIntentResponse({
+    success: Boolean(selfResult.success && mirrorNormalized.success),
+    status: mirrorNormalized.status || 'ready',
+    mode: 'hybrid',
+    hybridWalletMode,
+    idempotencyKey: mirrorPayload.idempotencyKey,
+    self: selfResult,
+    mirror: mirrorNormalized,
+  });
+}
+
+  return {
+    executeHybridRun,
+  };
+}