Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.9 KB
Raw Blame
/**
 * Handing this server's Projects, and their Model config, to a machine they were given to.
 *
 * An Agent running over there calls the model endpoint from over there, so that machine
 * needs the credential. Without this, picking a model here and starting the Session there
 * fails with "Model is not in the Project config".
 *
 * The key travels inside the tunnel to the machine's own `PUT /models`, which writes it to
 * `.project_config.toml` at mode 0600 — whoever can run this already has ssh to that machine
 * and can read that file. An ordinary authenticated call rather than a far-side script: the
 * endpoint validates, invalidates cached runtimes and tells open tabs.
 *
 * MERGED, NOT REPLACED. `PUT /models` is a whole-table replace, so every remote-only entry is
 * re-sent — WITHOUT `apiKey`, since omitting it keeps the stored value and a GET reports keys
 * masked. Ours win on a collision.
 */
import type { MachineApi } from "./machine-api.js";
import type { ModelEntry, ModelRef } from "@adelie/core";
import type {
  ModelInfo,
  ModelRefDto,
  ModelUpdateEntry,
  ModelsResponse,
  ModelsUpdateRequest,
} from "../api/types.js";

/** This side's half of the merge: a Project's configured models, keys in plaintext. */
export interface LocalModels {
  models: ModelEntry[];
  defaultModel?: ModelRef;
  visionModel?: ModelRef;
  /** Display name, so a Project created on the machine reads as the same Project it is. */
  name?: string;
}

/** What a sync did, in the words the connect log shows. */
export type ModelSyncOutcome =
  | {
      kind: "synced";
      /** Projects whose model table was written on that machine (empty = nothing needed it). */
      projects: string[];
      /** Of those, the ones this sync had to create over there first. */
      created: string[];
      /**
       * Projects the machine would not take, each with its own reason — a refusal is an
       * answer about ONE Project's boundary, and the Projects after it still get theirs.
       */
      refused: { projectId: string; detail: string }[];
    }
  | { kind: "failed"; detail: string };

/** Entry key: the `(provider, model_id)` pair, joined by a byte neither half can contain. */
const refKey = (provider: string, modelId: string): string => `${provider}\u0000${modelId}`;

/** One of ours, with its credential — the whole point of the exercise. */
function fromLocal(entry: ModelEntry): ModelUpdateEntry {
  return {
    provider: entry.provider,
    modelId: entry.model_id,
    ...(entry.display_name !== undefined ? { displayName: entry.display_name } : {}),
    ...(entry.context_window !== undefined ? { contextWindow: entry.context_window } : {}),
    ...(entry.client_type !== undefined ? { clientType: entry.client_type } : {}),
    ...(entry.vision !== undefined ? { vision: entry.vision } : {}),
    ...(entry.max_tokens !== undefined ? { maxTokens: entry.max_tokens } : {}),
    ...(entry.fast_mode === true ? { fastMode: true } : {}),
    ...(entry.pricing !== undefined
      ? {
          pricing: {
            cacheRead: entry.pricing.cache_read,
            cacheWrite: entry.pricing.cache_write,
            output: entry.pricing.output,
          },
        }
      : {}),
    // An entry with no inline key authenticates from THIS machine's environment
    // (ANTHROPIC_API_KEY and friends), and an environment variable is not ours to carry
    // anywhere. Omitted rather than cleared: the machine may have its own value for the same
    // pair, and destroying it would be worse than leaving it.
    ...(entry.api_key !== undefined && entry.api_key !== "" ? { apiKey: entry.api_key } : {}),
    ...(entry.base_url !== undefined ? { baseUrl: entry.base_url } : {}),
  };
}

/**
 * One of theirs, carried across the whole-table replace untouched.
 *
 * No `apiKey` — see the header: omitting it is what preserves the key already on that
 * machine. The one field that does not round-trip exactly is `vision`, which a GET reports
 * from the built-in catalog when the entry carries no annotation; re-sending it writes that
 * catalog value down explicitly. Same effective value, one more line in their TOML.
 */
function fromRemote(info: ModelInfo): ModelUpdateEntry {
  return {
    provider: info.provider,
    modelId: info.modelId,
    ...(info.displayName !== undefined ? { displayName: info.displayName } : {}),
    ...(info.contextWindow !== undefined ? { contextWindow: info.contextWindow } : {}),
    ...(info.clientType !== undefined ? { clientType: info.clientType } : {}),
    ...(info.vision !== undefined ? { vision: info.vision } : {}),
    ...(info.maxTokens !== undefined ? { maxTokens: info.maxTokens } : {}),
    ...(info.fastMode === true ? { fastMode: true } : {}),
    ...(info.pricing !== undefined ? { pricing: info.pricing } : {}),
    ...(info.credential?.baseUrl !== undefined ? { baseUrl: info.credential.baseUrl } : {}),
  };
}

/**
 * The table to PUT on a machine: ours, plus everything of theirs we are not replacing.
 *
 * Callers must not reach here with an empty local table — a whole-table replace built from
 * one would delete every model that machine has (syncModelsToMachine is what guards it).
 */
export function planModelSync(local: LocalModels, remote: ModelsResponse): ModelsUpdateRequest {
  const ours = new Set(local.models.map((entry) => refKey(entry.provider, entry.model_id)));
  const models: ModelUpdateEntry[] = [
    ...local.models.map(fromLocal),
    ...remote.models
      .filter((info) => !ours.has(refKey(info.provider, info.modelId)))
      .map(fromRemote),
  ];
  // The pointers follow ours. A Project with this id on that machine IS this Project — that
  // is what giving the machine to it meant — and a default pointing somewhere else is how a
  // Session started without an explicit model quietly runs on the wrong one. Only ever set to
  // a pair in the table being sent; one we cannot satisfy is left as theirs, since omitting
  // the field is what keeps it.
  const follow = (ref: ModelRef | undefined): ModelRefDto | undefined =>
    ref !== undefined && ours.has(refKey(ref.provider, ref.model_id))
      ? { provider: ref.provider, modelId: ref.model_id }
      : undefined;
  const defaultModel = follow(local.defaultModel);
  const visionModel = follow(local.visionModel);
  return {
    models,
    ...(defaultModel !== undefined ? { defaultModel } : {}),
    ...(visionModel !== undefined ? { visionModel } : {}),
  };
}

/** Project ids that machine has, narrowed from its own answer (it may be an older build). */
function projectIdsIn(text: string): string[] {
  const body: unknown = JSON.parse(text);
  if (body === null || typeof body !== "object") return [];
  const list = (body as { projects?: unknown }).projects;
  if (!Array.isArray(list)) return [];
  return list
    .map((entry) =>
      entry !== null && typeof entry === "object"
        ? (entry as { projectId?: unknown }).projectId
        : undefined,
    )
    .filter((id): id is string => typeof id === "string");
}

/**
 * Gives a machine the Projects it was given to, and the models they need.
 *
 * `projects` is the entitlement, and it is the ONLY input that decides what is written: a
 * machine belongs to the Projects that adopted it, and a Project that does not use it has no
 * business putting its keys on it.
 *
 * A Project missing over there is CREATED, with the same id. That is the point of an id being
 * stable: the Project on that machine is not a lookalike, it is this Project, and a Session
 * started on that machine sends this id for it to resolve. Creating it is not this server
 * inventing workspaces on a stranger's host — the host was handed to this Project, and a
 * machine that cannot answer for the Project that owns it is a machine that cannot run
 * anything for it.
 *
 * A creation that is REFUSED is reported and that Project is skipped: the machine saying no
 * (an id already taken by someone else's Project, a shape it will not accept) is an answer
 * about a boundary, and writing models around it is not this function's call to make. Skipped
 * means exactly that — the Projects after it are still written. Only the machine being
 * unreachable, or refusing to say what Projects it has, fails the sync as a whole.
 */
export async function syncModelsToMachine(opts: {
  api: MachineApi;
  /** This side's table for a Project, or null when it has no config for it. */
  loadLocal: (projectId: string) => Promise<LocalModels | null>;
  /** The Projects entitled to this machine — nothing outside this list is touched. */
  projects: string[];
}): Promise<ModelSyncOutcome> {
  let theirs: string[];
  try {
    const listed = await opts.api.request("GET", "/api/projects");
    if (listed.status !== 200) {
      return { kind: "failed", detail: `it answered ${listed.status} when asked its projects` };
    }
    theirs = projectIdsIn(listed.text);
  } catch (err) {
    return { kind: "failed", detail: err instanceof Error ? err.message : String(err) };
  }

  const synced: string[] = [];
  const created: string[] = [];
  const refused: { projectId: string; detail: string }[] = [];
  for (const projectId of opts.projects) {
    const local = await opts.loadLocal(projectId);
    // Nothing configured here is not a reason to touch their table: a replace built from an
    // empty local list would delete every model they have. It is also not a reason to create
    // the Project — an empty shell is not worth a directory on someone's machine.
    if (local === null || local.models.length === 0) continue;
    const path = `/api/projects/${encodeURIComponent(projectId)}/models`;
    try {
      if (!theirs.includes(projectId)) {
        const made = await opts.api.request("POST", "/api/projects", {
          projectId,
          ...(local.name !== undefined && local.name !== "" ? { name: local.name } : {}),
        });
        if (made.status < 200 || made.status >= 300) {
          refused.push({
            projectId,
            detail: `it refused to create ${projectId}: ${made.status} ${made.text.slice(0, 200)}`,
          });
          continue;
        }
        created.push(projectId);
      }
      const current = await opts.api.request("GET", path);
      if (current.status !== 200) {
        refused.push({
          projectId,
          detail: `it answered ${current.status} when asked the models of ${projectId}`,
        });
        continue;
      }
      const plan = planModelSync(local, JSON.parse(current.text) as ModelsResponse);
      const wrote = await opts.api.request("PUT", path, plan);
      if (wrote.status < 200 || wrote.status >= 300) {
        refused.push({
          projectId,
          detail: `it refused the models of ${projectId}: ${wrote.status} ${wrote.text.slice(0, 200)}`,
        });
        continue;
      }
      synced.push(projectId);
    } catch (err) {
      // Not a refusal: the channel itself gave out. Nothing after it would fare better.
      return { kind: "failed", detail: err instanceof Error ? err.message : String(err) };
    }
  }
  return { kind: "synced", projects: synced, created, refused };
}