@thirdfy/agent-cli 0.1.46 → 0.2.1

package/src/commands/polymarket.mjs

@@ -0,0 +1,89 @@
+import { loadProfileConfig } from '../core/context.mjs';
+import { negotiateCapabilities } from '../core/http.mjs';
+import { parseBooleanFlag } from '../core/runMode.mjs';
+
+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();
+}
+
+export function resolveConfigAgentKey(flags) {
+  const fromFlags = String(flags.agentKey || flags.agentApiKey || '').trim();
+  if (fromFlags) return fromFlags;
+  const config = loadProfileConfig();
+  const fromAgent = String(config?.agent?.agentKey || '').trim();
+  if (fromAgent) return fromAgent;
+  return extractAgentKey(config);
+}
+
+export function createPolymarketCommands({ commandPreflight, printEnvelope }) {
+  async function commandPolymarketStatus(ctx, flags) {
+    const agentKey = resolveConfigAgentKey(flags);
+    const capabilities = await negotiateCapabilities(ctx);
+    if (!flags.runMode) flags.runMode = 'agent_wallet';
+    if (agentKey) {
+      flags.action = 'get_polymarket_funding_status';
+      flags.params = JSON.stringify({
+        agentKey,
+        amountPusd: flags.amountPusd ? String(flags.amountPusd) : '5',
+        includeSetupStatus: true,
+      });
+    } else {
+      const params = {
+        includeBalance: parseBooleanFlag(flags.includeBalance, true),
+        includeGeoblock: parseBooleanFlag(flags.includeGeoblock, true),
+      };
+      flags.action = 'get_polymarket_setup_status';
+      flags.params = JSON.stringify(params);
+    }
+    await commandPreflight(ctx, flags, capabilities);
+  }
+
+  async function commandPolymarketSetup(ctx, flags) {
+    const capabilities = await negotiateCapabilities(ctx);
+    flags.action = 'get_polymarket_onboarding_plan';
+    const agentKey = resolveConfigAgentKey(flags);
+    flags.params =
+      flags.params ||
+      JSON.stringify({
+        ...(agentKey ? { agentKey } : {}),
+      });
+    if (!flags.runMode) flags.runMode = 'agent_wallet';
+    flags.__polymarketSetupGuide = true;
+    await commandPreflight(ctx, flags, capabilities);
+  }
+
+  async function commandPolymarketDryRun(ctx, flags) {
+    if (!flags.action) flags.action = 'place-polymarket-order';
+    if (!flags.params) {
+      printEnvelope({
+        success: false,
+        code: 'MISSING_PARAMS',
+        message: 'Provide --params for place_polymarket_order dry-run (tokenID, price, size, side)',
+        data: {},
+        meta: { apiBase: ctx.apiBase },
+      });
+      process.exit(1);
+    }
+    const capabilities = await negotiateCapabilities(ctx);
+    if (!flags.runMode) flags.runMode = 'agent_wallet';
+    await commandPreflight(ctx, flags, capabilities);
+  }
+
+  return {
+    commandPolymarketStatus,
+    commandPolymarketSetup,
+    commandPolymarketDryRun,
+  };
+}

package/src/commands/prompt.mjs

@@ -0,0 +1,33 @@
+import { requireFlag } from '../core/args.mjs';
+import { apiPost } from '../core/http.mjs';
+export function createPromptCommands({ printEnvelope }) {
+async function commandPrompt(ctx, flags, capabilities, promptTokens) {
+  const prompt = String(flags.prompt || promptTokens.join(' ') || '').trim();
+  if (!prompt) {
+    throw new Error('Missing prompt text. Use: thirdfy-agent prompt "<text>"');
+  }
+  // Jeff rail: deterministic wrapper around existing run contract.
+  printEnvelope({
+    success: true,
+    code: 'PROMPT_RECEIVED',
+    message: 'Prompt captured; execute with `jeff trade` or `run` using --run-mode.',
+    data: {
+      prompt,
+      suggestedCommands: [
+        'thirdfy-agent jeff trade --run-mode self --agent-api-key ... --action ... --params ...',
+        'thirdfy-agent jeff trade --run-mode hybrid --agent-api-key ... --action ... --params ...',
+      ],
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      profile: ctx.profile || null,
+      runMode: getEffectiveRunMode(ctx, flags),
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+  return {
+    commandPrompt,
+  };
+}

package/src/commands/telemetry.mjs

@@ -0,0 +1,146 @@
+import { requireFlag, parseJsonFlag } from '../core/args.mjs';
+import { apiGet, apiPost } from '../core/http.mjs';
+export function createTelemetryCommands({ printEnvelope, resolveAgentApiKey }) {
+function applySharedPortfolioListingFiltersToQuery(query, flags) {
+  if (flags.chainId) query.set('chainId', String(flags.chainId));
+  if (flags.network) query.set('networkId', String(flags.network));
+  if (flags.networkId) query.set('networkId', String(flags.networkId));
+  if (flags.chainType) query.set('chainType', String(flags.chainType));
+  if (flags.category) query.set('category', String(flags.category));
+}
+
+function buildAgentKeyPortfolioSummaryQuery(flags, { includeLimit = false } = {}) {
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const query = new URLSearchParams({ agentKey });
+  applySharedPortfolioListingFiltersToQuery(query, flags);
+  if (includeLimit && flags.limit) query.set('limit', String(flags.limit));
+  return { agentKey, query };
+}
+
+function metaPortfolioListingFilters(ctx, flags, capabilities, agentKey) {
+  return {
+    apiBase: ctx.apiBase,
+    agentKey,
+    chainId: flags.chainId ? Number(flags.chainId) : null,
+    networkId: flags.networkId || flags.network || null,
+    chainType: flags.chainType || null,
+    category: flags.category || null,
+    capabilitiesVersion: capabilities?.contractVersion || null,
+  };
+}
+
+async function commandDataSummary(ctx, flags, capabilities) {
+  const { agentKey, query } = buildAgentKeyPortfolioSummaryQuery(flags, { includeLimit: true });
+  const response = await apiGet(ctx, `/api/v1/agent/telemetry/summary?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: 'DATA_SUMMARY_OK',
+    message: 'Agent data summary loaded',
+    data: response,
+    meta: metaPortfolioListingFilters(ctx, flags, capabilities, agentKey),
+  });
+}
+
+async function commandAnalyticsPortfolio(ctx, flags, capabilities) {
+  const { agentKey, query } = buildAgentKeyPortfolioSummaryQuery(flags);
+  const response = await apiGet(ctx, `/api/v1/agent/portfolio/summary?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: 'ANALYTICS_PORTFOLIO_OK',
+    message: 'Agent portfolio summary loaded',
+    data: response,
+    meta: metaPortfolioListingFilters(ctx, flags, capabilities, agentKey),
+  });
+}
+
+async function commandAnalyticsLeaderboard(ctx, flags, capabilities) {
+  const query = new URLSearchParams();
+  const window = flags.window || '7d';
+  const metric = flags.metric || 'roiPct';
+  applySharedPortfolioListingFiltersToQuery(query, flags);
+  query.set('window', String(window));
+  query.set('metric', String(metric));
+  if (flags.limit) query.set('limit', String(flags.limit));
+  const response = await apiGet(ctx, `/api/v1/agent/portfolio/leaderboard?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: 'ANALYTICS_LEADERBOARD_OK',
+    message: 'Agent portfolio leaderboard loaded',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      networkId: flags.networkId || flags.network || null,
+      chainType: flags.chainType || null,
+      category: flags.category || null,
+      window,
+      metric,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandTrackList(ctx, flags, capabilities, kind) {
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const query = new URLSearchParams({ agentKey });
+  if (flags.limit) query.set('limit', String(flags.limit));
+  const response = await apiGet(ctx, `/api/v1/agent/telemetry/${kind}?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: kind === 'events' ? 'TRACK_EVENTS_OK' : 'TRACK_ACTIONS_OK',
+    message: kind === 'events' ? 'Tracked agent events loaded' : 'Tracked agent actions loaded',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      agentKey,
+      kind,
+    },
+  });
+}
+
+async function commandTrackAction(ctx, flags, capabilities) {
+  const agentApiKey = resolveAgentApiKey(flags, 'thirdfy');
+  const action = requireFlag(flags, 'action', 'Missing --action');
+  const payload = {
+    agentApiKey,
+    action,
+    status: String(flags.status || 'observed'),
+  };
+  if (flags.agentKey) payload.agentKey = String(flags.agentKey);
+  if (flags.eventId) payload.eventId = String(flags.eventId);
+  if (flags.idempotencyKey) payload.idempotencyKey = String(flags.idempotencyKey);
+  if (flags.category) payload.category = String(flags.category);
+  if (flags.source) payload.source = String(flags.source);
+  if (flags.provider) payload.provider = String(flags.provider);
+  if (flags.protocol) payload.protocol = String(flags.protocol);
+  if (flags.namespace) payload.namespace = String(flags.namespace);
+  if (flags.actionType) payload.actionType = String(flags.actionType);
+  if (flags.chainId) payload.chainId = Number(flags.chainId);
+  if (flags.amountUsd) payload.amountUsd = Number(flags.amountUsd);
+  if (flags.txHash) payload.txHash = String(flags.txHash);
+  if (flags.userDid) payload.userDid = String(flags.userDid);
+  if (flags.params) payload.params = parseJsonFlag(flags, 'params');
+  if (flags.decision) payload.decision = parseJsonFlag(flags, 'decision');
+  if (flags.proof) payload.proof = parseJsonFlag(flags, 'proof');
+
+  const response = await apiPost(ctx, '/api/v1/agent/telemetry/actions', payload);
+  printEnvelope({
+    success: Boolean(response?.success !== false),
+    code: response?.success === false ? 'TRACK_ACTION_FAILED' : 'TRACK_ACTION_OK',
+    message: response?.success === false ? 'Agent action tracking failed' : 'Agent action tracked',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      action,
+      chainId: payload.chainId || null,
+    },
+  });
+}
+
+  return {
+    commandDataSummary,
+    commandAnalyticsPortfolio,
+    commandAnalyticsLeaderboard,
+    commandTrackList,
+    commandTrackAction,
+  };
+}

package/src/commands/wallet.mjs

@@ -0,0 +1,129 @@
+import { requireFlag } from '../core/args.mjs';
+import { createCliError } from '../core/envelope.mjs';
+import { loadProfileConfig } from '../core/context.mjs';
+
+export function createWalletCommands(deps) {
+  const {
+    resolveActionSelection,
+    prepareActionParamsForFlags,
+    enforceOffchainVenueLaneCompatibility,
+    enforceChainCompatibility,
+    applyHyperliquidAgentWalletAddressDefault,
+    executeManagedWalletRun,
+    executeSelfRun,
+    submitSignedTx,
+    printEnvelope,
+  } = deps;
+
+
+async function commandWalletExecute(ctx, flags, capabilities) {
+  const normalizedFlags = { ...flags, runMode: 'agent_wallet' };
+  const resolved = await resolveActionSelection(ctx, normalizedFlags);
+  prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
+  enforceChainCompatibility(capabilities, normalizedFlags, 'agent_wallet');
+  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet');
+  const skipPreflight = Boolean(normalizedFlags.skipPreflight);
+  const result = await executeManagedWalletRun(ctx, normalizedFlags, resolved, { skipPreflight, managedPreflight });
+  printEnvelope({
+    success: result.success,
+    code: result.success ? 'WALLET_EXECUTED' : result.preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'RUN_FAILED',
+    message: result.success ? 'Managed wallet execution completed' : result.error || 'Managed wallet execution failed',
+    data: result,
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'agent_wallet',
+      idempotencyKey: result.idempotencyKey || null,
+      executionWalletAddress: result.executionWalletAddress || null,
+      profile: ctx.profile || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!result.success) process.exit(1);
+}
+
+
+async function commandWalletSign(ctx, flags, capabilities) {
+  const normalizedFlags = { ...flags, runMode: 'self' };
+  const resolved = await resolveActionSelection(ctx, normalizedFlags);
+  prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
+  enforceChainCompatibility(capabilities, normalizedFlags, 'self');
+  const selfResult = await executeSelfRun(ctx, normalizedFlags, resolved, {
+    skipPreflight: Boolean(normalizedFlags.skipPreflight),
+    runMode: 'self',
+  });
+  printEnvelope({
+    success: selfResult.success,
+    code: selfResult.success ? 'WALLET_SIGN_READY' : selfResult.preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'WALLET_SIGN_FAILED',
+    message: selfResult.success ? 'Unsigned transaction prepared for BYOW signing' : selfResult.error || 'wallet sign failed',
+    data: selfResult,
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      runMode: 'self',
+      profile: ctx.profile || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!selfResult.success) process.exit(1);
+}
+
+
+async function commandWalletSubmit(ctx, flags, capabilities) {
+  const signedTxHex = String(flags.signedTxHex || flags.signedTx || '').trim();
+  if (!signedTxHex) {
+    throw createCliError('MISSING_SIGNED_TX', 'wallet submit requires --signed-tx-hex');
+  }
+  const chainId = Number(flags.chainId || 8453);
+  const rpcUrl = String(
+    flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org'
+  ).trim();
+  const txHash = await submitSignedTx({ rpcUrl, chainId, signedTxHex });
+  printEnvelope({
+    success: true,
+    code: 'WALLET_SUBMITTED',
+    message: 'Signed transaction broadcasted',
+    data: {
+      txHash,
+      chainId,
+      signerMethod: 'byow',
+      executionMode: 'byow_submit',
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      rpcUrl,
+      profile: ctx.profile || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandWalletList(ctx, _flags) {
+  const config = loadProfileConfig();
+  const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  printEnvelope({
+    success: true,
+    code: 'WALLET_LIST_OK',
+    message: 'Linked wallets from local Thirdfy CLI profile',
+    data: {
+      primaryEvmWallet: wallets.primaryEvmWallet || null,
+      evm: Array.isArray(wallets.evm) ? wallets.evm : [],
+      solana: Array.isArray(wallets.solana) ? wallets.solana : [],
+      executionWallets: wallets.executionWallets || config.executionWallets || {},
+      hint: 'Run `thirdfy-agent login email <email>` to refresh linked wallets and agent execution wallets. Fund executionWallets for agent_wallet writes; linked owner wallets are auth identities.',
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+  return {
+    commandWalletExecute,
+    commandWalletSign,
+    commandWalletSubmit,
+    commandWalletList,
+  };
+}

package/src/core/args.mjs

@@ -0,0 +1,68 @@
+import fs from 'fs';
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+    const key = toCamel(token.slice(2));
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    i += 1;
+  }
+  return { flags, positionals };
+}
+
+export function isNonInteractive(flags = {}) {
+  return Boolean(flags.notInteractive || flags.ni || process.env.THIRDFY_NOT_INTERACTIVE === '1');
+}
+
+export function toCamel(input) {
+  return String(input || '')
+    .trim()
+    .replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function loadEnvFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (!(key in process.env)) process.env[key] = value;
+  }
+}
+
+export function requireFlag(flags, key, message) {
+  if (flags[key] === undefined || flags[key] === null || String(flags[key]).trim() === '') {
+    throw new Error(message || `Missing required flag --${key}`);
+  }
+  return flags[key];
+}
+
+export function parseJsonFlag(flags, key) {
+  const raw = flags[key];
+  if (raw === undefined || raw === null || raw === true) return undefined;
+  try {
+    return JSON.parse(String(raw));
+  } catch {
+    throw new Error(`Invalid JSON for --${key}`);
+  }
+}

package/src/core/constants.mjs

@@ -0,0 +1,31 @@
+export const DEFAULT_API_BASE = 'https://api.thirdfy.com';
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
+export const DEFAULT_BITFINEX_BASE_URL = 'https://api.bitfinex.com';
+export const BITFINEX_PERMISSION_PROFILES = {
+  funding: {
+    id: 'funding',
+    credentialRef: 'bitfinex:funding-primary',
+    required: {
+      funding: { read: 1, write: 1 },
+      wallets: { read: 1, write: 0 },
+    },
+  },
+  spot: {
+    id: 'spot',
+    credentialRef: 'bitfinex:spot-primary',
+    required: {
+      orders: { read: 1, write: 1 },
+      wallets: { read: 1, write: 0 },
+    },
+  },
+};
+export const RUN_MODES = ['thirdfy', 'self', 'hybrid', 'agent_wallet'];
+export const HYBRID_WALLET_MODES = ['self', 'agent_wallet'];
+export const CUSTODY_MODES = ['managed', 'external'];
+export const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
+export const PROFILE_DEFAULTS = {
+  personal: 'agent_wallet',
+  builder: 'hybrid',
+  network: 'thirdfy',
+};

package/src/core/context.mjs

@@ -0,0 +1,145 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { DEFAULT_CATALOG_CACHE_TTL_MS, PROFILE_DEFAULTS } from './constants.mjs';
+import { createCliError } from './envelope.mjs';
+import { apiGet } from './http.mjs';
+import {
+  normalizeCustodyMode,
+  normalizeProfileName,
+  normalizeRunMode,
+} from './runMode.mjs';
+
+const catalogCache = new Map();
+
+export function getProfileConfigPath() {
+  return path.join(os.homedir(), '.thirdfy', 'config.json');
+}
+
+export function loadProfileConfig() {
+  try {
+    const raw = fs.readFileSync(getProfileConfigPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+export function persistProfileConfig(config) {
+  const configPath = getProfileConfigPath();
+  const dirPath = path.dirname(configPath);
+  fs.mkdirSync(dirPath, { recursive: true, mode: 0o700 });
+  const payload = `${JSON.stringify(config, null, 2)}\n`;
+  fs.writeFileSync(configPath, payload, { encoding: 'utf8', mode: 0o600 });
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {
+    /* chmod unsupported */
+  }
+  try {
+    fs.chmodSync(dirPath, 0o700);
+  } catch {
+    /* ignore */
+  }
+}
+
+export function clonePlainConfigTree(input) {
+  const obj = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  try {
+    return structuredClone(obj);
+  } catch {
+    return JSON.parse(JSON.stringify(obj));
+  }
+}
+
+export function setNestedConfigValue(config, keyPath, value) {
+  const next = clonePlainConfigTree(config || {});
+  const parts = String(keyPath || '')
+    .split('.')
+    .map((v) => v.trim())
+    .filter(Boolean);
+  const blocked = new Set(['__proto__', 'prototype', 'constructor']);
+  if (parts.some((part) => blocked.has(part))) {
+    throw createCliError(
+      'CONFIG_KEY_INVALID',
+      'Invalid config key path: reserved segments (__proto__, prototype, constructor) are not allowed.'
+    );
+  }
+  if (!parts.length) return next;
+  let cursor = next;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+    const existing = cursor[key];
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key];
+  }
+  const finalKey = parts[parts.length - 1];
+  if (value === undefined || String(value).trim() === '') {
+    delete cursor[finalKey];
+  } else {
+    cursor[finalKey] = String(value);
+  }
+  return next;
+}
+
+export function resolveProfileState(flags) {
+  const persisted = loadProfileConfig();
+  const profile = normalizeProfileName(flags.profile || process.env.THIRDFY_PROFILE || persisted.profile || 'personal');
+  const runMode = normalizeRunMode(
+    flags.runMode ||
+      process.env.THIRDFY_RUN_MODE ||
+      persisted.runMode ||
+      PROFILE_DEFAULTS[profile] ||
+      'thirdfy'
+  );
+  const custodyMode = normalizeCustodyMode(
+    flags.custodyMode || process.env.THIRDFY_CUSTODY_MODE || persisted.custodyMode,
+    runMode
+  );
+  return {
+    profile,
+    runMode,
+    custodyMode,
+    configPath: getProfileConfigPath(),
+  };
+}
+
+export function getCachedActionsCatalogTtlMs() {
+  const fromEnv = Number(process.env.THIRDFY_ACTIONS_CATALOG_CACHE_TTL_MS || '');
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : DEFAULT_CATALOG_CACHE_TTL_MS;
+}
+
+export function extractActions(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 [];
+}
+
+export async function getCachedActionsCatalog(ctx, flags) {
+  const policyAware = Boolean(flags.agentApiKey);
+  const cacheKey = policyAware
+    ? `policy:${ctx.apiBase}:${String(flags.agentApiKey)}`
+    : `public:${ctx.apiBase}`;
+  const ttlMs = getCachedActionsCatalogTtlMs();
+  const now = Date.now();
+  const hit = catalogCache.get(cacheKey);
+  if (hit && hit.expiresAt > now) {
+    return hit.actions;
+  }
+  let endpoint = '/api/v1/agent/actions/catalog';
+  if (policyAware) {
+    endpoint = `/api/v1/agent/actions?agentApiKey=${encodeURIComponent(String(flags.agentApiKey))}`;
+  }
+  const response = await apiGet(ctx, endpoint);
+  const actions = extractActions(response);
+  catalogCache.set(cacheKey, {
+    actions,
+    expiresAt: now + ttlMs,
+  });
+  return actions;
+}

package/src/core/envelope.mjs

@@ -0,0 +1,20 @@
+export function createCliError(code, message, payload = {}) {
+  const error = new Error(message);
+  error.payload = {
+    error: code,
+    blockedReason: code,
+    blockedStage: 'client_validation',
+    ...payload,
+  };
+  return error;
+}
+
+export function printEnvelope(payload, { jsonMode = false } = {}) {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  const status = payload.success ? 'OK' : 'ERROR';
+  process.stdout.write(`[${status}] ${payload.code}: ${payload.message}\n`);
+  process.stdout.write(`${JSON.stringify(payload.data || {}, null, 2)}\n`);
+}