Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

14.2 KB
Raw Blame
// Keep execution IDs stable: saved tasks and older peers still select a mode.
// Pair only conventional sibling IDs with the same harness and connection.
import { isDeepStrictEqual } from 'node:util';
import { hasCredentialBootstrap } from './credentialBootstrap.js';

const MODE_KEY_DEFAULTS = { endpoint: '', apiKey: '', envVars: {}, credentialBootstrap: null };

/**
 * The fields two records must AGREE on to be one harness in two modes.
 *
 * Exported because it is a constraint on writers, not just a detail of the
 * reader below: anything a pair minter varies per mode has to stay clear of
 * this list, or it mints a pair this function then refuses to group — the exact
 * failure a dual-mode create exists to prevent. `command` is checked separately
 * (it has no empty-value default).
 *
 * DERIVED from `MODE_KEY_DEFAULTS` rather than restated, because the pairing
 * test and `sharedModeUpdates`' fan-out list are one list seen from two sides:
 * a key that says "these two describe the same connection" but is NOT fanned
 * out when it changes splits the card on the very edit that changed it, and
 * leaves the mode the editor did not open pointed at the old backend. Adding a
 * key to the defaults above therefore opts it into both.
 */
export const MODE_GROUPED_KEYS = Object.freeze(Object.keys(MODE_KEY_DEFAULTS));

/**
 * Provider settings shared by the CLI and TUI modes of a harness. The records
 * stay separate because saved selections name an execution mode, but a pair
 * must not carry conflicting model and generation policy.
 */
export const MODE_SHARED_SETTINGS_KEYS = Object.freeze([
  'modelAccess',
  'defaultModel',
  'lightModel',
  'mediumModel',
  'heavyModel',
  'ultraModel',
  'effort',
  'fallbackProvider',
  'fallbackModel',
  'catalogNarrowing',
  'hardwareRequirements',
  'modelHardwareRequirements',
  'secretEnvVars',
  'ignoreUserConfig',
  'codexAuthMode',
  'numCtx',
  'temperature',
  'topP',
  'thinking',
  'contextWindow',
  'textTransport',
]);

/** True when a record NAMES a connection-identity value rather than leaving it at the empty default. */
function namesModeValue(provider, key) {
  if (key === 'credentialBootstrap') return hasCredentialBootstrap(provider);
  const value = provider?.[key];
  if (typeof value === 'string') return value.length > 0;
  if (value && typeof value === 'object') return Object.keys(value).length > 0;
  return false;
}

/** A fanned-out value must not ALIAS one object across two stored records. */
const detachModeValue = value => (value && typeof value === 'object' ? structuredClone(value) : value);
const hasConfiguredModeValue = (value) => {
  if (value === undefined || value === null || value === '') return false;
  if (Array.isArray(value)) return value.length > 0;
  if (typeof value === 'object') return Object.keys(value).length > 0;
  return true;
};

/**
 * Fields belonging to the CLI mode ALONE, which must not ride the shared body
 * to the TUI sibling {@link expandModePair} mints beside it.
 *
 * `headlessArgs` is the non-interactive argv — a flag list handed to a program
 * being driven without a terminal, meaningless to a PTY launch, and already
 * declared mode-specific by `PROVIDER_MODE_OVERRIDE_KEYS`.
 *
 * Deliberately NOT here: `textTransport` and its consents. A record ADVERTISING
 * the Codex app-server transport is not a record permitted to use it — the two
 * explicit consents are, and they are never fanned out (see
 * `sharedModeUpdates`). The shipped Codex pair declares the transport on BOTH
 * modes, so dropping it would make a hand-minted pair differ from the seeded
 * one for the same program.
 *
 * Every key here must stay clear of {@link MODE_GROUPED_KEYS} — dropping one of
 * those would mint a pair `providerModeGroups` then refuses to group.
 */
export const CLI_ONLY_KEYS = Object.freeze(['headlessArgs']);

export function providerModeGroups(providers) {
  const byId = new Map(providers.map(provider => [provider.id, provider]));
  const paired = new Set();
  const groups = [];
  for (const tui of providers.filter(provider => provider.type === 'tui' && /-tui(?:-|$)/.test(provider.id))) {
    const stem = tui.id.replace(/-tui(?=-|$)/, '');
    const cli = [byId.get(stem), byId.get(`${stem}-cli`)].find(provider => provider?.type === 'cli');
    if (!cli || paired.has(cli.id) || !cli.command || cli.command !== tui.command) continue;
    // Backend, credential and environment: siblings naming DIFFERENT ones are
    // two connections, not one. A pair where only one names a value is the
    // asymmetry `unifyProviderModes` converges, so it does not reach here as a
    // lasting split.
    if (!MODE_GROUPED_KEYS.every(key =>
      isDeepStrictEqual(cli[key] || MODE_KEY_DEFAULTS[key], tui[key] || MODE_KEY_DEFAULTS[key]))) continue;
    groups.push([cli, tui]);
    paired.add(cli.id);
    paired.add(tui.id);
  }
  return [...groups, ...providers.filter(provider => !paired.has(provider.id)).map(provider => [provider])];
}

export function sharedModeUpdates(updates) {
  // Arguments, timeouts, routing consent and TUI timing remain mode-specific.
  //
  // Every `MODE_GROUPED_KEYS` field is shared for the reason the pairing
  // test above keys on it: endpoint, API key, env vars and bootstrap describe
  // the CONNECTION, not a mode's argv. The editor opens the group's
  // representative (the CLI mode), so any of them saved there and not fanned
  // out leaves the TUI mode — the one "Launch in Shell" resolves its command
  // line and env from — pointed at the old backend with the old credential,
  // and splits the one card in two on the next load. `unifyProviderModes`
  // converges a pair that arrived asymmetric by some other route.
  // A paired harness has one provider configuration as well as one connection.
  // Mirror shared settings from whichever mode the user edited; clone their
  // objects so legacy CLI/TUI records don't alias mutable values in memory.
  const shared = Object.fromEntries(['enabled', 'models', 'modelContextWindows', ...MODE_SHARED_SETTINGS_KEYS, ...MODE_GROUPED_KEYS]
    .filter(key => Object.hasOwn(updates, key))
    .map(key => [key, detachModeValue(updates[key])]));
  return shared;
}

/**
 * Give a mode sibling the connection-identity values its pair already carries.
 *
 * Grouped over a projection with every {@link MODE_GROUPED_KEYS} field ERASED,
 * because an asymmetric pair is invisible to the real rule — the unfanned key
 * is exactly the value it disagrees on, and an edit that changed two of them at
 * once (an endpoint AND its API key) disagrees on two. Only this fill uses the
 * loose grouping; the enablement/model convergence below keeps the strict one.
 *
 * Only a pair that is INCOMPLETE is repaired, under two conditions that
 * together mean the result is one mode's connection rather than a blend of two.
 * Either failing disqualifies the whole group, not just the offending key.
 *
 * It must not CONTRADICT — a key two modes both name with different values is a
 * deliberate configuration (two connections that happen to share a command),
 * and picking a winner between two endpoints or two credentials is nobody's
 * call to make silently.
 *
 * And every fill must come from the SAME donor mode. Two modes naming DISJOINT
 * halves of a connection contradict nowhere, so the check above waves them
 * through — yet merging them mints a hybrid neither record described: a CLI
 * mode holding only an API key beside a TUI mode holding only an endpoint would
 * hand that credential to a backend it was never entered for. With one donor,
 * every key the recipient does name already equals the donor's, so the repaired
 * pair is exactly the donor's connection — which is what "the editor wrote one
 * mode and the sibling never got it" actually looks like.
 */
function fillModeSiblingIdentity(providers) {
  const byId = new Map(providers.map(provider => [provider.id, provider]));
  const erased = Object.fromEntries(MODE_GROUPED_KEYS.map(key => [key, undefined]));
  let changed = false;
  for (const group of providerModeGroups(providers.map(provider => ({ ...provider, ...erased })))) {
    if (group.length < 2) continue;
    const modes = group.map(({ id }) => byId.get(id)).filter(Boolean);
    const namers = MODE_GROUPED_KEYS.map(key => [key, modes.filter(mode => namesModeValue(mode, key))]);
    if (namers.some(([key, named]) => named.some(mode => !isDeepStrictEqual(mode[key], named[0][key])))) continue;
    const fills = namers.filter(([, named]) => named.length === 1);
    if (new Set(fills.map(([, named]) => named[0].id)).size > 1) continue;
    for (const [key, named] of fills) {
      for (const mode of modes) {
        if (namesModeValue(mode, key)) continue;
        mode[key] = detachModeValue(named[0][key]);
        changed = true;
      }
    }
  }
  return changed;
}

export function unifyProviderModes(data) {
  const providers = Object.values(data.providers || {});
  // Identity FIRST: a pair split only by an unfanned connection field is
  // rejoined here, so the convergence below sees the one connection it is.
  let changed = fillModeSiblingIdentity(providers);
  for (const group of providerModeGroups(providers)) {
    if (group.length < 2) continue;
    // The CLI is the long-standing representative of a paired card. When an
    // older install has different shared settings on the two mode records, use
    // its values when present. If the CLI has no value, retain a configured
    // TUI value rather than clearing it during the compatibility reconcile.
    const canonical = group.find(provider => provider.type === 'cli') || group[0];
    for (const key of MODE_SHARED_SETTINGS_KEYS) {
      const source = hasConfiguredModeValue(canonical[key])
        ? canonical
        : group.find(provider => provider.id !== canonical.id && hasConfiguredModeValue(provider[key]));
      for (const provider of group) {
        const value = source?.[key];
        if (isDeepStrictEqual(provider[key], value)) continue;
        if (value === undefined) delete provider[key];
        else provider[key] = detachModeValue(value);
        changed = true;
      }
    }
    // Context-window observations are catalog metadata. Merge them so the
    // compatibility reconcile keeps facts learned from either old mode, then
    // mirror the same detached map to both records.
    const hasContextWindows = group.some(provider =>
      provider.modelContextWindows && Object.keys(provider.modelContextWindows).length > 0);
    if (hasContextWindows) {
      const modelContextWindows = Object.assign(
        {},
        ...group.filter(mode => mode.id !== canonical.id).map(mode => mode.modelContextWindows || {}),
        canonical.modelContextWindows || {},
      );
      for (const provider of group) {
        if (isDeepStrictEqual(provider.modelContextWindows, modelContextWindows)) continue;
        provider.modelContextWindows = { ...modelContextWindows };
        changed = true;
      }
    } else {
      for (const provider of group) {
        if (Object.hasOwn(provider, 'modelContextWindows')) {
          delete provider.modelContextWindows;
          changed = true;
        }
      }
    }
    const enabled = group.some(provider => provider.enabled === true);
    const models = [...new Set(group.flatMap(provider => provider.models || []))];
    for (const provider of group) {
      if (provider.enabled !== enabled || !isDeepStrictEqual(provider.models, models)) {
        Object.assign(provider, { enabled, models: [...models] });
        changed = true;
      }
    }
  }
  return changed;
}

/**
 * The id and display name a harness's TUI sibling takes.
 *
 * `providerModeGroups` above pairs `<stem>` with `<stem>-tui`, so this is the
 * WRITE side of the rule it reads: mint a sibling any other way and the two
 * records stop being one harness. Declared here, beside the reader, and used by
 * every minter — `expandModePair` below, `mintRouteIds` and `createBinding`
 * for connection-backed routes — so the convention has one spelling.
 *
 * A distinct name matters as much as a distinct id: two identically-named rows
 * in the provider list are indistinguishable.
 */
export const modeSiblingId = (stem, mode) => (mode === 'tui' ? `${stem}-tui` : stem);
export const modeSiblingName = (name, mode) => (mode === 'tui' ? `${name} TUI` : name);

/**
 * ONE mode's create payload, derived from the body both modes share.
 *
 * The single writer of the pair convention: every {@link MODE_GROUPED_KEYS}
 * field (and `command`) comes from the shared body, and only `id`, `name`,
 * `type`, the {@link CLI_ONLY_KEYS} the TUI half must not inherit, and this
 * mode's own declared overrides differ. Mint a sibling any other way and
 * `providerModeGroups` stops seeing one harness.
 *
 * The shared body is the CLI mode's, so the drop is one-sided — and a value
 * declared explicitly in `overrides` still wins, because it lands after.
 *
 * @param {{id?:string, name:string}} shared - the body both modes are built from
 * @param {'cli'|'tui'} mode
 * @param {object} [overrides] - this mode's own fields (argv, prompt delay)
 */
export function modeSiblingPayload(shared, mode, overrides = {}) {
  const stem = shared.id || String(shared.name).toLowerCase().replace(/[^a-z0-9]/g, '-');
  const inherited = mode === 'tui'
    ? Object.fromEntries(Object.entries(shared).filter(([key]) => !CLI_ONLY_KEYS.includes(key)))
    : shared;

  return {
    ...inherited,
    ...overrides,
    id: modeSiblingId(stem, mode),
    name: modeSiblingName(shared.name, mode),
    type: mode,
  };
}

/**
 * Split one dual-mode create body into its per-mode create payloads, or `null`
 * when the body declares no `modes`.
 *
 * A program that runs both headlessly and interactively is one program on one
 * backend, but a record stores exactly one `type` — so configuring both used to
 * mean adding the same command twice and hoping the two records happened to
 * satisfy the pairing rule above. This mints them in that shape by
 * construction, through {@link modeSiblingPayload}.
 *
 * @param {{modes?:Record<string,object>, id?:string, name:string}} providerData
 * @returns {object[]|null} one create payload per mode, CLI first
 */
export function expandModePair(providerData) {
  const modes = providerData?.modes;
  if (!modes || typeof modes !== 'object') return null;

  const { modes: _modes, ...shared } = providerData;
  return ['cli', 'tui'].map((mode) => modeSiblingPayload(shared, mode, modes[mode]));
}