@crvouga/dev-fleet 0.0.0-stage → 0.1.0

package/src/t3/accounts.ts

@@ -0,0 +1,81 @@
+import {
+  accountSlug as slug,
+  discoverAccounts,
+  type Account,
+} from '../agents/accounts';
+import { proxyKey } from '../agents/secrets';
+
+export type Roster = () => Promise<Account[]>;
+
+/** The accounts signed in on the CLI proxy, read with this node's own key.
+ * Throws when the proxy does not answer, so providers are never dropped
+ * because the roster was unreadable.
+ */
+export const proxyAccounts: Roster = async () =>
+  discoverAccounts(await proxyKey());
+
+/** How T3 runs each tool for one account. The launcher pins every request to
+ * the account named by WS_AGENT_ACCOUNT; no credential is ever placed here.
+ */
+const TOOLS: Record<
+  string,
+  { driver: string; label: string; config: Record<string, string> }
+> = {
+  claude: {
+    driver: 'claudeAgent',
+    label: 'Claude',
+    config: {
+      binaryPath: '${workspace}/agents/claude-proxy',
+      homePath: '${agents}/${node}/claude/account-${account}',
+    },
+  },
+  codex: {
+    driver: 'codex',
+    label: 'Codex',
+    config: {
+      binaryPath: '${workspace}/agents/codex-proxy.ts',
+      homePath: '${agents}/${node}/codex/account-${account}',
+    },
+  },
+  opencode: {
+    driver: 'opencode',
+    label: 'AntiGravity',
+    config: {
+      binaryPath: '${workspace}/agents/opencode-proxy.ts',
+    },
+  },
+};
+
+/** One `<Provider> <account email>` instance per signed-in account, identical
+ * on every machine because every machine reads the same proxy.
+ */
+export function accountInstances(
+  accounts: Account[],
+  variables: Record<string, string>
+): Record<string, unknown> {
+  const instances: Record<string, unknown> = {};
+  for (const account of accounts) {
+    const tool = TOOLS[account.tool];
+    if (!tool) continue;
+    const values: Record<string, string> = {
+      ...variables,
+      account: slug(account.email),
+    };
+    instances[`personal_${slug(account.prefix)}`.slice(0, 64)] = {
+      driver: tool.driver,
+      displayName: `${tool.label} ${account.email}`,
+      enabled: true,
+      config: Object.fromEntries(
+        Object.entries(tool.config).map(([key, value]) => [
+          key,
+          value.replace(/\$\{(\w+)\}/g, (_, name: string) => values[name]!),
+        ])
+      ),
+      environment: [
+        { name: 'WS_AGENT_NODE', value: variables['node'], sensitive: false },
+        { name: 'WS_AGENT_ACCOUNT', value: account.email, sensitive: false },
+      ],
+    };
+  }
+  return instances;
+}

package/src/t3/desired.ts

@@ -0,0 +1,165 @@
+import { join, resolve } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { FleetUsageError } from '../errors';
+import { object, read } from './files';
+import { proxyName } from './names';
+import { accountInstances, proxyAccounts, type Roster } from './accounts';
+
+export interface T3Options {
+  id?: string;
+  t3Home?: string;
+  definition?: string;
+  planHash?: string;
+  dryRun?: boolean;
+  import?: string;
+  /** Internal: the proxy account roster (read live when omitted). */
+  roster?: Roster;
+}
+
+export function nodeId(value?: string): string {
+  const id =
+    value ??
+    hostname()
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .slice(0, 63);
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(id))
+    throw new FleetUsageError('Invalid node ID. Use --id NAME.');
+  return id;
+}
+
+export function paths(options: T3Options, workspace: string) {
+  const base = resolve(
+    options.t3Home ?? process.env['T3CODE_HOME'] ?? join(homedir(), '.t3')
+  );
+  return {
+    settings: join(base, 'userdata/settings.json'),
+    state: join(base, 'userdata/personal-managed.json'),
+    definition: resolve(
+      options.definition ?? join(workspace, 'agents/t3.json')
+    ),
+  };
+}
+
+/** The managed instances: the fixed ones in the definition plus one per
+ * provider account signed in on the CLI proxy (`roster`, read live).
+ */
+export async function desired(
+  path: string,
+  workspace: string,
+  id: string,
+  roster: Roster = proxyAccounts
+) {
+  const raw = await read(path);
+  if (raw === null)
+    throw new FleetUsageError('T3 definition is missing in this checkout.');
+  const doc = object(raw);
+  if (
+    doc['version'] !== 1 ||
+    Object.keys(doc).some((key) => !['version', 'instances'].includes(key))
+  )
+    throw new FleetUsageError(
+      'Unsupported T3 definition. Expected version 1 and instances.'
+    );
+  const instances = object(JSON.stringify(doc['instances'] ?? null));
+  for (const [key, value] of Object.entries(instances))
+    validateInstance(key, value);
+  const agents =
+    process.platform === 'win32'
+      ? join(homedir(), 'AppData/Local/personal/agents')
+      : join(homedir(), '.config/personal/agents');
+  const variables: Record<string, string> = {
+    workspace: resolve(workspace),
+    agents,
+    node: id,
+  };
+  // Substitute individual strings, not serialized JSON: paths may contain quotes/backslashes.
+  return {
+    ...(expand(instances, variables) as Record<string, unknown>),
+    ...accountInstances(await roster(), variables),
+  };
+}
+
+function expand(value: unknown, variables: Record<string, string>): unknown {
+  if (typeof value === 'string')
+    return value.replace(/\$\{([^}]+)\}/g, (_, key: string) => {
+      if (!(key in variables))
+        throw new FleetUsageError('Unknown variable in T3 definition.');
+      return variables[key]!;
+    });
+  if (Array.isArray(value)) return value.map((item) => expand(item, variables));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, expand(item, variables)])
+    );
+  return value;
+}
+
+/** Each fixed driver accepts only the adapter fields fleet sets, under its
+ * conventional `<Provider> CLI Proxy` name. Credentials never appear here (T3
+ * refuses a managed policy that holds one): wrappers read them from Vault at
+ * launch.
+ */
+const DRIVERS: Record<
+  string,
+  { required: string[]; env?: Record<string, string> }
+> = {
+  opencode: { required: ['binaryPath'] },
+  grok: { required: ['binaryPath'], env: { XAI_API_KEY: 'fleet-cli-proxy' } },
+};
+
+function validateInstance(id: string, value: unknown): void {
+  const instance = object(JSON.stringify(value));
+  const config = object(JSON.stringify(instance['config']));
+  const driver = DRIVERS[String(instance['driver'])];
+  if (
+    !/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(id) ||
+    !driver ||
+    instance['displayName'] !== proxyName(String(instance['driver'])) ||
+    typeof instance['enabled'] !== 'boolean' ||
+    Object.keys(instance).some(
+      (key) =>
+        !['driver', 'displayName', 'enabled', 'config', 'environment'].includes(
+          key
+        )
+    ) ||
+    !validConfig(config, driver) ||
+    !validEnvironment(instance['environment'], driver.env ?? {})
+  )
+    throw new FleetUsageError(
+      'Invalid T3 instance definition; only the supported managed adapter fields are accepted.'
+    );
+}
+
+function validConfig(
+  config: Record<string, unknown>,
+  driver: { required: string[] }
+): boolean {
+  return (
+    Object.keys(config).every((key) => driver.required.includes(key)) &&
+    driver.required.every((key) => typeof config[key] === 'string')
+  );
+}
+
+/** WS_AGENT_NODE first, then exactly the driver's fixed non-secret values. */
+function validEnvironment(
+  env: unknown,
+  fixed: Record<string, string>
+): boolean {
+  const extra = Object.entries(fixed);
+  if (!Array.isArray(env) || env.length !== 1 + extra.length) return false;
+  const [node, ...rest] = env.map((item) => object(JSON.stringify(item)));
+  return (
+    node!['name'] === 'WS_AGENT_NODE' &&
+    node!['value'] === '${node}' &&
+    node!['sensitive'] === false &&
+    Object.keys(node!).length === 3 &&
+    rest.every(
+      (variable, index) =>
+        variable['name'] === extra[index]![0] &&
+        variable['value'] === extra[index]![1] &&
+        variable['sensitive'] === false &&
+        Object.keys(variable).length === 3
+    )
+  );
+}

package/src/t3/files.ts

@@ -0,0 +1,81 @@
+import {
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, parse, resolve } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { FleetUsageError } from '../errors';
+
+export const hash = (value: string): string =>
+  createHash('sha256').update(value).digest('hex');
+
+export async function safePath(path: string): Promise<void> {
+  for (
+    let current = resolve(path);
+    current !== parse(current).root;
+    current = dirname(current)
+  ) {
+    try {
+      if ((await lstat(current)).isSymbolicLink())
+        throw new FleetUsageError('Managed T3 paths cannot be symlinks.');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export async function read(path: string): Promise<string | null> {
+  await safePath(path);
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.size > 4 * 1024 * 1024)
+      throw new FleetUsageError(
+        'T3 configuration must be a regular file smaller than 4 MiB.'
+      );
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function write(path: string, contents: string): Promise<void> {
+  await safePath(path);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, contents, { mode: 0o600, flag: 'wx' });
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export function object(raw: string | null): Record<string, unknown> {
+  if (raw === null) return {};
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (value && typeof value === 'object' && !Array.isArray(value))
+      return value as Record<string, unknown>;
+  } catch {
+    /* No contents or parser details in errors. */
+  }
+  throw new FleetUsageError(
+    'Invalid T3 JSON object. Repair the file before reconciliation.'
+  );
+}
+
+export function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}

package/src/t3/names-check.ts

@@ -0,0 +1,53 @@
+import { desired, nodeId, paths } from './desired';
+import { conformT3Names } from './names';
+import type { Roster } from './accounts';
+import type { Check } from '../types';
+
+/** Fleet check: this machine's T3 lists every provider under the convention. */
+export async function providerNames(
+  id: string,
+  workspace: string,
+  apply: boolean,
+  { t3Home, roster }: { t3Home?: string; roster?: Roster } = {}
+): Promise<Check> {
+  try {
+    const target = paths(t3Home ? { t3Home } : {}, workspace);
+    const managed = Object.fromEntries(
+      Object.entries(
+        await desired(target.definition, workspace, nodeId(id), roster)
+      ).map(([instance, value]) => [
+        instance,
+        String((value as { displayName?: unknown }).displayName),
+      ])
+    );
+    const { changed } = await conformT3Names(target.settings, managed, {
+      apply,
+    });
+    return changed && !apply
+      ? {
+          id: 't3:provider-names',
+          status: 'warn',
+          summary: 'T3_PROVIDER_NAMES_PENDING',
+          remedy: {
+            action:
+              'fleet-sync renames these providers to the convention when applied.',
+          },
+        }
+      : {
+          id: 't3:provider-names',
+          status: 'pass',
+          summary:
+            'Every T3 provider is named "<Provider> CLI Proxy" or "<Provider> <account email>".',
+        };
+  } catch {
+    return {
+      id: 't3:provider-names',
+      status: 'fail',
+      summary: 'T3_PROVIDER_NAMES_UNVERIFIED',
+      remedy: {
+        action:
+          'T3 settings were unreadable or changed during the rename. Rerun fleet-sync; only provider display names are written.',
+      },
+    };
+  }
+}

package/src/t3/names.ts

@@ -0,0 +1,155 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { object, read, write } from './files';
+
+/** One naming convention for every provider T3 lists, on every machine:
+ * `<Provider> CLI Proxy` for a fleet-managed gateway instance and
+ * `<Provider> <account email>` for a native login.
+ */
+export const PROVIDER_NAMES: Record<string, string> = {
+  claudeAgent: 'Claude',
+  codex: 'Codex',
+  antigravity: 'AntiGravity',
+  grok: 'Grok',
+  opencode: 'OpenCode',
+  cursor: 'Cursor',
+};
+
+export const proxyName = (driver: string): string | undefined =>
+  PROVIDER_NAMES[driver] && `${PROVIDER_NAMES[driver]} CLI Proxy`;
+
+/** The account email is the only identity shown; without one the provider
+ * name stands alone rather than a guess.
+ */
+export const accountName = (
+  driver: string,
+  email?: string
+): string | undefined =>
+  PROVIDER_NAMES[driver] &&
+  (email ? `${PROVIDER_NAMES[driver]} ${email}` : PROVIDER_NAMES[driver]);
+
+export type Accounts = (
+  driver: string,
+  homePath?: string
+) => Promise<string | undefined>;
+
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,255}$/;
+const email = (value: unknown): string | undefined =>
+  typeof value === 'string' && EMAIL.test(value) ? value : undefined;
+
+async function json(path: string): Promise<Record<string, unknown>> {
+  return object(await readFile(path, 'utf8'));
+}
+
+/** Reads only the signed-in address from each client's own login record; a
+ * token is never returned, logged or sent anywhere.
+ */
+export const localAccounts: Accounts = async (driver, homePath) => {
+  try {
+    if (driver === 'claudeAgent') {
+      const account = (await json(join(homePath ?? homedir(), '.claude.json')))[
+        'oauthAccount'
+      ];
+      return email((account as Record<string, unknown>)?.['emailAddress']);
+    }
+    if (driver === 'codex') {
+      const home =
+        homePath ?? process.env['CODEX_HOME'] ?? join(homedir(), '.codex');
+      const tokens = (await json(join(home, 'auth.json')))['tokens'];
+      const claims = String(
+        (tokens as Record<string, unknown>)?.['id_token']
+      ).split('.')[1];
+      return email(
+        object(Buffer.from(claims ?? '', 'base64url').toString('utf8'))['email']
+      );
+    }
+  } catch {
+    /* Signed out or unreadable: the provider name stands alone. */
+  }
+  return undefined;
+};
+
+type Instance = Record<string, unknown>;
+const homeOf = (instance: Instance): string | undefined => {
+  const home = (instance['config'] as Record<string, unknown> | undefined)?.[
+    'homePath'
+  ];
+  return typeof home === 'string' ? home : undefined;
+};
+
+/** Every instance T3 lists gets its conventional name. Managed instances
+ * (`managed`: ID to name) are named by their definition; every other instance is renamed after its own
+ * signed-in account, and a signed-in default login T3 lists without a settings
+ * entry gains one. Only `displayName` is ever written.
+ */
+export async function conformNames(
+  current: Record<string, unknown>,
+  managed: Record<string, string>,
+  accounts: Accounts = localAccounts
+): Promise<Record<string, unknown>> {
+  const next: Record<string, unknown> = { ...current };
+  const named = new Set<string>();
+  for (const [id, value] of Object.entries(current)) {
+    // A worker's policy owns its managed instances; a copy left in its
+    // settings still shows until the policy loads, so it conforms too.
+    const renamed = Object.hasOwn(managed, id)
+      ? rename(value, () => managed[id])
+      : rename(value, accountName, await account(value, accounts));
+    if (!renamed) continue;
+    named.add(String(renamed['displayName']));
+    next[id] = renamed;
+  }
+  // T3 lists a driver's default instance (its ID is the driver) without an entry.
+  for (const driver of Object.keys(PROVIDER_NAMES)) {
+    const account = await accounts(driver);
+    const name = account && accountName(driver, account);
+    if (!name || named.has(name) || Object.hasOwn(current, driver)) continue;
+    next[driver] = { driver, displayName: name };
+  }
+  return next;
+}
+
+const account = (value: unknown, accounts: Accounts) =>
+  value && typeof value === 'object'
+    ? accounts(String((value as Instance)['driver']), homeOf(value as Instance))
+    : undefined;
+
+/** The instance under its conventional name; undefined for an unknown driver. */
+function rename(
+  value: unknown,
+  convention: (driver: string, email?: string) => string | undefined,
+  email?: string
+): Instance | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const instance = value as Instance;
+  const name = convention(String(instance['driver']), email);
+  if (!name) return undefined;
+  return instance['displayName'] === name
+    ? instance
+    : { ...instance, displayName: name };
+}
+
+/** Applies the convention to this machine's T3 settings. T3 watches the file,
+ * so names change live; nothing is restarted. Returns whether it changed.
+ */
+export async function conformT3Names(
+  settingsPath: string,
+  managed: Record<string, string>,
+  options: { apply: boolean; accounts?: Accounts }
+): Promise<{ changed: boolean }> {
+  const raw = await read(settingsPath);
+  const settings = object(raw);
+  const current = object(JSON.stringify(settings['providerInstances'] ?? {}));
+  const next = await conformNames(current, managed, options.accounts);
+  if (JSON.stringify(next) === JSON.stringify(current))
+    return { changed: false };
+  if (!options.apply) return { changed: true };
+  // T3 also writes this file: never overwrite a change made since the read.
+  if ((await read(settingsPath)) !== raw) throw new Error('T3_SETTINGS_BUSY');
+  await write(
+    settingsPath,
+    JSON.stringify({ ...settings, providerInstances: next }, null, 2) + '\n'
+  );
+  return { changed: true };
+}

package/src/t3/plan.ts

@@ -0,0 +1,82 @@
+import { FleetUsageError } from '../errors';
+import { canonical, hash, object, read } from './files';
+
+export type Change = {
+  id: string;
+  action: 'create' | 'update' | 'delete' | 'unchanged' | 'conflict';
+};
+export type T3Paths = { settings: string; state: string };
+
+export async function planT3(paths: T3Paths, desired: Record<string, unknown>) {
+  const raw = await read(paths.settings);
+  const stateRaw = await read(paths.state);
+  const settings = object(raw);
+  const current = object(JSON.stringify(settings['providerInstances'] ?? {}));
+  const owned = readOwnership(stateRaw, paths.settings);
+  const next = { ...current };
+  const changes: Change[] = [];
+  for (const [id, instance] of Object.entries(desired)) {
+    const exists = Object.hasOwn(current, id);
+    const action = actionFor(exists, owned.includes(id), current[id], instance);
+    changes.push({ id, action });
+    if (action !== 'conflict') next[id] = instance;
+  }
+  for (const id of owned.filter((id) => !Object.hasOwn(desired, id))) {
+    changes.push({
+      id,
+      action: Object.hasOwn(current, id) ? 'delete' : 'unchanged',
+    });
+    delete next[id];
+  }
+  const settingsChanged = canonical(next) !== canonical(current);
+  const state = ownership(paths.settings, Object.keys(desired));
+  return {
+    raw,
+    stateRaw,
+    settings: settingsChanged
+      ? { ...settings, providerInstances: next }
+      : settings,
+    state,
+    settingsChanged,
+    stateChanged: canonical(object(stateRaw)) !== canonical(state),
+    changes,
+    planHash: hash(
+      canonical({ target: paths.settings, raw, stateRaw, desired })
+    ),
+  };
+}
+
+export function ownership(target: string, ids: string[]) {
+  return { version: 1, target, instances: [...ids].sort() };
+}
+
+export function readOwnership(raw: string | null, target: string): string[] {
+  if (raw === null) return [];
+  const state = object(raw);
+  const ids = state['instances'];
+  if (
+    state['version'] !== 1 ||
+    state['target'] !== target ||
+    !Array.isArray(ids) ||
+    ids.some(
+      (id) =>
+        typeof id !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(id)
+    ) ||
+    new Set(ids).size !== ids.length
+  )
+    throw new FleetUsageError(
+      'Invalid T3 ownership state; restore its backup before reconciliation.'
+    );
+  return ids as string[];
+}
+
+function actionFor(
+  exists: boolean,
+  owned: boolean,
+  current: unknown,
+  desired: unknown
+): Change['action'] {
+  if (exists && !owned) return 'conflict';
+  if (!exists) return 'create';
+  return canonical(current) === canonical(desired) ? 'unchanged' : 'update';
+}

package/src/t3/providers.ts

@@ -0,0 +1,74 @@
+import type { Check } from '../types';
+import { desired, nodeId, paths } from './desired';
+import type { Roster } from './accounts';
+import { reconcileT3 } from './reconcile';
+import { stablePath, stableWorkspace } from '../platform/t3-policy';
+
+/** Every machine's T3 settings hold exactly the managed provider instances:
+ * the fixed ones plus one per account signed in on the CLI proxy. T3 watches
+ * its settings, so providers appear (and retired ones disappear) at once,
+ * without a restart. Workers additionally lock the same instances through T3
+ * administrator policy. The ownership-safe t3-apply engine preserves unrelated
+ * settings and unmanaged instances; an existing unowned instance of the same
+ * ID is reported, never overwritten.
+ */
+export async function machineProviders(
+  id: string,
+  workspace: string,
+  apply: boolean,
+  options: { t3Home?: string; roster?: Roster } = {}
+): Promise<Check> {
+  const remedy = {
+    action:
+      'Run devfleet t3-apply --dry-run on this machine and review any conflicting instance; adopt it with t3-apply --import ID only if it should be managed.',
+  };
+  try {
+    const target = paths(options, workspace);
+    // Providers launch from the stable path of the applied run checkout, not
+    // from this revision's own directory, which a later sync prunes.
+    const home = apply
+      ? await stableWorkspace(workspace)
+      : stablePath(workspace);
+    const instances = await desired(
+      target.definition,
+      home,
+      nodeId(id),
+      options.roster
+    );
+    const plan = await reconcileT3(target, instances, { apply: false });
+    const result =
+      apply && plan.ok && plan.changed
+        ? await reconcileT3(target, instances, {
+            apply: true,
+            planHash: plan.planHash,
+          })
+        : plan;
+    if (!result.ok)
+      return {
+        id: 't3:providers',
+        status: 'fail',
+        summary: 'T3_PROVIDER_CONFLICT',
+        remedy,
+      };
+    return result.changed && !apply
+      ? {
+          id: 't3:providers',
+          status: 'warn',
+          summary: 'T3_PROVIDERS_PENDING',
+          remedy,
+        }
+      : {
+          id: 't3:providers',
+          status: 'pass',
+          summary:
+            'T3 on this machine offers exactly the managed provider instances every machine gets.',
+        };
+  } catch {
+    return {
+      id: 't3:providers',
+      status: 'fail',
+      summary: 'T3_PROVIDERS_UNVERIFIED',
+      remedy,
+    };
+  }
+}