@venturewild/workspace 0.1.1 → 0.1.3

package/server/src/agent-readiness.mjs

@@ -0,0 +1,200 @@
+// Agent readiness — "is the wrapped agent actually able to talk?"
+//
+// THE GAP THIS CLOSES: detectAgents() only proves the `claude` binary is on the
+// PATH. It does NOT prove the user has signed in. A brand-new user who installed
+// the CLI but never ran `claude auth login` has a binary that resolves but every
+// `claude -p` turn fails with an auth error. Onboarding's folder-peek (step 2)
+// would then surface a scary error bubble — the exact "makes them feel stupid"
+// failure docs/user-experience.md §4 forbids, and the open question in §3.2.
+//
+// THE SECOND GAP (added 2026-06-01): being signed in is NOT the same as being
+// ABLE to run turns. A free claude.ai account can complete `claude auth login`
+// (so `loggedIn:true`) yet Claude Code still refuses every prompt — a paid plan
+// (Pro/Max/Team/Enterprise) or API billing is required. If we only checked
+// `loggedIn` we'd wave a free user straight into the folder-peek, where the
+// FIRST `claude -p` blows up with a billing error = the same scary bubble. So we
+// also read `subscriptionType` / `apiProvider` and raise a distinct `subscribe`
+// verdict ("you're in — you just need an active plan") instead.
+//
+// THE PROBE: `claude auth status` — a built-in, ZERO-TOKEN, cross-platform check
+// (verified on Claude Code 2.1.158). It reads whatever credential store the
+// platform uses (macOS Keychain, Windows ~/.claude/.credentials.json, Linux
+// config), so a naive credentials-file check (which would false-negative on a
+// signed-in Mac user like Mel) is wrong — we ask the CLI itself. It prints JSON:
+//   - signed in  → exit 0, {"loggedIn":true,"authMethod":"claude.ai",
+//                           "apiProvider":"firstParty","email":"…",
+//                           "subscriptionType":"max",…}
+//   - signed out → exit 1, {"loggedIn":false,"authMethod":"none",…}
+// We parse the JSON (authoritative) and fall back to the exit code if the shape
+// ever changes.
+//
+// API-KEY / TOKEN BILLING: if ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN /
+// CLAUDE_CODE_OAUTH_TOKEN) is set, `claude -p` bills through that and turns run
+// even without a claude.ai OAuth session — so we treat a configured key as
+// `ready` regardless of `auth status` (the sponsored / managed-key path).
+//
+// Only `claude` has this contract today. Other agents (gemini/glm/codex) report
+// `unknown` — we never block on a readiness we can't measure (fail-open), so a
+// Codex user is never gated by a Claude-shaped check.
+
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCb);
+
+// `claude auth status` is local-only (no network), but give it room on a cold
+// cache / slow disk. Comfortably under the 5s onboarding "feels instant" budget.
+const AUTH_PROBE_TIMEOUT_MS = 8000;
+
+// Subscription tiers that CAN run Claude Code turns vs. ones that cannot. Lower-
+// cased for comparison. An unknown, non-empty tier on a firstParty account is
+// treated leniently (assumed paid) so a future tier name never false-gates a
+// paying user behind a non-skippable wall — the empty/known-free cases are the
+// only ones we positively block.
+const PAID_TIERS = new Set(['pro', 'max', 'team', 'enterprise']);
+const UNPAID_TIERS = new Set(['free', 'none', 'inactive', 'expired', 'trial_expired']);
+
+// An API key / long-lived token configures billing directly — turns will run
+// even with no OAuth session. Checked before the auth probe.
+function hasApiBillingKey(env) {
+  const keys = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN'];
+  return keys.some((k) => typeof env?.[k] === 'string' && env[k].trim() !== '');
+}
+
+// Given a parsed `auth status` object for a signed-in user, can turns actually
+// run?  true = yes (paid plan or API billing), false = no (free / no plan),
+// null = unknown shape → caller treats as ready (lenient, never false-gates).
+export function canRunTurns(parsed) {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const sub =
+    typeof parsed.subscriptionType === 'string' ? parsed.subscriptionType.toLowerCase().trim() : '';
+  const provider =
+    typeof parsed.apiProvider === 'string' ? parsed.apiProvider.toLowerCase().trim() : '';
+  // A non-firstParty provider (console / bedrock / vertex) bills via API → runs.
+  if (provider && provider !== 'firstparty') return true;
+  if (PAID_TIERS.has(sub)) return true;
+  if (UNPAID_TIERS.has(sub)) return false;
+  // Signed in via claude.ai with NO subscription field at all → no active plan
+  // (the current CLI emits subscriptionType for paid accounts, so absence here
+  // is the free-account fingerprint).
+  if (sub === '') return false;
+  // Unknown, non-empty tier on a firstParty account — lean paid (don't gate).
+  return true;
+}
+
+/**
+ * Readiness verdict for one agent.
+ *   status: 'ready'      — installed AND able to run turns (signed-in + plan, or API key).
+ *           'subscribe'  — installed AND signed in, but no active plan → the user
+ *                          needs a Claude Pro (or higher) plan before turns run.
+ *           'login'      — installed but NOT signed in; the user must auth.
+ *           'missing'    — binary not on PATH (detect step already knew).
+ *           'unknown'    — installed, but this agent has no auth-status probe
+ *                          we understand → never gate on it (fail-open).
+ *   email:  parsed sign-in identity when known (claude only), else null.
+ *   hint:   a short, human, NON-technical line the UI can show as-is.
+ */
+export async function probeClaudeAuth(agent, runner = defaultRunner, env = process.env) {
+  if (!agent || !agent.available) {
+    return {
+      status: 'missing',
+      email: null,
+      hint: 'Claude Code isn’t installed yet. Install it, then come back.',
+    };
+  }
+  // Sponsored / managed billing: a configured key runs turns regardless of the
+  // OAuth session state, so don't gate.
+  if (hasApiBillingKey(env)) {
+    return { status: 'ready', email: null, hint: null };
+  }
+  const command = agent.resolvedPath || agent.binary;
+  try {
+    const { code, stdout } = await runner(command, ['auth', 'status']);
+    const parsed = parseAuthStatus(stdout);
+    // Authoritative: the JSON `loggedIn` flag. Fall back to the exit code
+    // (0 = signed in) only if the JSON is unparseable / shape-changed.
+    const loggedIn = parsed ? parsed.loggedIn === true : code === 0;
+    if (loggedIn) {
+      // Signed in — but can they actually run a turn? A free account can't.
+      if (canRunTurns(parsed) === false) {
+        return {
+          status: 'subscribe',
+          email: parsed?.email || null,
+          hint: 'You’re signed in — you just need an active Claude plan (Pro or higher) so your agent can run.',
+        };
+      }
+      return { status: 'ready', email: parsed?.email || null, hint: null };
+    }
+    // Signed out (or any non-ready shape). Treat as "needs login" — safer than
+    // claiming ready and then failing the first real turn mid-onboarding.
+    return {
+      status: 'login',
+      email: null,
+      hint: 'One quick thing: sign in to Claude so your agent can think.',
+    };
+  } catch (err) {
+    // The probe itself failed to run (timeout, spawn error, unexpected CLI
+    // version with no `auth` subcommand). Don't hard-block onboarding on our
+    // own probe breaking — report unknown and let the turn-runner be the
+    // ground truth. Surfaced for logging, not shown as a scary error.
+    return {
+      status: 'unknown',
+      email: null,
+      hint: null,
+      error: String(err?.message || err),
+    };
+  }
+}
+
+/**
+ * Readiness for the active agent. Claude gets the real probe; every other agent
+ * is 'unknown' (we have no auth-status contract for them, so we never gate).
+ */
+export async function probeAgentReadiness(agent, runner = defaultRunner, env = process.env) {
+  if (agent && agent.id === 'claude') {
+    return probeClaudeAuth(agent, runner, env);
+  }
+  return { status: 'unknown', email: null, hint: null };
+}
+
+// Parse `claude auth status` stdout. It prints a JSON object; tolerate leading/
+// trailing noise by extracting the first {...} span. Returns null if nothing
+// parseable is found (caller falls back to the exit code).
+export function parseAuthStatus(stdout) {
+  const text = String(stdout || '');
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const obj = JSON.parse(text.slice(start, end + 1));
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+// execFile wrapper that resolves (never rejects) on a non-zero exit, so the
+// caller can branch on { code, stdout } uniformly. Only a genuine spawn/timeout
+// failure rejects — that's the 'unknown' path above.
+function defaultRunner(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      args,
+      { timeout: AUTH_PROBE_TIMEOUT_MS, windowsHide: true },
+      (err, stdout, stderr) => {
+        if (err && typeof err.code !== 'number') {
+          // No numeric exit code => process never ran to completion
+          // (ENOENT, ETIMEDOUT, killed). That's a probe failure, not a verdict.
+          reject(err);
+          return;
+        }
+        resolve({
+          code: err ? err.code : 0,
+          stdout: stdout || '',
+          stderr: stderr || '',
+        });
+      },
+    );
+  });
+}