carthagent 0.0.0-stage → 1.0.7

package/lib/tui/auth.mjs

@@ -0,0 +1,249 @@
+/**
+ * Provider authentication for the carthagent console.
+ *
+ * The bundled engine ships a programmatic `ModelRuntime.login(providerId, type, interaction)`
+ * API (see `readStoredCredential` / `ModelRuntime` in the bundled engine).
+ * This module wraps it so the TUI can drive login as an in-console popup
+ * instead of handing the terminal over to the engine's interactive mode.
+ *
+ * The pure helpers here are unit-tested in tests/auth.test.mjs; the runtime
+ * loader imports the (heavy) bundled engine lazily, only when auth is opened.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { CloudClient, cloudControlUrl, formatCloudAccount, formatCloudUsage } from '../cloud/client.mjs';
+import { EXPERIENTIAL_PROVIDER_ID, registerExperientialProvider } from '../providers/experiential.mjs';
+import { SUBSCRIPTION_PROVIDER_IDS, registerSubscriptionProviders } from '../providers/subscription-models.mjs';
+import { CARTHAGENT_SHIP_PROVIDER_NAME } from '../providers/names.mjs';
+
+const AGENT_DIR = process.env.CARTHAGENT_AGENT_DIR || process.env.CARTHAGENT_CODING_AGENT_DIR || join(os.homedir(), '.carthagent', 'agent');
+
+const COMMON_API_KEY_ENVS = [
+  'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY',
+  'OPENROUTER_API_KEY', 'XAI_API_KEY', 'EXPLABS_API_KEY',
+  'GROQ_API_KEY', 'MISTRAL_API_KEY', 'DEEPSEEK_API_KEY',
+];
+
+function hasStoredCredential(agentDir) {
+  try {
+    const stored = JSON.parse(readFileSync(join(agentDir, 'auth.json'), 'utf8'));
+    if (!stored || typeof stored !== 'object' || Array.isArray(stored)) return false;
+    return Object.values(stored).some(credential => {
+      if (typeof credential === 'string') return !!credential.trim();
+      if (!credential || typeof credential !== 'object') return false;
+      return ['key', 'apiKey', 'access', 'refresh'].some(field => typeof credential[field] === 'string' && credential[field].trim());
+    });
+  } catch { return false; }
+}
+
+function hasConfiguredModelCredential(agentDir) {
+  try {
+    const stored = JSON.parse(readFileSync(join(agentDir, 'models.json'), 'utf8'));
+    const providers = stored?.providers;
+    if (!providers || typeof providers !== 'object' || Array.isArray(providers)) return false;
+    return Object.values(providers).some(provider => {
+      if (!provider || typeof provider !== 'object') return false;
+      return ['apiKey', 'api_key'].some(field => typeof provider[field] === 'string' && provider[field].trim());
+    });
+  } catch { return false; }
+}
+
+/** Quick lightweight check: does the user have any usable provider credential at all? */
+export function hasConfiguredProvider(env = process.env, agentDir = AGENT_DIR) {
+  if (hasStoredCredential(agentDir) || hasConfiguredModelCredential(agentDir)) return true;
+  return COMMON_API_KEY_ENVS.some(key => env[key]?.trim());
+}
+
+const PROVIDER_ORDER = new Map([
+  ['experiential-labs', 0],
+  ['anthropic', 10],
+  ['openai-codex', 20],
+  ['openai', 21],
+  ['openrouter', 30],
+]);
+
+/** Auth methods a provider advertises, in display order (subscription first). */
+export function authTypes(provider) {
+  const out = [];
+  if (provider?.auth?.oauth) out.push('oauth');
+  if (provider?.auth?.apiKey) out.push('api_key');
+  return out;
+}
+
+export function authTypeLabel(type, providerId) {
+  if (type === 'oauth' && providerId === EXPERIENTIAL_PROVIDER_ID) return 'browser sign-in';
+  return type === 'oauth' ? 'subscription (OAuth)' : 'API key';
+}
+
+/**
+ * Rows the shared provider picker can show. Ordering is product policy, not
+ * connection state: Carthagent Ship stays first, recommended providers retain
+ * fixed positions, and every other provider follows alphabetically.
+ */
+export function loginProviderList(runtime, { activeProviderId } = {}) {
+  const rows = [];
+  for (const provider of runtime.getProviders()) {
+    const types = authTypes(provider);
+    if (!types.length) continue;
+    let configured = false;
+    try { configured = !!runtime.getProviderAuthStatus(provider.id).configured; } catch { /* unknown */ }
+    rows.push({
+      id: provider.id,
+      name: provider.id === EXPERIENTIAL_PROVIDER_ID ? CARTHAGENT_SHIP_PROVIDER_NAME : (provider.name || provider.id),
+      types,
+      configured,
+      recommended: provider.id === 'experiential-labs',
+      priority: PROVIDER_ORDER.get(provider.id) ?? 1000,
+    });
+  }
+  rows.sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+  if (activeProviderId) rows.forEach(row => { row.active = row.id === activeProviderId; });
+  return rows;
+}
+
+/** New installs focus the recommended row; returning users focus their active provider. */
+export function loginProviderFocus(rows, activeProviderId) {
+  const active = activeProviderId ? rows.findIndex(row => row.id === activeProviderId) : -1;
+  if (active >= 0) return active;
+  const recommended = rows.findIndex(row => row.recommended);
+  return recommended >= 0 ? recommended : 0;
+}
+
+/** Case-insensitive filter over provider id/name. */
+export function filterLoginProviders(rows, query) {
+  const q = (query || '').trim().toLowerCase();
+  if (!q) return rows;
+  return rows.filter(r => r.id.toLowerCase().includes(q) || r.name.toLowerCase().includes(q));
+}
+
+/**
+ * Fold one `notify(event)` from `runtime.login` into popup-facing fields.
+ * `state` is mutated and returned for convenience. The popup owns `message`.
+ */
+export function applyAuthEvent(state, event) {
+  if (!event || typeof event !== 'object') return state;
+  switch (event.type) {
+    case 'auth_url':
+      state.url = event.url || '';
+      state.instructions = event.instructions || '';
+      state.message = 'Open the authorization URL in your browser';
+      break;
+    case 'device_code':
+      state.deviceCode = { userCode: event.userCode || '', verificationUri: event.verificationUri || '' };
+      state.message = 'Enter the code at the verification URL';
+      break;
+    case 'info':
+      if (event.message) state.message = event.message;
+      if (Array.isArray(event.links)) state.links = event.links;
+      break;
+    case 'progress':
+      if (event.message) state.message = event.message;
+      break;
+    default:
+      break;
+  }
+  return state;
+}
+
+/** Fresh popup state in the provider-picking phase. */
+export function newAuthState() {
+  return {
+    phase: 'providers', // providers | type | prompt | waiting
+    providers: [],
+    filter: '',
+    sel: 0,
+    typeSel: 0,
+    promptSel: 0,
+    provider: null,
+    type: null,
+    prompt: null,
+    input: '',
+    message: '',
+    instructions: '',
+    url: '',
+    links: [],
+    deviceCode: null,
+    error: '',
+    busy: false,
+  };
+}
+
+let runtimePromise = null;
+
+/** Lazily create a ModelRuntime bound to carthagent's isolated agent directory. */
+export function loadAuthRuntime() {
+  if (!runtimePromise) {
+    runtimePromise = import('../../vendor/agent/index.js')
+      .then(async engine => {
+        const runtime = registerExperientialProvider(await engine.ModelRuntime.create({}));
+        registerSubscriptionProviders(runtime, { agentDir: AGENT_DIR });
+        // registerProvider() starts an offline refresh asynchronously. Await a
+        // provider-scoped refresh so stored OAuth credentials, dynamic Cloud
+        // models, and subscription-discovered models are present before
+        // account checks or a child engine is launched.
+        await runtime.refresh?.({ providers: [EXPERIENTIAL_PROVIDER_ID, ...SUBSCRIPTION_PROVIDER_IDS], allowNetwork: true });
+        return runtime;
+      })
+      .catch(error => { runtimePromise = null; throw error; });
+  }
+  return runtimePromise;
+}
+
+/** Start a provider login; `prompt`/`notify`/`signal` follow the engine's contract. */
+export function startLogin(runtime, providerId, type, interaction) {
+  return runtime.login(providerId, type, interaction);
+}
+
+/** Authenticate, then refresh that provider so dynamic model discovery is immediate. */
+export async function loginAndRefresh(runtime, providerId, type, interaction) {
+  const result = await startLogin(runtime, providerId, type, interaction);
+  await runtime.refresh?.({ providers: [providerId], allowNetwork: true, signal: interaction?.signal });
+  return result;
+}
+
+async function cloudAccessToken(runtime) {
+  const status = await runtime?.checkAuth?.(EXPERIENTIAL_PROVIDER_ID);
+  if (status?.type !== 'oauth') throw new Error('cloud_login_required');
+  const resolution = await runtime.getAuth(EXPERIENTIAL_PROVIDER_ID);
+  const accessToken = resolution?.auth?.apiKey;
+  if (!accessToken) throw new Error('cloud_login_required');
+  return accessToken;
+}
+
+export async function loadCloudAccount(runtime, { env = process.env, fetchImpl = globalThis.fetch, signal } = {}) {
+  const accessToken = await cloudAccessToken(runtime);
+  return new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl }).account({ accessToken, signal });
+}
+
+export async function loadCloudUsage(runtime, { env = process.env, fetchImpl = globalThis.fetch, limit = 50, signal } = {}) {
+  const accessToken = await cloudAccessToken(runtime);
+  return new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl }).usage({ accessToken, limit, signal });
+}
+
+export async function loadCloudAccountUsage(runtime, options = {}) {
+  const accessToken = await cloudAccessToken(runtime);
+  const client = new CloudClient({ baseUrl: cloudControlUrl(options.env), fetchImpl: options.fetchImpl });
+  const request = { accessToken, signal: options.signal };
+  const [account, usage] = await Promise.all([
+    client.account(request),
+    client.usage({ ...request, limit: options.limit }),
+  ]);
+  return { account, usage };
+}
+
+export async function createCloudBillingLink(runtime, action, { env = process.env, fetchImpl = globalThis.fetch, plan, signal } = {}) {
+  const accessToken = await cloudAccessToken(runtime);
+  const client = new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl });
+  const returnUrl = `${cloudControlUrl(env)}/account`;
+  if (action === 'checkout') return client.checkout({ accessToken, successUrl: returnUrl, cancelUrl: returnUrl, priceId: plan, signal });
+  if (action === 'portal') return client.portal({ accessToken, returnUrl, signal });
+  throw new Error('unknown_billing_action');
+}
+
+export async function revokeCloudSession(runtime, sessionId, { env = process.env, fetchImpl = globalThis.fetch, signal } = {}) {
+  const accessToken = await cloudAccessToken(runtime);
+  return new CloudClient({ baseUrl: cloudControlUrl(env), fetchImpl }).revokeSession({ accessToken, sessionId, signal });
+}
+
+export { formatCloudAccount, formatCloudUsage };

package/lib/tui/carthage.mjs

@@ -0,0 +1,109 @@
+/** Rotating completion lines for the TUI banner — one is drawn at random when a
+ * run settles. Carthage-themed to match the Aleph mark. */
+
+export const CARTHAGE_LINES = [
+  'Qart-Hadasht endures',
+  'The cothon is calm',
+  'The fleet is in',
+  'Byrsa stands watch',
+  'Purple on the tide',
+  'Cedar holds fast',
+  'Hannibal approves',
+  'The harbormaster nods',
+  "Elissa's city rises",
+  'Tanit smiles',
+  'The galleys rest',
+  'Salt and cedar',
+  'The Barca line holds',
+  'Silver from Tartessos',
+  'The suffetes concur',
+  'New City, new win',
+  'The murex trade thrives',
+  'Utica sends regards',
+  'Across the Middle Sea',
+  'The seawall stands',
+  'Hanno sails on',
+  'Elephants crossed the Alps',
+  'The Alps are behind you',
+  'Cannae was harder',
+  'The quinqueremes row on',
+  "Melqart's favor is yours",
+  'The Punic ports are open',
+  'A stele raised in your honor',
+  'The Gulf of Tunis glitters',
+  'The tin routes run',
+  'Motya sends tribute',
+  'Sardinia remembers',
+  'The Hundred and Four approve',
+  'Hamilcar would grin',
+  "Hasdrubal's blessing",
+  'The agora buzzes',
+  'The breakwater holds',
+  'The Punic tide runs your way',
+  "Dido's dream endures",
+  'Carthago Nova salutes',
+  "The admiral's lantern is lit",
+  'Trade winds at your back',
+  'The merchant fleet prospers',
+  'The citadel is yours',
+  'Purple sails unfurled',
+  "Mago's harvest is in",
+  'The vineyards of the Bagradas',
+  'Olive presses run full',
+  'The last amphora is sealed',
+  'The mint strikes silver',
+  "Tanit's sign on the coin",
+  'The mare and the palm',
+  'Beyond the Pillars of Hercules',
+  'Gadir holds the strait',
+  'Numidian riders rest',
+  'Baal Hammon is pleased',
+  'Libyan wheat loads fast',
+  'The customs house is quiet',
+  "Delivered under Byrsa's shadow",
+  'The Phoenician star guides you',
+  'Charted to the edge of maps',
+  'Landfall, finally',
+  'Anchored in calm water',
+  'Cargo counted, cargo safe',
+  'The manifest is clean',
+  'Every bale stamped',
+  'Sealed and shipped',
+  'The ledger balances',
+  'Harbor dues paid',
+  'The convoy made it',
+  'Full cargo, calm seas',
+  'The emporium is stocked',
+  'The tide is with us',
+  'Sunset over the great harbor',
+  'The sea gate closes softly',
+  'The watch changes',
+  'Carthage remembers',
+  'The oxhide was worth it',
+  'Byrsa, measured in oxhide',
+  'The circle of the cothon',
+  'Two hundred oars, one rhythm',
+  'The arsenal is full',
+  'Pitch and pine',
+  'Rope of esparto',
+  'The lookout calls landfall',
+  'Where the gulf meets the wall',
+  'Sea-borne and sure',
+  'The Punic way prevails',
+  "Tyre's daughter prospers",
+  'Ivory and gold dust',
+  'Amber from the north',
+  'Crimson dye for the victor',
+  'The archive keeps your name',
+  "Eshmun's blessing",
+  'Wax tablets sealed',
+  'The drum calls the stroke',
+  'Dawn patrol returns',
+  'Cap Bon rises green',
+  'The Lake of Tunis at dusk',
+  'The prow cuts true',
+];
+
+export function pickCarthageLine() {
+  return CARTHAGE_LINES[Math.floor(Math.random() * CARTHAGE_LINES.length)];
+}

package/lib/tui/clipboard.mjs

@@ -0,0 +1,122 @@
+/**
+ * Best-effort clipboard *read* and *write* for the carthagent console.
+ *
+ * Terminals normally deliver a paste as bracketed-paste bytes, which the key
+ * parser already understands. Some setups instead bind Ctrl+V to the app
+ * (which only sees a raw 0x16 byte), so we shell out to the platform clipboard
+ * utility and fall back to a no-op when none is available.
+ *
+ * Similarly, terminal drag-selection (auto copy) emits OSC 52 escapes for
+ * compatible terminals, but macOS Terminal.app and many default configurations
+ * (e.g. iTerm2 without explicit clipboard access enabled, tmux) do not populate
+ * the system clipboard via OSC 52. We shell out to the native clipboard writer
+ * (pbcopy on macOS, wl-copy/xclip/xsel on Linux, PowerShell on Windows/WSL) so the
+ * selected text lands in the OS pasteboard directly.
+ *
+ * carthagent stays dependency-free: these are all standard OS/desktop tools (or
+ * PowerShell/clip on Windows/WSL), tried in order until one answers.
+ */
+import { execFile } from 'node:child_process';
+
+const readWindows = () => ['powershell.exe', ['-NoProfile', '-Command', '[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false); [Console]::Write((Get-Clipboard -Raw))']];
+const writeWindows = () => [
+  ['powershell.exe', ['-NoProfile', '-Command', '[Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false); Set-Clipboard -Value ([Console]::In.ReadToEnd())']],
+];
+
+/** Clipboard read commands for a platform, in preference order. */
+export function clipboardCommands(platform = process.platform, env = process.env) {
+  if (platform === 'darwin') return [['pbpaste', []]];
+  if (platform === 'win32') return [readWindows()];
+  if (platform !== 'linux') return [];
+  const linux = [
+    ['wl-paste', ['-n']],
+    ['xclip', ['-selection', 'clipboard', '-o']],
+    ['xsel', ['--clipboard', '--output']],
+  ];
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP || env.WSLENV) {
+    linux.push(readWindows());
+  }
+  return linux;
+}
+
+/** Clipboard write commands for a platform, in preference order. */
+export function clipboardWriteCommands(platform = process.platform, env = process.env) {
+  if (platform === 'darwin') return [['pbcopy', []]];
+  if (platform === 'win32') return writeWindows();
+  if (platform !== 'linux') return [];
+  const linux = [
+    ['wl-copy', []],
+    ['xclip', ['-selection', 'clipboard']],
+    ['xsel', ['--clipboard', '--input']],
+  ];
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP || env.WSLENV) {
+    linux.push(...writeWindows());
+  }
+  return linux;
+}
+
+/** Normalize clipboard text. Single-line fields strip all whitespace/control
+ *  bytes (keys, codes, URLs); multi-line keeps newlines but drops control junk. */
+export function sanitizePaste(text, { multiline = false } = {}) {
+  const s = String(text ?? '').replace(/\r\n?/g, '\n');
+  if (multiline) return s.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '');
+  return s.replace(/[\s\u0000-\u001f\u007f]+/g, '');
+}
+
+/** Read the OS clipboard, resolving to '' when no tool works. Never rejects. */
+export function readClipboard({ platform = process.platform, env = process.env, timeoutMs = 1200, commands = null } = {}) {
+  const cmds = commands || clipboardCommands(platform, env);
+  return new Promise(resolve => {
+    let index = 0;
+    const next = () => {
+      const entry = cmds[index++];
+      if (!entry) { resolve(''); return; } // no tool answered
+      const [cmd, args] = entry;
+      try {
+        execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024, windowsHide: true }, (error, stdout) => {
+          if (error) next();                // missing/failed tool → try the next
+          else resolve(String(stdout || ''));
+        });
+      } catch { next(); }
+    };
+    next();
+  });
+}
+
+/** Write text to the OS clipboard, resolving to true on success or false when no tool works. Never rejects. */
+export function writeClipboard(text, { platform = process.platform, env = process.env, timeoutMs = 1200, commands = null } = {}) {
+  const cmds = commands || clipboardWriteCommands(platform, env);
+  const data = String(text ?? '');
+  return new Promise(resolve => {
+    let index = 0;
+    const next = () => {
+      const entry = cmds[index++];
+      if (!entry) { resolve(false); return; } // no tool answered
+      const [cmd, args] = entry;
+      let handled = false;
+      try {
+        const child = execFile(cmd, args, { timeout: timeoutMs, windowsHide: true }, (error) => {
+          if (handled) return;
+          handled = true;
+          if (error) next();
+          else resolve(true);
+        });
+        child.on('error', () => {
+          if (handled) return;
+          handled = true;
+          next();
+        });
+        if (child.stdin) {
+          child.stdin.on('error', () => {});
+          child.stdin.end(Buffer.from(data, 'utf8'));
+        }
+      } catch {
+        if (!handled) {
+          handled = true;
+          next();
+        }
+      }
+    };
+    next();
+  });
+}