@thirdfy/agent-cli 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Thirdfy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @thirdfy/agent-cli
+
+`@thirdfy/agent-cli` is the standalone command-line product for Thirdfy agent operations.
+Use it to:
+
+- onboard and manage agent keys
+- discover allowed actions (including policy-aware discovery)
+- run governance preflight checks
+- queue execute-intent requests with idempotency
+- poll intent status with stable JSON output for automation
+
+If you want the full developer docs, start here:
+- [Thirdfy Agent CLI docs](https://docs.thirdfy.com/api/thirdfy-agent-cli)
+- [API Reference home](https://docs.thirdfy.com/api)
+- [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
+- [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
+
+## Install
+
+```bash
+npm install -g @thirdfy/agent-cli
+thirdfy-agent --version --json
+```
+
+Run without global install:
+
+```bash
+npx @thirdfy/agent-cli --help
+```
+
+## Quick start
+
+```bash
+export THIRDFY_API_BASE="https://api.thirdfy.com"
+export AGENT_API_KEY="..."
+export THIRDFY_AUTH_TOKEN="..."
+
+thirdfy-agent actions --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --json
+thirdfy-agent preflight --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent run --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --idempotency-key "swap-001" --json
+thirdfy-agent intent-status --api-base "$THIRDFY_API_BASE" --intent-id "<intentId>" --json
+```
+
+## Auth model
+
+- `AGENT_API_KEY`: execution identity and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
+- `THIRDFY_AUTH_TOKEN`: user-scoped onboarding and account/governance operations (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
+
+Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is complete.
+
+## Command groups
+
+- Discovery: `catalogs list`, `actions`
+- Execution: `preflight`, `run`, `intent-status`
+- Onboarding: `agent register`, `agent key rotate`, `agent key revoke`
+- Governance readiness: `delegation upsert`, `delegation status`, `credentials upsert`, `credentials status`
+- Account: `credits balance`
+
+## More docs
+
+- OpenClaw CLI onboarding flow:
+  [docs.thirdfy.com/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli](https://docs.thirdfy.com/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli)
+- Creator platform (agent registration and keys):
+  [thirdfy.com/creator](https://thirdfy.com/creator)
+
+## Development
+
+```bash
+npm run validate:cli-contract-schemas
+npm test
+npm run smoke:cli
+```
+
+## Release
+
+```bash
+npm version patch
+npm publish --access public
+```

package/bin/thirdfy-agent.mjs

@@ -0,0 +1,825 @@
+#!/usr/bin/env node
+
+import { randomUUID } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+
+const require = createRequire(import.meta.url);
+const { normalizeIntentResponse } = require('../src/utils/cli/intentNormalization.cjs');
+const {
+  normalizeDelegationStatus,
+  normalizeCredentialStatus,
+} = require('../src/utils/cli/delegationNormalization.cjs');
+
+const CLI_VERSION = '0.1.0';
+const DEFAULT_API_BASE = 'https://api.thirdfy.com';
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
+const catalogCache = new Map();
+
+const rawArgv = process.argv.slice(2);
+const parsed = parseArgs(rawArgv);
+const globalFlags = parsed.flags;
+const jsonMode = Boolean(globalFlags.json);
+
+if (globalFlags.env) {
+  loadEnvFile(globalFlags.env);
+}
+
+const apiBase = String(globalFlags.apiBase || process.env.THIRDFY_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+const timeoutMs = Number(globalFlags.timeout || process.env.THIRDFY_CLI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
+const verbose = Boolean(globalFlags.verbose);
+
+const context = {
+  apiBase,
+  timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : DEFAULT_TIMEOUT_MS,
+  jsonMode,
+  verbose,
+};
+
+const isEntrypoint = (() => {
+  try {
+    if (!process.argv[1]) return false;
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isEntrypoint) {
+  main().catch((error) => {
+    const statusCode = Number(error?.statusCode || 0) || undefined;
+    const payload = error?.payload && typeof error.payload === 'object' ? error.payload : {};
+    const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
+    const blockedStage = String(payload.blockedStage || '').trim() || undefined;
+    printEnvelope({
+      success: false,
+      code: statusCode ? 'API_REQUEST_FAILED' : 'CLI_UNHANDLED_ERROR',
+      message: error?.message || 'Unhandled CLI error',
+      data: {
+        statusCode,
+        blockedReason,
+        blockedStage,
+        payload,
+      },
+      meta: { version: CLI_VERSION, apiBase: context.apiBase },
+    });
+    process.exit(1);
+  });
+}
+
+async function main() {
+  if (globalFlags.version) {
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'thirdfy-agent version',
+      data: { version: CLI_VERSION },
+      meta: { apiBase: context.apiBase },
+    });
+    return;
+  }
+
+  if (globalFlags.help || parsed.positionals.length === 0) {
+    printHelp();
+    return;
+  }
+
+  const capabilities = await negotiateCapabilities(context);
+  const commandKey = parsed.positionals.slice(0, 2).join(' ');
+  const commandKey3 = parsed.positionals.slice(0, 3).join(' ');
+  const subFlags = parsed.flags;
+
+  switch (commandKey) {
+    case 'catalogs list':
+      await commandCatalogsList(context, subFlags, capabilities);
+      return;
+    case 'credits balance':
+      await commandCreditsBalance(context, subFlags, capabilities);
+      return;
+    case 'delegation upsert':
+      await commandDelegationUpsert(context, subFlags, capabilities);
+      return;
+    case 'delegation status':
+      await commandDelegationStatus(context, subFlags, capabilities);
+      return;
+    case 'credentials upsert':
+      await commandCredentialsUpsert(context, subFlags, capabilities);
+      return;
+    case 'credentials status':
+      await commandCredentialsStatus(context, subFlags, capabilities);
+      return;
+    case 'agent register':
+      await commandAgentRegister(context, subFlags, capabilities);
+      return;
+    default:
+      break;
+  }
+  if (commandKey3 === 'agent key rotate') {
+    await commandAgentKeyRotate(context, subFlags, capabilities);
+    return;
+  }
+  if (commandKey3 === 'agent key revoke') {
+    await commandAgentKeyRevoke(context, subFlags, capabilities);
+    return;
+  }
+
+  const rootCommand = parsed.positionals[0];
+  switch (rootCommand) {
+    case 'actions':
+      await commandActions(context, subFlags, capabilities);
+      return;
+    case 'preflight':
+      await commandPreflight(context, subFlags, capabilities);
+      return;
+    case 'run':
+      await commandRun(context, subFlags, capabilities);
+      return;
+    case 'intent-status':
+      await commandIntentStatus(context, subFlags, capabilities);
+      return;
+    default:
+      printEnvelope({
+        success: false,
+        code: 'UNKNOWN_COMMAND',
+        message: `Unknown command: ${parsed.positionals.join(' ')}`,
+        data: {},
+        meta: { version: CLI_VERSION },
+      });
+      process.exit(1);
+  }
+}
+
+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 };
+}
+
+function toCamel(input) {
+  return String(input || '')
+    .trim()
+    .replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function loadEnvFile(filePath) {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf('=');
+    if (idx <= 0) continue;
+    const key = trimmed.slice(0, idx).trim();
+    const value = trimmed.slice(idx + 1).trim().replace(/^"|"$/g, '');
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function requireFlag(flags, key, message) {
+  if (!flags[key]) {
+    throw new Error(message);
+  }
+  return String(flags[key]).trim();
+}
+
+function parseJsonFlag(flags, key) {
+  const raw = requireFlag(flags, key, `Missing --${key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)}`);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON for --${key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)}`);
+  }
+}
+
+async function commandCatalogsList(ctx, flags, capabilities) {
+  const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
+  const actions = extractActions(response);
+  const catalogs = [];
+  const seen = new Set();
+  for (const action of actions) {
+    const catalog = String(action.catalog || action.catalogId || action.provider || 'default').trim();
+    if (!catalog || seen.has(catalog)) continue;
+    seen.add(catalog);
+    catalogs.push({
+      id: catalog,
+      provider: String(action.provider || '').trim() || undefined,
+    });
+  }
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Catalogs loaded',
+    data: { catalogs },
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandActions(ctx, flags, capabilities) {
+  const policyAware = Boolean(flags.agentApiKey);
+  const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Actions loaded',
+    data: { actions },
+    meta: {
+      apiBase: ctx.apiBase,
+      policyAware,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandPreflight(ctx, flags, capabilities) {
+  const resolved = await resolveActionSelection(ctx, flags);
+  const payload = buildIntentPayload(flags, {
+    validationOnly: true,
+    forceIdempotency: false,
+    resolvedAction: resolved.resolvedAction,
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  printEnvelope({
+    success: normalized.success,
+    code: normalized.success ? 'PREFLIGHT_OK' : 'PREFLIGHT_FAILED',
+    message: normalized.success ? 'Preflight completed' : 'Preflight failed',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      catalog: flags.catalog || null,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+async function commandRun(ctx, flags, capabilities) {
+  const resolved = await resolveActionSelection(ctx, flags);
+  const skipPreflight = Boolean(flags.skipPreflight);
+  if (!skipPreflight) {
+    const preflightPayload = buildIntentPayload(flags, {
+      validationOnly: true,
+      forceIdempotency: false,
+      resolvedAction: resolved.resolvedAction,
+    });
+    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflightNormalized = normalizeIntentResponse(preflight);
+    const blockedCount = preflightNormalized.blocked || 0;
+    if (!preflightNormalized.success || blockedCount > 0) {
+      printEnvelope({
+        success: false,
+        code: 'PREFLIGHT_BLOCKED',
+        message: 'Preflight blocked execution',
+        data: preflightNormalized,
+        meta: {
+          apiBase: ctx.apiBase,
+          catalog: flags.catalog || null,
+          requestedAction: resolved.requestedAction,
+          resolvedAction: resolved.resolvedAction,
+          skippedPreflight: false,
+        },
+      });
+      process.exit(1);
+      return;
+    }
+  }
+
+  const payload = buildIntentPayload(flags, {
+    validationOnly: false,
+    forceIdempotency: true,
+    resolvedAction: resolved.resolvedAction,
+  });
+  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const normalized = normalizeIntentResponse(response);
+  printEnvelope({
+    success: normalized.success,
+    code: normalized.success ? 'RUN_QUEUED' : 'RUN_FAILED',
+    message: normalized.success ? 'Execution intent queued' : 'Execution failed',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: resolved.resolvedAction,
+      idempotencyKey: payload.idempotencyKey || null,
+      skippedPreflight: skipPreflight,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+async function commandIntentStatus(ctx, flags, capabilities) {
+  const intentId = requireFlag(flags, 'intentId', 'Missing --intent-id');
+  const response = await apiGet(ctx, `/api/v1/agent/execute-intent/status?intentId=${encodeURIComponent(intentId)}`);
+  const normalized = normalizeIntentResponse(response);
+  printEnvelope({
+    success: normalized.success,
+    code: normalized.success ? 'OK' : 'INTENT_STATUS_FAILED',
+    message: normalized.success ? 'Intent status loaded' : 'Intent status failed',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      intentId,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+  if (!normalized.success) process.exit(1);
+}
+
+async function commandCreditsBalance(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits balance');
+  const response = await apiGet(ctx, '/api/v1/credits/balance', {
+    Authorization: `Bearer ${authToken}`,
+  });
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Credits balance loaded',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandDelegationUpsert(ctx, flags, capabilities) {
+  const payload = {
+    userDid: requireFlag(flags, 'userDid', 'Missing --user-did'),
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    walletAddress: requireFlag(flags, 'walletAddress', 'Missing --wallet-address'),
+    chainId: Number(flags.chainId || 8453),
+    executionMode: String(flags.executionMode || 'delegated_execution_user'),
+  };
+  if (flags.sessionAccountAddress) payload.sessionAccountAddress = String(flags.sessionAccountAddress).trim();
+  if (flags.sessionAccountType) payload.sessionAccountType = String(flags.sessionAccountType).trim();
+  if (flags.permissionsContext) payload.permissionsContext = String(flags.permissionsContext).trim();
+  if (flags.delegationManager) payload.delegationManager = String(flags.delegationManager).trim();
+  if (flags.permissionsExpiry) payload.permissionsExpiry = String(flags.permissionsExpiry).trim();
+  if (flags.strategyManifestVersion) payload.strategyManifestVersion = String(flags.strategyManifestVersion).trim();
+  if (flags.strategyManifestHash) payload.strategyManifestHash = String(flags.strategyManifestHash).trim();
+  if (flags.modelAConstraints) payload.modelAConstraints = parseJsonFlag(flags, 'modelAConstraints');
+
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/upsert', '/api/v1/agent/agent/delegation/upsert'],
+    body: payload,
+  });
+  printEnvelope({
+    success: Boolean(response?.success !== false),
+    code: response?.updated ? 'DELEGATION_UPDATED' : 'DELEGATION_UPSERTED',
+    message: response?.message || 'Delegation upsert completed',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandDelegationStatus(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for delegation status');
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const chainId = Number(flags.chainId || 8453);
+  const verify = Boolean(flags.verify);
+  const route = verify
+    ? `/api/v1/agent/delegation/verify?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`
+    : `/api/v1/agent/delegation/check?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`;
+  const response = await apiGet(ctx, route, {
+    Authorization: `Bearer ${authToken}`,
+  });
+  const normalized = normalizeDelegationStatus(response);
+  printEnvelope({
+    success: true,
+    code: 'DELEGATION_STATUS_OK',
+    message: 'Delegation status loaded',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      verify,
+      governanceState: normalized.state || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandCredentialsUpsert(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials upsert');
+  const payload = {
+    venue: requireFlag(flags, 'venue', 'Missing --venue'),
+    apiKey: requireFlag(flags, 'apiKey', 'Missing --api-key'),
+    apiSecret: requireFlag(flags, 'apiSecret', 'Missing --api-secret'),
+    credentialType: String(flags.credentialType || 'api_key'),
+    credentialRef: String(flags.credentialRef || ''),
+  };
+  if (flags.passphrase) payload.passphrase = String(flags.passphrase);
+  if (flags.metadata) payload.metadata = parseJsonFlag(flags, 'metadata');
+  if (flags.policy) payload.policy = parseJsonFlag(flags, 'policy');
+  if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
+  if (flags.chainId) payload.chainId = Number(flags.chainId);
+
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/credentials/upsert', '/api/v1/agent/agent/delegation/credentials/upsert'],
+    body: payload,
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+    },
+  });
+  printEnvelope({
+    success: Boolean(response?.success !== false),
+    code: 'CREDENTIALS_UPSERTED',
+    message: 'Delegation credential upsert completed',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandCredentialsStatus(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials status');
+  const query = new URLSearchParams();
+  if (flags.venue) query.set('venue', String(flags.venue));
+  if (flags.credentialType) query.set('credentialType', String(flags.credentialType));
+  if (flags.credentialRef) query.set('credentialRef', String(flags.credentialRef));
+  const suffix = query.toString() ? `?${query.toString()}` : '';
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'GET',
+    routes: [
+      `/api/v1/agent/delegation/credentials/status${suffix}`,
+      `/api/v1/agent/agent/delegation/credentials/status${suffix}`,
+    ],
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+    },
+  });
+  const normalized = normalizeCredentialStatus(response);
+  printEnvelope({
+    success: true,
+    code: 'CREDENTIALS_STATUS_OK',
+    message: 'Delegation credential status loaded',
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      governanceState: normalized.state || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandAgentRegister(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent register');
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    name: requireFlag(flags, 'name', 'Missing --name'),
+  };
+  if (flags.email) payload.email = String(flags.email);
+  if (flags.bio) payload.bio = String(flags.bio);
+  if (flags.website) payload.website = String(flags.website);
+  if (flags.github) payload.github = String(flags.github);
+  if (flags.tags) {
+    payload.tags = String(flags.tags)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  if (flags.strategy) payload.strategy = parseJsonFlag(flags, 'strategy');
+  if (flags.apiKeyEnvelopePublicKey) payload.apiKeyEnvelopePublicKey = String(flags.apiKeyEnvelopePublicKey);
+
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/register-with-privy', payload, {
+    Authorization: `Bearer ${authToken}`,
+  });
+  printEnvelope({
+    success: true,
+    code: 'AGENT_REGISTERED',
+    message: 'Agent registered',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandAgentKeyRotate(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key rotate');
+  const payload = {};
+  if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/rotate', payload, {
+    Authorization: `Bearer ${authToken}`,
+  });
+  printEnvelope({
+    success: true,
+    code: 'AGENT_KEY_ROTATED',
+    message: 'Agent API key rotated',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandAgentKeyRevoke(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key revoke');
+  const payload = {};
+  if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/revoke', payload, {
+    Authorization: `Bearer ${authToken}`,
+  });
+  printEnvelope({
+    success: true,
+    code: 'AGENT_KEY_REVOKED',
+    message: 'Agent API key revoked',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+function buildIntentPayload(flags, options) {
+  const payload = {
+    agentApiKey: requireFlag(flags, 'agentApiKey', 'Missing --agent-api-key'),
+    action: String(options.resolvedAction || requireFlag(flags, 'action', 'Missing --action')).trim(),
+    params: parseJsonFlag(flags, 'params'),
+  };
+  if (flags.catalog) payload.catalog = String(flags.catalog).trim();
+  if (flags.chainId) payload.chainId = Number(flags.chainId);
+  if (flags.estimatedAmountUsd) payload.estimatedAmountUsd = Number(flags.estimatedAmountUsd);
+  if (flags.userDid) payload.userDid = String(flags.userDid);
+  if (options.validationOnly) payload.executionLane = 'validation_only';
+  if (options.forceIdempotency) {
+    payload.idempotencyKey = String(flags.idempotencyKey || `cli:${payload.action}:${Date.now()}:${randomUUID()}`);
+  } else if (flags.idempotencyKey) {
+    payload.idempotencyKey = String(flags.idempotencyKey);
+  }
+  return payload;
+}
+
+function getActionKey(action) {
+  return String(action?.action || action?.id || action?.key || action?.name || '')
+    .trim();
+}
+
+function getActionAliases(action) {
+  if (!Array.isArray(action?.aliases)) return [];
+  return action.aliases
+    .map((v) => String(v || '').trim())
+    .filter(Boolean);
+}
+
+function getCachedActionsCatalogTtlMs() {
+  const raw = Number(process.env.THIRDFY_CLI_CATALOG_CACHE_TTL_MS || DEFAULT_CATALOG_CACHE_TTL_MS);
+  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_CATALOG_CACHE_TTL_MS;
+  return raw;
+}
+
+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;
+}
+
+function formatActionList(items) {
+  return items
+    .map((v) => `\`${v}\``)
+    .join(', ');
+}
+
+function applyActionFilters(actions, flags) {
+  let filtered = actions;
+  if (flags.catalog) {
+    const expectedCatalog = String(flags.catalog).trim().toLowerCase();
+    filtered = filtered.filter((a) => String(a.catalog || a.catalogId || 'default').trim().toLowerCase() === expectedCatalog);
+  }
+  if (flags.provider) {
+    const expectedProvider = String(flags.provider).trim().toLowerCase();
+    filtered = filtered.filter((a) => String(a.provider || '').trim().toLowerCase() === expectedProvider);
+  }
+  return filtered;
+}
+
+async function resolveActionSelection(ctx, flags) {
+  const requestedAction = requireFlag(flags, 'action', 'Missing --action');
+  const requestedLower = requestedAction.toLowerCase();
+  const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  const keyed = actions
+    .map((action) => ({
+      key: getActionKey(action),
+      aliases: getActionAliases(action),
+    }))
+    .filter((entry) => entry.key);
+
+  if (!keyed.length) {
+    return { requestedAction, resolvedAction: requestedAction };
+  }
+
+  const exact = keyed.filter(
+    (entry) => entry.key.toLowerCase() === requestedLower || entry.aliases.some((a) => a.toLowerCase() === requestedLower)
+  );
+  if (exact.length === 1) {
+    return { requestedAction, resolvedAction: exact[0].key };
+  }
+  if (exact.length > 1) {
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(exact.map((v) => v.key))}.`
+    );
+  }
+
+  const fuzzy = keyed.filter(
+    (entry) =>
+      entry.key.toLowerCase().includes(requestedLower) ||
+      entry.aliases.some((a) => a.toLowerCase().includes(requestedLower))
+  );
+  if (fuzzy.length === 1) {
+    return { requestedAction, resolvedAction: fuzzy[0].key };
+  }
+  if (fuzzy.length > 1) {
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Did you mean one of: ${formatActionList(
+        fuzzy.slice(0, 10).map((v) => v.key)
+      )}?`
+    );
+  }
+  throw new Error(
+    `Unknown --action "${requestedAction}". No compatible action found in current catalog/provider scope.`
+  );
+}
+
+function getAuthToken(flags, missingMessage) {
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  if (!authToken) throw new Error(missingMessage);
+  return authToken;
+}
+
+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 [];
+}
+
+async function negotiateCapabilities(ctx) {
+  try {
+    const response = await apiGet(ctx, '/api/v1/agent/cli/capabilities');
+    return response;
+  } catch (error) {
+    if (ctx.verbose) {
+      process.stderr.write(`capabilities negotiation skipped: ${error.message}\n`);
+    }
+    return null;
+  }
+}
+
+async function apiGet(ctx, route, headers = {}) {
+  return requestJson(ctx, route, { method: 'GET', headers });
+}
+
+async function apiPost(ctx, route, body, headers = {}) {
+  return requestJson(ctx, route, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+async function requestJson(ctx, route, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ctx.timeoutMs);
+  try {
+    const response = await fetch(`${ctx.apiBase}${route}`, {
+      ...init,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const data = text ? safeJsonParse(text) : {};
+    if (!response.ok) {
+      const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
+      error.statusCode = response.status;
+      error.payload = data;
+      throw error;
+    }
+    return data;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function requestWithRouteFallback(ctx, options) {
+  const routes = Array.isArray(options.routes) ? options.routes : [];
+  let lastError = null;
+  for (const route of routes) {
+    try {
+      if (options.method === 'GET') {
+        return await apiGet(ctx, route, options.headers || {});
+      }
+      if (options.method === 'POST') {
+        return await apiPost(ctx, route, options.body || {}, options.headers || {});
+      }
+      throw new Error(`Unsupported method for fallback request: ${options.method}`);
+    } catch (error) {
+      lastError = error;
+      const statusCode = Number(error?.statusCode || 0);
+      if (statusCode !== 404) throw error;
+    }
+  }
+  throw lastError || new Error('No route variants succeeded');
+}
+
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function printEnvelope(payload) {
+  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`);
+}
+
+function printHelp() {
+  const help = `
+thirdfy-agent ${CLI_VERSION}
+
+Core commands:
+  thirdfy-agent catalogs list [--json]
+  thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--json]
+  thirdfy-agent delegation upsert --user-did <did> --agent-key <key> --wallet-address <addr> [--json]
+  thirdfy-agent delegation status --auth-token <token> --agent-key <key> [--verify] [--json]
+  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
+  thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
+  thirdfy-agent agent register --auth-token <token> --agent-key <key> --name <name> [--json]
+  thirdfy-agent agent key rotate --auth-token <token> [--agent-key <key>] [--json]
+  thirdfy-agent agent key revoke --auth-token <token> [--agent-key <key>] [--json]
+  thirdfy-agent preflight --agent-api-key <key> --action <id> --params <json> [--json]
+  thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--idempotency-key <key>] [--json]
+  thirdfy-agent intent-status --intent-id <id> [--json]
+  thirdfy-agent credits balance --auth-token <token> [--json]
+
+Global flags:
+  --api-base <url>   default: https://api.thirdfy.com
+  --env <file>       load env vars from file
+  --timeout <ms>     request timeout
+  --json             stable machine-readable output
+  --verbose          print adapter diagnostics
+  --version          print version
+`.trim();
+  process.stdout.write(`${help}\n`);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@thirdfy/agent-cli",
+  "version": "0.1.0",
+  "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
+  "type": "module",
+  "bin": {
+    "thirdfy-agent": "./bin/thirdfy-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/utils/cli/",
+    "src/contracts/cli/schemas/",
+    "scripts/validate-cli-contract-schemas.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.cjs\"",
+    "lint": "node --check ./bin/thirdfy-agent.mjs",
+    "validate:cli-contract-schemas": "node ./scripts/validate-cli-contract-schemas.mjs",
+    "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
+    "prepublishOnly": "npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
+  },
+  "keywords": [
+    "thirdfy",
+    "cli",
+    "agent",
+    "defi"
+  ],
+  "author": "Thirdfy",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thirdfy/agent-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thirdfy/agent-cli/issues"
+  },
+  "homepage": "https://github.com/thirdfy/agent-cli#readme"
+}

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+
+const SCHEMA_DIR = path.resolve(process.cwd(), 'src/contracts/cli/schemas');
+const REQUIRED_FILES = [
+  'actions.response.schema.json',
+  'preflight.response.schema.json',
+  'execute-intent.response.schema.json',
+  'intent-status.response.schema.json',
+];
+
+const REQUIRED_KEYS = ['$schema', 'title', 'type'];
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(SCHEMA_DIR)) {
+  fail(`Schema directory missing: ${SCHEMA_DIR}`);
+}
+
+for (const fileName of REQUIRED_FILES) {
+  const filePath = path.join(SCHEMA_DIR, fileName);
+  if (!fs.existsSync(filePath)) {
+    fail(`Missing schema file: ${fileName}`);
+  }
+  const raw = fs.readFileSync(filePath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    fail(`Invalid JSON in ${fileName}: ${error.message}`);
+  }
+
+  for (const key of REQUIRED_KEYS) {
+    if (!(key in parsed)) {
+      fail(`Missing key "${key}" in ${fileName}`);
+    }
+  }
+
+  if (!parsed.properties || typeof parsed.properties !== 'object') {
+    fail(`Schema ${fileName} must include top-level "properties" object`);
+  }
+}
+
+process.stdout.write('CLI schema snapshots are valid.\n');

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Critical Endpoint: actions",
+  "type": "object",
+  "required": [
+    "actions"
+  ],
+  "properties": {
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "action"
+        ],
+        "properties": {
+          "action": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "requiredParams": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "paramsSchema": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "catalog": {
+            "type": "string"
+          },
+          "catalogId": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/execute-intent.response.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Critical Endpoint: execute-intent",
+  "type": "object",
+  "required": [
+    "success",
+    "results"
+  ],
+  "properties": {
+    "success": {
+      "type": "boolean"
+    },
+    "intentId": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "total": {
+      "type": "number"
+    },
+    "executed": {
+      "type": "number"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "success"
+        ],
+        "properties": {
+          "success": {
+            "type": "boolean"
+          },
+          "txHash": {
+            "type": "string"
+          },
+          "resultType": {
+            "type": "string"
+          },
+          "blockedReason": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "error": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/intent-status.response.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Critical Endpoint: intent-status",
+  "type": "object",
+  "required": [
+    "success"
+  ],
+  "properties": {
+    "success": {
+      "type": "boolean"
+    },
+    "intentId": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "total": {
+      "type": "number"
+    },
+    "executed": {
+      "type": "number"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "error": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI Critical Endpoint: preflight (execute-intent validation_only)",
+  "type": "object",
+  "required": [
+    "success",
+    "results"
+  ],
+  "properties": {
+    "success": {
+      "type": "boolean"
+    },
+    "intentId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "type": "string"
+    },
+    "total": {
+      "type": "number"
+    },
+    "executed": {
+      "type": "number"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "success"
+        ],
+        "properties": {
+          "success": {
+            "type": "boolean"
+          },
+          "resultType": {
+            "type": "string"
+          },
+          "blockedReason": {
+            "type": "string"
+          },
+          "blockedStage": {
+            "type": "string"
+          },
+          "userDid": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "error": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

package/src/utils/cli/delegationNormalization.cjs

@@ -0,0 +1,40 @@
+function normalizeDelegationStatus(response) {
+  const data = response?.data && typeof response.data === 'object' ? response.data : response || {};
+  const raw = String(data?.status || data?.dbStatus || '').trim().toUpperCase();
+  const state = mapDelegationState(raw);
+  return {
+    state,
+    rawStatus: raw || null,
+    data,
+  };
+}
+
+function mapDelegationState(raw) {
+  if (!raw) return 'UNKNOWN';
+  if (raw === 'ACTIVE') return 'ACTIVE';
+  if (raw.includes('MISSING') && raw.includes('DELEGATION')) return 'MISSING_DELEGATION';
+  if (raw.includes('EXPIRED') && raw.includes('DELEGATION')) return 'EXPIRED_DELEGATION';
+  if (raw.includes('REVOKED') && raw.includes('DELEGATION')) return 'REVOKED_DELEGATION';
+  if (raw.includes('MISSING') && raw.includes('CREDENTIAL')) return 'MISSING_CREDENTIAL';
+  if (raw.includes('POLICY') && raw.includes('DEN')) return 'POLICY_DENIED';
+  if (raw.includes('CREDIT') && raw.includes('BLOCK')) return 'CREDITS_BLOCKED';
+  if (raw.includes('ACTION') && raw.includes('RAIL')) return 'ACTION_UNSUPPORTED_ON_RAIL';
+  return raw;
+}
+
+function normalizeCredentialStatus(response) {
+  const container = response?.data && typeof response.data === 'object' ? response.data : response || {};
+  const items = Array.isArray(container.items) ? container.items : [];
+  const active = items.filter((item) => String(item?.status || '').trim().toLowerCase() === 'active').length;
+  return {
+    state: active > 0 ? 'ACTIVE' : 'MISSING_CREDENTIAL',
+    total: items.length,
+    active,
+    items,
+  };
+}
+
+module.exports = {
+  normalizeDelegationStatus,
+  normalizeCredentialStatus,
+};

package/src/utils/cli/intentNormalization.cjs

@@ -0,0 +1,39 @@
+function summarizeBlockedReasons(results) {
+  const grouped = {};
+  for (const row of results) {
+    const reason = String(row?.blockedReason || '').trim();
+    if (!reason) continue;
+    grouped[reason] = (grouped[reason] || 0) + 1;
+  }
+  return grouped;
+}
+
+function normalizeIntentResponse(response) {
+  const results = Array.isArray(response?.results) ? response.results : [];
+  const isBlockedResult = (r) => {
+    const hasBlockedReason = String(r?.blockedReason || '').trim().length > 0;
+    return r?.resultType === 'blocked' || hasBlockedReason;
+  };
+  const blocked = results.filter(isBlockedResult).length;
+  const failed = results.filter((r) => !isBlockedResult(r) && (r?.resultType === 'failed' || r?.success === false)).length;
+  const executed = Number(response?.executed || 0);
+  const total = Number(response?.total || results.length || 0);
+  const success = Boolean(response?.success);
+  return {
+    success,
+    status: response?.status || (success ? 'queued' : 'failed'),
+    intentId: response?.intentId || null,
+    total,
+    executed,
+    blocked,
+    failed,
+    results,
+    blockedByReason: summarizeBlockedReasons(results),
+    error: response?.error || null,
+  };
+}
+
+module.exports = {
+  normalizeIntentResponse,
+  summarizeBlockedReasons,
+};