@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/agents/account-relay.ts

@@ -0,0 +1,111 @@
+/** Pins one agent process to one provider account. The proxy routes a model
+ * named `<prefix>/<model>` only to the credential that owns the prefix, but
+ * agents send whichever model the user picked. This loopback relay lives only
+ * as long as the agent it was started for: it adds the prefix to each request
+ * and forwards everything else (credentials, streaming) unchanged.
+ */
+export function startAccountRelay(
+  endpoint: string,
+  prefix: string
+): { url: string; stop: () => void } {
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    // Model streams are idle for as long as a model thinks.
+    idleTimeout: 0,
+    fetch: (request) => forward(request, endpoint, prefix),
+  });
+  return {
+    url: `http://127.0.0.1:${server.port}`,
+    stop: () => void server.stop(true),
+  };
+}
+
+type RelayOptions = {
+  send?: typeof fetch;
+  pause?: (seconds: number) => Promise<void>;
+};
+const sleep = (seconds: number) =>
+  new Promise<void>((done) => setTimeout(done, seconds * 1000));
+
+export async function forward(
+  request: Request,
+  endpoint: string,
+  prefix: string,
+  { send = fetch, pause = sleep }: RelayOptions = {}
+): Promise<Response> {
+  const url = new URL(request.url);
+  const headers = new Headers(request.headers);
+  // fetch sets these for the upstream request and decodes its response.
+  for (const name of ['host', 'content-length', 'accept-encoding'])
+    headers.delete(name);
+  let body: string | undefined;
+  if (request.body) {
+    // An unreadable body could not be pinned; never forward it to the pool.
+    if (headers.has('content-encoding'))
+      return new Response('The account relay needs an uncompressed request.', {
+        status: 415,
+      });
+    body = pinModel(await request.text(), prefix);
+  }
+  const attempt = () =>
+    send(endpoint + url.pathname + url.search, {
+      method: request.method,
+      headers,
+      ...(body === undefined ? {} : { body }),
+      redirect: 'error',
+      signal: request.signal,
+    });
+  const upstream = await reachProxy(attempt, request.signal, pause);
+  if (!upstream)
+    return new Response('The CLI proxy is unreachable.', { status: 502 });
+  const answered = new Headers(upstream.headers);
+  answered.delete('content-encoding');
+  answered.delete('content-length');
+  return new Response(upstream.body, {
+    status: upstream.status,
+    headers: answered,
+  });
+}
+
+/** Seconds to wait before each further attempt (about a minute in total). */
+export const RETRY_DELAYS = [1, 2, 4, 8, 15, 30];
+/** The route to the proxy answered instead of the proxy: its connector or the
+ * proxy itself is restarting. 502-504 from a gateway, 520-530 from Cloudflare.
+ */
+const routeDown = (status: number) =>
+  (status >= 502 && status <= 504) || (status >= 520 && status <= 530);
+
+/** A brief outage of the route must not end an agent's turn: nothing has been
+ * sent to the agent yet, so the same request is simply tried again until the
+ * proxy answers or the delays run out. The last answer is returned as it is.
+ */
+async function reachProxy(
+  attempt: () => Promise<Response>,
+  signal: AbortSignal,
+  pause: (seconds: number) => Promise<void>
+): Promise<Response | null> {
+  for (let tries = 0; ; tries++) {
+    const delay = RETRY_DELAYS[tries];
+    const response = await attempt().catch(() => null);
+    if (response && !routeDown(response.status)) return response;
+    if (delay === undefined || signal.aborted) return response;
+    await response?.body?.cancel().catch(() => undefined);
+    await pause(delay);
+  }
+}
+
+/** The JSON request with its model routed to the account; other bodies as-is. */
+export function pinModel(text: string, prefix: string): string {
+  try {
+    const payload: unknown = JSON.parse(text);
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      const model = (payload as { model?: unknown }).model;
+      if (typeof model === 'string' && !model.startsWith(`${prefix}/`))
+        return JSON.stringify({ ...payload, model: `${prefix}/${model}` });
+    }
+  } catch {
+    /* Not JSON: nothing to route. */
+  }
+  return text;
+}

package/src/agents/accounts.ts

@@ -0,0 +1,85 @@
+import { AgentConfigurationError } from './errors';
+import { registry } from './registry';
+
+/** One signed-in provider account on the proxy, offered through one tool. */
+export type Account = {
+  tool: string;
+  email: string;
+  /** Models named `<prefix>/<model>` are served only by this account. */
+  prefix: string;
+  /** Every model the account serves, preferred default first. */
+  models: string[];
+};
+
+type Route = { provider: string; models: string[] };
+const ROUTES = registry.proxy.accounts as Record<string, Route>;
+const EMAIL = /^[^\s@/]{1,64}@[^\s@/]{1,255}$/;
+
+/** Stable file and instance name for an account. */
+export const accountSlug = (value: string): string =>
+  value.toLowerCase().replace(/[^a-z0-9]+/g, '_');
+
+/** The proxy gives each account credential the prefix `<type>-<email>`. */
+export function accountPrefix(tool: string, email: string): string {
+  const route = ROUTES[tool];
+  if (!route || !EMAIL.test(email))
+    throw new AgentConfigurationError(
+      'Unknown provider account; T3 offers only accounts signed in on the CLI proxy.'
+    );
+  return `${route.provider}-${email}`;
+}
+
+/** Accounts are never declared in source: the proxy lists a prefixed copy of
+ * each model for every signed-in credential, and that list is the roster.
+ */
+export function accountsFrom(modelIds: string[]): Account[] {
+  const accounts: Account[] = [];
+  for (const [tool, route] of Object.entries(ROUTES)) {
+    const served = new Map<string, string[]>();
+    for (const id of modelIds) {
+      const slash = id.indexOf('/');
+      const owner = id.slice(0, slash);
+      if (slash < 0 || !owner.startsWith(`${route.provider}-`)) continue;
+      const email = owner.slice(route.provider.length + 1);
+      if (!EMAIL.test(email)) continue;
+      served.set(email, [...(served.get(email) ?? []), id.slice(slash + 1)]);
+    }
+    for (const email of [...served.keys()].sort())
+      accounts.push({
+        tool,
+        email,
+        prefix: `${route.provider}-${email}`,
+        models: preferred(served.get(email)!.sort(), route.models),
+      });
+  }
+  return accounts;
+}
+
+const preferred = (models: string[], first: string[]) => [
+  ...first.filter((model) => models.includes(model)),
+  ...models.filter((model) => !first.includes(model)),
+];
+
+/** Reads the roster with this node's own proxy key. Throws when the proxy does
+ * not answer: an unknown roster must never read as "no accounts".
+ */
+export async function discoverAccounts(
+  key: string,
+  send: typeof fetch = fetch
+): Promise<Account[]> {
+  const response = await send(registry.proxy.endpoint + '/v1/models', {
+    headers: { Authorization: `Bearer ${key}` },
+    redirect: 'error',
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok)
+    throw new AgentConfigurationError('The CLI proxy did not list its models.');
+  const body = (await response.json()) as { data?: { id?: unknown }[] };
+  if (!Array.isArray(body.data))
+    throw new AgentConfigurationError('The CLI proxy did not list its models.');
+  return accountsFrom(
+    body.data.flatMap((model) =>
+      typeof model.id === 'string' ? [model.id] : []
+    )
+  );
+}

package/src/agents/audit.ts

@@ -0,0 +1,77 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readFile, readdir } from 'node:fs/promises';
+import type { Platform } from '../platform/types';
+
+/** Content values never leave this module; the audit inventories ownership boundaries. */
+export async function auditMachine(platform: Platform) {
+  const home = homedir();
+  const paths = [
+    join(home, '.codex', 'config.toml'),
+    join(home, '.claude', 'settings.json'),
+    join(home, '.claude.json'),
+    join(home, '.gemini', 'settings.json'),
+    join(platform.opencodeDir(), 'opencode.json'),
+    join(home, '.cursor', 'mcp.json'),
+    join(home, '.t3', 'userdata', 'settings.json'),
+    join(home, '.config', 'cliproxy-fleet', 'settings.json'),
+  ];
+  const files = [];
+  for (const path of paths) files.push(await inspect(path));
+  const directories = [];
+  for (const tool of ['.codex', '.claude', '.gemini', '.cursor']) {
+    for (const kind of ['skills', 'plugins']) {
+      const path = join(home, tool, kind);
+      const entries = await readdir(path).catch(() => []);
+      directories.push({
+        tool,
+        kind,
+        entries: entries.length,
+        ownership: 'native/unmanaged; review sources before migration',
+      });
+    }
+  }
+  return {
+    version: 1,
+    files,
+    directories,
+    environment: Object.keys(process.env).filter((key) =>
+      /^(CODEX_|CLAUDE_|ANTHROPIC_|OPENAI_|GEMINI_|GOOGLE_|OPENCODE_|T3CODE_|CLIPROXY_|CURSOR_)/.test(
+        key
+      )
+    ),
+    warning:
+      'Metadata only; values, credentials and runtime state are withheld. This machine is not proof of fleet-wide coverage. Native/project/organization settings may add configuration.',
+  };
+}
+
+async function inspect(path: string) {
+  try {
+    const text = await readFile(path, 'utf8');
+    const value: unknown = path.endsWith('.toml')
+      ? Bun.TOML.parse(text)
+      : JSON.parse(text);
+    return {
+      path,
+      present: true,
+      fields: fieldNames(value),
+      ownership:
+        'native/unmanaged; dedicated dev-fleet profiles do not overwrite this file',
+    };
+  } catch (error) {
+    return {
+      path,
+      present: (error as NodeJS.ErrnoException).code !== 'ENOENT',
+      fields: [],
+      ownership:
+        'missing or unparseable; inspect locally, no raw error retained',
+    };
+  }
+}
+
+export function fieldNames(value: unknown): string[] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+  return Object.keys(value)
+    .filter((key) => /^[a-zA-Z_$][a-zA-Z0-9_$-]{0,63}$/.test(key))
+    .sort();
+}

package/src/agents/cli.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+/** Internal entry fleet-sync runs on each node for agent profile commands
+ * (`agents apply|status|verify|run`). People use `devfleet workstation agents`.
+ */
+import { Command } from 'commander';
+import { registerAgents } from './command';
+
+const program = new Command('fleet-agents')
+  .option('--json', 'Machine-readable output')
+  .option('--yes', 'Apply without confirmation')
+  .option('--non-interactive', 'Fail instead of prompting');
+registerAgents(program, () => program.opts());
+await program.parseAsync(process.argv);

package/src/agents/command.ts

@@ -0,0 +1,204 @@
+/* eslint-disable no-console -- this command's contract is JSON on stdout. */
+import { auditMachine } from './audit';
+import { AgentConfigurationError } from './errors';
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { currentPlatform } from '../platform';
+import { registry, select } from './registry';
+import { agentRoot } from './render';
+import { convergeAgents, plan, publicPlan } from './converge';
+import { launchProfile } from './launch';
+import { verifyProvider } from './verify';
+
+/** The global flags of the CLI that hosts these commands. */
+type GlobalOpts = { json?: boolean | undefined; yes?: boolean | undefined };
+
+/** The monorepo checkout that contains this package. */
+const workspaceRoot = (): string => join(import.meta.dir, '../..');
+
+async function revision(requireClean: boolean): Promise<string> {
+  if (requireClean) await requireCleanSources();
+  const child = Bun.spawn(['git', 'rev-parse', 'HEAD'], {
+    cwd: workspaceRoot(),
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+  const value = (await new Response(child.stdout).text()).trim();
+  if ((await child.exited) || !/^[a-f0-9]{40}$/.test(value))
+    throw new AgentConfigurationError('Cannot resolve checkout revision.');
+  return value;
+}
+
+type AgentOptions = {
+  node: string;
+  tool: string;
+  profile: string;
+  adopt?: boolean;
+  smoke?: boolean;
+};
+
+export function registerAgents(
+  program: Command,
+  globals: () => GlobalOpts
+): void {
+  const agents = program
+    .command('agents')
+    .description('[ws] Versioned agent/provider profiles');
+  agents
+    .command('inventory')
+    .action(() => console.log(JSON.stringify(registry, null, 2)));
+  agents
+    .command('audit')
+    .action(async () =>
+      console.log(
+        JSON.stringify(await auditMachine(currentPlatform()), null, 2)
+      )
+    );
+  registerT3Plan(agents);
+  for (const action of ['preview', 'apply', 'status', 'verify', 'run']) {
+    agents
+      .command(action)
+      .argument('[args...]')
+      .requiredOption('--node <id>', 'Explicit fleet node ID')
+      .option(
+        '--tool <tool>',
+        'codex|claude|opencode|gemini|grok|antigravity',
+        'codex'
+      )
+      .option('--profile <profile>', 'direct|proxy', 'direct')
+      .option(
+        '--adopt',
+        'Back up and replace conflicting dedicated profile files'
+      )
+      .option(
+        '--smoke',
+        'Spend tokens: one request, 16 output tokens, 30 second deadline'
+      )
+      .action(async (args: string[], options: AgentOptions) => {
+        try {
+          await execute(action, args, options, globals());
+        } catch (error) {
+          console.log(
+            JSON.stringify({
+              ok: false,
+              error:
+                error instanceof AgentConfigurationError
+                  ? error.message
+                  : 'Agent operation failed. Check node/tool/profile, review conflicts with preview, authenticate this node to Vault for proxy, and check approved model availability. No raw error or response is retained.',
+            })
+          );
+          process.exitCode = 1;
+        }
+      });
+  }
+}
+
+async function execute(
+  action: string,
+  args: string[],
+  options: AgentOptions,
+  global: GlobalOpts
+) {
+  const selection = select(options.node, options.tool, options.profile);
+  const root = agentRoot(homedir(), currentPlatform().name);
+  const context = {
+    root,
+    selection,
+    revision: await revision(['apply', 'run', 'verify'].includes(action)),
+  };
+  if (action === 'apply') {
+    if (!global.yes) throw new AgentConfigurationError('Apply requires --yes.');
+    console.log(
+      JSON.stringify({
+        ok: true,
+        ...(await convergeAgents(context, options.adopt)),
+      })
+    );
+    return;
+  }
+  const result = await plan(context);
+  const clean =
+    result.files.every((file) => file.state === 'unchanged') &&
+    result.previous?.fingerprint === result.fingerprint;
+  if (['run', 'verify'].includes(action)) {
+    if (!clean)
+      throw new AgentConfigurationError(
+        'Apply the reviewed configuration first.'
+      );
+    await runOrVerify(action, root, selection, {
+      args,
+      smoke: options.smoke === true,
+    });
+    return;
+  }
+  console.log(
+    JSON.stringify({
+      ok: action === 'preview' || clean,
+      ...publicPlan(result, context.revision),
+    })
+  );
+  if (action === 'status' && !clean) process.exitCode = 1;
+}
+
+async function runOrVerify(
+  action: string,
+  root: string,
+  selection: ReturnType<typeof select>,
+  input: { args: string[]; smoke: boolean }
+) {
+  if (action === 'run') {
+    process.exitCode = await launchProfile(root, selection, input.args);
+    return;
+  }
+  console.log(
+    JSON.stringify({
+      ok: true,
+      ...(await verifyProvider(selection, input.smoke)),
+    })
+  );
+}
+
+function registerT3Plan(agents: Command): void {
+  agents
+    .command('t3-plan')
+    .requiredOption('--node <id>', 'Fleet node ID')
+    .action((options: { node: string }) => {
+      const selection = select(options.node, 'codex', 'proxy');
+      const root = agentRoot(homedir(), currentPlatform().name);
+      console.log(
+        JSON.stringify(
+          {
+            applied: false,
+            instance: 'personal_codex_proxy',
+            driver: 'codex',
+            config: {
+              binaryPath: join(workspaceRoot(), 'agents/codex-proxy.ts'),
+              homePath: join(root, selection.node, 'codex', 'proxy'),
+            },
+            environment: [{ name: 'WS_AGENT_NODE', value: selection.node }],
+            instruction:
+              'Use these explicitly owned fields in a new T3 Codex provider instance. Preserve all other settings and secret references. Native Windows executable launch has not been validated.',
+          },
+          null,
+          2
+        )
+      );
+    });
+}
+
+async function requireCleanSources(): Promise<void> {
+  const child = Bun.spawn(
+    ['git', 'status', '--porcelain', '--', 'agents', 'src/agents'],
+    {
+      cwd: workspaceRoot(),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    }
+  );
+  const output = await new Response(child.stdout).text();
+  if ((await child.exited) || output.trim())
+    throw new AgentConfigurationError(
+      'Fleet agent sources are dirty. Commit/review configuration before applying or launching a managed profile. Local work was preserved.'
+    );
+}

package/src/agents/converge.ts

@@ -0,0 +1,123 @@
+import { AgentConfigurationError } from './errors';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { digest, registry, type Selection } from './registry';
+import { render } from './render';
+import {
+  atomicWrite,
+  backup,
+  fileState,
+  readOwned,
+  safeParents,
+} from './files';
+
+export type Receipt = {
+  version: 1;
+  revision: string;
+  fingerprint: string;
+  files: Record<string, string>;
+};
+export type Context = { root: string; revision: string; selection: Selection };
+
+export async function plan(context: Context) {
+  const { root, selection } = context;
+  const directory = join(
+    root,
+    selection.node,
+    selection.tool,
+    selection.profile
+  );
+  const receiptPath = join(directory, 'receipt.json');
+  const raw = await readOwned(receiptPath);
+  const previous = raw ? parseReceipt(raw) : null;
+  const outputs = render(selection);
+  const files = [];
+  for (const [name, content] of Object.entries(outputs)) {
+    const path = join(directory, name);
+    const current = await readOwned(path);
+    files.push({
+      name,
+      path,
+      content,
+      state: fileState(current, content, previous?.files[name]),
+    });
+  }
+  const fingerprint = digest(JSON.stringify({ registry, selection, outputs }));
+  return { directory, receiptPath, previous, files, fingerprint };
+}
+
+export async function convergeAgents(context: Context, adopt = false) {
+  await safeParents(context.root);
+  await mkdir(context.root, { recursive: true, mode: 0o700 });
+  const lock = join(context.root, '.apply-lock');
+  try {
+    await mkdir(lock);
+  } catch {
+    throw new AgentConfigurationError(
+      'Another apply is active; inspect .apply-lock before retrying.'
+    );
+  }
+  try {
+    const result = await plan(context);
+    if (!adopt && result.files.some((file) => file.state === 'conflict'))
+      throw new AgentConfigurationError(
+        'Unmanaged or modified configuration. Review locally, then use --adopt to back up and replace only this profile.'
+      );
+    for (const file of result.files) {
+      if (file.state === 'unchanged') continue;
+      if ((await readOwned(file.path)) !== null)
+        await backup(file.path, context.root);
+      await atomicWrite(file.path, file.content);
+    }
+    const receipt: Receipt = {
+      version: 1,
+      revision: context.revision,
+      fingerprint: result.fingerprint,
+      files: Object.fromEntries(
+        result.files.map((file) => [file.name, digest(file.content)])
+      ),
+    };
+    const encoded = JSON.stringify(receipt, null, 2) + '\n';
+    if ((await readOwned(result.receiptPath)) !== encoded)
+      await atomicWrite(result.receiptPath, encoded);
+    return {
+      ...publicPlan(result, context.revision),
+      appliedRevision: context.revision,
+      receiptMatches: true,
+    };
+  } finally {
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+
+export function publicPlan(
+  result: Awaited<ReturnType<typeof plan>>,
+  revision: string
+) {
+  return {
+    revision,
+    appliedRevision: result.previous?.revision ?? null,
+    fingerprint: result.fingerprint,
+    receiptMatches: result.previous?.fingerprint === result.fingerprint,
+    files: result.files.map(({ name, state }) => ({ name, state })),
+    t3EndToEnd: 'unverified',
+    authenticatedInference: 'unverified',
+  };
+}
+
+function parseReceipt(raw: string): Receipt {
+  const value = JSON.parse(raw) as Receipt;
+  if (
+    value.version !== 1 ||
+    !/^[a-f0-9]{40}$/.test(value.revision) ||
+    !/^[a-f0-9]{64}$/.test(value.fingerprint) ||
+    !value.files ||
+    !Object.values(value.files).every(
+      (hash) => typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash)
+    )
+  )
+    throw new AgentConfigurationError(
+      'Invalid configuration receipt. Inspect it locally and restore a known receipt before applying.'
+    );
+  return value;
+}