@thirdfy/agent-cli 0.1.48 → 0.2.1

package/src/commands/credentials.mjs

@@ -0,0 +1,102 @@
+import { createRequire } from 'module';
+import { requireFlag, parseJsonFlag } from '../core/args.mjs';
+import { requestWithRouteFallback } from '../core/http.mjs';
+import { createCliError } from '../core/envelope.mjs';
+import { BITFINEX_PERMISSION_PROFILES, DEFAULT_BITFINEX_BASE_URL } from '../core/constants.mjs';
+import { parseBooleanFlag } from '../core/runMode.mjs';
+
+const require = createRequire(import.meta.url);
+const { normalizeCredentialStatus } = require('../utils/cli/delegationNormalization.cjs');
+export function createCredentialsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders, probeBitfinexPermissions }) {
+async function commandCredentialsUpsert(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials upsert');
+  const venue = requireFlag(flags, 'venue', 'Missing --venue');
+  const permissionProfile = String(flags.permissionProfile || 'funding').trim().toLowerCase();
+  const bitfinexProfile =
+    String(venue).trim().toLowerCase() === 'bitfinex'
+      ? BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding
+      : null;
+  const payload = {
+    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 || bitfinexProfile?.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 probeEnabled =
+    String(venue).trim().toLowerCase() === 'bitfinex' &&
+    !parseBooleanFlag(flags.skipPermissionsProbe, false) &&
+    parseBooleanFlag(flags.verifyPermissions, true);
+  let permissionProbe = null;
+  if (probeEnabled) {
+    permissionProbe = await probeBitfinexPermissions({
+      apiKey: payload.apiKey,
+      apiSecret: payload.apiSecret,
+      permissionProfile: bitfinexProfile?.id || 'funding',
+      timeoutMs: ctx.timeoutMs,
+      baseUrl: String(flags.bitfinexBaseUrl || process.env.BITFINEX_BASE_URL || DEFAULT_BITFINEX_BASE_URL),
+    });
+  }
+
+  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,
+      permissionProbe,
+      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,
+    },
+  });
+}
+
+  return {
+    commandCredentialsUpsert,
+    commandCredentialsStatus,
+  };
+}

package/src/commands/delegation.mjs

@@ -0,0 +1,355 @@
+import { requireFlag, parseJsonFlag } from '../core/args.mjs';
+import { createCliError } from '../core/envelope.mjs';
+import { getEffectiveRunMode } from '../core/runMode.mjs';
+import { apiGet, apiPost, requestWithRouteFallback } from '../core/http.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { normalizeDelegationStatus } = require('../utils/cli/delegationNormalization.cjs');
+
+export function createDelegationCommands(deps) {
+  const {
+    buildOwnerAuthHeaders,
+    printEnvelope,
+    commandRun,
+  } = deps;
+
+
+async function commandDelegationCreate(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation create'
+  );
+  let sessionAccountAddress = String(flags.sessionAccountAddress || '').trim();
+  if (!sessionAccountAddress) {
+    try {
+      const executorAddressResponse = await apiGet(ctx, '/api/v1/agent/delegation/executor-address', {
+        ...authHeaders,
+      });
+      sessionAccountAddress = String(executorAddressResponse?.data?.executorAddress || '').trim();
+    } catch (error) {
+      if (ctx.verbose) {
+        process.stderr.write(
+          `delegation create: executor-address discovery failed, falling back to --session-account-address (${error?.message || 'unknown error'})\n`
+        );
+      }
+    }
+  }
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    ownerAddress: String(flags.ownerAddress || flags.walletAddress || '').trim() || requireFlag(flags, 'ownerAddress', 'Missing --owner-address'),
+    sessionAccountAddress: sessionAccountAddress || requireFlag(flags, 'sessionAccountAddress', 'Missing --session-account-address'),
+    chainId: Number(flags.chainId || 8453),
+    tokenAddress: requireFlag(flags, 'tokenAddress', 'Missing --token-address'),
+    maxUsdPerDay: Number(requireFlag(flags, 'maxUsdPerDay', 'Missing --max-usd-per-day')),
+    periodDuration: Number(flags.periodDuration || 86_400),
+    expirySeconds: Number(flags.expirySeconds || 86_400),
+  };
+  const response = await apiPost(ctx, '/api/v1/agent/delegation/create', payload, {
+    ...authHeaders,
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_CREATED' : 'DELEGATION_CREATE_FAILED',
+    message: response?.message || (success ? 'Delegation payload created' : 'Delegation create failed'),
+    data: {
+      ...response,
+      delegationModel: 'gator_erc7710',
+      nextSteps: success
+        ? [
+            'Sign data.delegation with the external wallet or OWS account that owns --owner-address.',
+            'Run `thirdfy-agent delegation activate --agent-key <key> --wallet-address <owner> --session-account-address <delegate> --delegation-manager <manager> --delegation <json> --signature <hex>`.',
+            'Verify with `thirdfy-agent delegation inspect --agent-key <key> --verify`, then use `delegation redeem` or run with --run-mode hybrid|thirdfy for delegated execution.',
+          ]
+        : [],
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationInitCustodial(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation init-custodial'
+  );
+  const payload = {
+    chainId: Number(flags.chainId || 8453),
+  };
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/init-custodial'],
+    body: payload,
+    headers: {
+      ...authHeaders,
+    },
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_CUSTODIAL_INITIALIZED' : 'DELEGATION_CUSTODIAL_INIT_FAILED',
+    message: response?.message || (success ? 'Custodial wallet initialized' : 'Custodial wallet init failed'),
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationCustodialGrant(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation custodial-grant'
+  );
+  const payload = {
+    chainId: Number(flags.chainId || 8453),
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    tokenAddress: requireFlag(flags, 'tokenAddress', 'Missing --token-address'),
+    maxUsdPerDay: Number(requireFlag(flags, 'maxUsdPerDay', 'Missing --max-usd-per-day')),
+    periodDuration: Number(flags.periodDuration || 86_400),
+    expirySeconds: Number(flags.expirySeconds || 86_400),
+  };
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/custodial-grant'],
+    body: payload,
+    headers: {
+      ...authHeaders,
+    },
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_CUSTODIAL_GRANTED' : 'DELEGATION_CUSTODIAL_GRANT_FAILED',
+    message: response?.message || (success ? 'Custodial delegation granted' : 'Custodial delegation grant failed'),
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationActivate(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation activate'
+  );
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    walletAddress: requireFlag(flags, 'walletAddress', 'Missing --wallet-address'),
+    sessionAccountAddress: requireFlag(flags, 'sessionAccountAddress', 'Missing --session-account-address'),
+    sessionAccountType: String(flags.sessionAccountType || 'smart').trim(),
+    chainId: Number(flags.chainId || 8453),
+    delegationManager: requireFlag(flags, 'delegationManager', 'Missing --delegation-manager'),
+    signature: requireFlag(flags, 'signature', 'Missing --signature'),
+  };
+  const delegation = parseJsonFlag(flags, 'delegation');
+  payload.delegation = delegation;
+  if (flags.permissionsExpiry) payload.permissionsExpiry = String(flags.permissionsExpiry).trim();
+  if (flags.permissionsContext) payload.permissionsContext = String(flags.permissionsContext).trim();
+  if (flags.permission) payload.permission = parseJsonFlag(flags, 'permission');
+  if (flags.permissionType) payload.permissionType = String(flags.permissionType).trim();
+  if (flags.permissionData) payload.permissionData = parseJsonFlag(flags, 'permissionData');
+  if (flags.modelAConstraints) payload.modelAConstraints = parseJsonFlag(flags, 'modelAConstraints');
+  const response = await apiPost(ctx, '/api/v1/agent/delegation/activate', payload, {
+    ...authHeaders,
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_ACTIVATED' : 'DELEGATION_ACTIVATE_FAILED',
+    message: response?.message || (success ? 'Delegation activated' : 'Delegation activate failed'),
+    data: {
+      ...response,
+      delegationModel: 'gator_erc7710',
+      nextSteps: success
+        ? [
+            'Run `thirdfy-agent delegation inspect --agent-key <key> --verify` to confirm period allowance and revocation state.',
+            'Use `thirdfy-agent delegation redeem --run-mode hybrid|thirdfy ...` when Thirdfy/session executor should act under this external-wallet delegation.',
+          ]
+        : [],
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationStatus(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_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, {
+    ...authHeaders,
+  });
+  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 commandDelegationInspect(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation inspect'
+  );
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const chainId = Number(flags.chainId || 8453);
+  const includeOnchain = Boolean(flags.verify || flags.includeOnchain || flags.onchain);
+  const checkRoute = `/api/v1/agent/delegation/check?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`;
+  const checkResponse = await apiGet(ctx, checkRoute, {
+    ...authHeaders,
+  });
+  const checkNormalized = normalizeDelegationStatus(checkResponse);
+
+  let verifyNormalized = null;
+  if (includeOnchain) {
+    const verifyRoute = `/api/v1/agent/delegation/verify?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`;
+    const verifyResponse = await apiGet(ctx, verifyRoute, {
+      ...authHeaders,
+    });
+    verifyNormalized = normalizeDelegationStatus(verifyResponse);
+  }
+
+  printEnvelope({
+    success: true,
+    code: 'DELEGATION_INSPECT_OK',
+    message: includeOnchain ? 'Delegation inspect loaded (with onchain verification)' : 'Delegation inspect loaded',
+    data: {
+      check: checkNormalized,
+      verify: verifyNormalized,
+      state: verifyNormalized?.state || checkNormalized.state,
+      rawStatus: verifyNormalized?.rawStatus || checkNormalized.rawStatus,
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      includeOnchain,
+      governanceState: verifyNormalized?.state || checkNormalized.state || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationRevoke(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation revoke'
+  );
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    reason: String(flags.reason || 'user_revoked').trim(),
+    chainId: Number(flags.chainId || 8453),
+  };
+  const response = await requestWithRouteFallback(ctx, {
+    method: 'POST',
+    routes: ['/api/v1/agent/delegation/revoke'],
+    body: payload,
+    headers: {
+      ...authHeaders,
+    },
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_REVOKED' : 'DELEGATION_REVOKE_FAILED',
+    message: response?.message || (success ? 'Delegation revoked' : 'Delegation revoke failed'),
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationBalance(ctx, flags, capabilities) {
+  const authHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing --auth-token/--owner-session-token (or THIRDFY_AUTH_TOKEN/THIRDFY_OWNER_SESSION_TOKEN) for delegation balance'
+  );
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const chainId = Number(flags.chainId || 8453);
+  const route = `/api/v1/agent/delegation/verify?agentKey=${encodeURIComponent(agentKey)}&chainId=${encodeURIComponent(String(chainId))}`;
+  const response = await apiGet(ctx, route, {
+    ...authHeaders,
+  });
+  const normalized = normalizeDelegationStatus(response);
+  const verifyData = normalized?.data?.onChainVerification || {};
+  printEnvelope({
+    success: true,
+    code: 'DELEGATION_BALANCE_OK',
+    message: 'Delegation allowance balance loaded',
+    data: {
+      state: normalized.state,
+      rawStatus: normalized.rawStatus,
+      delegatedWalletAddress: normalized?.data?.delegatedWalletAddress || null,
+      periodAvailableUsd: verifyData?.periodAvailableUsd ?? null,
+      periodAvailableBaseUnits: verifyData?.periodAvailableBaseUnits ?? null,
+      verified: verifyData?.verified ?? null,
+      isRevoked: verifyData?.isRevoked ?? null,
+      onChainVerification: verifyData || null,
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      governanceState: normalized.state || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDelegationRedeem(ctx, flags, capabilities) {
+  const selectedRunMode = getEffectiveRunMode(ctx, flags);
+  if (!['thirdfy', 'hybrid', 'agent_wallet'].includes(selectedRunMode)) {
+    throw createCliError('DELEGATION_REDEEM_MODE_INVALID', 'delegation redeem supports only --run-mode thirdfy|hybrid|agent_wallet');
+  }
+  const delegatedFlags = {
+    ...flags,
+    runMode: selectedRunMode,
+  };
+  if (!delegatedFlags.estimatedAmountUsd) {
+    delegatedFlags.estimatedAmountUsd = '5';
+  }
+  await commandRun(ctx, delegatedFlags, capabilities);
+}
+
+  return {
+    commandDelegationCreate,
+    commandDelegationInitCustodial,
+    commandDelegationCustodialGrant,
+    commandDelegationActivate,
+    commandDelegationStatus,
+    commandDelegationInspect,
+    commandDelegationRevoke,
+    commandDelegationBalance,
+    commandDelegationRedeem,
+  };
+}

package/src/commands/discovery.mjs

@@ -0,0 +1,77 @@
+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';
+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');
+  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);
+  const providerHint = getTradingProviderHint(flags.provider);
+  const effectiveRunMode = getEffectiveRunMode(ctx, flags);
+  const chainIdFilter = Number(flags.chainId || 0) || undefined;
+  const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Actions loaded',
+    data: { actions, ...(providerHint ? { providerHint } : {}) },
+    meta: {
+      apiBase: ctx.apiBase,
+      policyAware,
+      runMode: effectiveRunMode,
+      profile: ctx.profile || null,
+      chainCompatibility: chainSupport,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+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,
+    },
+  });
+}
+
+  return {
+    commandCatalogsList,
+    commandActions,
+    commandCreditsBalance,
+  };
+}