@thirdfy/agent-cli 0.4.3 → 0.5.1

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) {

package/src/runtime/certification/executionCertify.mjs

@@ -227,6 +227,7 @@ export function buildExecutionCertificationReport({
   runMode = null,
   expectedSchemaDigest = null,
   requiredActions = [],
+  catalogPolicyScoped = false,
 } = {}) {
   const version = String(cliVersion || PACKAGE_VERSION).trim();
   const normalizedRequiredActions = parseRequiredActions(requiredActions);
@@ -259,10 +260,25 @@ export function buildExecutionCertificationReport({
     }
   }
 
+  // A keyed catalog lists only the agent's allowlist. Bare certification then checks the venue
+  // writes this agent may call; the rest are reported as skipped, not as missing schemas.
+  // An unscoped (public) catalog that lacks a venue action still fails closed.
+  const scopeToAllowlist = bareCertification && catalogFetched && catalogPolicyScoped === true;
+  const liveActionKeys = new Set();
+  for (const row of liveActions || []) {
+    for (const name of [row?.action, ...(Array.isArray(row?.aliases) ? row.aliases : [])]) {
+      if (name) liveActionKeys.add(normalizeActionKey(String(name)));
+    }
+  }
+  const skippedVenueActions = [];
   const venueActionNames =
     normalizedRequiredActions.length > 0
       ? normalizedRequiredActions.filter((action) => isWriteAction(action))
-      : VENUE_WRITE_ACTION_FIXTURES.map((fixture) => fixture.action);
+      : VENUE_WRITE_ACTION_FIXTURES.map((fixture) => fixture.action).filter((action) => {
+          if (!scopeToAllowlist || liveActionKeys.has(normalizeActionKey(action))) return true;
+          skippedVenueActions.push({ action, reason: 'NOT_ON_AGENT_ALLOWLIST' });
+          return false;
+        });
 
   const venueActions = runSchemaCompatibilityChecks(catalogByAction, venueActionNames, {
     requireLiveCatalog: bareCertification,
@@ -380,6 +396,7 @@ export function buildExecutionCertificationReport({
     commandAvailability,
     authorityInputs,
     venueActions,
+    skippedVenueActions,
     checks,
   };
 }

package/src/runtime/execution/payloads.mjs

@@ -3,6 +3,7 @@ import { wrapWriteIdempotencyKeyForHostedRuntime } from '../../core/execution/ho
 import { resolveExecutionContextFromEnv } from '../../core/execution/executionContext.mjs';
 import { requireFlag, parseJsonFlag } from '../../core/args.mjs';
 import { findAgentApiKey, loadProfileConfig } from '../../core/context.mjs';
+import { apiBaseFor, oauthSessionForApi, oauthSessionIsAgentCredential } from '../../core/oauth/session.mjs';
 import { createCliError } from '../../core/envelope.mjs';
 import { toLegacyVenueActionKey } from '../../core/venueBrand.mjs';
 import { normalizeRunMode, normalizeManagedRunMode, normalizeHybridWalletMode } from '../../core/runMode.mjs';
@@ -62,6 +63,11 @@ function buildBuildTxPayload(flags, resolvedAction, apiAction) {
 function resolveAgentKey(flags) {
   const explicit = String(flags.agentKey || '').trim();
   if (explicit) return explicit.toLowerCase();
+  // With an OAuth sign-in as the agent credential, the agent is the one the owner picked for it.
+  if (oauthSessionIsAgentCredential(flags)) {
+    const oauthAgent = String(oauthSessionForApi(apiBaseFor(flags))?.agentKey || '').trim();
+    if (oauthAgent) return oauthAgent.toLowerCase();
+  }
   const envKey = String(process.env.THIRDFY_AGENT_KEY || process.env.AGENT_KEY || '').trim();
   if (envKey) return envKey.toLowerCase();
   const config = loadProfileConfig();

package/src/runtime/handlers.mjs

@@ -218,6 +218,7 @@ export function createRuntimeHandlers(deps) {
     resolveEffectiveUserDid,
     negotiateCapabilities,
     commandAgentRegister: __agent.commandAgentRegister,
+    CLI_VERSION,
   });
 
   return {