@thirdfy/agent-cli 0.2.78 → 0.2.80

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.80] - 2026-10-01
+
+### Fixed
+
+- **`actions --chain-id <id>` now filters.** It returned the whole catalog (359 rows) for any chain. It now keeps rows whose `supportedChains` includes the chain, plus rows with no `supportedChains` (chain-agnostic; several offchain venues have none yet). `run` and `preflight` are unchanged. Pin: `test/dogeos-provider-discovery.test.cjs`.
+- **DogeOS quickstart and provider runbook used an action that does not exist.** `barkswap.swap` with `amountInRaw` failed with `PARAMS_SCHEMA_INVALID`. The docs now use the live catalog names (`dogeos-barkswap-get-quote`, `dogeos-barkswap-execute-swap` with `amountIn` in token units, `dogeos-laika-buy-token` with `dogeAmountWei`), list all 19 DogeOS actions across `dogeos-barkswap`, `dogeos-laika` and `dogeos-ecosystem`, and add the public testnet facts: RPC, explorer, faucet, WDOGE/USDC addresses, user-paid DOGE gas, and the allowlist 403.
+
+## [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

package/README.md

@@ -40,11 +40,10 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.78
+## What's new in v0.2.80
 
-- Avantis, the Base perps venue, is now **Veranta**. Use `--provider veranta` / `veranta-vault` and Veranta action names such as `place_veranta_perps_order` and `get_veranta_positions`.
-- Avantis names (`--provider avantis`, `place_avantis_perps_order`, `venue readiness avantis`) keep working. A Veranta name finds the matching action whether the Thirdfy API catalog lists Veranta or Avantis names.
-- `venue readiness|setup|fund veranta` works; `avantis` is still accepted.
+- **`actions --chain-id <id>` now filters** to actions that run on that chain, plus chain-agnostic ones. Before, it returned the whole catalog for any chain.
+- **DogeOS quickstart rewritten for the public testnet**: live action names (`dogeos-barkswap-get-quote`, `dogeos-barkswap-execute-swap`, `dogeos-laika-buy-token`), RPC, explorer, faucet, WDOGE/USDC addresses, and user-paid DOGE gas. See [docs/dogeos-quickstart.md](./docs/dogeos-quickstart.md).
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start
@@ -321,7 +320,7 @@ 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`, `veranta`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.78",
+  "version": "0.2.80",
   "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

@@ -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/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/discovery.mjs

@@ -3,6 +3,7 @@ import { apiGet, apiPost } from '../core/http.mjs';
 import { extractActions, getCachedActionsCatalog } from '../core/context.mjs';
 import { getEffectiveRunMode } from '../core/runMode.mjs';
 import { formatCreditsBalanceSummary } from '../lib/creditsUsdSummary.mjs';
+import { filterActionsByChain } from '../runtime/actions/chainFilter.mjs';
 export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getTradingProviderHint, resolveChainSupport, getAuthToken, resolveAgentApiKey }) {
 async function commandCatalogsList(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
@@ -32,10 +33,10 @@ async function commandCatalogsList(ctx, flags, capabilities) {
 
 async function commandActions(ctx, flags, capabilities) {
   const policyAware = Boolean(flags.agentApiKey);
-  const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  const chainIdFilter = Number(flags.chainId || 0) || undefined;
+  const actions = filterActionsByChain(applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags), chainIdFilter);
   const providerHint = getTradingProviderHint(flags.provider);
   const effectiveRunMode = getEffectiveRunMode(ctx, flags);
-  const chainIdFilter = Number(flags.chainId || 0) || undefined;
   const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
   printEnvelope({
     success: true,

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');
+}

package/src/commands/signals/typedReading.mjs

@@ -0,0 +1,55 @@
+/**
+ * The typed reading of a data read (Thirdfy API typed results, thirdfy-api-v2#681): `typed`, with
+ * `parseIssues`, `freshness` and `attribution`, wherever the run result nests it. Human output shows
+ * it before the full result, so a reader does not dig through the provider's raw `payload`.
+ */
+
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/** Keys never searched: the raw vendor reply can be large and never holds the typed reading. */
+const SKIPPED_KEYS = new Set(['payload', 'telemetry', 'preflight', 'laneMetadata']);
+const MAX_DEPTH = 6;
+
+function parseJsonText(value) {
+  if (typeof value !== 'string') return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{')) return value;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * The first object (breadth-first) that carries `typed`, returned as
+ * `{ typed, parseIssues, freshness?, attribution? }`; null when the result has no typed reading.
+ */
+export function findTypedReading(result) {
+  let level = [result];
+  for (let depth = 0; depth <= MAX_DEPTH && level.length; depth += 1) {
+    const next = [];
+    for (const raw of level) {
+      const candidate = parseJsonText(raw);
+      if (!isRecord(candidate)) continue;
+      if (Object.prototype.hasOwnProperty.call(candidate, 'typed')) {
+        return {
+          typed: candidate.typed ?? null,
+          parseIssues: Array.isArray(candidate.parseIssues) ? candidate.parseIssues : [],
+          ...(isRecord(candidate.freshness) ? { freshness: candidate.freshness } : {}),
+          ...(typeof candidate.attribution === 'string' && candidate.attribution ? { attribution: candidate.attribution } : {}),
+        };
+      }
+      for (const [key, value] of Object.entries(candidate)) {
+        if (!SKIPPED_KEYS.has(key)) next.push(value);
+      }
+    }
+    level = next;
+  }
+  return null;
+}
+
+/** The human-mode block printed before the full result. */
+export function formatTypedReadingLead(reading) {
+  return `Typed reading:\n${JSON.stringify(reading, null, 2)}\nFull result:`;
+}

package/src/commands/wallet.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 { loadProfileConfig } from '../core/context.mjs';
 
 export function createWalletCommands(deps) {
@@ -47,7 +47,7 @@ async function commandWalletExecute(ctx, flags, capabilities) {
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
-  if (!result.success) process.exit(1);
+  if (!result.success) await exitAfterOutput(1);
 }
 
 
@@ -76,7 +76,7 @@ async function commandWalletSign(ctx, flags, capabilities) {
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
-  if (!selfResult.success) process.exit(1);
+  if (!selfResult.success) await exitAfterOutput(1);
 }
 
 

package/src/contracts/cli/schemas/signals.response.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Endpoint: signals",
+  "type": "object",
+  "required": ["apps", "signals"],
+  "properties": {
+    "apps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["appId", "title", "signalIds"],
+        "properties": {
+          "appId": { "type": "string" },
+          "title": { "type": "string" },
+          "kind": { "type": ["string", "null"] },
+          "category": { "type": ["string", "null"] },
+          "summary": { "type": ["string", "null"] },
+          "manifestVersion": { "type": ["number", "null"] },
+          "attribution": { "type": ["string", "null"] },
+          "displayValues": { "type": ["boolean", "null"] },
+          "docsUrl": { "type": "string" },
+          "signalIds": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "fields", "freshness", "roles", "action"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "summary": { "type": ["string", "null"] },
+          "measures": { "type": ["string", "null"] },
+          "scope": { "type": ["string", "null"] },
+          "universe": {},
+          "fields": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name"],
+              "properties": {
+                "name": { "type": "string" },
+                "path": { "type": ["string", "null"] },
+                "type": { "type": ["string", "null"] },
+                "unit": { "type": ["string", "null"] },
+                "range": { "type": "array", "items": { "type": "number" } },
+                "values": { "type": "array", "items": { "type": "string" } },
+                "description": { "type": "string" }
+              }
+            }
+          },
+          "asOfPath": { "type": ["string", "null"] },
+          "freshness": {
+            "type": "object",
+            "properties": {
+              "cadenceSec": { "type": ["number", "null"] },
+              "freshnessSec": { "type": ["number", "null"] },
+              "horizonHours": { "type": ["number", "null"] }
+            }
+          },
+          "roles": { "type": "array", "items": { "type": "string" } },
+          "rules": { "type": "array", "items": { "type": "string" } },
+          "action": { "type": "string" },
+          "dataCategory": { "type": ["string", "null"] },
+          "billingTier": { "type": ["string", "null"] },
+          "credits": { "type": ["number", "null"] },
+          "appId": { "type": ["string", "null"] },
+          "manifestVersion": { "type": ["number", "null"] },
+          "attribution": { "type": ["string", "null"] },
+          "displayValues": { "type": ["boolean", "null"] },
+          "docsUrl": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/core/envelope.mjs

@@ -1,5 +1,3 @@
-import { writeSync } from 'node:fs';
-
 export function createCliError(code, message, payload = {}) {
   const error = new Error(message);
   error.payload = {
@@ -11,11 +9,52 @@ export function createCliError(code, message, payload = {}) {
   return error;
 }
 
-export function printEnvelope(payload, { jsonMode = false } = {}) {
-  // writeSync: callers often process.exit() immediately after print. Async
-  // process.stdout.write can truncate JSON when stdout is a pipe (tests/CI).
+/**
+ * `humanLead`: text printed in human mode between the status line and the data JSON (a typed
+ * reading, a signal list). `humanData: false` prints the lead instead of the data JSON, with a
+ * pointer to --json. JSON mode ignores both: the envelope stays as it was.
+ */
+export function printEnvelope(payload, { jsonMode = false, humanLead, humanData = true } = {}) {
+  // process.stdout.write queues the whole text. fs.writeSync(1) did not: once Node has opened
+  // process.stdout, a pipe is non-blocking and writeSync writes only what fits in the pipe buffer
+  // (64 KiB on macOS), so a large --json envelope read by a slow consumer was cut. Exits go
+  // through exitAfterOutput, which waits for this queue to drain.
+  const lead = typeof humanLead === 'string' && humanLead ? `${humanLead}\n` : '';
+  const body = lead && humanData === false ? 'Use --json for the full listing.' : JSON.stringify(payload.data || {}, null, 2);
   const text = jsonMode
     ? `${JSON.stringify(payload, null, 2)}\n`
-    : `[${payload.success ? 'OK' : 'ERROR'}] ${payload.code}: ${payload.message}\n${JSON.stringify(payload.data || {}, null, 2)}\n`;
-  writeSync(1, text);
+    : `[${payload.success ? 'OK' : 'ERROR'}] ${payload.code}: ${payload.message}\n${lead}${body}\n`;
+  process.stdout.write(text);
+}
+
+/** How long exitAfterOutput waits for output to drain before exiting anyway. */
+export const DEFAULT_EXIT_DRAIN_TIMEOUT_MS = 10_000;
+
+function exitDrainTimeoutMs() {
+  const override = Number(process.env.THIRDFY_AGENT_EXIT_DRAIN_TIMEOUT_MS);
+  return Number.isFinite(override) && override >= 0 ? override : DEFAULT_EXIT_DRAIN_TIMEOUT_MS;
+}
+
+/**
+ * Exit with `code` after stdout and stderr have written everything queued. process.exit() right
+ * after a write drops what a pipe has not taken yet. A reader that stops reading cannot hold the
+ * CLI open: after THIRDFY_AGENT_EXIT_DRAIN_TIMEOUT_MS (default 10 s) it exits with `code` anyway.
+ * The returned promise never settles, so `await exitAfterOutput(1)` (or `return
+ * exitAfterOutput(1)`) stops the caller where process.exit did.
+ */
+export function exitAfterOutput(code = 0) {
+  process.exitCode = code;
+  const streams = [process.stdout, process.stderr].filter((stream) => stream && !stream.destroyed && stream.writable);
+  let pending = streams.length;
+  if (!pending) process.exit(code);
+  setTimeout(() => process.exit(code), exitDrainTimeoutMs());
+  for (const stream of streams) {
+    // The callback runs once every earlier write on this stream has been handed to the OS
+    // (or failed, for example EPIPE when the reader has gone).
+    stream.write('', () => {
+      pending -= 1;
+      if (pending === 0) process.exit(code);
+    });
+  }
+  return new Promise(() => {});
 }

package/src/runtime/actions/chainFilter.mjs

@@ -0,0 +1,13 @@
+/**
+ * `actions --chain-id <id>` keeps catalog rows that run on that chain.
+ * A row without `supportedChains` is chain-agnostic and stays.
+ */
+export function filterActionsByChain(actions, chainId) {
+  const wanted = Number(chainId || 0);
+  if (!wanted || !Array.isArray(actions)) return actions;
+  return actions.filter((action) => {
+    const chains = action?.supportedChains;
+    if (!Array.isArray(chains) || chains.length === 0) return true;
+    return chains.some((value) => Number(value) === wanted);
+  });
+}

package/src/runtime/actions/selection.mjs

@@ -348,6 +348,16 @@ function applyActionFilters(actions, flags) {
     const expectedProvider = normalizeProviderId(flags.provider);
     filtered = filtered.filter((a) => actionMatchesProvider(a, expectedProvider, filtered));
   }
+  if (flags.dataCategory) {
+    // Catalog `dataCategory` (Thirdfy API data contract); rows without one are not data reads.
+    const categories = new Set(
+      String(flags.dataCategory)
+        .split(',')
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean),
+    );
+    filtered = filtered.filter((a) => categories.has(String(a?.dataCategory || '').trim().toLowerCase()));
+  }
   return filtered;
 }
 

package/src/runtime/handlers.mjs

@@ -11,6 +11,7 @@ import { createDelegationCommands } from '../commands/delegation.mjs';
 import { createConsoleMandateCommands } from '../commands/consoleMandate.mjs';
 import { createBootstrapCommands } from '../commands/bootstrap.mjs';
 import { createDiscoveryCommands } from '../commands/discovery.mjs';
+import { createSignalsCommands } from '../commands/signals/command.mjs';
 import { createCreditsCommands } from '../commands/credits.mjs';
 import { createChatCommands } from '../commands/chat.mjs';
 import { createBrainCommands } from '../commands/brain.mjs';
@@ -67,6 +68,8 @@ export function createRuntimeHandlers(deps) {
     resolveAgentApiKey,
   });
 
+  const __signals = createSignalsCommands({ printEnvelope });
+
   const __credits = createCreditsCommands({
     printEnvelope,
     getAuthToken,
@@ -232,6 +235,7 @@ export function createRuntimeHandlers(deps) {
     commandManagedSetup: __doctor.commandManagedSetup,
     commandCatalogsList: __discovery.commandCatalogsList,
     commandActions: __discovery.commandActions,
+    commandSignals: __signals.commandSignals,
     commandCreditsBalance: __discovery.commandCreditsBalance,
     commandCreditsTransactions: __credits.commandCreditsTransactions,
     commandCreditsUsage: __credits.commandCreditsUsage,

package/src/runtime/main.mjs

@@ -1,5 +1,5 @@
 import { createRequire } from 'module';
-import { printEnvelope as corePrintEnvelope } from '../core/envelope.mjs';
+import { exitAfterOutput, printEnvelope as corePrintEnvelope } from '../core/envelope.mjs';
 import { negotiateCapabilities } from '../core/http.mjs';
 import {
   buildCliProgram,
@@ -38,7 +38,7 @@ export function createThirdfyAgentRuntime() {
         process.argv.includes('--json') ||
         (cliProgram ? cliProgram.opts()?.json : false)
     );
-    corePrintEnvelope(payload, { jsonMode });
+    corePrintEnvelope(payload, { jsonMode, humanLead: options.humanLead, humanData: options.humanData });
   }
 
   function prepareContextFromFlags(flags) {
@@ -174,7 +174,7 @@ export function createThirdfyAgentRuntime() {
           return;
         }
         const exitCode = Number(error.exitCode ?? 1);
-        process.exit(exitCode);
+        await exitAfterOutput(exitCode);
       }
       throw error;
     }
@@ -204,7 +204,7 @@ export function createThirdfyAgentRuntime() {
       },
       meta: { version: CLI_VERSION, apiBase: context.apiBase },
     });
-    process.exit(1);
+    return exitAfterOutput(1);
   }
 
   return {