@thirdfy/agent-cli 0.2.68 → 0.2.70

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.70] - 2026-09-16
+
+### Fixed
+
+- `--action get_aave_markets` (and other snake/kebab pairs) resolves to the first-class catalog key before colliding earn aliases. Matches `thirdfy-mcp` **0.0.120**. Pin: `test/catalog-canonical-action-resolution.test.cjs`.
+
+### Changed
+
+- Hosted runtime write idempotency is generic (`hostedRuntimeIdempotency`) instead of EarnOrg-only helpers. Keys still use the `earnclaw:{runtimeId}:` wire prefix so Thirdfy action-event join stays the same. Pairs with `thirdfy-mcp` **0.0.120** and Thirdfy API **3.14.48**.
+
+## [0.2.69] - 2026-09-16
+
+### Fixed
+
+- Managed `agent_wallet` reads do not fall back to `/execute-intent` on `PARAMS_SCHEMA_INVALID` / unknown-key. Fallback stays limited to `does not support execute rail`. Matches `thirdfy-mcp` **0.0.119**. Pin: `test/agent-wallet-readonly-fallback.test.cjs`.
+
 ## [0.2.68] - 2026-09-16
 
 ### Fixed

package/README.md

@@ -40,10 +40,10 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.68
+## What's new in v0.2.70
 
-- Avantis `complete_avantis_onboarding` defaults `estimatedAmountUsd` to `1` when the caller omits it.
-- `--confirmWrites` / `--confirm` merge into execute params so a Claude-style root confirmation reaches AgentKit.
+- `--action get_aave_markets` resolves to the first-class catalog key before colliding earn aliases.
+- Hosted runtime write keys stay scoped by runtime UUID so Thirdfy action events can join.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start

package/package.json

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

package/src/core/executionContext.mjs

@@ -50,3 +50,7 @@ export function mergeExecutionContext(body) {
   if (!executionContext.source) executionContext.source = 'hosted_runtime';
   return { ...body, executionContext };
 }
+
+export {
+  wrapWriteIdempotencyKeyForHostedRuntime,
+} from './hostedRuntimeIdempotency.mjs';

package/src/core/hostedRuntimeIdempotency.mjs

@@ -0,0 +1,44 @@
+import { randomUUID } from 'node:crypto';
+
+/** Stable Thirdfy execute namespace for hosted runtimes (any control plane). Legacy wire token. */
+export const HOSTED_RUNTIME_IDEMPOTENCY_NAMESPACE = 'earnclaw';
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export const HOSTED_RUNTIME_SCOPED_KEY_RE = new RegExp(
+  `^${HOSTED_RUNTIME_IDEMPOTENCY_NAMESPACE}:[0-9a-f-]{36}:`,
+  'i',
+);
+
+export function readHostedRuntimeUuid(value) {
+  const trimmed = String(value || '').trim();
+  return UUID_RE.test(trimmed) ? trimmed.toLowerCase() : undefined;
+}
+
+export function isHostedRuntimeScopedIdempotencyKey(key) {
+  return HOSTED_RUNTIME_SCOPED_KEY_RE.test(String(key || '').trim());
+}
+
+export function formatHostedRuntimeScopedIdempotencyKey({ runtimeId, channel, suffix }) {
+  const rid = readHostedRuntimeUuid(runtimeId);
+  if (!rid) return String(suffix || '').trim();
+  const ch = String(channel || 'thirdfy')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .slice(0, 32);
+  const tail = String(suffix || '').trim() || `write-${Date.now()}:${randomUUID()}`;
+  return `${HOSTED_RUNTIME_IDEMPOTENCY_NAMESPACE}:${rid}:${ch}:${tail}`;
+}
+
+export function wrapWriteIdempotencyKeyForHostedRuntime(existingKey, runtimeId, _action, channel = 'thirdfy') {
+  const existing = String(existingKey || '').trim();
+  const rid = readHostedRuntimeUuid(runtimeId);
+  if (existing && isHostedRuntimeScopedIdempotencyKey(existing)) return existing;
+  if (rid) {
+    const suffix = existing || `cli:${Date.now()}:${randomUUID()}`;
+    return formatHostedRuntimeScopedIdempotencyKey({ runtimeId: rid, channel, suffix });
+  }
+  return existing;
+}

package/src/runtime/actions/selection.mjs

@@ -35,6 +35,13 @@ function canonicalActionKey(action) {
     .toLowerCase();
 }
 
+function canonicalizeCatalogActionKey(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, '-');
+}
+
 function inferActionProvider(action) {
   // API catalog metadata (`providerId`, `domain`, `category`) is the source of truth.
   // This fallback only keeps older catalog rows / older API deployments discoverable.
@@ -337,8 +344,12 @@ function getActionProvider(action) {
 
 async function resolveActionSelection(ctx, flags) {
   const requestedAction = requireFlag(flags, 'action', 'Missing --action');
-  const requestedLower = requestedAction.toLowerCase();
   const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  return resolveActionFromRows(requestedAction, actions, flags);
+}
+
+function resolveActionFromRows(requestedAction, actions, flags = {}) {
+  const requestedLower = String(requestedAction || '').toLowerCase();
   const keyed = actions
     .map((action) => ({
       key: getActionKey(action),
@@ -381,11 +392,50 @@ async function resolveActionSelection(ctx, flags) {
     );
   }
 
+  const requestedCanonical = canonicalizeCatalogActionKey(requestedAction);
+  const canonicalKey = keyed.filter(
+    (entry) => canonicalizeCatalogActionKey(entry.key) === requestedCanonical
+  );
+  if (canonicalKey.length === 1) {
+    return {
+      requestedAction,
+      resolvedAction: canonicalKey[0].key,
+      resolvedActionMeta: canonicalKey[0].action || null,
+    };
+  }
+  if (canonicalKey.length > 1) {
+    const identities = new Set(canonicalKey.map((entry) => canonicalizeCatalogActionKey(entry.key)));
+    if (identities.size === 1) {
+      const kebab = canonicalKey.find((entry) => entry.key.toLowerCase() === requestedCanonical);
+      const picked = kebab || canonicalKey[0];
+      return {
+        requestedAction,
+        resolvedAction: picked.key,
+        resolvedActionMeta: picked.action || null,
+      };
+    }
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(
+        canonicalKey.map((v) => v.key)
+      )}.`
+    );
+  }
+
   const exactAlias = keyed.filter((entry) => entry.aliases.some((a) => a.toLowerCase() === requestedLower));
   if (exactAlias.length === 1) {
     return { requestedAction, resolvedAction: exactAlias[0].key, resolvedActionMeta: exactAlias[0].action || null };
   }
   if (exactAlias.length > 1) {
+    const preferred = exactAlias.filter(
+      (entry) => canonicalizeCatalogActionKey(entry.key) === requestedCanonical
+    );
+    if (preferred.length === 1) {
+      return {
+        requestedAction,
+        resolvedAction: preferred[0].key,
+        resolvedActionMeta: preferred[0].action || null,
+      };
+    }
     const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
     throw new Error(
       `Ambiguous --action "${requestedAction}". Alias matches multiple actions: ${formatActionList(
@@ -420,6 +470,8 @@ async function resolveActionSelection(ctx, flags) {
     normalizeProviderId,
     applyActionFilters,
     getActionProvider,
+    canonicalizeCatalogActionKey,
+    resolveActionFromRows,
     resolveActionSelection,
   };
 }

package/src/runtime/execution/earnclawRuntimeWriteGate.mjs

@@ -1,63 +1,7 @@
-import { createCliError } from '../../core/envelope.mjs';
-
-function readUuid(value) {
-  const trimmed = String(value || '').trim();
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)
-    ? trimmed
-    : undefined;
-}
-
-const POLYMARKET_PLACE_ACTIONS = new Set([
-  'place_polymarket_order',
-  'place-polymarket-order',
-  'place_prediction_order',
-  'place-prediction-order',
-]);
-
-export function resolveEarnclawRuntimeId(env = process.env) {
-  const runtimeId = readUuid(env.THIRDFY_EXECUTION_RUNTIME_ID)
-    || readUuid(env.EARNCLAW_RUNTIME_ID);
-  return runtimeId ? runtimeId.toLowerCase() : '';
-}
-
-export function normalizePolymarketPlaceAction(action) {
-  return String(action || '')
-    .trim()
-    .toLowerCase()
-    .replace(/_/g, '-');
-}
-
-export function isPolymarketPlaceAction(action) {
-  const key = String(action || '').trim().toLowerCase();
-  if (POLYMARKET_PLACE_ACTIONS.has(key)) return true;
-  return normalizePolymarketPlaceAction(key) === 'place-polymarket-order'
-    || normalizePolymarketPlaceAction(key) === 'place-prediction-order';
-}
-
-/**
- * On EarnClaw-managed Hermes machines, ad-hoc CLI/MCP/dashboard tool calls can
- * place Polymarket orders without pack execute-gate. Require an earnclaw-scoped
- * idempotency key so only adapter/operator keys pass.
- */
-export function assertEarnclawPolymarketWriteIdempotency({
-  action,
-  idempotencyKey,
-  paramsIdempotencyKey,
-  env = process.env,
-} = {}) {
-  if (!isPolymarketPlaceAction(action)) return null;
-  const runtimeId = resolveEarnclawRuntimeId(env);
-  if (!runtimeId) return null;
-
-  const prefix = `earnclaw:${runtimeId}`;
-  const keys = [idempotencyKey, paramsIdempotencyKey]
-    .map((key) => String(key || '').trim())
-    .filter(Boolean);
-  if (keys.some((key) => key.toLowerCase().startsWith(prefix))) return null;
-
-  throw createCliError(
-    'EARNCLAW_PM_IDEMPOTENCY_REQUIRED',
-    `EarnClaw runtime ${runtimeId} requires Polymarket place orders to use idempotencyKey starting with "${prefix}". ` +
-      'Pack execute-gate and operator exits set this automatically. Bare CLI/dashboard tool writes are blocked.',
-  );
-}
+/** @deprecated Import from ./hostedRuntimeWriteGate.ts */
+export {
+  assertHostedRuntimePolymarketWriteIdempotency as assertEarnclawPolymarketWriteIdempotency,
+  resolveHostedRuntimeIdFromEnv as resolveEarnclawRuntimeId,
+  isPolymarketPlaceAction,
+  normalizePolymarketPlaceAction,
+} from './hostedRuntimeWriteGate.mjs';

package/src/runtime/execution/hostedRuntimeWriteGate.mjs

@@ -0,0 +1,56 @@
+import { createCliError } from '../../core/envelope.mjs';
+import {
+  HOSTED_RUNTIME_IDEMPOTENCY_NAMESPACE,
+  readHostedRuntimeUuid,
+} from '../../core/hostedRuntimeIdempotency.mjs';
+
+const POLYMARKET_PLACE_ACTIONS = new Set([
+  'place_polymarket_order',
+  'place-polymarket-order',
+  'place_prediction_order',
+  'place-prediction-order',
+]);
+
+export function resolveHostedRuntimeIdFromEnv(env = process.env) {
+  return (
+    readHostedRuntimeUuid(env.THIRDFY_EXECUTION_RUNTIME_ID)
+    || readHostedRuntimeUuid(env.EARNCLAW_RUNTIME_ID)
+  );
+}
+
+export function normalizePolymarketPlaceAction(action) {
+  return String(action || '')
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, '-');
+}
+
+export function isPolymarketPlaceAction(action) {
+  const key = String(action || '').trim().toLowerCase();
+  if (POLYMARKET_PLACE_ACTIONS.has(key)) return true;
+  return normalizePolymarketPlaceAction(key) === 'place-polymarket-order'
+    || normalizePolymarketPlaceAction(key) === 'place-prediction-order';
+}
+
+export function assertHostedRuntimePolymarketWriteIdempotency({
+  action,
+  idempotencyKey,
+  paramsIdempotencyKey,
+  env = process.env,
+} = {}) {
+  if (!isPolymarketPlaceAction(action)) return null;
+  const runtimeId = resolveHostedRuntimeIdFromEnv(env);
+  if (!runtimeId) return null;
+
+  const prefix = `${HOSTED_RUNTIME_IDEMPOTENCY_NAMESPACE}:${runtimeId}`;
+  const keys = [idempotencyKey, paramsIdempotencyKey]
+    .map((key) => String(key || '').trim())
+    .filter(Boolean);
+  if (keys.some((key) => key.toLowerCase().startsWith(prefix))) return null;
+
+  throw createCliError(
+    'HOSTED_RUNTIME_PM_IDEMPOTENCY_REQUIRED',
+    `Hosted runtime ${runtimeId} requires Polymarket place orders to use idempotencyKey starting with "${prefix}". ` +
+      'Pack execute-gate and operator exits set this automatically. Bare CLI/dashboard tool writes are blocked.',
+  );
+}

package/src/runtime/execution/managedReadExecuteRail.mjs

@@ -0,0 +1,22 @@
+/**
+ * Managed `agent_wallet` reads prefer `/execute`. Execute-intent is only a fallback when that
+ * rail rejects the action (`does not support execute rail`). Schema failures must not fall back
+ * to an empty queued execute-intent envelope.
+ *
+ * Keep in sync with `thirdfy-mcp` `src/lib/managedReadExecuteRail.ts`.
+ */
+
+export const EXECUTE_RAIL_UNSUPPORTED_FRAGMENT = 'does not support execute rail';
+
+export function managedReadExecuteErrorText(data) {
+  return String(data?.error || data?.message || data?.code || data?.blockedReason || '').toLowerCase();
+}
+
+export function shouldFallbackManagedReadToExecuteIntent({ isReadOnly, errorText } = {}) {
+  if (!isReadOnly) return false;
+  const err = String(errorText || '').toLowerCase();
+  if (err.includes('params_schema_invalid') || err.includes('invalid paramsschema') || err.includes('unknown key')) {
+    return false;
+  }
+  return err.includes(EXECUTE_RAIL_UNSUPPORTED_FRAGMENT);
+}

package/src/runtime/execution/payloads.mjs

@@ -1,9 +1,11 @@
 import { randomUUID } from 'crypto';
+import { wrapWriteIdempotencyKeyForHostedRuntime } from '../../core/hostedRuntimeIdempotency.mjs';
+import { resolveExecutionContextFromEnv } from '../../core/executionContext.mjs';
 import { requireFlag, parseJsonFlag } from '../../core/args.mjs';
 import { loadProfileConfig } from '../../core/context.mjs';
 import { createCliError } from '../../core/envelope.mjs';
 import { normalizeRunMode, normalizeManagedRunMode, normalizeHybridWalletMode } from '../../core/runMode.mjs';
-import { assertEarnclawPolymarketWriteIdempotency } from './earnclawRuntimeWriteGate.mjs';
+import { assertHostedRuntimePolymarketWriteIdempotency } from './hostedRuntimeWriteGate.mjs';
 import { resolveTokenInForFunding } from '../../core/fundingTokenIn.mjs';
 
 function isTruthyFlag(value) {
@@ -157,7 +159,14 @@ function buildManagedExecutePayload(flags, options) {
   } else if (flags.idempotencyKey) {
     payload.executionIdempotencyKey = String(flags.idempotencyKey);
   }
-  assertEarnclawPolymarketWriteIdempotency({
+  if (payload.executionIdempotencyKey) {
+    payload.executionIdempotencyKey = wrapWriteIdempotencyKeyForHostedRuntime(
+      payload.executionIdempotencyKey,
+      resolveExecutionContextFromEnv().runtimeId,
+      payload.action,
+    );
+  }
+  assertHostedRuntimePolymarketWriteIdempotency({
     action: payload.action,
     idempotencyKey: payload.executionIdempotencyKey,
     paramsIdempotencyKey: managedParams?.idempotencyKey,
@@ -203,8 +212,15 @@ function buildIntentPayload(flags, options) {
   } else if (flags.idempotencyKey) {
     payload.idempotencyKey = String(flags.idempotencyKey);
   }
+  if (payload.idempotencyKey) {
+    payload.idempotencyKey = wrapWriteIdempotencyKeyForHostedRuntime(
+      payload.idempotencyKey,
+      resolveExecutionContextFromEnv().runtimeId,
+      payload.action,
+    );
+  }
   if (!options.validationOnly) {
-    assertEarnclawPolymarketWriteIdempotency({
+    assertHostedRuntimePolymarketWriteIdempotency({
       action: payload.action,
       idempotencyKey: payload.idempotencyKey,
       paramsIdempotencyKey: payload.params?.idempotencyKey,

package/src/runtime/execution/runners.mjs

@@ -12,6 +12,7 @@ import {
 import { apiGet, apiPost } from '../../core/http.mjs';
 import { withActionTimeout } from '../../core/actionTimeouts.mjs';
 import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
+import { shouldFallbackManagedReadToExecuteIntent } from './managedReadExecuteRail.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -85,9 +86,10 @@ function isReadOnlyAction(resolved) {
 }
 
 function shouldFallbackAgentWalletToExecuteIntent(resolved, response) {
-  if (!isReadOnlyAction(resolved)) return false;
-  const err = String(response?.error || response?.message || '').toLowerCase();
-  return err.includes('does not support execute rail');
+  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