@thirdfy/agent-cli 0.2.34 → 0.2.35

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.35] - 2026-07-25
+
+### Fixed
+
+- Read-only detection now matches the Thirdfy API action manifest instead of a narrower client-side guess. `fetch_*`, `show_*`, `dogeos_get_*`, `*_info`, `dogeos_barkswap_get_quote`, `dogeos_laika_read_contract`, and `dogeos_laika_token_state` were previously classified as writes, so under `--run-mode agent_wallet` they went to the execute rail and came back as execution envelopes rather than data. A test now pins the two lists together so they cannot drift apart again.
+- `--run-mode self` and `--run-mode hybrid` serve read-only actions from the read rail. Previously a read under `self` either failed with `SELF_MODE_REQUIRES_BUILD_TX` or, when catalog metadata was missing, asked `/api/v1/agent/build-tx` to build a transaction for a market-data query. Under `hybrid` the payload was nested beneath `managed`, where callers reading `results` could not find it, and a mirror failure could mark a successful read as failed.
+- `normalizeIntentResponse` no longer drops top-level `data` and `raw`. It is a whitelist, and read responses carry their payload in `data`, so a caller could receive a well-formed envelope with nothing in it.
+
+### Changed
+
+- Bitfinex reads under `--run-mode hybrid` are served from the delegated rail instead of returning `HYBRID_MODE_REQUIRES_BUILD_TX` with a hint to rerun using `--run-mode thirdfy`. The guard still applies to Bitfinex writes.
+
 ## [0.2.34] - 2026-07-25
 
 ### Fixed

package/README.md

@@ -40,10 +40,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.34
+## What's new in v0.2.35
 
-- Read-only actions (`get_*`, `list_*`, `search_*`) requested with `--run-mode agent_wallet` now return the provider payload directly instead of an execution envelope. Market data reads such as `get_hyperliquid_perps_meta` no longer come back wrapped as an intent.
-- Reads are no longer gated on execution-wallet funding. The execution address is still reported, but an unfunded wallet does not block a read. Routing and identity checks still apply.
+- Read-only actions return the provider payload directly in every run mode. Market data reads such as `get_hyperliquid_perps_meta` no longer come back wrapped as an execution intent, and `--run-mode self` no longer refuses them.
+- Read detection now matches the Thirdfy action catalog, so `fetch_*`, `show_*`, `dogeos_get_*`, and `*_info` actions are recognized as reads.
+- Reads are not gated on execution-wallet funding. The execution address is still reported, but an unfunded wallet does not block a read. Routing and identity checks still apply.
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 

package/package.json

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

package/src/core/readOnlyActions.mjs

@@ -0,0 +1,46 @@
+/**
+ * Read-only action classification.
+ *
+ * This mirrors `isReadOnlyAction` in the Thirdfy API
+ * (`src/services/agents/execution/catalog/actionContractManifest.ts`). Keep the two in sync: when the
+ * client and the server disagree about what counts as a read, reads get sent to the managed-wallet
+ * execute rail and come back shaped as an execution envelope instead of provider data.
+ */
+
+const READ_ONLY_PREFIXES = ['get_', 'list_', 'fetch_', 'search_', 'show_', 'dogeos_get_'];
+
+const READ_ONLY_EXACT = new Set([
+  'dogeos_barkswap_get_quote',
+  'dogeos_laika_read_contract',
+  'dogeos_laika_token_state',
+]);
+
+export function normalizeActionKey(actionKey) {
+  return String(actionKey || '')
+    .trim()
+    .toLowerCase()
+    .replace(/-/g, '_');
+}
+
+export function isReadOnlyActionName(actionKey) {
+  const key = normalizeActionKey(actionKey);
+  if (!key) return false;
+  if (READ_ONLY_EXACT.has(key)) return true;
+  if (key.endsWith('_info')) return true;
+  return READ_ONLY_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+/**
+ * Catalog metadata can mark an action read-only even when the name does not match. Production
+ * defaults set `supportsExecute: true` on nearly everything, so this rarely fires on its own.
+ */
+export function isReadOnlyActionMeta(meta) {
+  if (!meta || typeof meta !== 'object') return false;
+  return meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
+}
+
+export function isReadOnlyResolvedAction(resolved, options = {}) {
+  const meta = resolved?.resolvedActionMeta;
+  if (options.requireMeta && (!meta || typeof meta !== 'object')) return false;
+  return isReadOnlyActionName(resolved?.resolvedAction) || isReadOnlyActionMeta(meta);
+}

package/src/runtime/execution/runners.mjs

@@ -11,6 +11,7 @@ import {
 } from '../../core/runMode.mjs';
 import { apiGet, apiPost } from '../../core/http.mjs';
 import { withActionTimeout } from '../../core/actionTimeouts.mjs';
+import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -80,15 +81,7 @@ function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedActio
 }
 
 function isReadOnlyAction(resolved) {
-  const meta = resolved?.resolvedActionMeta || {};
-  const action = String(resolved?.resolvedAction || '')
-    .trim()
-    .toLowerCase()
-    .replace(/-/g, '_');
-  const readOnlyByName =
-    action.startsWith('get_') || action.startsWith('search_') || action.startsWith('list_');
-  const readOnlyByMeta = meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
-  return readOnlyByName || readOnlyByMeta;
+  return isReadOnlyResolvedAction(resolved);
 }
 
 // Reads carry no transaction, so wallet balance never blocks them. Every other preflight failure
@@ -139,6 +132,34 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     };
   }
   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,
+        runMode: 'self',
+        mirrorOnly: false,
+      });
+      const response = await apiPost(ctx, '/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,
@@ -157,43 +178,74 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
       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',
+  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,
+        runMode: 'hybrid',
+        mirrorOnly: false,
+        hybridWalletMode: options.hybridWalletMode,
+      });
+      const response = await apiPost(ctx, '/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,
+        runMode: 'agent_wallet',
+        mirrorOnly: false,
         hybridWalletMode: 'agent_wallet',
-        managed: managedNormalized,
-        mirror: mirrorNormalized,
-        error: managedNormalized.error || mirrorNormalized.error || null,
-      }),
-    };
+      });
+      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,
@@ -249,14 +301,20 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   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
-        ? 'SELF_UNSIGNED_TX_READY'
+        ? readOnlySuccess
+          ? 'SELF_READ_COMPLETED'
+          : 'SELF_UNSIGNED_TX_READY'
         : preflightBlocked
           ? 'PREFLIGHT_BLOCKED'
           : 'SELF_EXECUTION_FAILED',
       message: normalized.success
-        ? 'Unsigned transaction prepared for self-custody execution'
+        ? 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',
@@ -269,12 +327,22 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   const hybridWalletMode = normalizeHybridWalletMode(
     normalized.hybridWalletMode || options?.hybridWalletMode || flags.hybridWalletMode || 'self',
   );
+  const readOnlySuccess =
+    normalized.success && normalized.routeFallback === 'execute_intent_read_only';
   return {
-    code: normalized.success ? 'HYBRID_READY' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'HYBRID_FAILED',
+    code: normalized.success
+      ? readOnlySuccess
+        ? 'HYBRID_READ_COMPLETED'
+        : 'HYBRID_READY'
+      : preflightBlocked
+        ? 'PREFLIGHT_BLOCKED'
+        : 'HYBRID_FAILED',
     message: normalized.success
-      ? hybridWalletMode === 'agent_wallet'
-        ? 'Hybrid execution prepared (agent wallet + mirror preflight)'
-        : 'Hybrid execution prepared (self tx + mirror preflight)'
+      ? 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',
@@ -319,7 +387,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
   return normalized;
 }
 
-async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, preflight) {
+async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, preflight, reportedMode = 'agent_wallet') {
   const userDid = resolveEffectiveUserDid(flags, {
     runMode: 'agent_wallet',
     hybridWalletMode: options?.hybridWalletMode,
@@ -338,7 +406,7 @@ async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, pre
     { ...options, skipPreflight: true },
     'thirdfy'
   );
-  intentResult.mode = 'agent_wallet';
+  intentResult.mode = reportedMode;
   intentResult.routeFallback = 'execute_intent_read_only';
   if (preflight) {
     intentResult.executionWalletPreflight = preflight;
@@ -449,6 +517,12 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
 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,
@@ -491,6 +565,14 @@ async function executeSelfRun(ctx, flags, resolved, options) {
 
 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) {

package/src/runtime/validation/actionParamsGate.mjs

@@ -1,4 +1,5 @@
 import { createCliError } from '../../core/envelope.mjs';
+import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import {
   sanitizeParamsForSchemaValidation,
   validateParamsSchema,
@@ -12,15 +13,7 @@ export function resolveActionParamsSchema(resolved) {
 }
 
 export function isReadOnlyCatalogAction(resolved) {
-  const meta = resolved?.resolvedActionMeta;
-  if (!meta || typeof meta !== 'object') return false;
-  const action = String(resolved?.resolvedAction || '')
-    .trim()
-    .toLowerCase()
-    .replace(/-/g, '_');
-  const readOnlyByName = action.startsWith('get_') || action.startsWith('list_') || action.startsWith('search_');
-  const readOnlyByMeta = meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
-  return readOnlyByName || readOnlyByMeta;
+  return isReadOnlyResolvedAction(resolved, { requireMeta: true });
 }
 
 export function validateResolvedActionParams(resolved, params) {

package/src/utils/cli/intentNormalization.cjs

@@ -34,7 +34,14 @@ function normalizeIntentResponse(response) {
   const topLevelDelegationSignal = String(response?.delegationSignal || '').trim() || null;
   const policyEvaluated = response?.policyEvaluated === true;
   const preflightBlocked = response?.preflightBlocked === true;
+  // This function is a whitelist, so any provider payload outside the known keys is dropped. Read
+  // actions return their data in `data` (and sometimes `raw`) rather than in `results`, so those two
+  // must survive or the caller gets a well-formed envelope with nothing in it.
+  const passthrough = {};
+  if (response?.data !== undefined) passthrough.data = response.data;
+  if (response?.raw !== undefined) passthrough.raw = response.raw;
   return {
+    ...passthrough,
     success,
     status: response?.status || (success ? 'queued' : 'failed'),
     intentId: response?.intentId || null,