@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/agents/doctor.ts

@@ -0,0 +1,107 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { agentRoot } from './render';
+import { registry, select } from './registry';
+import { plan } from './converge';
+import type { Platform } from '../platform/types';
+import type { DoctorCheck } from '../doctor-check';
+
+export async function agentChecks(platform: Platform): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+  for (const [tool, definition] of Object.entries(registry.tools)) {
+    const binary = Bun.which(definition.binary);
+    checks.push({
+      id: `agent:${tool}`,
+      label: `${tool} installed`,
+      severity: binary ? 'pass' : 'warn',
+      detail: binary
+        ? await version(definition.binary)
+        : 'Not on PATH. Use shared mise for managed CLIs; desktop apps remain OS prerequisites.',
+    });
+  }
+  const root = agentRoot(homedir(), platform.name);
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  let profiles = 0;
+  for (const node of entries
+    .filter(
+      (entry) =>
+        entry.isDirectory() && /^[a-z0-9][a-z0-9-]{0,62}$/.test(entry.name)
+    )
+    .slice(0, 64)) {
+    for (const tool of Object.keys(registry.defaults)) {
+      for (const profile of ['direct', 'proxy']) {
+        const check = await profileCheck(root, node.name, tool, profile);
+        if (check) {
+          checks.push(check);
+          profiles++;
+        }
+      }
+    }
+  }
+  if (profiles === 0)
+    checks.push({
+      id: 'agent:profiles',
+      label: 'Managed profiles',
+      severity: 'warn',
+      detail:
+        'No applied profiles. Run bun src/agents/cli.ts agents preview --node ID, then bun src/agents/cli.ts --yes agents apply --node ID.',
+    });
+  return checks;
+}
+
+async function profileCheck(
+  root: string,
+  node: string,
+  tool: string,
+  profile: string
+): Promise<DoctorCheck | null> {
+  const receiptPath = join(root, node, tool, profile, 'receipt.json');
+  if (!(await lstat(receiptPath).catch(() => null))) return null;
+  try {
+    const result = await plan({
+      root,
+      selection: select(node, tool, profile),
+      revision: 'unverified',
+    });
+    if (!result.previous) return null;
+    const clean =
+      result.files.every((file) => file.state === 'unchanged') &&
+      result.previous.fingerprint === result.fingerprint;
+    return {
+      id: `agent:${node}:${tool}:${profile}`,
+      label: 'Managed profile drift',
+      severity: clean ? 'pass' : 'fail',
+      detail: `Applied revision ${result.previous.revision}; static configuration ${clean ? 'matches' : 'drifted'}. Secret availability, endpoint, inference and T3 end-to-end require bun src/agents/cli.ts agents verify/operator tests.`,
+    };
+  } catch {
+    return {
+      id: `agent:${node}:${tool}:${profile}`,
+      label: 'Managed profile drift',
+      severity: 'fail',
+      detail:
+        'Profile or receipt cannot be validated. Inspect locally and preview before applying; raw contents withheld.',
+    };
+  }
+}
+
+async function version(binary: string): Promise<string> {
+  try {
+    const child = Bun.spawn([binary, '--version'], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const timer = setTimeout(() => child.kill(), 5000);
+    try {
+      const text = await new Response(child.stdout).text();
+      const match = text.match(/\b\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?\b/);
+      return (await child.exited) === 0 && match
+        ? `Version ${match[0]}; installation pins remain owned by mise.`
+        : 'Version unverified.';
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return 'Version unverified.';
+  }
+}

package/src/agents/errors.ts

@@ -0,0 +1,2 @@
+/** Only explicitly authored messages may cross the agent CLI error boundary. */
+export class AgentConfigurationError extends Error {}

package/src/agents/files.ts

@@ -0,0 +1,73 @@
+import { AgentConfigurationError } from './errors';
+import {
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+  copyFile,
+  chmod,
+} from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { digest } from './registry';
+
+export async function safeParents(path: string): Promise<void> {
+  let current = path;
+  while (current !== parse(current).root) {
+    try {
+      if ((await lstat(current)).isSymbolicLink())
+        throw new AgentConfigurationError(
+          'Symlink conflict; move the managed destination before applying.'
+        );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    current = dirname(current);
+  }
+}
+
+export async function readOwned(path: string): Promise<string | null> {
+  await safeParents(path);
+  try {
+    if (!(await lstat(path)).isFile())
+      throw new AgentConfigurationError(
+        'Managed destination is not a regular file.'
+      );
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function atomicWrite(path: string, value: string): Promise<void> {
+  await safeParents(path);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, value, { flag: 'wx', mode: 0o600 });
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+export async function backup(path: string, root: string): Promise<void> {
+  const dir = join(root, 'backups');
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const target = join(dir, randomUUID());
+  await copyFile(path, target);
+  await chmod(target, 0o600);
+}
+
+export function fileState(
+  current: string | null,
+  desired: string,
+  previous?: string
+): string {
+  if (current === desired) return 'unchanged';
+  if (current === null) return 'create';
+  return previous === digest(current) ? 'update' : 'conflict';
+}

package/src/agents/fleet-verify.ts

@@ -0,0 +1,156 @@
+import { providerFailureCode } from './provider-errors';
+import { verifyRoundTrip } from './round-trip';
+import { proxyKey } from './secrets';
+import type { Check } from '../types';
+import { registry, type Selection } from './registry';
+import { verifyProvider } from './verify';
+import { fileURLToPath } from 'node:url';
+import {
+  cacheKey,
+  cachedCheck,
+  sourceKey,
+  type VerifyCache,
+} from './verify-cache';
+
+/** The verifier's own code: changing how providers are checked re-verifies.
+ * Resolved from the module URL: the published CLI loads this on Node, which has
+ * no `import.meta.dir`.
+ */
+const VERIFIER_SOURCES = ['fleet-verify.ts', 'verify.ts', 'round-trip.ts'].map(
+  (name) => fileURLToPath(new URL(name, import.meta.url))
+);
+
+/** Uses the selected gateway credential in this node's noninteractive environment.
+ * Authentication/inference evidence does not certify native clients or paired T3.
+ */
+export async function verifyFleetProviders(
+  node: string,
+  cache: VerifyCache = {}
+): Promise<Check[]> {
+  let key: string;
+  try {
+    key = await proxyKey();
+  } catch {
+    return Object.keys(registry.proxy.routes).map((provider) => ({
+      id: `provider:${provider}:authentication`,
+      status: 'fail',
+      summary: 'PROVIDER_UNATTENDED_CREDENTIAL_REQUIRED',
+      remedy: {
+        action:
+          'Restore this node’s existing Vault authorization and renewal. No model requests or native OAuth login were attempted.',
+      },
+    }));
+  }
+
+  // Warm runs reuse recent passes, but always prove this node's key still
+  // authenticates to the live gateway; if it does not, verify everything.
+  const live = await gatewayAuthenticates(key);
+  const code = await sourceKey(VERIFIER_SOURCES);
+  // Providers are independent upstream accounts: verify them concurrently so
+  // the slowest one, not their sum, bounds the step. Order stays stable.
+  return Promise.all(
+    Object.entries(registry.proxy.routes).map(([provider, route]) =>
+      cachedCheck(
+        `provider-${node}-${provider}`,
+        cacheKey(node, registry.proxy.endpoint, route, code),
+        () => verifyRoute(node, provider, route, key),
+        {
+          ...cache,
+          bypass: Boolean(cache.bypass) || !live,
+          reuse: (check) => check.summary !== QUOTA_SUMMARY,
+        }
+      )
+    )
+  );
+}
+
+/** One cheap authenticated model listing: Vault key, proxy and route are live. */
+async function gatewayAuthenticates(key: string): Promise<boolean> {
+  try {
+    const response = await fetch(registry.proxy.endpoint + '/v1/models', {
+      headers: { Authorization: `Bearer ${key}` },
+      redirect: 'error',
+      signal: AbortSignal.timeout(15_000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function verifyRoute(
+  node: string,
+  provider: string,
+  route: { model: string; native: string | null; harness: string },
+  key: string
+): Promise<Check> {
+  const selection: Selection = {
+    node,
+    profile: 'proxy',
+    tool: (route.native ?? route.harness) as Selection['tool'],
+    model: route.model,
+  };
+  try {
+    const evidence = await verifyProvider(selection, true, key);
+    await verifyRoundTrip(route.model, key);
+    return {
+      id: `provider:${provider}:inference`,
+      status: evidence.inference === 'pass' ? 'pass' : 'fail',
+      summary:
+        'Gateway authentication, bounded inference, completed streaming and safe echo tool round trip verified from node environment. Native CLI/T3 execution is separate.',
+    };
+  } catch (error) {
+    return inferenceFailure(provider, providerFailureCode(error));
+  }
+}
+
+/** Rate limits and exhausted quota are expected on shared subscription
+ * accounts: the gateway authenticated and routed the request, and the account
+ * recovers on its own. They are not reported at all (a quiet pass).
+ */
+const QUOTA = new Set(['PROVIDER_RATE_LIMITED']);
+/** Summary of the quiet pass; native session checks skip these accounts. */
+export const QUOTA_SUMMARY =
+  'Gateway authenticated and routed the request; the provider account is rate limited or out of quota and recovers on its own.';
+
+/** Proxy routes whose provider account is out of quota in these checks. */
+export function quotaLimited(checks: Check[]): Set<string> {
+  return new Set(
+    checks
+      .filter((check) => check.summary === QUOTA_SUMMARY)
+      .map((check) => check.id.split(':')[1]!)
+  );
+}
+
+/** Other conditions owned by the upstream provider account (outage, billing)
+ * do not mean this node is misconfigured: the gateway answered and routed the
+ * request. They are warnings, so a provider outage never fails fleet-sync.
+ */
+const UPSTREAM: Record<string, string> = {
+  PROVIDER_UPSTREAM_UNAVAILABLE:
+    'The provider returned a server error through the gateway. Retry later; no fleet change is needed.',
+  PROVIDER_MODEL_UNAVAILABLE:
+    'The provider refused the declared model (often billing or account access). Fix the provider account, or change the model in agents/registry.json.',
+  PROVIDER_TIMEOUT:
+    'The provider did not answer within the bounded verification deadline. Retry later.',
+};
+
+export function inferenceFailure(provider: string, code: string): Check {
+  if (QUOTA.has(code))
+    return {
+      id: `provider:${provider}:inference`,
+      status: 'pass',
+      summary: QUOTA_SUMMARY,
+    };
+  const upstream = UPSTREAM[code];
+  return {
+    id: `provider:${provider}:inference`,
+    status: upstream ? 'warn' : 'fail',
+    summary: code,
+    remedy: {
+      action:
+        upstream ??
+        `Verify unattended Vault access and the declared ${provider} model on the singleton gateway. Preserve OAuth state; do not log native auth on proxy clients.`,
+    },
+  };
+}

package/src/agents/launch.ts

@@ -0,0 +1,290 @@
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { AgentConfigurationError } from './errors';
+import { registry, type Selection } from './registry';
+import { accountPrefix, accountSlug, discoverAccounts } from './accounts';
+import { startAccountRelay } from './account-relay';
+import { proxyKey } from './secrets';
+import { pinnedBinary, pinnedPath } from './toolchain';
+
+/** `account` (its email) pins a proxy launch to one signed-in proxy account. */
+export async function launchProfile(
+  root: string,
+  selection: Selection,
+  args: string[],
+  account?: string
+): Promise<number> {
+  const directory = join(
+    root,
+    selection.node,
+    selection.tool,
+    selection.profile
+  );
+  const env = { ...process.env };
+  env['PATH'] = pinnedPath(env);
+  // Do not allow an ambient gateway to silently change the selected route.
+  for (const name of [
+    'OPENAI_BASE_URL',
+    'ANTHROPIC_BASE_URL',
+    'ANTHROPIC_AUTH_TOKEN',
+    'CLAUDE_CODE_USE_BEDROCK',
+    'CLAUDE_CODE_USE_VERTEX',
+    'CLAUDE_CODE_USE_FOUNDRY',
+    'CLIPROXY_API_KEY',
+    'GOOGLE_GEMINI_BASE_URL',
+    'GROK_MODELS_BASE_URL',
+    'GROK_CODE_XAI_API_KEY',
+    'XAI_API_KEY',
+  ])
+    delete env[name];
+  if (selection.profile === 'proxy') {
+    env['CLIPROXY_API_KEY'] = await proxyKey();
+    configureGatewayEnvironment(env, selection);
+  }
+  toolEnvironment(env, selection, directory);
+  const pinned =
+    account && selection.profile === 'proxy'
+      ? await pinAccount(env, selection, { account, directory })
+      : null;
+  try {
+    return await spawnAgent(selection, directory, env, [
+      pinned?.args ?? [],
+      args,
+    ]);
+  } finally {
+    pinned?.stop();
+  }
+}
+
+async function spawnAgent(
+  selection: Selection,
+  directory: string,
+  env: NodeJS.ProcessEnv,
+  [pinned, args]: [string[], string[]]
+): Promise<number> {
+  // Resolve the executable before launchArgs may point HOME at the profile.
+  const executable =
+    selection.tool === 'antigravity' && args[0] !== 'acp'
+      ? pinnedBinary(selection.tool, env)
+      : selection.tool;
+  const command = [
+    executable,
+    ...pinned,
+    ...launchArgs(selection, directory, args, env),
+  ];
+  if (selection.tool === 'antigravity' && args[0] === 'acp')
+    return relayAcp(command, env);
+  const child = Bun.spawn(command, {
+    env,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  return child.exited;
+}
+
+/** Routes every request of this launch to one account's proxy credential.
+ * Claude and Codex send whichever model was picked, so they talk to a loopback
+ * relay that adds the account's model prefix. OpenCode lists exactly the
+ * account's prefixed models, so it needs no relay.
+ */
+export async function pinAccount(
+  env: NodeJS.ProcessEnv,
+  selection: Selection,
+  { account, directory }: { account: string; directory: string },
+  { relay = startAccountRelay, discover = discoverAccounts } = {}
+): Promise<{ args: string[]; stop: () => void }> {
+  const prefix = accountPrefix(selection.tool, account);
+  // What the account serves right now, preferred default first.
+  const served = (await discover(env['CLIPROXY_API_KEY'] ?? '')).find(
+    (entry) => entry.tool === selection.tool && entry.email === account
+  );
+  if (!served)
+    throw new AgentConfigurationError(
+      'This account is not signed in on the CLI proxy.'
+    );
+  if (selection.tool === 'opencode') {
+    delete env['OPENCODE_CONFIG'];
+    env['OPENCODE_CONFIG_CONTENT'] = JSON.stringify(accountOpenCode(served));
+    return { args: [], stop: () => {} };
+  }
+  const { url, stop } = relay(registry.proxy.endpoint, prefix);
+  if (selection.tool === 'claude') {
+    env['ANTHROPIC_BASE_URL'] = url;
+    // Aliases and the default must name models a Claude account serves.
+    const [opus, sonnet, haiku] = (
+      registry.proxy.accounts as Record<string, { models: string[] }>
+    )['claude']!.models;
+    env['ANTHROPIC_DEFAULT_OPUS_MODEL'] = opus;
+    env['ANTHROPIC_DEFAULT_SONNET_MODEL'] = sonnet;
+    env['ANTHROPIC_DEFAULT_HAIKU_MODEL'] = haiku;
+    env['ANTHROPIC_MODEL'] = sonnet;
+    return { args: [], stop };
+  }
+  // Each account keeps its own Codex sessions; the provider is declared on
+  // the command line because that home has no rendered config.
+  env['CODEX_HOME'] = join(directory, '..', `account-${accountSlug(account)}`);
+  mkdirSync(env['CODEX_HOME'], { recursive: true, mode: 0o700 });
+  const provider = {
+    name: 'Personal CLI Proxy',
+    base_url: `${url}/v1`,
+    env_key: 'CLIPROXY_API_KEY',
+    wire_api: 'responses',
+    requires_openai_auth: false,
+    supports_websockets: false,
+  };
+  return {
+    args: [
+      ['model', served.models[0]],
+      ['model_provider', 'personal_proxy'],
+      ...Object.entries(provider).map(
+        ([key, value]) =>
+          [`model_providers.personal_proxy.${key}`, value] as const
+      ),
+    ].flatMap(([key, value]) => ['-c', `${key}=${JSON.stringify(value)}`]),
+    stop,
+  };
+}
+
+/** OpenCode configuration that offers only one account's models. */
+function accountOpenCode(route: { prefix: string; models: string[] }) {
+  const models = route.models.map((model) => `${route.prefix}/${model}`);
+  return {
+    $schema: 'https://opencode.ai/config.json',
+    model: `personal_proxy/${models[0]}`,
+    enabled_providers: ['personal_proxy'],
+    provider: {
+      personal_proxy: {
+        npm: '@ai-sdk/openai',
+        options: {
+          baseURL: registry.proxy.endpoint + '/v1',
+          apiKey: '{env:CLIPROXY_API_KEY}',
+        },
+        models: Object.fromEntries(
+          models.map((id) => [id, { name: id.slice(route.prefix.length + 1) }])
+        ),
+      },
+    },
+  };
+}
+
+/** Per-tool profile selection and self-updater switches. */
+function toolEnvironment(
+  env: NodeJS.ProcessEnv,
+  selection: Selection,
+  directory: string
+): void {
+  if (selection.tool === 'claude') env['DISABLE_AUTOUPDATER'] = '1';
+  if (selection.tool === 'codex') env['CODEX_HOME'] = directory;
+  if (selection.tool === 'opencode')
+    env['OPENCODE_CONFIG'] = join(directory, 'opencode.json');
+  if (selection.tool === 'gemini') env['GEMINI_CLI_HOME'] = directory;
+  if (selection.tool === 'grok') {
+    env['GROK_HOME'] = directory;
+    env['GROK_DISABLE_AUTOUPDATER'] = '1';
+  }
+  // Only "true" disables Antigravity's in-place self-updater ("1" is ignored).
+  if (selection.tool === 'antigravity')
+    env['AGY_CLI_DISABLE_AUTO_UPDATE'] = 'true';
+}
+
+/** T3's managed policy may not carry a credential, so its Antigravity
+ * instance keeps the default Google sign-in method. The proxy key is the
+ * credential here: the one ACP `authenticate` request is switched to the
+ * Gemini API-key method on its way in; every other message passes unchanged.
+ */
+async function relayAcp(
+  command: string[],
+  env: NodeJS.ProcessEnv
+): Promise<number> {
+  const child = Bun.spawn(command, {
+    env,
+    stdin: 'pipe',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  void (async () => {
+    let pending = '';
+    for await (const chunk of process.stdin) {
+      pending += String(chunk);
+      let end = pending.indexOf('\n');
+      while (end >= 0) {
+        void child.stdin.write(
+          rewriteAuthenticate(pending.slice(0, end)) + '\n'
+        );
+        pending = pending.slice(end + 1);
+        end = pending.indexOf('\n');
+      }
+      void child.stdin.flush();
+    }
+    if (pending) void child.stdin.write(rewriteAuthenticate(pending));
+    void child.stdin.end();
+  })();
+  return child.exited;
+}
+
+const BROWSER_SIGN_IN = new Set(['oauth-personal', 'oauth-business']);
+
+/** Rewrites only an ACP `authenticate` request for a browser sign-in method. */
+export function rewriteAuthenticate(line: string): string {
+  if (!line.includes('"authenticate"')) return line;
+  try {
+    const message = JSON.parse(line) as {
+      method?: unknown;
+      params?: { methodId?: unknown };
+    };
+    if (
+      message.method !== 'authenticate' ||
+      !BROWSER_SIGN_IN.has(String(message.params?.methodId))
+    )
+      return line;
+    return JSON.stringify({
+      ...message,
+      params: { ...message.params, methodId: 'gemini-api-key' },
+    });
+  } catch {
+    return line;
+  }
+}
+
+/** Tool-specific arguments that select the rendered profile. */
+export function launchArgs(
+  selection: Selection,
+  directory: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): string[] {
+  if (selection.tool === 'claude')
+    return ['--settings', join(directory, 'settings.json'), ...args];
+  if (selection.tool === 'antigravity') {
+    // Over ACP (how T3 runs it) T3 owns a private GEMINI_HOME and selects the
+    // Gemini API key method; the proxy key and endpoint come from this wrapper.
+    // Run directly, the fleet profile is the home; one-shot print mode only
+    // reads ~/.gemini, so it also runs with HOME set to the profile.
+    if (args[0] === 'acp') {
+      env['GEMINI_HOME'] ??= join(directory, '.gemini');
+      return ['acp', '--disable-telemetry', ...args.slice(1)];
+    }
+    env['HOME'] = directory;
+  }
+  return args;
+}
+
+function configureGatewayEnvironment(
+  env: NodeJS.ProcessEnv,
+  selection: Selection
+): void {
+  if (selection.tool === 'gemini' || selection.tool === 'antigravity') {
+    delete env['GOOGLE_GENAI_USE_VERTEXAI'];
+    delete env['GOOGLE_GENAI_USE_GCA'];
+    env['GOOGLE_GEMINI_BASE_URL'] = registry.proxy.endpoint;
+    env['GEMINI_API_KEY'] = env['CLIPROXY_API_KEY'];
+  }
+  if (selection.tool === 'claude') {
+    delete env['ANTHROPIC_API_KEY'];
+    env['ANTHROPIC_BASE_URL'] = registry.proxy.endpoint;
+    env['ANTHROPIC_AUTH_TOKEN'] = env['CLIPROXY_API_KEY'];
+    for (const family of ['OPUS', 'SONNET', 'HAIKU'])
+      env[`ANTHROPIC_DEFAULT_${family}_MODEL`] = selection.model;
+  }
+}