@thirdfy/agent-cli 0.4.3 → 0.5.0

package/src/core/context.mjs

@@ -4,6 +4,7 @@ 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 { apiBaseFor, oauthSessionForApi, oauthSessionIsAgentCredential } from './oauth/session.mjs';
 import {
   normalizeCustodyMode,
   normalizeProfileName,
@@ -121,21 +122,27 @@ export function extractActions(response) {
 }
 
 /**
- * The agent API key from `--agent-api-key`, then THIRDFY_AGENT_API_KEY, then config `agent.apiKey`;
- * empty when none is set. The same order execution uses, without its missing-key error.
+ * The agent credential from `--agent-api-key`, then THIRDFY_AGENT_API_KEY, then the OAuth sign-in
+ * for this API (`thirdfy-agent login`, its access token), then config `agent.apiKey`; empty when
+ * none is set.
+ * The same order execution uses, without its missing-key error. An OAuth token is sent as
+ * `Authorization: Bearer` (and refreshed) by `src/core/http.mjs`.
  */
 export function findAgentApiKey(flags = {}) {
   const explicit = String(flags.agentApiKey || '').trim();
   if (explicit) return explicit;
   const envKey = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
   if (envKey) return envKey;
-  return String(loadProfileConfig()?.agent?.apiKey || '').trim();
+  const config = loadProfileConfig();
+  const oauth = oauthSessionForApi(apiBaseFor(flags), config);
+  if (oauth) return oauth.accessToken;
+  return String(config?.agent?.apiKey || '').trim();
 }
 
 /**
  * Whose credits a credits read is about. Same precedence as `wallet profile`: an owner credential
- * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key, then
- * owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
+ * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key or an
+ * OAuth sign-in, then owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
  * agentApiKeyExplicit }`; `ledger` is `agent` or `owner`.
  */
 export function resolveCreditsLedger(flags = {}) {
@@ -148,7 +155,10 @@ export function resolveCreditsLedger(flags = {}) {
     ).trim(),
   );
   const agentApiKey = findAgentApiKey(flags);
-  const agent = !explicitOwner && (agentApiKeyExplicit || (!storedOwner && Boolean(agentApiKey)));
+  // An OAuth sign-in (`thirdfy-agent login`) is a deliberate choice of one agent: it comes before
+  // owner auth stored in env or config, as an explicit --agent-api-key does.
+  const oauthAgent = oauthSessionIsAgentCredential(flags, process.env, config);
+  const agent = !explicitOwner && (agentApiKeyExplicit || oauthAgent || (!storedOwner && Boolean(agentApiKey)));
   return { ledger: agent ? 'agent' : 'owner', agentApiKey, agentApiKeyExplicit };
 }
 

package/src/core/errorEnvelope.mjs

@@ -20,6 +20,8 @@ export const NEXT_ACTIONS = Object.freeze({
   fund_native_gas: "The execution wallet cannot pay this chain's gas. Fund it with the native coin first.",
   owner_reenable_agent_signer: "The wallet owner removed Thirdfy's signer. The owner must re-enable the agent.",
   use_evm_chain: 'This Thirdfy API does not run that chain family (Solana). Use an EVM chain the API lists in `chains`.',
+  reauthenticate: 'The sign-in expired or was revoked. Sign in again: `thirdfy-agent login`.',
+  reauthenticate_with_trade: 'This sign-in is read-only. Sign in again with trade access: `thirdfy-agent login --trade`.',
 });
 
 /** Credits refusal codes the API sends (HTTP 402). */
@@ -56,6 +58,10 @@ const CLIENT_CODE_FIELDS = Object.freeze({
   SOLANA_NOT_ENABLED: { retryable: false, nextAction: 'use_evm_chain' },
   BROADCAST_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
   EFFECT_CHECK_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
+  OAUTH_SESSION_EXPIRED: { retryable: false, nextAction: 'reauthenticate' },
+  OAUTH_ACCESS_DENIED: { retryable: false, nextAction: 'reauthenticate' },
+  OAUTH_LOGIN_TIMEOUT: { retryable: true, nextAction: 'retry_later' },
+  OAUTH_DISCOVERY_FAILED: { retryable: true, nextAction: 'retry_later' },
 });
 
 const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));

package/src/core/http.mjs

@@ -3,6 +3,7 @@ import {
   mergeExecutionContext,
   resolveExecutionContextFromInput,
 } from './execution/executionContext.mjs';
+import { freshOAuthAccessToken, isOAuthAccessToken, readOAuthSession } from './oauth/session.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -123,7 +124,21 @@ function mergeExecutionContextHeaders(headers = {}, body = {}) {
   };
 }
 
-export async function apiPost(ctx, route, body, headers = {}) {
+/**
+ * Execute payloads carry the agent credential in the body (`agentApiKey`). An OAuth sign-in never
+ * goes in a body: it moves to the header, where `withOAuthBearer` sends it as `Authorization: Bearer`.
+ */
+function moveOAuthCredentialToHeader(body, headers) {
+  const credential = body.agentApiKey ?? body.agent_api_key;
+  if (!isOAuthAccessToken(credential)) return { body, headers };
+  const { agentApiKey: _a, agent_api_key: _b, ...rest } = body;
+  return { body: rest, headers: { 'x-agent-api-key': credential, ...headers } };
+}
+
+export async function apiPost(ctx, route, rawBody, rawHeaders = {}) {
+  const moved = moveOAuthCredentialToHeader(rawBody && typeof rawBody === 'object' ? rawBody : {}, rawHeaders);
+  const body = moved.body;
+  const headers = moved.headers;
   const normalizedBody = body && typeof body === 'object' ? body : {};
   const mergedBody = mergeExecutionContext(normalizedBody);
   return requestJson(ctx, route, {
@@ -136,7 +151,25 @@ export async function apiPost(ctx, route, body, headers = {}) {
   });
 }
 
-async function requestJsonOnce(ctx, route, init) {
+/**
+ * An OAuth sign-in passed as the agent credential (`findAgentApiKey`) goes as
+ * `Authorization: Bearer`, refreshed first when it is about to expire. Owner auth already in
+ * `Authorization` wins; the OAuth token is then not sent.
+ */
+async function withOAuthBearer(ctx, init) {
+  const headers = { ...(init.headers || {}) };
+  const credential = headers['x-agent-api-key'];
+  if (!isOAuthAccessToken(credential)) return { init, oauth: false };
+  const session = readOAuthSession();
+  const token = session?.accessToken === credential ? (await freshOAuthAccessToken({ timeoutMs: ctx.timeoutMs })) || credential : credential;
+  delete headers['x-agent-api-key'];
+  if (!headers.Authorization && !headers.authorization) headers.Authorization = `Bearer ${token}`;
+  return { init: { ...init, headers }, oauth: true };
+}
+
+async function requestJsonOnce(ctx, route, rawInit) {
+  const { __oauthRetried, ...plainInit } = rawInit;
+  const { init, oauth } = await withOAuthBearer(ctx, plainInit);
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), ctx.timeoutMs);
   try {
@@ -147,6 +180,18 @@ async function requestJsonOnce(ctx, route, init) {
     const text = await response.text();
     const data = text ? safeJsonParse(text) : {};
     rememberResponseHeaders(data, response);
+    // A 401 to an OAuth sign-in: refresh once and send again. Nothing ran on a 401, so this is safe
+    // for writes too. A refresh the auth server refuses is OAUTH_SESSION_EXPIRED.
+    if (response.status === 401 && oauth && !__oauthRetried) {
+      const token = await freshOAuthAccessToken({ timeoutMs: ctx.timeoutMs, force: true });
+      if (token) {
+        return await requestJsonOnce(ctx, route, {
+          ...plainInit,
+          headers: { ...(plainInit.headers || {}), 'x-agent-api-key': token },
+          __oauthRetried: true,
+        });
+      }
+    }
     if (!response.ok) {
       const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
       error.statusCode = response.status;

package/src/core/oauth/authServer.mjs

@@ -0,0 +1,192 @@
+import { createCliError } from '../envelope.mjs';
+
+/**
+ * The auth.thirdfy.com calls `thirdfy-agent login` makes: metadata (RFC 8414), client registration
+ * (RFC 7591, a public client with a loopback redirect), the authorize URL, the code exchange and
+ * refresh (PKCE S256, `resource` = the API, RFC 8707), and revocation (RFC 7009).
+ */
+
+const KNOWN_ISSUERS = new Map([
+  ['api.thirdfy.com', 'https://auth.thirdfy.com'],
+  ['api-test.thirdfy.com', 'https://auth-test.thirdfy.com'],
+]);
+
+/** Registered once per issuer; any loopback port matches this redirect. */
+export const CLI_REDIRECT_URI = 'http://127.0.0.1/callback';
+export const CLI_CLIENT_NAME = 'Thirdfy Agent CLI';
+
+const trimSlash = (value) => String(value || '').trim().replace(/\/+$/, '');
+
+/** --issuer, then THIRDFY_AUTH_ISSUER, then the issuer paired with a known API base. */
+export function resolveIssuer(apiBase, flags = {}, env = process.env) {
+  const explicit = trimSlash(flags.issuer || env.THIRDFY_AUTH_ISSUER);
+  if (explicit) return explicit;
+  let host = '';
+  try {
+    host = new URL(apiBase).host;
+  } catch {
+    host = '';
+  }
+  const known = KNOWN_ISSUERS.get(host);
+  if (known) return known;
+  throw createCliError(
+    'OAUTH_ISSUER_REQUIRED',
+    `No sign-in server is known for ${apiBase}. Pass --issuer <url> (or set THIRDFY_AUTH_ISSUER), or sign in with \`thirdfy-agent login email <address>\`.`,
+    { blockedStage: 'auth' },
+  );
+}
+
+async function fetchJson(url, init, timeoutMs, failureCode) {
+  let response;
+  try {
+    response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    throw createCliError(failureCode, `Could not reach ${new URL(url).origin}: ${error?.message || 'network error'}`, {
+      blockedStage: 'auth',
+      retryable: true,
+    });
+  }
+  const text = await response.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = {};
+  }
+  return { response, body };
+}
+
+const oauthError = (code, body, fallback) =>
+  createCliError(code, String(body?.error_description || body?.message || body?.error || fallback), {
+    blockedStage: 'auth',
+    oauthError: body?.error || null,
+  });
+
+/** RFC 8414 metadata, checked for what the CLI needs: the issuer, S256, and the API as a resource. */
+export async function discoverAuthServer(issuer, resource, timeoutMs) {
+  const { response, body } = await fetchJson(
+    `${issuer}/.well-known/oauth-authorization-server`,
+    { headers: { accept: 'application/json' } },
+    timeoutMs,
+    'OAUTH_DISCOVERY_FAILED',
+  );
+  if (!response.ok || trimSlash(body?.issuer) !== issuer || !body?.authorization_endpoint || !body?.token_endpoint) {
+    throw createCliError('OAUTH_DISCOVERY_FAILED', `${issuer} did not answer as a Thirdfy sign-in server (HTTP ${response.status}).`, {
+      blockedStage: 'auth',
+    });
+  }
+  const methods = Array.isArray(body.code_challenge_methods_supported) ? body.code_challenge_methods_supported : [];
+  if (!methods.includes('S256')) {
+    throw createCliError('OAUTH_DISCOVERY_FAILED', `${issuer} does not support PKCE S256.`, { blockedStage: 'auth' });
+  }
+  const resources = Array.isArray(body.protected_resources) ? body.protected_resources.map(trimSlash) : null;
+  if (resources && !resources.includes(trimSlash(resource))) {
+    throw createCliError(
+      'OAUTH_RESOURCE_NOT_SUPPORTED',
+      `${issuer} does not issue sign-ins for ${resource} yet. Use \`thirdfy-agent login email <address>\` for now.`,
+      { blockedStage: 'auth' },
+    );
+  }
+  return body;
+}
+
+/** A public client (no secret) with the loopback redirect, registered once per issuer. */
+export async function registerCliClient(metadata, { version, timeoutMs }) {
+  if (!metadata.registration_endpoint) {
+    throw createCliError('OAUTH_REGISTRATION_UNAVAILABLE', `${metadata.issuer} does not accept client registration.`, {
+      blockedStage: 'auth',
+    });
+  }
+  const { response, body } = await fetchJson(
+    metadata.registration_endpoint,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({
+        client_name: CLI_CLIENT_NAME,
+        redirect_uris: [CLI_REDIRECT_URI],
+        token_endpoint_auth_method: 'none',
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        client_uri: 'https://www.npmjs.com/package/@thirdfy/agent-cli',
+        software_id: 'thirdfy-agent-cli',
+        ...(version ? { software_version: String(version) } : {}),
+      }),
+    },
+    timeoutMs,
+    'OAUTH_REGISTRATION_FAILED',
+  );
+  if (!response.ok || !body?.client_id) throw oauthError('OAUTH_REGISTRATION_FAILED', body, `Client registration failed (HTTP ${response.status}).`);
+  return String(body.client_id);
+}
+
+export function buildAuthorizeUrl(metadata, { clientId, redirectUri, challenge, state, scope, resource }) {
+  const url = new URL(metadata.authorization_endpoint);
+  url.search = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    state,
+    scope,
+    resource,
+  }).toString();
+  return url.toString();
+}
+
+async function tokenRequest(tokenEndpoint, params, timeoutMs, failureCode) {
+  const { response, body } = await fetchJson(
+    tokenEndpoint,
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(params).toString(),
+    },
+    timeoutMs,
+    failureCode,
+  );
+  if (!response.ok || !body?.access_token) {
+    const code = body?.error === 'invalid_grant' ? 'OAUTH_SESSION_EXPIRED' : failureCode;
+    throw oauthError(code, body, `Token request failed (HTTP ${response.status}).`);
+  }
+  return body;
+}
+
+export function exchangeCode(metadata, { clientId, code, redirectUri, verifier, resource }, timeoutMs) {
+  return tokenRequest(
+    metadata.token_endpoint,
+    { grant_type: 'authorization_code', code, redirect_uri: redirectUri, client_id: clientId, code_verifier: verifier, resource },
+    timeoutMs,
+    'OAUTH_CODE_EXCHANGE_FAILED',
+  );
+}
+
+export function refreshTokens({ tokenEndpoint, clientId, refreshToken, resource }, timeoutMs) {
+  return tokenRequest(
+    tokenEndpoint,
+    { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId, ...(resource ? { resource } : {}) },
+    timeoutMs,
+    'OAUTH_REFRESH_FAILED',
+  );
+}
+
+/** RFC 7009: best effort; the answer is 200 even for an unknown token. */
+export async function revokeToken({ revocationEndpoint, clientId, token }, timeoutMs) {
+  if (!revocationEndpoint || !token) return false;
+  try {
+    const { response } = await fetchJson(
+      revocationEndpoint,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ token, client_id: clientId }).toString(),
+      },
+      timeoutMs,
+      'OAUTH_REVOKE_FAILED',
+    );
+    return response.ok;
+  } catch {
+    return false;
+  }
+}

package/src/core/oauth/pkce.mjs

@@ -0,0 +1,17 @@
+import { createHash, randomBytes } from 'crypto';
+
+/** RFC 7636 PKCE (S256 only, as auth.thirdfy.com requires) and the OAuth `state` value. */
+
+export function base64url(bytes) {
+  return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function createPkcePair() {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge, method: 'S256' };
+}
+
+export function createState() {
+  return base64url(randomBytes(16));
+}

package/src/core/oauth/session.mjs

@@ -0,0 +1,117 @@
+import { DEFAULT_API_BASE } from '../constants.mjs';
+import { createCliError } from '../envelope.mjs';
+import { loadProfileConfig, persistProfileConfig } from '../context.mjs';
+import { refreshTokens } from './authServer.mjs';
+
+/**
+ * The OAuth sign-in `thirdfy-agent login` stores in `~/.thirdfy/config.json` (`auth.oauth`, mode
+ * 0600): one agent's access and refresh tokens from auth.thirdfy.com. It is the agent credential
+ * when no `--agent-api-key` or `THIRDFY_AGENT_API_KEY` is set. The HTTP layer sends it as
+ * `Authorization: Bearer` and refreshes it before it expires (rotation: each refresh returns a new
+ * refresh token).
+ */
+
+/** auth.thirdfy.com access tokens: `{userId}:{grantId}:{secret}`. Agent API keys and JWTs never match. */
+const OAUTH_TOKEN_SHAPE = /^[^\s:]+:[^\s:]+:[^\s:]+$/;
+
+/** Refresh when fewer than this many seconds are left, so a command never starts with a dying token. */
+const REFRESH_MARGIN_SECONDS = 120;
+
+export function isOAuthAccessToken(value) {
+  return OAUTH_TOKEN_SHAPE.test(String(value || '').trim());
+}
+
+export function readOAuthSession(config = loadProfileConfig()) {
+  const session = config?.auth?.oauth;
+  if (!session || typeof session !== 'object') return null;
+  if (!isOAuthAccessToken(session.accessToken)) return null;
+  return session;
+}
+
+const trimBase = (value) => String(value || '').trim().replace(/\/+$/, '');
+
+/** The API base a command talks to: --api-base, then THIRDFY_API_BASE, then the default (as runtime/context). */
+export function apiBaseFor(flags = {}, env = process.env) {
+  return trimBase(flags.apiBase || env.THIRDFY_API_BASE || DEFAULT_API_BASE);
+}
+
+/**
+ * The sign-in for this API. A sign-in is issued for one API (its `resource`): one for api-test is
+ * never sent to production, or the reverse.
+ */
+export function oauthSessionForApi(apiBase, config = loadProfileConfig()) {
+  const session = readOAuthSession(config);
+  return session && trimBase(session.resource) === trimBase(apiBase) ? session : null;
+}
+
+/**
+ * The OAuth sign-in acts as the agent unless an agent API key is passed or set in the environment,
+ * and only on the API it was issued for.
+ */
+export function oauthSessionIsAgentCredential(flags = {}, env = process.env, config = loadProfileConfig()) {
+  if (String(flags.agentApiKey || '').trim()) return false;
+  if (String(env.THIRDFY_AGENT_API_KEY || '').trim()) return false;
+  return Boolean(oauthSessionForApi(apiBaseFor(flags, env), config));
+}
+
+export function writeOAuthSession(session) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  persistProfileConfig({ ...config, auth: { ...auth, oauth: session } });
+}
+
+export function clearOAuthSession() {
+  const config = loadProfileConfig();
+  if (!config.auth?.oauth) return;
+  const { oauth: _removed, ...auth } = config.auth;
+  persistProfileConfig({ ...config, auth });
+}
+
+/** The stored session after a token response (code exchange or refresh). */
+export function sessionFromTokens(base, tokens, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiresIn = Number(tokens.expires_in);
+  return {
+    ...base,
+    accessToken: String(tokens.access_token),
+    refreshToken: tokens.refresh_token ? String(tokens.refresh_token) : base.refreshToken || null,
+    expiresAt: Number.isFinite(expiresIn) && expiresIn > 0 ? nowSeconds + expiresIn : null,
+    scope: tokens.scope ? String(tokens.scope) : base.scope || '',
+    obtainedAt: nowSeconds,
+  };
+}
+
+let refreshInFlight = null;
+
+/**
+ * The access token to send, refreshed first when it is about to expire (or when `force`, after the
+ * API answered 401). A refresh the auth server refuses (`invalid_grant`: revoked, or the owner no
+ * longer owns the agent) is `OAUTH_SESSION_EXPIRED`: sign in again.
+ */
+
+export async function freshOAuthAccessToken({ timeoutMs, force = false } = {}) {
+  // One refresh at a time: the refresh token rotates, so a second refresh with the same token
+  // would be refused. Concurrent callers share the first one's result.
+  if (refreshInFlight) return refreshInFlight;
+  const session = readOAuthSession();
+  if (!session) return null;
+  const now = Math.floor(Date.now() / 1000);
+  const expiring = Number.isFinite(Number(session.expiresAt)) && Number(session.expiresAt) - now < REFRESH_MARGIN_SECONDS;
+  if (!force && !expiring) return session.accessToken;
+  if (!session.refreshToken || !session.tokenEndpoint || !session.clientId) {
+    throw createCliError('OAUTH_SESSION_EXPIRED', 'The sign-in expired. Sign in again: thirdfy-agent login', { blockedStage: 'auth' });
+  }
+  refreshInFlight = (async () => {
+    const tokens = await refreshTokens(
+      { tokenEndpoint: session.tokenEndpoint, clientId: session.clientId, refreshToken: session.refreshToken, resource: session.resource },
+      timeoutMs || 30_000,
+    );
+    const next = sessionFromTokens(session, tokens);
+    writeOAuthSession(next);
+    return next.accessToken;
+  })();
+  try {
+    return await refreshInFlight;
+  } finally {
+    refreshInFlight = null;
+  }
+}

package/src/lib/creditsUsdSummary.mjs

@@ -1,54 +1,153 @@
 /**
- * Credits balances and action costs are shown in credits, never as a dollar price per credit or per
- * request (owner decision 2026-10-14; thirdfy-mcp #252 `stripUsdFields`). Buying credits keeps its USD
- * amount (`credits buy --usd`): that is a purchase, not a request price.
+ * Credits are Thirdfy's internal ledger unit; people see a USD balance. The public docs say so
+ * (thirdfy-docs credits page: "Your balance shows in USD; credits are the internal unit") and never
+ * state what an action costs (DOCUMENTATION_GUIDE: no credit costs, no USD-per-credit rate). Owner
+ * rule 2026-10-15; same rules as thirdfy-mcp `usdFirstCredits.ts` (thirdfy/thirdfy-mcp#279).
+ *
+ * `credits balance` and `pricing quote` keep `availableUsd`, free request counts, `wouldBePaidBy` and
+ * `displayCurrency`. Every credit count, per-credit rate and per-action price is dropped, so a reader
+ * can say "$4.20 left" but not "286 credits" or "$0.18 a request". The owner's fallback balance, which
+ * the API sends in credits only, gets an `availableUsd` at the API's own `retailUsdPerCredit` (the rate
+ * the API uses for the agent's `availableUsd`). Buying keeps its USD amount (`credits buy --usd`).
  */
+
+const KEEP_USD = new Set(['availableUsd']);
+/** Credit counts the API names without "credit" (`totalAvailable`: the owner route's balance plus free requests). */
+const CREDIT_COUNTS = new Set(['balance', 'totalEarned', 'totalSpent', 'totalAvailable']);
+const CREDIT_KEY = /credit/i;
 const USD_KEY = /usd/i;
 
-/** The value with every key that names USD (and displayCurrency / pricingCurrency) removed, at any depth. */
-export function stripUsdFields(value) {
-  if (Array.isArray(value)) return value.map(stripUsdFields);
-  if (!value || typeof value !== 'object') return value;
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const finite = (value) => {
+  const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+  return Number.isFinite(n) ? n : undefined;
+};
+
+export const roundUsd = (usd) => Math.round(usd * 100) / 100;
+
+const formatUsd = (amount) => `$${roundUsd(amount).toFixed(2)}`;
+
+/** The API's display rate wherever the payload carries it (top level or `data`). */
+export function retailUsdPerCreditOf(value) {
+  if (!isRecord(value)) return undefined;
+  const own = finite(value.retailUsdPerCredit);
+  if (own !== undefined && own > 0) return own;
+  return isRecord(value.data) ? retailUsdPerCreditOf(value.data) : undefined;
+}
+
+/** A credits amount in USD at the API's rate, or undefined when either is missing. */
+export function usdFromCredits(credits, rate) {
+  const amount = finite(credits);
+  return amount === undefined || rate === undefined ? undefined : roundUsd(amount * rate);
+}
+
+/** The value with balances in USD and no credit count, per-credit rate or per-action price, at any depth. */
+export function toUsdFirst(value, rate = retailUsdPerCreditOf(value)) {
+  if (Array.isArray(value)) return value.map((item) => toUsdFirst(item, rate));
+  if (!isRecord(value)) return value;
   const out = {};
   for (const [key, inner] of Object.entries(value)) {
-    if (USD_KEY.test(key) || key === 'displayCurrency' || key === 'pricingCurrency') continue;
-    out[key] = stripUsdFields(inner);
+    const scalar = !isRecord(inner) && !Array.isArray(inner);
+    if (CREDIT_KEY.test(key) && scalar) continue;
+    if (USD_KEY.test(key) && !KEEP_USD.has(key)) continue;
+    if (CREDIT_COUNTS.has(key) && typeof inner === 'number') continue;
+    // The owner route's ledger unit (`currency: 'credits'`): the balance is shown in USD.
+    if (key === 'currency' && typeof inner === 'string' && CREDIT_KEY.test(inner)) continue;
+    out[key] = toUsdFirst(inner, rate);
+  }
+  // A balance the API sends only in credits (the owner's fallback) is shown in USD.
+  if (out.availableUsd === undefined && finite(value.balanceCredits) !== undefined) {
+    const usd = usdFromCredits(value.balanceCredits, rate);
+    if (usd !== undefined) out.availableUsd = usd;
   }
   return out;
 }
 
 const isCount = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
 
+/** The balance route's fields: in `data` (`{ success, data }`) or at the top. */
+function balanceFields(payload) {
+  if (!isRecord(payload)) return undefined;
+  const inner = payload.data;
+  if (isRecord(inner) && ('freeDailyLimit' in inner || 'freeAllowance' in inner || 'availableUsd' in inner || 'balanceCredits' in inner)) return inner;
+  return payload;
+}
+
+/** The balance in USD: `availableUsd`, else the credits balance at the API's rate. */
+function balanceUsd(payload) {
+  const fields = balanceFields(payload);
+  if (!fields) return undefined;
+  if (isCount(fields.availableUsd)) return fields.availableUsd;
+  return usdFromCredits(fields.balanceCredits ?? fields.balance, retailUsdPerCreditOf(payload));
+}
+
+/** Who pays next: the agent's part (or null) and the rest, in billing order. Undefined for an older API. */
+function freeQuotaParts(payload) {
+  const fields = balanceFields(payload);
+  if (!fields) return undefined;
+  const { ownerCreditsFallback, balanceCredits } = fields;
+  // The agent route says freeDailyLimit / freeRequestsRemainingToday; the owner route freeAllowance / freeRemainingToday.
+  const freeDailyLimit = fields.freeDailyLimit ?? fields.freeAllowance;
+  const freeRequestsRemainingToday = fields.freeRequestsRemainingToday ?? fields.freeRemainingToday;
+  if (!isCount(freeDailyLimit) || !isCount(freeRequestsRemainingToday)) return undefined;
+  const rate = retailUsdPerCreditOf(payload);
+  const agentUsd = isCount(fields.availableUsd) ? fields.availableUsd : usdFromCredits(balanceCredits, rate);
+  let agent = null;
+  if (isCount(agentUsd) && agentUsd > 0) agent = `The agent's balance (${formatUsd(agentUsd)}) pays first`;
+  else if (isCount(balanceCredits) && balanceCredits > 0) agent = "The agent's balance pays first";
+  const rest = [`${freeRequestsRemainingToday} of ${freeDailyLimit} free requests left today`];
+  if (isRecord(ownerCreditsFallback) && ownerCreditsFallback.enabled === true) {
+    const ownerUsd = usdFromCredits(ownerCreditsFallback.balanceCredits, rate);
+    rest.push(isCount(ownerUsd) ? `then the owner's balance (${formatUsd(ownerUsd)}) pays` : "then the owner's balance pays");
+  }
+  rest.push('then top up the balance');
+  return { agent, rest };
+}
+
 /**
  * Who pays next for the agent's actions, from the agent credits route's fields (thirdfy-api-v2#884):
  * `freeRequestsRemainingToday` of `freeDailyLimit` (free requests per UTC day) and
- * `ownerCreditsFallback` (the owner's credits pay once the agent's credits and free requests are
- * used). Billing order: agent's credits, free requests, owner's credits, refusal. Same wording as
- * thirdfy-mcp `creditsFreeQuotaNote` (#253). Undefined when an older API omits the fields.
+ * `ownerCreditsFallback` (the owner's balance pays once the agent's balance and free requests are
+ * used). Billing order: agent's balance, free requests, owner's balance, refusal. Amounts in USD,
+ * never credits; same wording as thirdfy-mcp `creditsFreeQuotaNote` (#279). Undefined when an older
+ * API omits the fields.
  */
 export function creditsFreeQuotaNote(payload) {
-  const fields = payload?.data && typeof payload.data === 'object' && 'freeDailyLimit' in payload.data ? payload.data : payload;
-  if (!fields || typeof fields !== 'object') return undefined;
-  const { freeDailyLimit, freeRequestsRemainingToday, ownerCreditsFallback, balanceCredits } = fields;
-  if (!isCount(freeDailyLimit) || !isCount(freeRequestsRemainingToday)) return undefined;
-  const parts = [];
-  if (isCount(balanceCredits) && balanceCredits > 0) parts.push(`The agent's credits (${balanceCredits}) pay first`);
-  parts.push(`${freeRequestsRemainingToday} of ${freeDailyLimit} free requests left today`);
-  if (ownerCreditsFallback && typeof ownerCreditsFallback === 'object' && ownerCreditsFallback.enabled === true) {
-    const owner = ownerCreditsFallback.balanceCredits;
-    parts.push(isCount(owner) ? `then the owner's credits (${owner}) pay` : "then the owner's credits pay");
-  }
-  parts.push('then buy credits');
-  return `${parts.join('; ')}.`;
+  const parts = freeQuotaParts(payload);
+  if (!parts) return undefined;
+  return `${[...(parts.agent ? [parts.agent] : []), ...parts.rest].join('; ')}.`;
 }
 
-/** The balance in credits only, with who pays next when the API says. */
+/**
+ * The balance in dollars, never credits, with who pays next when the API says, for example
+ * "$4.20 left; 8 of 20 free requests left today; then the owner's balance ($86.22) pays; then top up the balance."
+ */
 export function formatCreditsBalanceSummary(response) {
-  const credits = `${response?.balance ?? response?.balanceCredits ?? 0} credits`;
-  const note = creditsFreeQuotaNote(response);
-  return note ? `${credits}. ${note}` : credits;
+  const usd = balanceUsd(response);
+  const lead = usd === undefined ? 'balance in USD not reported by this API' : `${formatUsd(usd)} left`;
+  const parts = freeQuotaParts(response);
+  return `${[lead, ...(parts ? parts.rest : [])].join('; ')}.`;
+}
+
+const PAYER_LABELS = {
+  agent_credits: "the agent's balance",
+  free_request: 'a free request',
+  owner_credits: "the owner's balance",
+  none: 'nobody: it would be refused until the balance is topped up',
+};
+
+/** `wouldBePaidBy` in words, with the API's value in parentheses. Never a price. */
+export function describeWouldBePaidBy(wouldBePaidBy) {
+  const raw = String(wouldBePaidBy || '').trim();
+  if (!raw) return undefined;
+  return PAYER_LABELS[raw] ? `${PAYER_LABELS[raw]} (${raw})` : raw;
 }
 
+/**
+ * `models list` / `models estimate` are owner model-pricing reports (owner auth only) and are left as
+ * they were by the USD-first rule, as thirdfy-mcp left its owner-token credits tools.
+ */
 export function formatCreditsModelsSummary(response) {
   const firstModel = response?.models?.[0];
   if (firstModel?.estimatedUsdPerTurn != null) {