@thirdfy/agent-cli 0.2.17 → 0.2.20

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.20] - 2026-07-04
+
+### Added
+
+- `brain` command group: `sections`, `suggest`, `preflight`, `graduate` for Console Brain read/preflight-first strategy lanes (pairs with Thirdfy API **v3.10.0** Brain routes).
+
+## [0.2.19] - 2026-07-04
+
+### Changed
+
+- Release packaging and docs alignment (no Brain commands in this tag; use **v0.2.20** for `brain`).
+
+## [0.2.18] - 2026-07-02
+
+### Changed
+
+- `credits balance`, `credits models list`, and `credits models estimate` human-readable summaries lead with USD when the API returns `availableUsd`, `estimatedUsdPerTurn`, or `chargedUsd` (Thirdfy API **v3.9.5+** USD credits Phase 1). JSON output unchanged. Pairs with `thirdfy-mcp` **v0.0.67+**.
+
 ## [0.2.17] - 2026-07-02
 
 ### Changed

package/README.md

@@ -40,9 +40,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.17
+## What's new in v0.2.20
 
-- Lighter onboarding writes (`complete_lighter_onboarding`, `setup_lighter_api_key`, `register_lighter_api_key`) use a 180s HTTP timeout by default so `run` and `wallet execute` do not abort before CCTP credit or Ethereum `changePubKey` completes. Override with `THIRDFY_CLI_LONG_TIMEOUT_MS`. Pairs with Thirdfy API **v3.9.4+** and `thirdfy-mcp` **v0.0.66+**.
+- **Console Brain:** `thirdfy-agent brain sections|suggest|preflight|graduate` read ranked Trading, Yield, and Prediction lanes from Thirdfy API (no local ranking).
+- Brain commands support `--strategy`, `--section`, `--capital-usd`, `--risk`, and `--target earnclaw` for read/preflight-first strategy workflows.
+- Pairs with Thirdfy API **v3.10.0** Brain routes (`GET /api/v1/console/brain-*`). See [`docs/command-reference.md`](./docs/command-reference.md).
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 
@@ -312,6 +314,7 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 - Delegation operations: `delegation show`, `delegation inspect`, `delegation revoke`
 - Delegation execution helpers: `delegation balance`, `delegation redeem`
 - Account: `credits balance`
+- Console Brain: `brain sections`, `brain suggest`, `brain preflight`, `brain graduate` (read/preflight-first; see [`docs/command-reference.md`](./docs/command-reference.md))
 
 ## CLI routing (Commander + runtime)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.17",
+  "version": "0.2.20",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "src/core/",
     "src/commands/",
     "src/cli/",
+    "src/lib/",
     "src/runtime/",
     "src/utils/cli/",
     "src/contracts/cli/schemas/",

package/src/cli/manifest.mjs

@@ -92,6 +92,30 @@ export const CLI_MANIFEST = [
     options: ['auth', 'execution', 'polymarket'],
     description: 'Polymarket dry-run preflight',
   },
+  {
+    path: ['venue', 'readiness'],
+    handler: 'commandVenueReadiness',
+    options: ['auth', 'venue'],
+    description: 'Normalized venue readiness (polymarket, hyperliquid, lighter)',
+    args: { query: true },
+    tier: 'online',
+  },
+  {
+    path: ['venue', 'setup'],
+    handler: 'commandVenueSetup',
+    options: ['auth', 'venue'],
+    description: 'Prepare or complete venue onboarding via shared API contract',
+    args: { query: true },
+    tier: 'online',
+  },
+  {
+    path: ['venue', 'fund'],
+    handler: 'commandVenueFund',
+    options: ['auth', 'venue'],
+    description: 'Return venue funding plan (does not move funds implicitly)',
+    args: { query: true },
+    tier: 'online',
+  },
   {
     path: ['hummingbot', 'status'],
     handler: 'commandHummingbotStatus',
@@ -196,6 +220,56 @@ export const CLI_MANIFEST = [
     options: ['auth', 'execution'],
     description: 'Quote action-tier credits for a catalog action',
   },
+  {
+    path: ['chat', 'send'],
+    handler: 'commandChatSend',
+    tier: 'online',
+    options: ['auth', 'chat', 'chains'],
+    description: 'Send a Console chat message (streaming)',
+    args: { message: '[message...]' },
+  },
+  {
+    path: ['chat', 'threads'],
+    handler: 'commandChatThreads',
+    tier: 'online',
+    options: ['auth'],
+    description: 'List Console chat threads',
+  },
+  {
+    path: ['chat', 'models'],
+    handler: 'commandChatModels',
+    tier: 'online',
+    options: ['auth'],
+    description: 'List Console chat models from catalog',
+  },
+  {
+    path: ['brain', 'sections'],
+    handler: 'commandBrainSections',
+    tier: 'online',
+    options: ['auth', 'chains', 'brain'],
+    description: 'Read Console Brain sections for trading, yield, and prediction',
+  },
+  {
+    path: ['brain', 'suggest'],
+    handler: 'commandBrainSuggest',
+    tier: 'online',
+    options: ['auth', 'chains', 'brain'],
+    description: 'Return a structured Brain strategy draft from current signals',
+  },
+  {
+    path: ['brain', 'preflight'],
+    handler: 'commandBrainPreflight',
+    tier: 'online',
+    options: ['auth', 'chains', 'brain'],
+    description: 'Run read-only Brain preflight checks for a strategy',
+  },
+  {
+    path: ['brain', 'graduate'],
+    handler: 'commandBrainGraduate',
+    tier: 'online',
+    options: ['auth', 'brain'],
+    description: 'Prepare an EarnClaw handoff proposal without deploying',
+  },
   {
     path: ['data', 'summary'],
     handler: 'commandDataSummary',

package/src/cli/options/brain.mjs

@@ -0,0 +1,10 @@
+export function attachBrainOptions(cmd) {
+  return cmd
+    .option('--strategy <id>', 'Brain strategy id (default base-usdc-yield)')
+    .option('--strategy-id <id>', 'alias for --strategy')
+    .option('--section <lane>', 'yield | trading | prediction')
+    .option('--capital-usd <amount>', 'optional capital size for strategy draft')
+    .option('--risk <level>', 'low | medium | high')
+    .option('--target <name>', 'handoff target (earnclaw)')
+    .option('--include-degraded', 'include degraded Brain sections', false);
+}

package/src/cli/options/chat.mjs

@@ -0,0 +1,9 @@
+export function attachChatOptions(cmd) {
+  return cmd
+    .option('--network <id>', 'network id (for example base-mainnet)')
+    .option('--model <key>', 'chat model key from catalog')
+    .option('--thread <id>', 'existing chat thread id')
+    .option('--continue', 'continue the last persisted thread')
+    .option('--persona <mode>', 'chat persona mode', 'thirdfy')
+    .option('--tool-domains <list>', 'comma-separated tool pack ids (prediction, earn, perps_hl, ...)');
+}

package/src/cli/options/index.mjs

@@ -12,6 +12,9 @@ import { attachHummingbotOptions } from './hummingbot.mjs';
 import { attachAgentRegisterOptions } from './agent.mjs';
 import { attachChainOptions } from './chains.mjs';
 import { attachCreditsOptions } from './credits.mjs';
+import { attachChatOptions } from './chat.mjs';
+import { attachVenueOptions } from './venue.mjs';
+import { attachBrainOptions } from './brain.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,
@@ -27,6 +30,9 @@ const BUNDLES = {
   agent: attachAgentRegisterOptions,
   chains: attachChainOptions,
   credits: attachCreditsOptions,
+  chat: attachChatOptions,
+  venue: attachVenueOptions,
+  brain: attachBrainOptions,
 };
 
 /** @param {import('commander').Command} cmd */

package/src/cli/options/venue.mjs

@@ -0,0 +1,12 @@
+export function attachVenueOptions(cmd) {
+  return cmd
+    .option('--amount <usd>', 'Funding amount in USD')
+    .option('--amount-usd <usd>', 'Alias for --amount')
+    .option('--main-wallet-address <address>', 'Hyperliquid main wallet address')
+    .option('--api-wallet-address <address>', 'Hyperliquid API wallet address')
+    .option('--l1-address <address>', 'Lighter L1 address')
+    .option('--include-geoblock', 'Include Polymarket geoblock probes', true)
+    .option('--no-include-geoblock', 'Skip Polymarket geoblock probes')
+    .option('--complete', 'Run complete onboarding writes (setup command only)')
+    .option('--confirm-writes', 'Confirm onboarding writes');
+}

package/src/cli/register.mjs

@@ -50,6 +50,9 @@ function registerManifestEntry(program, entry, nodeByPath, deps) {
   if (entry.args?.query) {
     leaf.argument(entry.args.query);
   }
+  if (entry.args?.message) {
+    leaf.argument(entry.args.message);
+  }
 
   const handler = handlers[entry.handler];
   if (!handler) {
@@ -62,6 +65,11 @@ function registerManifestEntry(program, entry, nodeByPath, deps) {
 
     if (entry.args?.address) {
       extra.address = actionArgs[0];
+    } else if (entry.args?.message) {
+      const messageArg = actionArgs[0];
+      extra.message = Array.isArray(messageArg)
+        ? messageArg.join(' ')
+        : String(messageArg || '').trim();
     } else if (entry.args?.query) {
       const queryArg = actionArgs[0];
       extra.query = Array.isArray(queryArg) ? queryArg : queryArg !== undefined ? [queryArg] : [];
@@ -78,6 +86,8 @@ function registerManifestEntry(program, entry, nodeByPath, deps) {
       } else if (entry.handler === 'commandPrompt') {
         const tokens = Array.isArray(extra.query) ? extra.query : [];
         await handler(ctx, flags, capabilities, tokens);
+      } else if (entry.handler === 'commandChatSend') {
+        await handler(ctx, flags, capabilities, extra.message);
       } else {
         await handler(ctx, flags, capabilities);
       }

package/src/commands/bootstrap.mjs

@@ -26,6 +26,8 @@ export function createBootstrapCommands(deps) {
     printEnvelope,
     extractAgentApiKey,
     extractAgentKey,
+    maskSecret,
+    buildOwnerAuthHeaders,
     buildOnboardingHelp,
     buildWalletChallengePayload,
     issueBootstrapToken,
@@ -162,12 +164,47 @@ async function commandHelpOnboarding(ctx, _flags) {
 }
 
 
-async function commandWhoami(ctx, _flags) {
+async function commandWhoami(ctx, flags) {
   const config = loadProfileConfig();
   const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
   const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
   const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  const chat = config.chat && typeof config.chat === 'object' ? config.chat : {};
   const runMode = ctx.runMode || config.runMode || 'agent_wallet';
+
+  let mandateSummary = null;
+  let mandateSummaryError = null;
+  const hasPrivyAuth = Boolean(
+    auth.authToken ||
+      auth.ownerSessionToken ||
+      process.env.THIRDFY_AUTH_TOKEN ||
+      process.env.THIRDFY_OWNER_SESSION_TOKEN ||
+      flags.authToken,
+  );
+  const hasAgentApiKey = Boolean(agent.apiKey || process.env.THIRDFY_AGENT_API_KEY);
+
+  if (hasPrivyAuth) {
+    try {
+      const headers = buildOwnerAuthHeaders(
+        flags,
+        'Missing credentials for mandate summary (auth token or owner session required).',
+      );
+      const chainId = Number(chat.chainId || flags.chainId || 8453);
+      const query = new URLSearchParams({ chainId: String(chainId) });
+      const walletAddress = String(
+        wallets.primaryEvmWallet || flags.walletAddress || '',
+      ).trim();
+      if (walletAddress) query.set('walletAddress', walletAddress);
+      mandateSummary = await apiGet(
+        ctx,
+        `/api/v1/console/mandate-summary?${query.toString()}`,
+        headers,
+      );
+    } catch (error) {
+      mandateSummaryError = error?.message || 'MANDATE_SUMMARY_FAILED';
+    }
+  }
+
   printEnvelope({
     success: true,
     code: 'WHOAMI_OK',
@@ -188,6 +225,14 @@ async function commandWhoami(ctx, _flags) {
         agentApiKey: maskSecret(agent.apiKey),
         agentKey: agent.agentKey || null,
       },
+      chat: {
+        lastThreadId: chat.lastThreadId || null,
+        defaultChatModel: chat.defaultChatModel || null,
+        chainId: chat.chainId || null,
+      },
+      mandateSummary,
+      mandateSummaryError,
+      mandateSummarySkipped: !hasPrivyAuth && hasAgentApiKey ? 'requires_privy_auth' : null,
       wallets: {
         userDid: wallets.userDid || config.identity?.userDid || null,
         primaryEvmWallet: wallets.primaryEvmWallet || null,

package/src/commands/brain.mjs

@@ -0,0 +1,135 @@
+import { loadProfileConfig } from '../core/context.mjs';
+import { apiGet } from '../core/http.mjs';
+
+function buildAuthHeaders(flags) {
+  const config = loadProfileConfig();
+  const explicitOwner = String(flags.ownerSessionToken || '').trim();
+  const explicitAuth = String(flags.authToken || '').trim();
+  const ownerSession = String(
+    process.env.THIRDFY_OWNER_SESSION_TOKEN || config?.auth?.ownerSessionToken || '',
+  ).trim();
+  const authToken = String(process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+
+  if (explicitOwner || ownerSession) {
+    return { 'x-owner-session-token': explicitOwner || ownerSession };
+  }
+  const token = explicitAuth || authToken;
+  if (token) {
+    return { Authorization: `Bearer ${token}` };
+  }
+  throw new Error(
+    'Missing credentials: provide --auth-token, THIRDFY_AUTH_TOKEN, or --owner-session-token.',
+  );
+}
+
+function resolveChainId(flags, config) {
+  if (flags.chainId) {
+    const parsed = Number(flags.chainId);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  const fromConfig = Number(config?.chat?.chainId || 0);
+  if (Number.isFinite(fromConfig) && fromConfig > 0) return fromConfig;
+  return 8453;
+}
+
+function resolveWalletAddress(flags, config) {
+  const explicit = String(flags.walletAddress || '').trim();
+  if (explicit) return explicit;
+  const wallets = config?.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  return String(wallets.primaryEvmWallet || '').trim() || undefined;
+}
+
+function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null || value === '') continue;
+    search.set(key, String(value));
+  }
+  const query = search.toString();
+  return query ? `?${query}` : '';
+}
+
+function printBrainEnvelope(printEnvelope, flags, code, message, data) {
+  printEnvelope(
+    {
+      success: true,
+      code,
+      message,
+      data,
+      meta: { readOnly: true },
+    },
+    flags,
+  );
+}
+
+export function createBrainCommands({ printEnvelope }) {
+  async function commandBrainSections(ctx, flags) {
+    const config = loadProfileConfig();
+    const chainId = resolveChainId(flags, config);
+    const walletAddress = resolveWalletAddress(flags, config);
+    const query = buildQuery({
+      chainId,
+      walletAddress,
+      includeDegraded: flags.includeDegraded === false ? 'false' : 'true',
+    });
+    const data = await apiGet(ctx, `/api/v1/console/brain-sections${query}`, buildAuthHeaders(flags));
+    printBrainEnvelope(printEnvelope, flags, 'OK', 'Brain sections loaded', data);
+    return data;
+  }
+
+  async function commandBrainSuggest(ctx, flags) {
+    const config = loadProfileConfig();
+    const chainId = resolveChainId(flags, config);
+    const walletAddress = resolveWalletAddress(flags, config);
+    const strategyId = String(flags.strategy || flags.strategyId || '').trim();
+    const section = String(flags.section || '').trim();
+    const queryParams = {
+      capitalUsd: flags.capitalUsd,
+      risk: flags.risk,
+      chainId,
+      walletAddress,
+    };
+    if (strategyId) {
+      queryParams.strategyId = strategyId;
+    } else if (section) {
+      queryParams.section = section;
+    } else {
+      queryParams.strategyId = 'base-usdc-yield';
+    }
+    const query = buildQuery(queryParams);
+    const data = await apiGet(ctx, `/api/v1/console/brain/suggest${query}`, buildAuthHeaders(flags));
+    printBrainEnvelope(printEnvelope, flags, 'OK', 'Brain strategy draft loaded', data);
+    return data;
+  }
+
+  async function commandBrainPreflight(ctx, flags) {
+    const config = loadProfileConfig();
+    const chainId = resolveChainId(flags, config);
+    const walletAddress = resolveWalletAddress(flags, config);
+    const query = buildQuery({
+      strategyId: flags.strategy || flags.strategyId || 'base-usdc-yield',
+      chainId,
+      walletAddress,
+    });
+    const data = await apiGet(ctx, `/api/v1/console/brain/preflight${query}`, buildAuthHeaders(flags));
+    printBrainEnvelope(printEnvelope, flags, 'OK', 'Brain preflight loaded', data);
+    return data;
+  }
+
+  async function commandBrainGraduate(ctx, flags) {
+    const query = buildQuery({
+      strategyId: flags.strategy || flags.strategyId || 'base-usdc-yield',
+      target: flags.target || 'earnclaw',
+    });
+    const data = await apiGet(ctx, `/api/v1/console/brain/graduate${query}`, buildAuthHeaders(flags));
+    printBrainEnvelope(printEnvelope, flags, 'OK', 'Brain EarnClaw handoff proposal loaded', data);
+    return data;
+  }
+
+  return {
+    commandBrainSections,
+    commandBrainSuggest,
+    commandBrainPreflight,
+    commandBrainGraduate,
+  };
+}

package/src/commands/chat.mjs

@@ -0,0 +1,404 @@
+import { parseBooleanFlag } from '../core/runMode.mjs';
+import { loadProfileConfig, persistProfileConfig } from '../core/context.mjs';
+import { apiGet, safeJsonParse } from '../core/http.mjs';
+
+const NETWORK_CHAIN_IDS = {
+  'base-mainnet': 8453,
+  'base-sepolia': 84532,
+};
+
+const DEFAULT_CHAT_CHAIN_ID = 8453;
+const CHAT_STREAM_TIMEOUT_MS = 180_000;
+
+function resolveChatChainId(flags, config) {
+  if (flags.chainId) {
+    const parsed = Number(flags.chainId);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  const network = String(flags.network || '').trim().toLowerCase();
+  if (network && NETWORK_CHAIN_IDS[network]) return NETWORK_CHAIN_IDS[network];
+  const fromConfig = Number(config?.chat?.chainId || 0);
+  if (Number.isFinite(fromConfig) && fromConfig > 0) return fromConfig;
+  return DEFAULT_CHAT_CHAIN_ID;
+}
+
+function buildChatAuthHeaders(flags) {
+  const config = loadProfileConfig();
+  const explicitOwner = String(flags.ownerSessionToken || '').trim();
+  const explicitAuth = String(flags.authToken || '').trim();
+  const ownerSession = String(
+    process.env.THIRDFY_OWNER_SESSION_TOKEN || config?.auth?.ownerSessionToken || '',
+  ).trim();
+  const authToken = String(process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+
+  if (explicitOwner || ownerSession) {
+    return { 'x-owner-session-token': explicitOwner || ownerSession };
+  }
+  const token = explicitAuth || authToken;
+  if (token) {
+    return { Authorization: `Bearer ${token}` };
+  }
+  throw new Error(
+    'Missing chat credentials: provide --auth-token, THIRDFY_AUTH_TOKEN, or --owner-session-token.',
+  );
+}
+
+function buildChatRequestHeaders(flags, modelKey) {
+  const headers = {
+    'content-type': 'application/json',
+    Accept: 'text/plain; charset=utf-8',
+    ...buildChatAuthHeaders(flags),
+  };
+  if (modelKey) {
+    headers['x-thirdfy-chat-model'] = modelKey;
+  }
+  const persona = String(flags.persona || 'thirdfy').trim();
+  if (persona) {
+    headers['x-thirdfy-chat-persona'] = persona;
+  }
+  return headers;
+}
+
+function resolveChatModelKey(flags, config) {
+  return (
+    String(flags.model || '').trim() ||
+    String(config?.chat?.defaultChatModel || '').trim() ||
+    ''
+  );
+}
+
+function resolveChatThreadId(flags, config) {
+  const explicit = String(flags.thread || flags.threadId || '').trim();
+  if (explicit) return explicit;
+  if (parseBooleanFlag(flags.continue, false)) {
+    return String(config?.chat?.lastThreadId || '').trim() || undefined;
+  }
+  return undefined;
+}
+
+function resolveUserAddress(flags, config) {
+  const explicit = String(flags.walletAddress || '').trim();
+  if (explicit) return explicit;
+  const wallets = config?.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  return String(wallets.primaryEvmWallet || '').trim() || undefined;
+}
+
+function parseToolDomains(flags) {
+  const raw = String(flags.toolDomains || '').trim();
+  if (!raw) return undefined;
+  const domains = raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  return domains.length ? domains : undefined;
+}
+
+function parseDataStreamLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  if (trimmed.startsWith('data: ')) {
+    try {
+      return safeJsonParse(trimmed.slice(6));
+    } catch {
+      return null;
+    }
+  }
+
+  const colonIndex = trimmed.indexOf(':');
+  if (colonIndex <= 0) return null;
+  const prefix = trimmed.slice(0, colonIndex);
+  const payload = trimmed.slice(colonIndex + 1);
+
+  if (prefix === '0') {
+    try {
+      return { type: 'text', value: String(JSON.parse(payload)) };
+    } catch {
+      return { type: 'text', value: payload };
+    }
+  }
+
+  if (prefix === '2') {
+    try {
+      const data = JSON.parse(payload);
+      return { type: 'data', value: Array.isArray(data) ? data : [data] };
+    } catch {
+      return null;
+    }
+  }
+
+  if (prefix === '3') {
+    try {
+      return { type: 'error', value: JSON.parse(payload) };
+    } catch {
+      return { type: 'error', value: payload };
+    }
+  }
+
+  return null;
+}
+
+function extractThreadMetaFromDataItems(items) {
+  if (!Array.isArray(items)) return null;
+  for (const item of items) {
+    if (item && typeof item === 'object' && item.type === 'thread_meta' && item.threadId) {
+      return item;
+    }
+  }
+  return null;
+}
+
+function parseThreadMetaHeader(raw) {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.type === 'thread_meta') {
+      return parsed;
+    }
+    if (parsed && typeof parsed === 'object' && parsed.threadId) {
+      return { type: 'thread_meta', ...parsed };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+async function requestChatStream(ctx, body, headers) {
+  const controller = new AbortController();
+  const timeoutMs = Math.max(Number(ctx.timeoutMs || 0), CHAT_STREAM_TIMEOUT_MS);
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(`${ctx.apiBase}/api/v1/chat/stream`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      const data = text ? safeJsonParse(text) : {};
+      const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
+      error.statusCode = response.status;
+      error.payload = data;
+      throw error;
+    }
+
+    let threadMeta =
+      parseThreadMetaHeader(response.headers.get('X-Thirdfy-Chat-Thread-Meta')) || null;
+    let threadId = response.headers.get('X-Thirdfy-Chat-Thread-Id') || undefined;
+    let content = '';
+    let streamError = null;
+    const toolCalls = [];
+
+    if (response.body) {
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let lineBuffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        lineBuffer += decoder.decode(value, { stream: true });
+        const lines = lineBuffer.split('\n');
+        lineBuffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const parsedLine = parseDataStreamLine(line);
+          if (!parsedLine) continue;
+
+          if (parsedLine.type === 'text') {
+            content += parsedLine.value;
+            continue;
+          }
+
+          if (parsedLine.type === 'error') {
+            streamError = String(parsedLine.value || 'stream error');
+            continue;
+          }
+
+          if (parsedLine.type === 'data') {
+            const meta = extractThreadMetaFromDataItems(parsedLine.value);
+            if (meta) {
+              threadMeta = meta;
+              if (meta.threadId) threadId = String(meta.threadId);
+            }
+            continue;
+          }
+
+          if (parsedLine.type === 'content' || parsedLine.type === 'text-delta') {
+            content += String(parsedLine.content || parsedLine.textDelta || parsedLine.text || '');
+          }
+          if (parsedLine.type === 'tool-call' && parsedLine.toolName) {
+            toolCalls.push(String(parsedLine.toolName));
+          }
+          if (parsedLine.type === 'data' && Array.isArray(parsedLine.data)) {
+            const meta = extractThreadMetaFromDataItems(parsedLine.data);
+            if (meta) {
+              threadMeta = meta;
+              if (meta.threadId) threadId = String(meta.threadId);
+            }
+          }
+          if (parsedLine.type === 'error') {
+            streamError = String(parsedLine.error || parsedLine.message || 'stream error');
+          }
+          if (parsedLine.type === 'done') {
+            const meta = parsedLine.thread_meta || parsedLine.threadMeta;
+            if (meta && typeof meta === 'object') {
+              threadMeta = meta;
+              if (meta.threadId) threadId = String(meta.threadId);
+            }
+            if (parsedLine.threadId) threadId = String(parsedLine.threadId);
+          }
+          const debug = parsedLine.debug;
+          if (debug && Array.isArray(debug.toolCallsList)) {
+            for (const item of debug.toolCallsList) toolCalls.push(String(item));
+          }
+        }
+      }
+
+      const tail = lineBuffer.trim();
+      if (tail) {
+        const parsedLine = parseDataStreamLine(tail);
+        if (parsedLine?.type === 'text') content += parsedLine.value;
+        if (parsedLine?.type === 'data') {
+          const meta = extractThreadMetaFromDataItems(parsedLine.value);
+          if (meta) {
+            threadMeta = meta;
+            if (meta.threadId) threadId = String(meta.threadId);
+          }
+        }
+      }
+    }
+
+    if (streamError) {
+      const error = new Error(streamError);
+      error.statusCode = 502;
+      throw error;
+    }
+
+    return {
+      content,
+      threadId: threadId || threadMeta?.threadId || body.threadId,
+      threadMeta,
+      toolCalls,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function persistChatPreferences(config, { threadId, modelKey, chainId }) {
+  const next = {
+    ...config,
+    chat: {
+      ...(config.chat && typeof config.chat === 'object' ? config.chat : {}),
+    },
+  };
+  if (threadId) next.chat.lastThreadId = String(threadId);
+  if (modelKey) next.chat.defaultChatModel = String(modelKey);
+  if (chainId) next.chat.chainId = Number(chainId);
+  persistProfileConfig(next);
+  return next.chat;
+}
+
+export function createChatCommands({ printEnvelope }) {
+  async function commandChatSend(ctx, flags, _capabilities, messageArg) {
+    const message = String(messageArg || flags.message || '').trim();
+    if (!message) {
+      throw new Error('Missing message. Use: thirdfy-agent chat send "<message>"');
+    }
+
+    const config = loadProfileConfig();
+    const chainId = resolveChatChainId(flags, config);
+    const modelKey = resolveChatModelKey(flags, config);
+    const threadId = resolveChatThreadId(flags, config);
+    const userAddress = resolveUserAddress(flags, config);
+    const toolDomains = parseToolDomains(flags);
+
+    const body = {
+      messages: [{ role: 'user', content: message }],
+      chainId,
+      personaMode: String(flags.persona || 'thirdfy').trim() || 'thirdfy',
+      ...(threadId ? { threadId } : {}),
+      ...(modelKey ? { modelKey } : {}),
+      ...(userAddress ? { userAddress } : {}),
+      ...(toolDomains ? { toolDomains } : {}),
+    };
+
+    const headers = buildChatRequestHeaders(flags, modelKey);
+    const stream = await requestChatStream(ctx, body, headers);
+
+    const resolvedThreadId = stream.threadId || threadId;
+    const resolvedModelKey = stream.threadMeta?.modelKey || modelKey;
+    const persisted = persistChatPreferences(config, {
+      threadId: resolvedThreadId,
+      modelKey: resolvedModelKey,
+      chainId,
+    });
+
+    if (!flags.json && stream.content) {
+      process.stdout.write(stream.content);
+      if (!stream.content.endsWith('\n')) process.stdout.write('\n');
+    }
+
+    const threadLabel = resolvedThreadId ? ` (thread ${resolvedThreadId})` : '';
+    printEnvelope({
+      success: true,
+      code: 'CHAT_SEND_OK',
+      message: flags.json ? 'Chat response completed' : `Chat response completed${threadLabel}`,
+      data: {
+        ...(flags.json ? { content: stream.content } : {}),
+        threadId: resolvedThreadId || null,
+        threadMeta: stream.threadMeta || null,
+        toolCalls: stream.toolCalls,
+        modelKey: resolvedModelKey || null,
+        chainId,
+        persisted,
+      },
+      meta: {
+        apiBase: ctx.apiBase,
+        continued: parseBooleanFlag(flags.continue, false),
+        network: flags.network || null,
+      },
+    });
+  }
+
+  async function commandChatThreads(ctx, flags) {
+    const headers = buildChatAuthHeaders(flags);
+    const query = new URLSearchParams();
+    if (flags.limit) query.set('limit', String(flags.limit));
+    if (flags.status) query.set('status', String(flags.status));
+    const route = query.size
+      ? `/api/v1/chat/threads?${query.toString()}`
+      : '/api/v1/chat/threads';
+    const response = await apiGet(ctx, route, headers);
+    printEnvelope({
+      success: true,
+      code: 'CHAT_THREADS_OK',
+      message: 'Chat threads loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase },
+    });
+  }
+
+  async function commandChatModels(ctx, flags) {
+    const headers = buildChatAuthHeaders(flags);
+    const response = await apiGet(ctx, '/api/v1/chat/models', headers);
+    printEnvelope({
+      success: true,
+      code: 'CHAT_MODELS_OK',
+      message: 'Chat models loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase },
+    });
+  }
+
+  return {
+    commandChatSend,
+    commandChatThreads,
+    commandChatModels,
+  };
+}

package/src/commands/credits.mjs

@@ -1,5 +1,9 @@
 import { requireFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import {
+  formatCreditsEstimateSummary,
+  formatCreditsModelsSummary,
+} from '../lib/creditsUsdSummary.mjs';
 
 function resolveToolCallsEstimate(flags) {
   const raw = flags.toolCalls ?? flags.toolCallsList;
@@ -67,10 +71,7 @@ export function createCreditsCommands({ printEnvelope, getAuthToken }) {
     const response = await apiGet(ctx, '/api/v1/credits/pricing/models', {
       Authorization: `Bearer ${authToken}`,
     });
-    const firstModel = response?.models?.[0];
-    const summary = firstModel?.estimatedUsdPerTurn != null
-      ? `${response?.models?.length ?? 0} models · e.g. ${firstModel.modelKey} ~$${Number(firstModel.estimatedUsdPerTurn).toFixed(2)}/turn`
-      : `${response?.models?.length ?? 0} models loaded`;
+    const summary = formatCreditsModelsSummary(response);
     printEnvelope({
       success: true,
       code: 'OK',
@@ -99,9 +100,7 @@ export function createCreditsCommands({ printEnvelope, getAuthToken }) {
       { Authorization: `Bearer ${authToken}` },
     );
     const estimate = response?.estimate;
-    const summary = estimate?.chargedUsd != null
-      ? `~$${Number(estimate.chargedUsd).toFixed(2)} charged (${estimate.chargedCredits ?? estimate.totalCredits} credits)`
-      : `${estimate?.chargedCredits ?? estimate?.totalCredits ?? '?'} credits`;
+    const summary = formatCreditsEstimateSummary(estimate);
     printEnvelope({
       success: true,
       code: 'OK',

package/src/commands/discovery.mjs

@@ -2,6 +2,7 @@ import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 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';
 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');
@@ -57,10 +58,7 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/credits/balance', {
     Authorization: `Bearer ${authToken}`,
   });
-  const summary =
-    typeof response?.availableUsd === 'number'
-      ? `$${response.availableUsd.toFixed(2)} available (${response.balance ?? 0} credits)`
-      : `${response?.balance ?? 0} credits`;
+  const summary = formatCreditsBalanceSummary(response);
   printEnvelope({
     success: true,
     code: 'OK',

package/src/commands/venue.mjs

@@ -0,0 +1,110 @@
+import { apiGet, apiPost } from '../core/http.mjs';
+import { loadProfileConfig } from '../core/context.mjs';
+
+const VENUES = new Set(['polymarket', 'hyperliquid', 'lighter']);
+
+function resolveVenue(flags) {
+  const fromQuery = Array.isArray(flags.query) ? flags.query[0] : flags.query;
+  const venue = String(flags.venue || fromQuery || '').trim().toLowerCase();
+  if (!VENUES.has(venue)) {
+    throw new Error(`Unsupported venue "${venue}". Use polymarket, hyperliquid, or lighter.`);
+  }
+  return venue;
+}
+
+function extractAgentKey(value) {
+  if (!value || typeof value !== 'object') return '';
+  const candidates = [
+    value.agentKey,
+    value.data?.agentKey,
+    value.bootstrap?.agentKey,
+    value.registration?.agentKey,
+    value.registration?.registration?.agentKey,
+    value.data?.registration?.agentKey,
+    value.data?.registration?.registration?.agentKey,
+    value.owner?.creatorWallet,
+    value.data?.owner?.creatorWallet,
+  ];
+  return String(candidates.find((candidate) => String(candidate || '').trim()) || '').trim();
+}
+
+function resolveVenueAgentKey(flags) {
+  const fromFlags = String(flags.agentKey || '').trim();
+  if (fromFlags) return fromFlags;
+  const config = loadProfileConfig();
+  const fromAgent = String(config?.agent?.agentKey || '').trim();
+  if (fromAgent) return fromAgent;
+  const fromConfig = extractAgentKey(config);
+  if (fromConfig) return fromConfig;
+  throw new Error('Missing --agent-key (or config.agent.agentKey). Venue tooling uses --agent-api-key only for authentication.');
+}
+
+function buildAgentQuery(agentKey, flags) {
+  const query = new URLSearchParams({ agentKey });
+  if (flags.mainWalletAddress) query.set('mainWalletAddress', String(flags.mainWalletAddress));
+  if (flags.apiWalletAddress) query.set('apiWalletAddress', String(flags.apiWalletAddress));
+  if (flags.l1Address) query.set('l1Address', String(flags.l1Address));
+  if (flags.amountUsd) query.set('amountUsd', String(flags.amountUsd));
+  if (flags.includeGeoblock === false) query.set('includeGeoblock', 'false');
+  return query;
+}
+
+export function createVenueCommands({ printEnvelope, resolveAgentApiKey }) {
+  function buildAuthHeaders(flags) {
+    const agentApiKey = resolveAgentApiKey(flags, flags.runMode || 'agent_wallet');
+    return { 'x-agent-api-key': agentApiKey };
+  }
+
+  async function commandVenueReadiness(ctx, flags) {
+    const venue = resolveVenue(flags);
+    const agentKey = resolveVenueAgentKey(flags);
+    const query = buildAgentQuery(agentKey, flags);
+    query.set('venue', venue);
+    const response = await apiGet(ctx, `/api/v1/agent/venue/readiness?${query.toString()}`, buildAuthHeaders(flags));
+    printEnvelope(response);
+  }
+
+  async function commandVenueSetup(ctx, flags) {
+    const venue = resolveVenue(flags);
+    const agentKey = resolveVenueAgentKey(flags);
+    const complete = Boolean(flags.complete);
+    const confirmWrites = Boolean(flags.confirmWrites);
+    const body = {
+      venue,
+      agentKey,
+      dryRun: complete ? false : !confirmWrites,
+      confirmWrites,
+      ...(flags.mainWalletAddress ? { mainWalletAddress: String(flags.mainWalletAddress) } : {}),
+      ...(flags.apiWalletAddress ? { apiWalletAddress: String(flags.apiWalletAddress) } : {}),
+      ...(flags.l1Address ? { l1Address: String(flags.l1Address) } : {}),
+      ...(flags.amountUsd ? { amountUsd: Number(flags.amountUsd) } : {}),
+    };
+    const path = flags.complete ? '/api/v1/agent/venue/complete' : '/api/v1/agent/venue/prepare';
+    const response = await apiPost(ctx, path, body, buildAuthHeaders(flags));
+    printEnvelope(response);
+  }
+
+  async function commandVenueFund(ctx, flags) {
+    const venue = resolveVenue(flags);
+    const agentKey = resolveVenueAgentKey(flags);
+    const amountUsd = Number(flags.amount || flags.amountUsd || 0);
+    if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
+      throw new Error('Provide --amount with a positive USD value.');
+    }
+    const response = await apiPost(ctx, '/api/v1/agent/venue/fund', {
+      venue,
+      agentKey,
+      amountUsd,
+      ...(flags.mainWalletAddress ? { mainWalletAddress: String(flags.mainWalletAddress) } : {}),
+      ...(flags.apiWalletAddress ? { apiWalletAddress: String(flags.apiWalletAddress) } : {}),
+      ...(flags.l1Address ? { l1Address: String(flags.l1Address) } : {}),
+    }, buildAuthHeaders(flags));
+    printEnvelope(response);
+  }
+
+  return {
+    commandVenueReadiness,
+    commandVenueSetup,
+    commandVenueFund,
+  };
+}

package/src/lib/creditsUsdSummary.mjs

@@ -0,0 +1,21 @@
+export function formatCreditsBalanceSummary(response) {
+  if (typeof response?.availableUsd === 'number') {
+    return `$${response.availableUsd.toFixed(2)} available (${response.balance ?? 0} credits)`;
+  }
+  return `${response?.balance ?? 0} credits`;
+}
+
+export function formatCreditsModelsSummary(response) {
+  const firstModel = response?.models?.[0];
+  if (firstModel?.estimatedUsdPerTurn != null) {
+    return `${response?.models?.length ?? 0} models · e.g. ${firstModel.modelKey} ~$${Number(firstModel.estimatedUsdPerTurn).toFixed(2)}/turn`;
+  }
+  return `${response?.models?.length ?? 0} models loaded`;
+}
+
+export function formatCreditsEstimateSummary(estimate) {
+  if (estimate?.chargedUsd != null) {
+    return `~$${Number(estimate.chargedUsd).toFixed(2)} charged (${estimate.chargedCredits ?? estimate.totalCredits} credits)`;
+  }
+  return `${estimate?.chargedCredits ?? estimate?.totalCredits ?? '?'} credits`;
+}

package/src/runtime/handlers.mjs

@@ -9,11 +9,14 @@ import { createDelegationCommands } from '../commands/delegation.mjs';
 import { createBootstrapCommands } from '../commands/bootstrap.mjs';
 import { createDiscoveryCommands } from '../commands/discovery.mjs';
 import { createCreditsCommands } from '../commands/credits.mjs';
+import { createChatCommands } from '../commands/chat.mjs';
+import { createBrainCommands } from '../commands/brain.mjs';
 import { createTelemetryCommands } from '../commands/telemetry.mjs';
 import { createCredentialsCommands } from '../commands/credentials.mjs';
 import { createAgentCommands } from '../commands/agent.mjs';
 import { createDoctorCommands } from '../commands/doctor.mjs';
 import { createPromptCommands } from '../commands/prompt.mjs';
+import { createVenueCommands } from '../commands/venue.mjs';
 
 /**
  * Wire command-module factories and local handlers for Commander manifest registration.
@@ -62,6 +65,14 @@ export function createRuntimeHandlers(deps) {
     getAuthToken,
   });
 
+  const __chat = createChatCommands({
+    printEnvelope,
+  });
+
+  const __brain = createBrainCommands({
+    printEnvelope,
+  });
+
   const __telemetry = createTelemetryCommands({
     printEnvelope,
     resolveAgentApiKey,
@@ -94,6 +105,7 @@ export function createRuntimeHandlers(deps) {
   });
 
   const __prompt = createPromptCommands({ printEnvelope });
+  const __venue = createVenueCommands({ printEnvelope, resolveAgentApiKey });
 
   const __hyperliquid = createHyperliquidHelpers({
     getPreparedParams,
@@ -157,6 +169,8 @@ export function createRuntimeHandlers(deps) {
     printEnvelope,
     extractAgentApiKey,
     extractAgentKey,
+    maskSecret,
+    buildOwnerAuthHeaders,
     buildOnboardingHelp: __doctor.buildOnboardingHelp,
     buildWalletChallengePayload: __agent.buildWalletChallengePayload,
     issueBootstrapToken: __agent.issueBootstrapToken,
@@ -179,6 +193,7 @@ export function createRuntimeHandlers(deps) {
     ...__agent,
     ...__doctor,
     ...__prompt,
+    ...__venue,
     commandDoctorSelf: __doctor.commandDoctorSelf,
     commandDoctorAuth: __doctor.commandDoctorAuth,
     commandManagedSetup: __doctor.commandManagedSetup,
@@ -190,6 +205,13 @@ export function createRuntimeHandlers(deps) {
     commandModelsList: __credits.commandModelsList,
     commandModelsEstimate: __credits.commandModelsEstimate,
     commandPricingQuote: __credits.commandPricingQuote,
+    commandChatSend: __chat.commandChatSend,
+    commandChatThreads: __chat.commandChatThreads,
+    commandChatModels: __chat.commandChatModels,
+    commandBrainSections: __brain.commandBrainSections,
+    commandBrainSuggest: __brain.commandBrainSuggest,
+    commandBrainPreflight: __brain.commandBrainPreflight,
+    commandBrainGraduate: __brain.commandBrainGraduate,
     commandDataSummary: __telemetry.commandDataSummary,
     commandTrackList: __telemetry.commandTrackList,
     commandTrackAction: __telemetry.commandTrackAction,
@@ -203,5 +225,8 @@ export function createRuntimeHandlers(deps) {
     commandAnalyticsPortfolio: __telemetry.commandAnalyticsPortfolio,
     commandAnalyticsLeaderboard: __telemetry.commandAnalyticsLeaderboard,
     commandPrompt: __prompt.commandPrompt,
+    commandVenueReadiness: __venue.commandVenueReadiness,
+    commandVenueSetup: __venue.commandVenueSetup,
+    commandVenueFund: __venue.commandVenueFund,
   };
 }