carthagent 0.0.0-stage → 1.0.7

package/lib/budget.mjs

@@ -0,0 +1,37 @@
+// Session accounting is deliberately independent of delivery-plan revisions.
+export function budgetLimits(getFlag) {
+  const limits = {};
+  for (const [key, flag] of [['tools', 'tools'], ['seconds', 'seconds'], ['repairs', 'repairs']]) {
+    const raw = getFlag(`delivery-max-${flag}`) ?? '0';
+    if (!/^\d+$/.test(String(raw)) || !Number.isSafeInteger(Number(raw)) || Number(raw) > 1000000) throw Error(`delivery-max-${flag} must be an integer from 0 to 1000000`);
+    limits[key] = Number(raw);
+  }
+  return limits;
+}
+export function newBudget(limits, now = Date.now()) {
+  return { startedAt: now, limits, tools: 0, repairs: 0, stopped: null };
+}
+export function budgetReason(budget, action, now = Date.now()) {
+  if (!budget) return null;
+  if (budget.stopped) return budget.stopped;
+  if (budget.limits.seconds && now - budget.startedAt >= budget.limits.seconds * 1000) return 'elapsed-time';
+  if (action === 'tool' && budget.limits.tools && budget.tools >= budget.limits.tools) return 'tool-calls';
+  if (action === 'repair' && budget.limits.repairs && budget.repairs >= budget.limits.repairs) return 'repair-rounds';
+  return null;
+}
+
+export function validateBudgetOptions(opts, { allowWithoutDelivery = false } = {}) {
+  const keys = ['maxTools', 'maxSeconds', 'maxRepairs'];
+  if (!allowWithoutDelivery && opts.delivery === false && keys.some(key => opts[key] !== undefined)) {
+    throw Error('Budget options require the delivery extension');
+  }
+  budgetLimits(flag => opts[{ 'delivery-max-tools': 'maxTools', 'delivery-max-seconds': 'maxSeconds', 'delivery-max-repairs': 'maxRepairs' }[flag]]);
+}
+export function budgetSnapshot(budget, now = Date.now()) {
+  if (!budget) return { enabled: false };
+  return { ...budget, remaining: {
+    tools: budget.limits.tools ? Math.max(0, budget.limits.tools - budget.tools) : null,
+    repairs: budget.limits.repairs ? Math.max(0, budget.limits.repairs - budget.repairs) : null,
+    seconds: budget.limits.seconds ? Math.max(0, Math.ceil((budget.startedAt + budget.limits.seconds * 1000 - now) / 1000)) : null
+  }, reason: budgetReason(budget, undefined, now) };
+}

package/lib/cdp.mjs

@@ -0,0 +1,221 @@
+/**
+ * Minimal Chrome DevTools Protocol client for the bundled headless browser.
+ * Replaces the geckodriver/WebDriver tier: chrome-headless-shell is launched
+ * with --remote-debugging-port=0 and driven over the DevTools websocket —
+ * navigation, DOM assertions, clicks, screenshots and console-error capture
+ * with a single binary and zero npm deps.
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { findChromium, ensureBundledBrowser, isSandboxFailure } from './browser-bin.mjs';
+
+const MAX_ERRORS = 50;
+
+/** Spawn the headless shell once and return its browser-level DevTools ws URL. */
+function spawnShell(binary, extraArgs, { timeoutMs = 30000 } = {}) {
+  const profile = mkdtempSync(join(tmpdir(), 'carthagent-chrome-'));
+  const child = spawn(binary, [
+    ...extraArgs,
+    '--remote-debugging-port=0', '--user-data-dir=' + profile,
+    '--no-first-run', '--no-default-browser-check', '--disable-extensions',
+    '--mute-audio', 'about:blank',
+  ], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', d => { stderr += d; });
+  return new Promise((resolve, reject) => {
+    const fail = e => { child.kill(); rmSync(profile, { recursive: true, force: true }); reject(e); };
+    const timer = setTimeout(() => fail(Error(`browser did not expose DevTools within ${timeoutMs}ms: ${stderr.slice(-500)}`)), timeoutMs);
+    child.stderr.on('data', () => {
+      const m = stderr.match(/DevTools listening on (ws:\/\/\S+)/);
+      if (m) {
+        clearTimeout(timer);
+        child.removeAllListeners('error');
+        child.removeAllListeners('close');
+        resolve({ child, wsUrl: m[1], profile, stderr: () => stderr });
+      }
+    });
+    child.on('error', e => { clearTimeout(timer); fail(e); });
+    child.on('close', () => { clearTimeout(timer); fail(Error(`browser exited before DevTools opened: ${stderr.slice(-500)}`)); });
+  });
+}
+
+/** Spawn the shell, retrying once with --no-sandbox when the environment
+ * blocks Chromium's process sandbox (Ubuntu >=23.10 AppArmor, containers). */
+async function launchBrowser(options = {}) {
+  let binary = findChromium();
+  if (!binary) binary = await ensureBundledBrowser();
+  try {
+    return await spawnShell(binary, [], options);
+  } catch (e) {
+    if (e?.message && isSandboxFailure(e.message)) {
+      return await spawnShell(binary, ['--no-sandbox'], options);
+    }
+    throw e;
+  }
+}
+
+/** Minimal CDP session over one websocket, scoped to a page target. */
+async function connectSession(wsUrl, { timeoutMs = 15000 } = {}) {
+  const socket = new WebSocket(wsUrl);
+  const pending = new Map();
+  const errors = [];
+  let dropped = 0;
+  let sequence = 0;
+  let sessionId;
+  let closed = false;
+  socket.addEventListener('close', () => { closed = true; });
+  socket.addEventListener('message', event => {
+    let message;
+    try { message = JSON.parse(event.data); } catch { return; }
+    if (message.id !== undefined) {
+      const handler = pending.get(message.id);
+      if (handler) { pending.delete(message.id); handler(message); }
+      return;
+    }
+    const { method, params } = message;
+    let entry;
+    if (method === 'Runtime.consoleAPICalled' && params.type === 'error') {
+      entry = { type: 'console', text: (params.args || []).map(a => a.value ?? a.description ?? '').join(' ').slice(0, 2000) };
+    } else if (method === 'Runtime.exceptionThrown') {
+      const d = params.exceptionDetails || {};
+      entry = { type: 'exception', text: String(d.exception?.description || d.text || 'uncaught exception').slice(0, 2000),
+        stack: (d.stackTrace?.callFrames || []).slice(0, 8).map(f => ({ url: String(f.url).slice(0, 500), lineNumber: f.lineNumber, columnNumber: f.columnNumber })) };
+    } else if (method === 'Log.entryAdded' && params.entry.level === 'error') {
+      entry = { type: params.entry.source, text: String(params.entry.text ?? '').slice(0, 2000) };
+    }
+    if (!entry) return;
+    if (errors.length === MAX_ERRORS) { dropped++; return; }
+    errors.push(entry);
+  });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(Error('DevTools connection timed out')), timeoutMs);
+    socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+    socket.addEventListener('error', () => { clearTimeout(timer); reject(Error('DevTools connection failed')); }, { once: true });
+  });
+  function send(method, params = {}, session) {
+    if (closed) return Promise.reject(Error('DevTools connection closed'));
+    const id = ++sequence;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(Error(`CDP ${method} timed out`)); }, timeoutMs);
+      pending.set(id, message => {
+        clearTimeout(timer);
+        if (message.error) reject(Error(`CDP ${method}: ${message.error.message}`));
+        else resolve(message.result);
+      });
+      socket.send(JSON.stringify(session ? { id, method, params, sessionId: session } : { id, method, params }));
+    });
+  }
+  const { targetId } = await send('Target.createTarget', { url: 'about:blank' });
+  const attached = await send('Target.attachToTarget', { targetId, flatten: true });
+  sessionId = attached.sessionId;
+  const cmd = (method, params) => send(method, params, sessionId);
+  await Promise.all([cmd('Page.enable'), cmd('Runtime.enable'), cmd('Log.enable'), cmd('Page.setLifecycleEventsEnabled', { enabled: true })]);
+  return {
+    send, cmd, sessionId, targetId,
+    errors, dropped: () => dropped,
+    navigate(url) {
+      // Resolve on loadEventFired; caller applies the navigation timeout.
+      const loaded = new Promise(resolve => {
+        const listener = event => {
+          let message;
+          try { message = JSON.parse(event.data); } catch { return; }
+          if (message.method === 'Page.loadEventFired' && message.sessionId === sessionId) {
+            socket.removeEventListener('message', listener);
+            resolve();
+          }
+        };
+        socket.addEventListener('message', listener);
+      });
+      return { loaded, navigating: cmd('Page.navigate', { url }) };
+    },
+    close() { socket.close(); },
+  };
+}
+
+function evaluateExpression(cmd, expression) {
+  return cmd('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: false })
+    .then(r => {
+      if (r.exceptionDetails) throw Object.assign(Error(`page eval failed: ${r.exceptionDetails.text}`), { webdriverCode: 'eval error' });
+      return r.result?.value;
+    });
+}
+
+/**
+ * Real-browser check over CDP — mirrors the webdriverCheck contract:
+ * navigate, poll selector/text assertions, click once, screenshot, then fail on
+ * captured console/page errors. Categories: launch, capture, navigation,
+ * assertion, interaction, screenshot, cleanup.
+ */
+export async function cdpCheck({ url, steps = [], screenshot, waitMs = 5000 }) {
+  if (!Number.isInteger(waitMs) || waitMs < 1 || waitMs > 60000) throw Object.assign(Error('waitMs must be an integer from 1 to 60000'), { category: 'configuration' });
+  let phase = 'launch';
+  let stepIndex;
+  let currentStep;
+  let failure;
+  let browser;
+  try {
+    browser = await launchBrowser();
+  } catch (error) {
+    throw Object.assign(error, { category: 'launch' });
+  }
+  let session;
+  try {
+    phase = 'capture';
+    session = await connectSession(browser.wsUrl);
+    phase = 'navigation';
+    const { loaded, navigating } = session.navigate(url);
+    await Promise.race([
+      Promise.all([navigating, loaded]),
+      new Promise((_, reject) => setTimeout(() => reject(Error('page load timed out')), 15000)),
+    ]);
+    for (const [index, step] of steps.entries()) {
+      phase = 'assertion'; stepIndex = index; currentStep = step;
+      const deadline = Date.now() + waitMs;
+      const sel = JSON.stringify(step.selector);
+      for (;;) {
+        try {
+          if (step.text !== undefined) {
+            const text = await evaluateExpression(session.cmd, `document.querySelector(${sel})?.innerText ?? null`);
+            if (text == null) throw Object.assign(Error(`${step.selector}: not found`), { webdriverCode: 'no such element' });
+            if (!String(text).includes(step.text)) throw Object.assign(Error(`${step.selector}: expected ${JSON.stringify(step.text)}, got ${JSON.stringify(String(text).slice(0, 200))}`), { webdriverCode: 'text mismatch' });
+          } else {
+            const found = await evaluateExpression(session.cmd, `!!document.querySelector(${sel})`);
+            if (!found) throw Object.assign(Error(`${step.selector}: not found`), { webdriverCode: 'no such element' });
+          }
+          break;
+        } catch (error) {
+          if (!['no such element', 'text mismatch', 'eval error'].includes(error.webdriverCode) || Date.now() >= deadline) throw error;
+          await new Promise(r => setTimeout(r, Math.min(100, Math.max(1, deadline - Date.now()))));
+        }
+      }
+      if (step.action === 'click') {
+        phase = 'interaction';
+        await evaluateExpression(session.cmd, `document.querySelector(${sel})?.click()`);
+      }
+    }
+    stepIndex = undefined; currentStep = undefined; phase = 'screenshot';
+    if (screenshot) {
+      const shot = await session.cmd('Page.captureScreenshot', { format: 'png' });
+      mkdirSync(dirname(screenshot), { recursive: true });
+      writeFileSync(screenshot, Buffer.from(shot.data, 'base64'));
+    }
+  } catch (error) {
+    failure = Object.assign(error, { category: phase, stepIndex, selector: currentStep?.selector, expected: currentStep?.text });
+  }
+  if (session) {
+    try {
+      // Round trip on the same channel before consuming the observed log.
+      await session.cmd('Runtime.evaluate', { expression: 'true' });
+      if (session.errors.length) failure ||= Object.assign(Error('Unexpected browser errors'), { category: 'browser-errors' });
+    } catch (error) { failure ||= Object.assign(error, { category: 'capture' }); }
+    if (failure && session.errors.length) Object.assign(failure, { browserErrors: [...session.errors], droppedBrowserErrors: session.dropped() });
+  }
+  phase = 'cleanup';
+  try { session?.close(); } catch {}
+  try { browser.child.kill('SIGKILL'); } catch {}
+  try { rmSync(browser.profile, { recursive: true, force: true }); } catch {}
+  if (failure) throw failure;
+  return { pass: true, engine: 'chrome-headless-shell', screenshot: screenshot || null, consoleChecked: true };
+}

package/lib/cloud/client.mjs

@@ -0,0 +1,275 @@
+const DEFAULT_CLOUD_URL = 'https://api.carthagent.xyz';
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const MAX_ERROR_DETAIL = 240;
+
+let spawnProcess = null;
+
+export const CARTHAGENT_CLOUD_URL_ENV = 'CARTHAGENT_CLOUD_URL';
+
+export function cloudControlUrl(env = process.env) {
+  const override = env?.[CARTHAGENT_CLOUD_URL_ENV]?.trim();
+  return (override || DEFAULT_CLOUD_URL).replace(/\/+$/, '');
+}
+
+function abortError(signal) {
+  return signal?.reason instanceof Error ? signal.reason : new Error('cancelled');
+}
+
+export async function openBrowser(url, { platform = process.platform, env = process.env, spawnImpl } = {}) {
+  const target = String(url || '').trim();
+  if (!/^https?:\/\//i.test(target)) return false;
+  if (!spawnImpl) {
+    spawnProcess ||= import('node:child_process').then(module => module.spawn);
+    spawnImpl = await spawnProcess;
+  }
+  let command;
+  let args;
+  if (platform === 'darwin') [command, args] = ['open', [target]];
+  else if (platform === 'win32') [command, args] = ['cmd.exe', ['/d', '/s', '/c', 'start', '', target.replace(/&/g, '^&')]];
+  else if (env?.WSL_DISTRO_NAME || env?.WSL_INTEROP) [command, args] = ['cmd.exe', ['/d', '/s', '/c', 'start', '', target.replace(/&/g, '^&')]];
+  else [command, args] = ['xdg-open', [target]];
+  return new Promise(resolve => {
+    try {
+      const child = spawnImpl(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+      let settled = false;
+      const done = value => { if (!settled) { settled = true; resolve(value); } };
+      child.once?.('error', () => done(false));
+      child.once?.('spawn', () => { child.unref?.(); done(true); });
+      setTimeout(() => done(true), 100).unref?.();
+    } catch { resolve(false); }
+  });
+}
+
+export function delay(ms, signal) {
+  if (signal?.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, Math.max(0, ms));
+    function done() { signal?.removeEventListener('abort', cancelled); resolve(); }
+    function cancelled() { clearTimeout(timer); signal?.removeEventListener('abort', cancelled); reject(abortError(signal)); }
+    signal?.addEventListener('abort', cancelled, { once: true });
+  });
+}
+
+function errorCode(payload, fallback) {
+  if (typeof payload?.error === 'string' && payload.error) return payload.error;
+  if (typeof payload?.error?.code === 'string' && payload.error.code) return payload.error.code;
+  if (typeof payload?.error?.message === 'string' && payload.error.message) return payload.error.message;
+  return fallback;
+}
+
+function errorWithCode(code, status, detail) {
+  const error = new Error(code || `cloud_http_${status}`);
+  error.code = code || `cloud_http_${status}`;
+  error.status = status;
+  if (detail) error.detail = detail;
+  return error;
+}
+
+export class CloudClient {
+  constructor({ baseUrl = cloudControlUrl(), fetchImpl = globalThis.fetch, sleep = delay } = {}) {
+    this.baseUrl = String(baseUrl).replace(/\/+$/, '');
+    this.fetch = fetchImpl;
+    this.sleep = sleep;
+  }
+
+  async request(path, { method = 'GET', accessToken, body, signal } = {}) {
+    if (typeof this.fetch !== 'function') throw new Error('Carthagent Ship requires fetch support.');
+    const headers = { accept: 'application/json' };
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    if (accessToken) headers.authorization = `Bearer ${accessToken}`;
+    const response = await this.fetch(`${this.baseUrl}${path}`, {
+      method, headers, signal,
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+      try { payload = JSON.parse(text); } catch { payload = null; }
+    }
+    if (!response.ok) {
+      const fallback = `cloud_http_${response.status}`;
+      throw errorWithCode(errorCode(payload, fallback), response.status, text.slice(0, MAX_ERROR_DETAIL));
+    }
+    return payload ?? {};
+  }
+
+  createDeviceAuthorization({ clientName = 'Carthagent CLI', installId = null, signal } = {}) {
+    const body = { clientName };
+    if (installId) body.installId = installId;
+    return this.request('/v1/device/authorizations', { method: 'POST', body, signal });
+  }
+
+  pollDeviceToken({ deviceCode, signal } = {}) {
+    return this.request('/v1/device/token', { method: 'POST', body: { deviceCode }, signal });
+  }
+
+  refresh({ refreshToken, signal } = {}) {
+    return this.request('/v1/token/refresh', { method: 'POST', body: { refreshToken }, signal });
+  }
+
+  account({ accessToken, signal } = {}) {
+    return this.request('/v1/account', { accessToken, signal });
+  }
+
+  usage({ accessToken, limit = 50, signal } = {}) {
+    const bounded = Number.isSafeInteger(limit) ? Math.max(1, Math.min(200, limit)) : 50;
+    return this.request(`/v1/account/usage?limit=${bounded}`, { accessToken, signal });
+  }
+
+  revokeCurrent({ accessToken, signal } = {}) {
+    return this.request('/v1/token/revoke', { method: 'POST', accessToken, signal });
+  }
+
+  revokeSession({ accessToken, sessionId, signal } = {}) {
+    return this.request(`/v1/account/sessions/${encodeURIComponent(sessionId)}`, { method: 'DELETE', accessToken, signal });
+  }
+
+  checkout({ accessToken, successUrl, cancelUrl, priceId, signal } = {}) {
+    return this.request('/v1/billing/checkout', { method: 'POST', accessToken, body: { successUrl, cancelUrl, priceId }, signal });
+  }
+
+  portal({ accessToken, returnUrl, signal } = {}) {
+    return this.request('/v1/billing/portal', { method: 'POST', accessToken, body: { returnUrl }, signal });
+  }
+
+  async authorizeDevice({ clientName = 'Carthagent CLI', installId = null, notify = () => {}, signal } = {}) {
+    const authorization = await this.createDeviceAuthorization({ clientName, installId, signal });
+    const verificationUri = authorization.verificationUriComplete || authorization.verificationUri;
+    notify({
+      type: 'device_code',
+      userCode: authorization.userCode,
+      verificationUri,
+      intervalSeconds: authorization.interval,
+      expiresInSeconds: authorization.expiresIn,
+    });
+    notify({ type: 'auth_url', url: verificationUri, instructions: `Approve device code ${authorization.userCode} in your browser.` });
+    const deadline = Date.now() + Number(authorization.expiresIn || 600) * 1000;
+    const interval = Math.max(1_000, Number(authorization.interval || DEFAULT_POLL_INTERVAL_MS / 1000) * 1000);
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw abortError(signal);
+      try {
+        return await this.pollDeviceToken({ deviceCode: authorization.deviceCode, signal });
+      } catch (error) {
+        if (error.code !== 'authorization_pending') throw error;
+      }
+      notify({ type: 'progress', message: 'Waiting for browser approval…' });
+      await this.sleep(interval, signal);
+    }
+    throw errorWithCode('expired_token', 410);
+  }
+}
+
+export function oauthCredentials(tokens, now = Date.now()) {
+  if (!tokens?.accessToken || !tokens?.refreshToken || !Number.isFinite(Number(tokens.expiresIn))) throw new Error('invalid_token_response');
+  return {
+    access: tokens.accessToken,
+    refresh: tokens.refreshToken,
+    expires: now + Math.max(1, Number(tokens.expiresIn)) * 1000,
+  };
+}
+
+export function formatNanoUsd(value) {
+  if (!Number.isSafeInteger(value)) return 'unavailable';
+  const sign = value < 0 ? '-' : '';
+  const absolute = Math.abs(value);
+  const dollars = Math.floor(absolute / 1_000_000_000);
+  const cents = Math.floor((absolute % 1_000_000_000) / 10_000_000);
+  return `${sign}$${dollars}.${String(cents).padStart(2, '0')}`;
+}
+
+function formatEpochSeconds(value) {
+  const seconds = Number(value);
+  return Number.isFinite(seconds) ? new Date(seconds * 1000).toISOString() : null;
+}
+
+export function cloudManagedUsageRecovery(value) {
+  const text = String(value?.code || value?.message || value || '');
+  if (/daily_limit_reached|managed daily usage limit/i.test(text)) return 'Managed daily usage is exhausted. It resets at 00:00 UTC. Use /account for headroom or /login for BYOK.';
+  if (/monthly_allowance_exhausted|managed monthly allowance/i.test(text)) return 'Managed monthly usage is exhausted. Use /billing portal to manage the plan or /login for BYOK.';
+  if (/subscription_inactive|managed subscription is not active/i.test(text)) return 'The managed subscription is inactive. Use /billing portal or /login for BYOK.';
+  if (/insufficient_quota|insufficient.credit|credit (?:is )?exhausted/i.test(text)) return 'Carthagent Ship credit is exhausted. Use /billing checkout where available or /login for BYOK.';
+  return null;
+}
+
+const METER_WIDTH = 16;
+const meterBar = ratio => {
+  const bounded = Math.min(1, Math.max(0, Number.isFinite(ratio) ? ratio : 0));
+  return '\u2593'.repeat(Math.round(bounded * METER_WIDTH)).padEnd(METER_WIDTH, '\u2591');
+};
+const meterPercent = ratio => `${Math.round(Math.min(1, Math.max(0, Number.isFinite(ratio) ? ratio : 0)) * 100)}%`;
+const managedRatio = bucket => {
+  const allowance = Number(bucket?.allowanceNanoUsd ?? bucket?.limitNanoUsd);
+  const available = Number(bucket?.availableNanoUsd);
+  return Number.isFinite(allowance) && allowance > 0 ? (allowance - Math.max(0, available)) / allowance : 0;
+};
+const shortUtcDate = epochSeconds => {
+  const date = epochSeconds ? new Date(Number(epochSeconds) * 1000) : null;
+  return date && Number.isFinite(date.getTime())
+    ? date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', timeZone: 'UTC' }) : null;
+};
+const utcClock = value => {
+  const date = value ? new Date(value) : null;
+  return date && Number.isFinite(date.getTime()) ? `${date.toISOString().slice(11, 16)} UTC` : null;
+};
+const compactTokens = value => {
+  if (!Number.isSafeInteger(value)) return '?';
+  return Math.abs(value) >= 1000 ? `${(value / 1000).toFixed(1).replace(/\.0$/, '')}k` : String(value);
+};
+
+export function managedUsageMeterLines(managed, { indent = '' } = {}) {
+  const lines = [];
+  if (managed?.monthly) {
+    const ratio = managedRatio(managed.monthly);
+    const renews = shortUtcDate(managed.periodEnd);
+    lines.push(`${indent}monthly   ${meterPercent(ratio).padStart(4)}   ${meterBar(ratio)}${renews ? `   renews ${renews}` : ''}`);
+  }
+  if (managed?.daily) {
+    const ratio = managedRatio(managed.daily);
+    const resets = utcClock(managed.daily.resetsAt);
+    lines.push(`${indent}daily     ${meterPercent(ratio).padStart(4)}   ${meterBar(ratio)}${resets ? `   resets ${resets}` : ''}`);
+  }
+  return lines;
+}
+
+export function formatCloudUsage(payload, { account, byok = false } = {}) {
+  const usage = Array.isArray(payload?.data) ? payload.data : [];
+  const managed = account?.managedUsage;
+  const lines = [];
+  lines.push(`\u{10900}  ${managed?.planName ? managed.planName.toUpperCase() : 'SHIP'} \u00b7 USAGE`);
+  lines.push(...managedUsageMeterLines(managed, { indent: '    ' }));
+  if (byok) lines.push('    this session uses an external provider \u2014 not counted here');
+  if (!usage.length) {
+    lines.push('    no settled requests yet');
+    return lines.join('\n');
+  }
+  lines.push('    ' + '\u2500'.repeat(44));
+  for (const [index, item] of usage.slice(0, 5).entries()) {
+    const label = index === 0 ? 'last 5    ' : '          ';
+    const status = item?.status && item.status !== 'completed' ? ` \u00b7 ${item.status}` : '';
+    lines.push(`    ${label}${item?.alias || 'Ship model'} \u00b7 ${compactTokens(item?.inputTokens)} in / ${compactTokens(item?.outputTokens)} out${status}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatCloudAccount(account, { usage } = {}) {
+  const subscription = account?.subscription || {};
+  const managed = account?.managedUsage;
+  const planName = managed?.planName || 'plan';
+  const lines = [
+    `Carthagent Ship account ${account?.accountId || 'unknown'}`,
+    `Credit: ${formatNanoUsd(account?.balance?.availableNanoUsd)} available`,
+    `Plan: ${subscription.status && subscription.status !== 'none' ? `${planName} (${subscription.status})` : 'Free'}`,
+  ];
+  const subscriptionEnd = formatEpochSeconds(subscription.current_period_end);
+  if (subscriptionEnd) lines.push(`Renews/ends: ${subscriptionEnd}`);
+  if (managed) {
+    lines.push(...managedUsageMeterLines(managed));
+  } else if (subscription.status && subscription.status !== 'none' && ['active', 'trialing'].includes(subscription.status)) {
+    lines.push('Managed usage: unavailable for the current billing period');
+  }
+  if (usage) lines.push(formatCloudUsage(usage));
+  const sessions = Array.isArray(account?.sessions) ? account.sessions : [];
+  const active = sessions.filter(session => !session.revoked_at).length;
+  lines.push(`CLI sessions: ${active} active, ${sessions.length - active} revoked`);
+  return lines.join('\n');
+}