@thirdfy/agent-cli 0.2.77 → 0.2.79

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## [0.2.79] - 2026-09-30
+
+### Added
+
+- **`thirdfy-agent signals [--provider <id>] [--role direction|filter|context] [--json]`** lists the data provider apps (CoinMarketCap, Nansen, Allora, ...) and the signals they publish, from the Thirdfy action catalog's app manifests (`apps[]` and each read's `signals[]`, Thirdfy API thirdfy-api-v2#682): id, title, what it measures, fields with paths, types and units, freshness (cadence, max age, horizon), roles, rules, the read that returns it, credits per call with the billing tier, attribution and whether values may be displayed. Human mode prints one block per signal. An unknown `--role` fails with `SIGNAL_ROLE_INVALID`. An API without app manifests lists nothing. Pin: `test/signals-command.test.cjs`.
+- **`thirdfy-agent actions --data-category <category[,category]>`** keeps only data reads of those categories (`market_data`, `signal`, `research`, `wallet`), case-insensitive.
+- **`run` shows a data read's typed reading first in human mode**: `typed`, `parseIssues`, `freshness` and `attribution` (Thirdfy API typed results, thirdfy-api-v2#681), then the full result. `--json` is unchanged. Pin: `test/typed-reading-output.test.cjs`.
+
+### Fixed
+
+- **Large output is no longer cut when it goes to a pipe.** The envelope was written with `fs.writeSync(1)`, which ignored a partial write: once Node has opened `process.stdout` (or the reader side made the shared pipe non-blocking), a pipe is non-blocking and `writeSync` writes only what fits in the pipe buffer (64 KiB on macOS). That is how `actions --data-category signal,research --json` piped to another program was once cut at 65,514 characters. Output now goes through `process.stdout.write`, and every command that exits with a status (failed `run` / `preflight` / `wallet` / `doctor` checks, missing flags in `condor`, `hummingbot`, `polymarket`, Commander errors, unhandled errors) sets `process.exitCode` and exits only after stdout and stderr have drained (`exitAfterOutput` in `src/core/envelope.mjs`). A reader that stops reading cannot hold the CLI open: after 10 s (`THIRDFY_AGENT_EXIT_DRAIN_TIMEOUT_MS`) it exits with the intended code anyway. Exit codes are unchanged. Pin: `test/output-drain.test.cjs` (over 1 MB of JSON through a slow pipe reader, blocking and non-blocking stdout, the exit path, and a reader that never reads).
+
+## [0.2.78] - 2026-09-24
+
+### Changed
+
+- **Avantis is now Veranta.** The Base perps venue rebranded (ticker AVNT unchanged). Help, errors, provider hints and docs say Veranta. Provider hints for `avantis` / `avantis-vault` list Veranta action names (`place_veranta_perps_order`, `deposit_veranta_vault`, ...) and carry `displayName: "Veranta"` and `providerAliases`.
+
+### Added
+
+- **Veranta names work against every API deployment.** A Veranta action name (`*_veranta_*`) resolves to the catalog row the API in hand has: the Veranta row on an API with Veranta names, the Avantis row on one without. Avantis names keep working, including against a catalog that lists them only as aliases of Veranta rows. With no catalog to check, a Veranta name is sent in the Avantis spelling, which every deployment accepts. `pricing quote` does the same.
+- **`veranta` / `veranta-vault` provider aliases.** `--provider veranta` lists the same actions as `--provider avantis` (and `veranta-vault` as `avantis-vault`). `venue readiness|setup|fund veranta` calls the API with the `avantis` venue id. `avantis` is still accepted everywhere.
+- **Hardcoded venue lists recognise both spellings:** the offchain-venue lane guard (`OFFCHAIN_VENUE_ORDER_SELF_UNSUPPORTED`), the 180s long timeout for onboarding and market open/close, the `agent_wallet` `traderAddress` default, the `complete_*_onboarding` `estimatedAmountUsd` default, and `certify` venue fixtures (a live Veranta row replaces the Avantis fixture; the schema digest is spelling-independent).
+- Error codes and internal identifiers are unchanged (`avantis_delegate`, `AVANTIS_*` setup blockers, provider ids `avantis` / `avantis-vault`). Pin: `test/veranta-rebrand.test.cjs`.
+
 ## [0.2.77] - 2026-09-24
 
 ### Changed

package/README.md

@@ -40,13 +40,13 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.77
+## What's new in v0.2.79
 
-- The agent API key is sent in the `x-agent-api-key` header, never in a URL.
-- A write the API answers from an earlier identical one is marked `idempotentReplay: true`. Send a new `--idempotency-key` to place another.
-- `agent_wallet` reads make one API call (no separate wallet preflight when the read does not need it).
-- `deposit_earn_position` accepts `amountHuman` / `amountInHuman` as `amount`. Unknown actions report `blockedReason: UNKNOWN_ACTION` with `suggestions`.
-- Built on commander 14 and ethers 6.17; Node 20+ is still supported.
+- **`thirdfy-agent signals`** lists the data provider apps (CoinMarketCap, Nansen, Allora, ...) and the signals they publish: what each measures, its fields and units, freshness, roles, the read that returns it, credits per call and attribution. Filter with `--provider <id>` and `--role direction|filter|context`; add `--json` for the envelope. No key is needed to browse.
+- **`thirdfy-agent actions --data-category <category[,category]>`** keeps only data reads of those categories (`market_data`, `signal`, `research`, `wallet`).
+- **`run` shows a data read's typed reading first** in human mode (`typed`, `parseIssues`, `freshness`, `attribution`), then the full result. `--json` is unchanged.
+- Large `--json` output piped to another program is no longer cut at the pipe buffer size. Exit codes are unchanged.
+- Signals and typed readings need Thirdfy API 3.17.0 or later; an older API lists no signals.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start
@@ -323,10 +323,10 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 
 ## Command groups
 
-- Discovery: `catalogs list`, `actions` (optional `--provider`, `--chain-id`; see [`docs/command-reference.md`](./docs/command-reference.md) for trading vs earn vs prediction providers and case-insensitive matching)
+- Discovery: `catalogs list`, `signals` (data provider apps and their signals: fields with units, freshness, roles, credits, attribution; `--provider`, `--role`), `actions` (optional `--provider`, `--chain-id`, `--data-category`; see [`docs/command-reference.md`](./docs/command-reference.md) for trading vs earn vs prediction providers and case-insensitive matching)
 - Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
 - Polymarket: `polymarket status`, `polymarket setup`, `polymarket dry-run`
-- Venue tooling: `venue readiness`, `venue setup`, `venue fund` (`polymarket`, `hyperliquid`, `lighter`, `avantis`)
+- Venue tooling: `venue readiness`, `venue setup`, `venue fund` (`polymarket`, `hyperliquid`, `lighter`, `veranta`)
 - Hummingbot: `hummingbot status`, `connectors`, `executor-schema`, `executor-create`, `executor-stop`, `gateway-networks`, `gateway-connectors`
 - Condor Pattern A: `condor policy-status`, `condor preflight`
 - Managed signer execution: `wallet execute`, `wallet sign`, `wallet submit`, `agent run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.77",
+  "version": "0.2.79",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.cjs",
-    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs",
+    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/commands/signals/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs",
     "validate:cli-manifest-handlers": "node ./scripts/validate-cli-manifest-handlers.mjs",
     "validate:runtime-boundaries": "node ./scripts/validate-runtime-boundaries.mjs",
     "validate:npm-pack": "node ./scripts/validate-npm-pack.mjs",

package/scripts/validate-cli-contract-schemas.mjs

@@ -9,6 +9,7 @@ const REQUIRED_FILES = [
   'preflight.response.schema.json',
   'execute-intent.response.schema.json',
   'intent-status.response.schema.json',
+  'signals.response.schema.json',
 ];
 
 const REQUIRED_KEYS = ['$schema', 'title', 'type'];

package/src/cli/manifest.mjs

@@ -103,7 +103,7 @@ export const CLI_MANIFEST = [
     path: ['venue', 'readiness'],
     handler: 'commandVenueReadiness',
     options: ['auth', 'venue'],
-    description: 'Normalized venue readiness (polymarket, hyperliquid, lighter, avantis)',
+    description: 'Normalized venue readiness (polymarket, hyperliquid, lighter, veranta)',
     args: { query: '<venue>' },
     tier: 'online',
   },
@@ -622,9 +622,16 @@ export const CLI_MANIFEST = [
     path: ['actions'],
     handler: 'commandActions',
     tier: 'online',
-    options: ['auth', 'execution'],
+    options: ['auth', 'execution', 'dataCategory'],
     description: 'List allowed actions',
   },
+  {
+    path: ['signals'],
+    handler: 'commandSignals',
+    tier: 'online',
+    options: ['signals'],
+    description: 'List data provider apps and the signals they publish (fields, units, freshness, roles, credits)',
+  },
   {
     path: ['preflight'],
     handler: 'commandPreflight',

package/src/cli/options/data.mjs

@@ -0,0 +1,14 @@
+/** Options of the data commands: `signals`, and the data-category filter of `actions`. */
+
+export function attachSignalsOptions(cmd) {
+  return cmd
+    .option('--provider <id>', 'only this provider app (cmc, nansen, allora, ...)')
+    .option('--role <role>', 'only signals a strategy may give this role: direction|filter|context');
+}
+
+export function attachDataCategoryOptions(cmd) {
+  return cmd.option(
+    '--data-category <category>',
+    'only data reads of this category (market_data, signal, research, wallet); comma-separated for several',
+  );
+}

package/src/cli/options/index.mjs

@@ -17,6 +17,7 @@ import { attachChatOptions } from './chat.mjs';
 import { attachVenueOptions } from './venue.mjs';
 import { attachBrainOptions } from './brain.mjs';
 import { attachCertificationOptions } from './certification.mjs';
+import { attachDataCategoryOptions, attachSignalsOptions } from './data.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,
@@ -37,6 +38,8 @@ const BUNDLES = {
   venue: attachVenueOptions,
   brain: attachBrainOptions,
   certification: attachCertificationOptions,
+  signals: attachSignalsOptions,
+  dataCategory: attachDataCategoryOptions,
 };
 
 /** @param {import('commander').Command} cmd */

package/src/commands/avantis.mjs

@@ -1,11 +1,14 @@
+import { toLegacyVenueActionKey } from '../core/venueBrand.mjs';
+
+/**
+ * Veranta (formerly Avantis) helpers. Names keep the Avantis spelling (internal identifiers); every
+ * check accepts both the `*_avantis_*` and `*_veranta_*` action spellings.
+ */
 export function createAvantisHelpers(deps) {
   const { getPreparedParams, resolveManagedExecutionPreflight } = deps;
 
   function avantisDefaultAddressParamForAction(action) {
-    const canonical = String(action || '')
-      .trim()
-      .toLowerCase()
-      .replace(/_/g, '-');
+    const canonical = toLegacyVenueActionKey(action).replace(/_/g, '-');
     if (
       canonical === 'get-avantis-open-orders' ||
       canonical === 'get-avantis-positions' ||

package/src/commands/condor.mjs

@@ -1,4 +1,5 @@
 import { apiPost } from '../core/http.mjs';
+import { exitAfterOutput } from '../core/envelope.mjs';
 import { parseJsonFlag } from '../core/args.mjs';
 import { negotiateCapabilities } from '../core/http.mjs';
 import { resolveConfigAgentKey } from './polymarket.mjs';
@@ -27,7 +28,7 @@ function failMissingIdentity(printEnvelope, ctx, message) {
     data: {},
     meta: { apiBase: ctx.apiBase },
   });
-  process.exit(1);
+  return exitAfterOutput(1);
 }
 
 export function createCondorCommands({ commandRun, printEnvelope }) {
@@ -35,7 +36,7 @@ export function createCondorCommands({ commandRun, printEnvelope }) {
     const agentApiKey = agentApiKeyFromFlags(flags, ctx);
     const userDid = userDidFromFlags(flags);
     if (!agentApiKey || !userDid) {
-      failMissingIdentity(
+      await failMissingIdentity(
         printEnvelope,
         ctx,
         'Provide --agent-api-key and --user-did for Condor policy status'
@@ -60,7 +61,7 @@ export function createCondorCommands({ commandRun, printEnvelope }) {
     const idempotencyKey = String(flags.idempotencyKey || flags.idempotency_key || '').trim();
     const estimatedAmountUsd = Number(flags.estimatedAmountUsd || flags.estimated_amount_usd || 0);
     if (!agentApiKey || !userDid) {
-      failMissingIdentity(
+      await failMissingIdentity(
         printEnvelope,
         ctx,
         'Provide --agent-api-key and --user-did for Condor preflight'
@@ -74,7 +75,7 @@ export function createCondorCommands({ commandRun, printEnvelope }) {
         data: {},
         meta: { apiBase: ctx.apiBase },
       });
-      process.exit(1);
+      await exitAfterOutput(1);
     }
     if (!Number.isFinite(estimatedAmountUsd) || estimatedAmountUsd <= 0) {
       printEnvelope({
@@ -84,7 +85,7 @@ export function createCondorCommands({ commandRun, printEnvelope }) {
         data: {},
         meta: { apiBase: ctx.apiBase },
       });
-      process.exit(1);
+      await exitAfterOutput(1);
     }
     const params = parseJsonFlag(flags, 'params') || {};
     const orgId = orgIdFromFlags(flags);

package/src/commands/credits.mjs

@@ -1,5 +1,6 @@
 import { requireFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import { toAvantisSpelling } from '../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
   formatCreditsModelsSummary,
@@ -117,7 +118,8 @@ export function createCreditsCommands({ printEnvelope, getAuthToken }) {
       ctx,
       '/api/v1/credits/pricing/quote',
       {
-        actionKey: action,
+        // Veranta names price as their Avantis spelling, which every API deployment knows.
+        actionKey: toAvantisSpelling(action),
         chainId: Number(flags.chainId || 8453),
       },
       { Authorization: `Bearer ${authToken}` },

package/src/commands/doctor.mjs

@@ -3,6 +3,7 @@ import { requireFlag } from '../core/args.mjs';
 import { apiGet, requestWithRouteFallback } from '../core/http.mjs';
 import { loadProfileConfig, getProfileConfigPath, getCachedActionsCatalog } from '../core/context.mjs';
 import { DEFAULT_API_BASE, PROFILE_DEFAULTS } from '../core/constants.mjs';
+import { exitAfterOutput } from '../core/envelope.mjs';
 import { normalizeRunMode, normalizeManagedRunMode } from '../core/runMode.mjs';
 import { buildExecutionCertificationReport } from '../runtime/certification/executionCertify.mjs';
 
@@ -87,7 +88,7 @@ async function commandDoctorSelf(ctx, flags) {
       rpcUrl,
     },
   });
-  if (!ok) process.exit(1);
+  if (!ok) await exitAfterOutput(1);
 }
 
 function buildOnboardingHelp(ctx) {
@@ -233,7 +234,7 @@ async function commandDoctorAuth(ctx, _flags) {
     },
     meta: { apiBase: ctx.apiBase },
   });
-  if (!ok) process.exit(1);
+  if (!ok) await exitAfterOutput(1);
 }
 
 async function commandManagedSetup(ctx, flags, capabilities) {
@@ -310,7 +311,7 @@ async function commandManagedSetup(ctx, flags, capabilities) {
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
-  if (!success) process.exit(1);
+  if (!success) await exitAfterOutput(1);
 }
 
 async function commandDoctorCertifyExecution(ctx, flags) {
@@ -361,7 +362,7 @@ async function commandDoctorCertifyExecution(ctx, flags) {
       cliVersion: CLI_VERSION,
     },
   });
-  if (!report.ok) process.exit(1);
+  if (!report.ok) await exitAfterOutput(1);
 }
 
   return {

package/src/commands/execute.mjs

@@ -1,5 +1,5 @@
 import { requireFlag } from '../core/args.mjs';
-import { createCliError } from '../core/envelope.mjs';
+import { createCliError, exitAfterOutput } from '../core/envelope.mjs';
 import {
   getEffectiveRunMode,
   normalizeHybridWalletMode,
@@ -7,6 +7,7 @@ import {
   parseBooleanFlag,
 } from '../core/runMode.mjs';
 import { apiGet } from '../core/http.mjs';
+import { findTypedReading, formatTypedReadingLead } from './signals/typedReading.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -84,7 +85,7 @@ async function commandPreflight(ctx, flags, capabilities) {
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
-  if (!normalized.success) process.exit(1);
+  if (!normalized.success) await exitAfterOutput(1);
 }
 
 
@@ -144,25 +145,30 @@ async function commandRun(ctx, flags, capabilities) {
         },
       }
     : normalized;
-  printEnvelope({
-    success: normalized.success,
-    code: backendResult.code,
-    message: backendResult.message,
-    data,
-    meta: {
-      apiBase: ctx.apiBase,
-      requestedAction: resolved.requestedAction,
-      resolvedAction: resolved.resolvedAction,
-      idempotencyKey: backendResult.idempotencyKey || null,
-      runMode,
-      hybridWalletMode,
-      profile: ctx.profile || null,
-      skippedPreflight: skipPreflight,
-      swapInput: flags.__swapInput || null,
-      capabilitiesVersion: capabilities?.contractVersion || null,
+  // A data read's typed reading goes first in human output; --json keeps the envelope unchanged.
+  const typedReading = normalized?.success ? findTypedReading(data) : null;
+  printEnvelope(
+    {
+      success: normalized.success,
+      code: backendResult.code,
+      message: backendResult.message,
+      data,
+      meta: {
+        apiBase: ctx.apiBase,
+        requestedAction: resolved.requestedAction,
+        resolvedAction: resolved.resolvedAction,
+        idempotencyKey: backendResult.idempotencyKey || null,
+        runMode,
+        hybridWalletMode,
+        profile: ctx.profile || null,
+        skippedPreflight: skipPreflight,
+        swapInput: flags.__swapInput || null,
+        capabilitiesVersion: capabilities?.contractVersion || null,
+      },
     },
-  });
-  if (!normalized.success) process.exit(1);
+    typedReading ? { humanLead: formatTypedReadingLead(typedReading) } : {},
+  );
+  if (!normalized.success) await exitAfterOutput(1);
 }
 
 
@@ -224,7 +230,7 @@ async function commandIntentStatus(ctx, flags, capabilities) {
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
-  if (!normalized.success) process.exit(1);
+  if (!normalized.success) await exitAfterOutput(1);
 }
 
 
@@ -251,7 +257,7 @@ async function commandSelfExec(ctx, flags, capabilities) {
         resolvedAction: resolved.resolvedAction,
       },
     });
-    process.exit(1);
+    await exitAfterOutput(1);
   }
 
   const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, selfResult);

package/src/commands/hummingbot.mjs

@@ -1,4 +1,5 @@
 import { apiGet, apiPost } from '../core/http.mjs';
+import { exitAfterOutput } from '../core/envelope.mjs';
 import { parseJsonFlag } from '../core/args.mjs';
 import { negotiateCapabilities } from '../core/http.mjs';
 import { resolveConfigAgentKey } from './polymarket.mjs';
@@ -27,7 +28,7 @@ function failMissingIdentity(printEnvelope, ctx, message) {
     data: {},
     meta: { apiBase: ctx.apiBase },
   });
-  process.exit(1);
+  return exitAfterOutput(1);
 }
 
 export function createHummingbotCommands({ printEnvelope, commandRun }) {
@@ -63,7 +64,7 @@ export function createHummingbotCommands({ printEnvelope, commandRun }) {
     const userDid = userDidFromFlags(flags);
     const params = parseJsonFlag(flags, 'params') || {};
     if (!agentApiKey || !userDid) {
-      failMissingIdentity(
+      await failMissingIdentity(
         printEnvelope,
         ctx,
         'Provide --agent-api-key and --user-did for governed executor create'
@@ -97,7 +98,7 @@ export function createHummingbotCommands({ printEnvelope, commandRun }) {
     const executorId = String(flags.executorId || flags.executor_id || '').trim();
     const params = parseJsonFlag(flags, 'params') || {};
     if (!agentApiKey || !userDid) {
-      failMissingIdentity(printEnvelope, ctx, 'Provide --agent-api-key and --user-did for governed executor stop');
+      await failMissingIdentity(printEnvelope, ctx, 'Provide --agent-api-key and --user-did for governed executor stop');
     }
     if (!executorId) {
       printEnvelope({
@@ -107,7 +108,7 @@ export function createHummingbotCommands({ printEnvelope, commandRun }) {
         data: {},
         meta: { apiBase: ctx.apiBase, orgId },
       });
-      process.exit(1);
+      await exitAfterOutput(1);
     }
     const body = {
       ...params,
@@ -135,12 +136,12 @@ export function createHummingbotCommands({ printEnvelope, commandRun }) {
         data: {},
         meta: { apiBase: ctx.apiBase },
       });
-      process.exit(1);
+      await exitAfterOutput(1);
     }
     const agentApiKey = agentApiKeyFromFlags(flags, ctx);
     const userDid = userDidFromFlags(flags);
     if (!agentApiKey || !userDid) {
-      failMissingIdentity(
+      await failMissingIdentity(
         printEnvelope,
         ctx,
         'Provide --agent-api-key and --user-did for Gateway discovery reads'

package/src/commands/polymarket.mjs

@@ -1,6 +1,7 @@
 import { loadProfileConfig } from '../core/context.mjs';
 import { negotiateCapabilities } from '../core/http.mjs';
 import { parseBooleanFlag } from '../core/runMode.mjs';
+import { exitAfterOutput } from '../core/envelope.mjs';
 
 function extractAgentKey(value) {
   if (!value || typeof value !== 'object') return '';
@@ -74,7 +75,7 @@ export function createPolymarketCommands({ commandRun, commandPreflight, printEn
         data: {},
         meta: { apiBase: ctx.apiBase },
       });
-      process.exit(1);
+      await exitAfterOutput(1);
     }
     const capabilities = await negotiateCapabilities(ctx);
     if (!flags.runMode) flags.runMode = 'agent_wallet';

package/src/commands/signals/command.mjs

@@ -0,0 +1,39 @@
+import { apiGet } from '../../core/http.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import { SIGNAL_ROLES, buildSignalsListing, formatSignalsListing } from './signalRows.mjs';
+
+/**
+ * `thirdfy-agent signals`: the provider apps and signals the Thirdfy action catalog publishes (what
+ * each signal measures, fields with units, freshness, roles, credits, attribution). Reads the public
+ * catalog, which carries `apps[]`; no key needed.
+ */
+export function createSignalsCommands({ printEnvelope }) {
+  async function commandSignals(ctx, flags, capabilities) {
+    const role = String(flags.role || '').trim().toLowerCase();
+    if (role && !SIGNAL_ROLES.includes(role)) {
+      throw createCliError('SIGNAL_ROLE_INVALID', `--role must be one of ${SIGNAL_ROLES.join(', ')}`, {
+        role: flags.role,
+        allowedRoles: SIGNAL_ROLES,
+      });
+    }
+    const provider = String(flags.provider || '').trim();
+    const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
+    const listing = buildSignalsListing(response, { provider, role });
+    printEnvelope(
+      {
+        success: true,
+        code: 'OK',
+        message: `Signals loaded: ${listing.signals.length} signal(s) from ${listing.apps.length} app(s)`,
+        data: listing,
+        meta: {
+          apiBase: ctx.apiBase,
+          filters: { provider: provider || null, role: role || null },
+          capabilitiesVersion: capabilities?.contractVersion || null,
+        },
+      },
+      { humanLead: formatSignalsListing(listing), humanData: false },
+    );
+  }
+
+  return { commandSignals };
+}

package/src/commands/signals/signalRows.mjs

@@ -0,0 +1,153 @@
+/**
+ * The signals listing, built from the Thirdfy action catalog (provider app manifests, thirdfy-app.json
+ * v1): `apps[]` at the top level and `signals[]` on each data read. Pure: no HTTP, no printing.
+ */
+
+/** The roles a strategy may give a signal (manifest v1). */
+export const SIGNAL_ROLES = ['direction', 'filter', 'context'];
+
+const text = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+const lower = (value) => text(value).toLowerCase();
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+const snake = (action) => lower(action).replace(/-/g, '_');
+
+function extractCatalogActions(response) {
+  if (Array.isArray(response)) return response;
+  if (Array.isArray(response?.actions)) return response.actions;
+  if (Array.isArray(response?.data?.actions)) return response.data.actions;
+  return [];
+}
+
+function extractApps(response) {
+  if (Array.isArray(response?.apps)) return response.apps;
+  if (Array.isArray(response?.data?.apps)) return response.data.apps;
+  return [];
+}
+
+/** 900 -> "15m", 3600 -> "1h", 45 -> "45s", 129600 -> "1.5d"; "" when absent. */
+export function formatDuration(seconds) {
+  const value = Number(seconds);
+  if (!Number.isFinite(value) || value <= 0) return '';
+  for (const [size, unit] of [[86400, 'd'], [3600, 'h'], [60, 'm']]) {
+    if (value >= size) return `${Number((value / size).toFixed(1))}${unit}`;
+  }
+  return `${Number(value.toFixed(1))}s`;
+}
+
+function fieldRows(fields) {
+  if (!isRecord(fields)) return [];
+  return Object.entries(fields).map(([name, field]) => {
+    const spec = isRecord(field) ? field : {};
+    return {
+      name,
+      path: text(spec.path) || null,
+      type: text(spec.type) || null,
+      unit: text(spec.unit) || null,
+      ...(Array.isArray(spec.range) ? { range: spec.range } : {}),
+      ...(Array.isArray(spec.values) ? { values: spec.values } : {}),
+      ...(text(spec.description) ? { description: text(spec.description) } : {}),
+    };
+  });
+}
+
+function appSummary(app) {
+  const redistribution = isRecord(app.redistribution) ? app.redistribution : {};
+  return {
+    appId: text(app.appId),
+    title: text(app.title) || text(app.appId),
+    kind: text(app.kind) || null,
+    category: text(app.category) || null,
+    summary: text(app.summary) || null,
+    manifestVersion: Number.isFinite(Number(app.manifestVersion)) ? Number(app.manifestVersion) : null,
+    attribution: text(redistribution.attribution) || null,
+    displayValues: typeof redistribution.displayValues === 'boolean' ? redistribution.displayValues : null,
+    ...(text(app.docsUrl) ? { docsUrl: text(app.docsUrl) } : {}),
+    signalIds: Array.isArray(app.signalIds) ? app.signalIds.map(text).filter(Boolean) : [],
+  };
+}
+
+/**
+ * Apps and signals from one catalog response, filtered by provider (app id or the action's
+ * provider id) and role. A catalog without manifest fields (an older API) gives empty lists.
+ */
+export function buildSignalsListing(response, { provider, role } = {}) {
+  const apps = new Map(extractApps(response).filter((app) => isRecord(app) && text(app.appId)).map((app) => [lower(app.appId), app]));
+  const wantedProvider = lower(provider);
+  const wantedRole = lower(role);
+  const signals = [];
+  const seen = new Set();
+  for (const action of extractCatalogActions(response)) {
+    if (!isRecord(action) || !Array.isArray(action.signals) || action.enabled === false) continue;
+    const appId = lower(action.app?.appId) || lower(action.providerId);
+    if (wantedProvider && appId !== wantedProvider && lower(action.providerId) !== wantedProvider) continue;
+    const app = apps.get(appId);
+    const redistribution = isRecord(app?.redistribution) ? app.redistribution : {};
+    for (const signal of action.signals) {
+      const id = text(signal?.id);
+      if (!id || seen.has(id)) continue;
+      const roles = Array.isArray(signal.roles) ? signal.roles.map(lower).filter(Boolean) : [];
+      if (wantedRole && !roles.includes(wantedRole)) continue;
+      seen.add(id);
+      signals.push({
+        id,
+        title: text(signal.title) || id,
+        summary: text(signal.summary) || null,
+        measures: text(signal.measures) || null,
+        scope: text(signal.scope) || null,
+        universe: signal.universe ?? null,
+        fields: fieldRows(signal.fields),
+        asOfPath: text(signal.asOf?.path) || null,
+        freshness: {
+          cadenceSec: Number.isFinite(Number(signal.cadenceSec)) ? Number(signal.cadenceSec) : null,
+          freshnessSec: Number.isFinite(Number(signal.freshnessSec)) ? Number(signal.freshnessSec) : null,
+          horizonHours: Number.isFinite(Number(signal.horizonHours)) && signal.horizonHours !== null ? Number(signal.horizonHours) : null,
+        },
+        roles,
+        rules: Array.isArray(signal.rules) ? signal.rules.map(text).filter(Boolean) : [],
+        action: snake(action.action),
+        dataCategory: text(action.dataCategory) || null,
+        billingTier: text(action.billingTier) || null,
+        credits: typeof action.credits === 'number' && Number.isFinite(action.credits) ? action.credits : null,
+        appId: appId || null,
+        manifestVersion: Number.isFinite(Number(action.app?.manifestVersion)) ? Number(action.app.manifestVersion) : null,
+        attribution: text(signal.attribution) || text(redistribution.attribution) || null,
+        displayValues: typeof redistribution.displayValues === 'boolean' ? redistribution.displayValues : null,
+        ...(text(signal.docsUrl) ? { docsUrl: text(signal.docsUrl) } : {}),
+      });
+    }
+  }
+  const listedAppIds = new Set(signals.map((signal) => signal.appId).filter(Boolean));
+  // With a filter, only the apps that still have a signal listed.
+  const filtered = Boolean(wantedProvider || wantedRole);
+  const appRows = [...apps.values()].filter((app) => !filtered || listedAppIds.has(lower(app.appId))).map(appSummary);
+  return { apps: appRows, signals };
+}
+
+function fieldLabel(field) {
+  const details = [];
+  if (field.unit) details.push(field.unit);
+  if (Array.isArray(field.range) && field.range.length === 2) details.push(`${field.range[0]}-${field.range[1]}`);
+  if (!details.length && field.type) details.push(field.type);
+  return details.length ? `${field.name} (${details.join(', ')})` : field.name;
+}
+
+/** Human lines: one per signal, then the credit lines to show. */
+export function formatSignalsListing({ apps, signals }) {
+  if (!signals.length) return 'No signals in the catalog for this filter.';
+  const lines = signals.map((signal) => {
+    const timing = [
+      signal.freshness.cadenceSec ? `every ${formatDuration(signal.freshness.cadenceSec)}` : '',
+      signal.freshness.freshnessSec ? `fresh ${formatDuration(signal.freshness.freshnessSec)}` : '',
+      signal.freshness.horizonHours ? `horizon ${formatDuration(signal.freshness.horizonHours * 3600)}` : '',
+    ].filter(Boolean);
+    const cost = signal.credits !== null ? `${signal.credits} credits` : '';
+    return [
+      `${signal.id}  ${signal.title}`,
+      `    measures ${signal.measures || '?'} (${signal.scope || 'market'}); roles ${signal.roles.join(', ') || '-'}; ${[...timing, cost].filter(Boolean).join('; ')}`,
+      `    fields ${signal.fields.map(fieldLabel).join(', ') || '-'}; action ${signal.action}`,
+      ...(signal.attribution ? [`    ${signal.attribution}`] : []),
+    ].join('\n');
+  });
+  const appLine = apps.length ? `Apps: ${apps.map((app) => `${app.appId} (${app.title})`).join(', ')}` : '';
+  return [appLine, ...lines].filter(Boolean).join('\n');
+}