@thirdfy/agent-cli 0.4.0 → 0.4.2

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

@@ -0,0 +1,253 @@
+import { pickNativeGasFields } from '../nativeGas.mjs';
+import {
+  appendActionPreflightQuery,
+  blockedActionPreflight,
+  blockedActionPreflightFromError,
+  describeExecutionVenue,
+  pickActionPreflightFields,
+} from '../actionPreflight.mjs';
+import { parseBooleanFlag } from '../../../core/runMode.mjs';
+import { apiGet } from '../../../core/http.mjs';
+import { resolveWalletExecuteChainId } from '../../../core/execution/walletExecuteChainId.mjs';
+import {
+  describeInsufficientNativeGas,
+  isSvmChainId,
+  sameWalletAddress,
+} from '../../../core/chainRegistry.mjs';
+import { readWalletControl } from '../walletControl.mjs';
+import { actionNameForApi } from '../../actions/selection.mjs';
+import { blockedResultFields } from '../../../core/errorEnvelope.mjs';
+import { isReadOnlyAction } from './managedResponse.mjs';
+
+/** The agent_wallet preflight: the read fast path and the execution-wallet preflight. */
+export function createManagedPreflight(deps) {
+  const {
+    getPreparedParams,
+    resolveEffectiveUserDid,
+    resolveTokenInForFunding,
+    resolveAgentApiKey,
+    resolveAgentKey,
+  } = deps;
+
+const ROBINHOOD_MAINNET_CHAIN_ID = 4663;
+
+/**
+ * agent_wallet reads skip the /execution-wallet preflight: the API resolves the agent's execution
+ * wallet itself, so the extra round trip only matters when a read uses its answer: a strict wallet
+ * match, a funding check, or the Robinhood delegated lane. An expected wallet equal to the agent key
+ * is not a separate wallet to match first; the wallet the API reports is checked after the read.
+ * Mirrors thirdfy-mcp `walletExecute` readFastPath.
+ */
+function shouldUseManagedReadFastPath(flags, resolved, options = {}) {
+  if (!isReadOnlyAction(resolved)) return false;
+  if (options.requireFundingCheck === true) return false;
+  const runMode = String(flags.runMode || 'agent_wallet').trim().toLowerCase();
+  if (runMode !== 'agent_wallet') return false;
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
+  const agentKey = String(typeof resolveAgentKey === 'function' ? resolveAgentKey(flags) : flags.agentKey || '').trim();
+  if (expectedWallet && !sameWalletAddress(expectedWallet, agentKey)) return false;
+  let chainId;
+  try {
+    chainId = resolveWalletExecuteChainId({
+      action: String(resolved?.resolvedAction || flags.action || '').trim(),
+      chainId: flags.chainId,
+      params: getPreparedParams(flags),
+    });
+  } catch {
+    // Unresolvable chain (e.g. a CCTP quote without sourceChainId): the preflight path reports it.
+    return false;
+  }
+  return Number(chainId) !== ROBINHOOD_MAINNET_CHAIN_ID;
+}
+
+async function resolveManagedExecutionPreflight(ctx, flags, resolved, options = {}) {
+  const action = String(resolved?.resolvedAction || flags.action || '').trim();
+  const params = getPreparedParams(flags);
+  const chainId = resolveWalletExecuteChainId({
+    action,
+    chainId: flags.chainId,
+    params,
+  });
+  const runMode = String(options.runMode || 'agent_wallet').trim().toLowerCase();
+  const agentApiKey = resolveAgentApiKey(flags, runMode);
+  const userDid = resolveEffectiveUserDid(flags, {
+    runMode,
+    hybridWalletMode: options.hybridWalletMode,
+    preferDelegationIdentity: options.preferDelegationIdentity,
+  });
+  if (!userDid) {
+    return {
+      success: false,
+      blockedReason: 'MISSING_USER_DID',
+      blockedStage: 'routing',
+      error:
+        runMode === 'agent_wallet'
+          ? 'Solo agent_wallet requires --agent-key, THIRDFY_AGENT_KEY, config.agent.agentKey, or --user-did did:wallet:<agentKey>. Subscriber Privy DIDs require delegation; use did:wallet for direct agent execution.'
+          : 'Managed wallet execution requires --user-did, THIRDFY_USER_DID, or a saved userDid from `thirdfy-agent login email`.',
+      signerMethod: 'managed_wallet_server',
+    };
+  }
+  const tokenIn = resolveTokenInForFunding(params, action, resolved?.resolvedActionMeta?.behavior?.spend);
+  const query = new URLSearchParams({
+    userDid,
+    chainId: String(chainId),
+    runMode,
+  });
+  if (tokenIn) query.set('tokenIn', tokenIn);
+  const evaluateAction = options.evaluateAction === true;
+  if (evaluateAction) appendActionPreflightQuery(query, { action, apiAction: actionNameForApi(resolved), params, flags });
+  const executionVenue = describeExecutionVenue(action, chainId);
+  const preflightSeed = options.preflightSeed && typeof options.preflightSeed === 'object'
+    ? options.preflightSeed
+    : null;
+  if (preflightSeed && preflightSeed.success === false) {
+    return preflightSeed;
+  }
+  // A seed (address default lookup) carries no policy answer; an action preflight asks the API again.
+  const useSeed = Boolean(preflightSeed) && !evaluateAction;
+  let response;
+  if (useSeed) {
+    response = {
+      executionWalletAddress: preflightSeed.executionWalletAddress || null,
+      signerMethod: preflightSeed.signerMethod || null,
+      fundingTokenBalance: preflightSeed.fundingTokenBalance || null,
+      ...pickNativeGasFields(preflightSeed),
+    };
+  } else {
+    try {
+      response = await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
+        'x-agent-api-key': agentApiKey,
+      });
+    } catch (error) {
+      const blocked = evaluateAction ? blockedActionPreflightFromError(error) : null;
+      if (!blocked) throw error;
+      return {
+        ...blocked,
+        userDid,
+        chainId,
+        ...(executionVenue ? { executionVenue } : {}),
+      };
+    }
+  }
+  // An action preflight the API answered 2xx but refused is a block too (thirdfy-mcp previewOrder).
+  if (evaluateAction && response?.success === false) {
+    return {
+      ...blockedActionPreflight(response, {
+        errorFields: blockedResultFields(String(response.blockedReason || 'PREFLIGHT_BLOCKED')),
+      }),
+      userDid,
+      chainId,
+      ...(executionVenue ? { executionVenue } : {}),
+    };
+  }
+  const actionFields = evaluateAction ? pickActionPreflightFields(response) : {};
+  // API 4.0 wallet control, as thirdfy-mcp reports it: the API refuses writes itself (before
+  // signing), so preflight only reports it. Solana is exempt from the API's gate.
+  const walletControlFields = readWalletControl(response, { svm: isSvmChainId(chainId) });
+  // Keep the API's case: Solana base58 addresses are case-sensitive (lowercasing corrupts them).
+  const executionWalletAddress = String(response?.executionWalletAddress || '').trim();
+  const signerMethod = String(response?.signerMethod || 'managed_wallet_server').trim();
+  const rawBalance = String(response?.fundingTokenBalance?.raw || '').trim();
+  let parsedRawBalance = null;
+  if (rawBalance) {
+    try {
+      parsedRawBalance = BigInt(rawBalance);
+    } catch {
+      // Reads pass requireFundingCheck: false; a malformed balance must not block them.
+      // Writes still fail closed on unparseable fundingTokenBalance.raw.
+      if (options.requireFundingCheck) {
+        return {
+          success: false,
+          blockedReason: 'INVALID_FUNDING_BALANCE',
+          blockedStage: 'sizing',
+          error: `Execution wallet ${executionWalletAddress || 'unknown'} returned invalid funding token balance.`,
+          executionWalletAddress,
+          signerMethod,
+          fundingTokenBalance: response?.fundingTokenBalance || null,
+          ...actionFields,
+          ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
+        };
+      }
+    }
+  }
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
+  const allowWalletMismatch = parseBooleanFlag(flags.allowWalletMismatch, false);
+
+  if (
+    expectedWallet
+    && executionWalletAddress
+    && !sameWalletAddress(expectedWallet, executionWalletAddress)
+    && !allowWalletMismatch
+  ) {
+    return {
+      success: false,
+      blockedReason: 'EXECUTION_WALLET_MISMATCH',
+      ...blockedResultFields('EXECUTION_WALLET_MISMATCH'),
+      blockedStage: 'routing',
+      error: `Funded wallet (${expectedWallet}) does not match execution wallet (${executionWalletAddress}). Use --allow-wallet-mismatch to override.`,
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
+    };
+  }
+
+  if (options.requireFundingCheck && parsedRawBalance !== null && parsedRawBalance <= 0n) {
+    return {
+      success: false,
+      blockedReason: 'INSUFFICIENT_FUNDS',
+      ...blockedResultFields('INSUFFICIENT_FUNDS'),
+      blockedStage: 'sizing',
+      error: `Execution wallet ${executionWalletAddress || 'unknown'} has insufficient tokenIn balance.`,
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
+    };
+  }
+
+  // User-pays-gas chains (DogeOS, Solana): the API reports native gas readiness (API 3.18.2+). Keep
+  // it, and stop a write before /execute when the API says the wallet cannot pay gas (gasReady false).
+  const nativeGas = pickNativeGasFields(response);
+  if (options.requireFundingCheck && nativeGas.gasReady === false) {
+    return {
+      success: false,
+      blockedReason: 'INSUFFICIENT_NATIVE_GAS',
+      ...blockedResultFields('INSUFFICIENT_NATIVE_GAS'),
+      blockedStage: 'sizing',
+      error: nativeGas.nativeGasWarning?.message || describeInsufficientNativeGas(executionWalletAddress, chainId),
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
+      ...nativeGas,
+    };
+  }
+
+  return {
+    success: true,
+    executionWalletAddress,
+    signerMethod,
+    fundingTokenBalance: response?.fundingTokenBalance || null,
+    userDid,
+    chainId,
+    tokenIn: tokenIn || null,
+    ...nativeGas,
+    ...actionFields,
+    ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
+  };
+}
+
+  return {
+    shouldUseManagedReadFastPath,
+    resolveManagedExecutionPreflight,
+  };
+}

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

@@ -0,0 +1,119 @@
+import { parseBooleanFlag } from '../../../core/runMode.mjs';
+import { responseHeadersFor } from '../../../core/http.mjs';
+import { idempotentReplayFields } from '../../../core/execution/hostedRuntimeIdempotency.mjs';
+import { isReadOnlyResolvedAction } from '../../../core/execution/readOnlyActions.mjs';
+import { sameWalletAddress } from '../../../core/chainRegistry.mjs';
+import { riskRefusalFields } from '../../risk/riskRefusal.mjs';
+import { shouldFallbackManagedReadToExecuteIntent } from '../managedReadExecuteRail.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../../../utils/cli/intentNormalization.cjs');
+
+/** Managed (agent_wallet) execute answers: the read-only check, read-response shaping, and the read fast-path marker and wallet check. */
+
+export function isReadOnlyAction(resolved) {
+  return isReadOnlyResolvedAction(resolved);
+}
+
+export function shouldFallbackAgentWalletToExecuteIntent(resolved, response) {
+  return shouldFallbackManagedReadToExecuteIntent({
+    isReadOnly: isReadOnlyAction(resolved),
+    errorText: String(response?.error || response?.message || response?.code || response?.blockedReason || ''),
+  });
+}
+
+// Managed /execute often returns provider payloads as JSON strings under data.result. Pack parsers
+// (and find_value_by_key) need a real object tree, so coerce strings that look like JSON.
+export function coerceJsonTreeValue(value) {
+  if (typeof value !== 'string') return value;
+  const trimmed = value.trim();
+  if (!trimmed || (trimmed[0] !== '{' && trimmed[0] !== '[')) return value;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+export function shapeManagedExecuteReadResponse(response) {
+  if (!response || typeof response !== 'object') return response;
+  const data =
+    response.data && typeof response.data === 'object' ? { ...response.data } : response.data;
+  if (data && typeof data === 'object' && Object.prototype.hasOwnProperty.call(data, 'result')) {
+    data.result = coerceJsonTreeValue(data.result);
+  }
+  return { ...response, data };
+}
+
+export function normalizeManagedExecuteResponse(response, { preflight, payload, isRead }) {
+  const shaped = isRead ? shapeManagedExecuteReadResponse(response) : response;
+  const normalized = normalizeIntentResponse({
+    success: Boolean(shaped?.success),
+    status: shaped?.success ? 'completed' : 'failed',
+    mode: 'agent_wallet',
+    txHash: shaped?.txHash || null,
+    blockedReason: shaped?.blockedReason || shaped?.data?.blockedReason || null,
+    blockedStage: shaped?.blockedStage || shaped?.data?.blockedStage || null,
+    error: shaped?.error || null,
+    executionWalletAddress:
+      shaped?.executionWalletAddress || shaped?.data?.executionWalletAddress || null,
+    signerMethod: 'managed_wallet_server',
+    idempotencyKey: payload.executionIdempotencyKey || null,
+    executionWalletPreflight: preflight,
+    amountNormalization:
+      shaped?.amountNormalization || shaped?.data?.amountNormalization || null,
+    // Reads must keep provider payload on the envelope. EarnClaw packs parse
+    // data.raw.data.result (see parse_thirdfy_action_result).
+    ...(isRead && shaped?.data !== undefined ? { data: shaped.data } : {}),
+    raw: shaped,
+  });
+  normalized.executionWalletAddress =
+    shaped?.executionWalletAddress || shaped?.data?.executionWalletAddress || null;
+  normalized.signerMethod = 'managed_wallet_server';
+  normalized.executionWalletPreflight = preflight;
+  normalized.amountNormalization =
+    shaped?.amountNormalization || shaped?.data?.amountNormalization || null;
+  normalized.raw = shaped;
+  normalized.idempotencyKey = payload.executionIdempotencyKey || null;
+  // A risk-policy refusal nests riskRefusal under data; lift it as thirdfy-mcp walletExecute does.
+  const refusal = shaped?.success ? undefined : riskRefusalFields(shaped || {});
+  if (refusal) Object.assign(normalized, refusal);
+  // A replay means nothing new ran; say so, or the caller reads it as a fresh fill.
+  if (!isRead) {
+    Object.assign(
+      normalized,
+      idempotentReplayFields(response, responseHeadersFor(response), 'executionIdempotencyKey'),
+    );
+  }
+  return normalized;
+}
+
+/** Marker a read on the fast path carries instead of an execution-wallet preflight. */
+export const READ_FAST_PATH_PREFLIGHT = Object.freeze({ success: true, skipped: 'read_fast_path' });
+
+/**
+ * The fast path only runs when the expected wallet is empty or equals the agent key. The preflight
+ * path refuses a wallet that differs from the execution wallet, so apply the same rule to the wallet
+ * the API reports for the read.
+ */
+export function fastPathWalletMismatch(flags, response) {
+  // 0x addresses compare case-insensitively; Solana base58 is case-sensitive and kept as sent.
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
+  if (!expectedWallet || parseBooleanFlag(flags.allowWalletMismatch, false)) return null;
+  const apiWallet = String(response?.executionWalletAddress || response?.data?.executionWalletAddress || '').trim();
+  if (!apiWallet || sameWalletAddress(apiWallet, expectedWallet)) return null;
+  const normalized = normalizeIntentResponse({
+    success: false,
+    status: 'failed',
+    mode: 'agent_wallet',
+    blockedReason: 'EXECUTION_WALLET_MISMATCH',
+    blockedStage: 'routing',
+    error: `Funded wallet (${expectedWallet}) does not match execution wallet (${apiWallet}). Use --allow-wallet-mismatch to override.`,
+    preflightBlocked: true,
+    executionWalletAddress: apiWallet,
+  });
+  normalized.executionWalletAddress = apiWallet;
+  normalized.executionWalletPreflight = READ_FAST_PATH_PREFLIGHT;
+  return normalized;
+}

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

@@ -0,0 +1,232 @@
+import { createCliError } from '../../../core/envelope.mjs';
+import { normalizeEffectCheckMode } from '../../../core/runMode.mjs';
+import { apiPost } from '../../../core/http.mjs';
+import { resolveChainRpcUrl } from '../../../core/chainRegistry.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 self lane: build the transaction, sign and broadcast locally, then check its effect. */
+export function createSelfLane(deps, lanes) {
+  const {
+    buildIntentPayload,
+    buildBuildTxPayload,
+    getPreparedParams,
+    shouldUseBuildTxExecution,
+    loadEthers,
+    signAndBroadcastWithOws,
+    readEffectBalances,
+    resolveUnsignedTx,
+    sleepMs,
+  } = deps;
+  const { runReadOnlyActionViaIntentRail } = lanes;
+
+async function executeSelfRun(ctx, flags, resolved, options) {
+  const skipPreflight = Boolean(options?.skipPreflight);
+  const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
+  // A read has no transaction to build or sign, so the self lane has nothing to do with it. Without
+  // this it either fails with SELF_MODE_REQUIRES_BUILD_TX or, when catalog metadata is missing, asks
+  // /build-tx to produce a transaction for a market-data query.
+  if (isReadOnlyAction(resolved)) {
+    return runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, null, options?.runMode || 'self');
+  }
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+      apiAction: actionNameForApi(resolved),
+      runMode: 'self',
+      mirrorOnly: false,
+    });
+    const preflight = await apiPost({ ...ctx, writeAction: false }, '/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;
+    }
+  }
+  if (!shouldUseBuildTxExecution(options?.runMode || 'self', resolved)) {
+    const normalized = normalizeIntentResponse({
+      success: false,
+      status: 'failed',
+      blockedReason: blockedReasonCode,
+      blockedStage: 'routing',
+      error: 'Selected action does not support build-tx self lane. Use --run-mode thirdfy for delegated CEX execution.',
+    });
+    normalized.preflightBlocked = true;
+    return normalized;
+  }
+  const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction, actionNameForApi(resolved));
+  // build-tx returns an unsigned transaction; nothing is broadcast, so a timeout may be resent.
+  const buildTx = await apiPost({ ...ctx, writeAction: false }, '/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 performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
+  const txd = resolveUnsignedTx(selfResult);
+  if (!txd?.to || !txd?.data) {
+    throw createCliError('SELF_UNSIGNED_TX_MISSING', 'Self execution did not return a valid unsigned transaction');
+  }
+  const chainId = Number(txd.chainId || flags.chainId || 8453);
+  const walletAddress = String(flags.walletAddress || process.env.MARKET_MAKER_WALLET_ADDRESS || '').trim();
+  const owsWalletName = String(flags.owsWalletName || process.env.OWS_WALLET_NAME || '').trim();
+  const rpcUrl = resolveChainRpcUrl({ chainId, rpcUrl: flags.rpcUrl });
+  if (!rpcUrl) {
+    throw createCliError('RPC_URL_REQUIRED', `self-exec has no known RPC for chain ${chainId}; pass --rpc-url <url> for that chain`);
+  }
+  if (!walletAddress) {
+    throw createCliError('SIGNING_FAILED', 'Missing --wallet-address (or MARKET_MAKER_WALLET_ADDRESS) for self-exec signing.');
+  }
+  if (!owsWalletName) {
+    throw createCliError('SIGNING_FAILED', 'Missing --ows-wallet-name (or OWS_WALLET_NAME) for self-exec signing.');
+  }
+
+  const params = getPreparedParams(flags);
+  const effectTokenIn = String(flags.effectTokenIn || params.tokenIn || '').trim();
+  const effectTokenOut = String(flags.effectTokenOut || params.tokenOut || '').trim();
+  const effectMode = normalizeEffectCheckMode(flags.effectCheck || process.env.THIRDFY_EFFECT_CHECK || 'relaxed');
+  const effectRetries = Number(flags.effectCheckRetries || process.env.THIRDFY_EFFECT_CHECK_RETRIES || 2);
+  const effectWaitMs = Number(flags.effectCheckWaitMs || process.env.THIRDFY_EFFECT_CHECK_WAIT_MS || 1200);
+
+  let balancesBefore = null;
+  if (effectMode !== 'off' && effectTokenIn && effectTokenOut) {
+    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
+  }
+
+  let submission;
+  try {
+    submission = await signAndBroadcastWithOws({
+      txd,
+      chainId,
+      walletAddress,
+      owsWalletName,
+      rpcUrl,
+    });
+  } catch (error) {
+    throw createCliError('SIGNING_FAILED', error?.message || 'OWS signing failed');
+  }
+
+  let receipt;
+  try {
+    receipt = await submission.sent.wait();
+  } catch (error) {
+    throw createCliError('BROADCAST_FAILED', error?.message || 'Broadcast wait failed');
+  }
+  const status = Number(receipt?.status ?? 0);
+  if (status !== 1) {
+    throw createCliError('BROADCAST_FAILED', 'Transaction receipt status is not success', {
+      receiptStatus: receipt?.status ?? null,
+      txHash: submission.sent.hash,
+    });
+  }
+
+  const effectCheck = await resolveEffectCheckResult({
+    mode: effectMode,
+    rpcUrl,
+    walletAddress,
+    tokenIn: effectTokenIn,
+    tokenOut: effectTokenOut,
+    balancesBefore,
+    retries: effectRetries,
+    waitMs: effectWaitMs,
+  });
+  if (effectCheck.checked && !effectCheck.hasEffect && effectMode === 'strict') {
+    throw createCliError('EFFECT_CHECK_FAILED', 'Transaction mined but did not produce observable token effect.', {
+      txHash: submission.sent.hash,
+      effectCheck,
+      mode: effectMode,
+    });
+  }
+
+  return {
+    txHash: submission.sent.hash,
+    chainId,
+    blockNumber: receipt?.blockNumber ?? null,
+    status: receipt?.status ?? null,
+    unsignedTx: txd,
+    effectCheck,
+    lane: 'self',
+    signer: 'ows',
+    resolvedAction,
+    apiBase: ctx.apiBase,
+  };
+}
+
+async function resolveEffectCheckResult({
+  mode,
+  rpcUrl,
+  walletAddress,
+  tokenIn,
+  tokenOut,
+  balancesBefore,
+  retries,
+  waitMs,
+}) {
+  const baseResult = {
+    checked: true,
+    mode,
+    hasEffect: false,
+    inDeltaRaw: '0',
+    outDeltaRaw: '0',
+    attempts: 0,
+    retries: Math.max(0, Number(retries || 0)),
+  };
+  if (mode === 'off') {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'disabled' };
+  }
+  if (!tokenIn || !tokenOut || !balancesBefore) {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'token_pair_missing' };
+  }
+  const maxAttempts = Math.max(1, Number(retries || 0) + 1);
+  let last = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut);
+    const inDeltaRaw = (BigInt(balancesBefore.tokenIn) - BigInt(balancesAfter.tokenIn)).toString();
+    const outDeltaRaw = (BigInt(balancesAfter.tokenOut) - BigInt(balancesBefore.tokenOut)).toString();
+    const hasEffect = BigInt(inDeltaRaw) > 0n || BigInt(outDeltaRaw) > 0n;
+    last = {
+      checked: true,
+      mode,
+      hasEffect,
+      inDeltaRaw,
+      outDeltaRaw,
+      attempts: attempt,
+      retries: maxAttempts - 1,
+    };
+    if (hasEffect) return last;
+    if (attempt < maxAttempts) await sleepMs(waitMs);
+  }
+  return {
+    ...(last || baseResult),
+    warning: 'No balance delta observed after retries; treating as non-fatal in relaxed mode.',
+  };
+}
+
+async function submitSignedTx({ rpcUrl, chainId, signedTxHex }) {
+  const ethers = await loadEthers();
+  const { JsonRpcProvider } = ethers;
+  const provider = new JsonRpcProvider(rpcUrl, chainId);
+  const sent = await provider.broadcastTransaction(String(signedTxHex));
+  return sent?.hash || null;
+}
+
+  return {
+    executeSelfRun,
+    performSelfBroadcast,
+    resolveEffectCheckResult,
+    submitSignedTx,
+  };
+}