Skip to content

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

21.0 KB
Raw Blame
/**
 * Model & credential config routes:
 * GET|PUT /api/projects/:p/models, PUT /api/projects/:p/models/default,
 * POST /api/projects/:p/models/test, POST /api/projects/:p/models/detect,
 * POST /api/projects/:p/models/list, POST /api/projects/:p/models/detect-vision (the model
 * reference `(provider, modelId)` is sent as a pair in the request body, avoiding
 * URL-encoding issues), POST /api/projects/:p/models/assign-user-key, GET
 * /api/projects/:p/models/balance. Any member can read (api_key is masked) and read a group's
 * balance; only the owner can modify, test, or detect.
 */
import { Hono } from "hono";
import type {
  DefaultModelResponse,
  EndpointModelListRequest,
  ModelBalanceResponse,
  ModelProtocolDetectRequest,
  ModelRefDto,
  ModelsUpdateRequest,
  ModelTestRequest,
  ModelUpdateEntry,
  ModelUserKeyAssignResponse,
  ModelVisionDetectRequest,
  ServerEvent,
} from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import { badRequest, readJson, requireString, requireValidId } from "../validate.js";
import { isHttpUrl } from "../../services/protocol-detect.js";
import type { ChannelHub } from "../../runtime/channel.js";
import type { SessionManager } from "../../runtime/session-manager.js";
import type { SessionIndex } from "../../mechanisms/sessions.js";
import type { Access, ProjectConfigStore } from "../../mechanisms/projects.js";
import type { Machines } from "../../machines/service.js";
import type { UserVault } from "../../mechanisms/vault.js";
import { ModelBalances } from "../../services/model-balance.js";

/** What this route group reaches — bound by its module (src/modules). */
export interface ModelsRouteDeps {
  /** The machines this Project uses receive a credential change too (machines/service.ts). */
  machines: Machines;
  channels: ChannelHub;
  manager: SessionManager;
  projectConfigService: ProjectConfigStore;
  access: Access;
  sessionsRepo: SessionIndex;
  /** The caller's own user-level vault: the source of an assigned key (assign-user-key). */
  userVault: UserVault;
}

/**
 * Live unlock for auth-dead composers: after a models/credential update, publish
 * `credentials_updated` to every EXISTING channel of this Project's Sessions (`peek` —
 * never creates channels: a tab that isn't subscribed learns the same fact from the models
 * response's `updatedAt` when it next loads). Shared with the key-minting routes, which
 * change the same credentials by a different path.
 */
export function publishCredentialsUpdated(deps: ModelsRouteDeps, projectId: string): void {
  const event: ServerEvent = { type: "credentials_updated" };
  for (const row of deps.sessionsRepo.listByProject(projectId)) {
    deps.channels.peek(row.sessionId)?.publish(event, "server_event");
  }
}

/**
 * EVERYTHING that follows a change to a Project's model config, in one place, so that no
 * path that writes it can forget one of the three: the whole-table PUT, the default switch,
 * and the key-minting flows all end here.
 *
 * - Effective-value semantics (mirrors the vault route): no hot swap into a Task already in
 *   flight, but every cached runtime in this Project is invalidated — the next Task on any
 *   of its Sessions re-resumes and reads the new api_key / base_url. Without this, a key
 *   edit would not reach a loaded Session until the 30-minute idle sweep or a restart.
 * - Live unlock: open tabs clear their auth-dead composer immediately (no reload needed).
 * - The machines run their own Agents against their own config, so a change here has to
 *   reach them or their Sessions keep failing on the old one — or start on the wrong default.
 *   Not awaited: the person editing is not the one who should wait for a set of ssh tunnels.
 */
export function modelConfigChanged(deps: ModelsRouteDeps, projectId: string): void {
  deps.manager.invalidateProjectRuntimes(projectId);
  publishCredentialsUpdated(deps, projectId);
  void deps.machines.syncModelsEverywhere(projectId);
}

/** Validate a paired reference object ({ provider, modelId }); shape mismatch throws 400. */
function parseRef(value: unknown, label: string): ModelRefDto {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    throw badRequest(`${label} must be a { provider, modelId } object.`);
  }
  const r = value as Record<string, unknown>;
  return {
    provider: requireString(r, "provider", { minLen: 1, maxLen: 64, label: `${label}.provider` }),
    modelId: requireString(r, "modelId", { minLen: 1, maxLen: 200, label: `${label}.modelId` }),
  };
}

/** Validate the PUT request body and shape it into a ModelsUpdateRequest (rejects any shape errors). */
function parseModelsUpdate(body: Record<string, unknown>): ModelsUpdateRequest {
  if (!Array.isArray(body.models)) throw badRequest("models must be an array.");
  const models: ModelUpdateEntry[] = body.models.map((item, i) => {
    if (item === null || typeof item !== "object" || Array.isArray(item)) {
      throw badRequest(`models[${i}] must be an object.`);
    }
    const m = item as Record<string, unknown>;
    const entry: ModelUpdateEntry = {
      provider: requireString(m, "provider", {
        minLen: 1,
        maxLen: 64,
        label: `models[${i}].provider`,
      }),
      modelId: requireString(m, "modelId", {
        minLen: 1,
        maxLen: 200,
        label: `models[${i}].modelId`,
      }),
    };
    if (m.displayName !== undefined) {
      if (typeof m.displayName !== "string" || m.displayName.length > 100) {
        throw badRequest(`models[${i}].displayName must be a string of at most 100 characters.`);
      }
      // The empty string is carried through rather than dropped: an absent field means
      // "inherit the built-in catalog's name" and an empty one means "the user cleared it",
      // and the service cannot tell those apart if the validator collapses them here.
      entry.displayName = m.displayName;
    }
    // A key change (either the provider group or the upstream id) goes through renamedFrom's paired old reference; unknown fields are ignored.
    if (m.renamedFrom !== undefined) {
      entry.renamedFrom = parseRef(m.renamedFrom, `models[${i}].renamedFrom`);
    }
    if (m.contextWindow !== undefined) {
      if (typeof m.contextWindow !== "number" || !(m.contextWindow > 0)) {
        throw badRequest(`models[${i}].contextWindow must be a positive number.`);
      }
      entry.contextWindow = m.contextWindow;
    }
    if (m.clientType !== undefined) {
      if (typeof m.clientType !== "string" || m.clientType.length > 64) {
        throw badRequest(`models[${i}].clientType must be a string of at most 64 characters.`);
      }
      // An empty string is treated as "unspecified", leaving AgentHub to infer it from modelId.
      if (m.clientType) entry.clientType = m.clientType;
    }
    if (m.vision !== undefined) {
      if (typeof m.vision !== "boolean") {
        throw badRequest(`models[${i}].vision must be a boolean.`);
      }
      entry.vision = m.vision;
    }
    if (m.maxTokens !== undefined) {
      if (typeof m.maxTokens !== "number" || !Number.isInteger(m.maxTokens) || m.maxTokens <= 0) {
        throw badRequest(`models[${i}].maxTokens must be a positive integer.`);
      }
      entry.maxTokens = m.maxTokens;
    }
    if (m.fastMode !== undefined) {
      if (typeof m.fastMode !== "boolean") {
        throw badRequest(`models[${i}].fastMode must be a boolean.`);
      }
      entry.fastMode = m.fastMode;
    }
    if (m.pricing !== undefined) {
      const p = m.pricing as Record<string, unknown>;
      if (p === null || typeof p !== "object" || Array.isArray(p)) {
        throw badRequest(`models[${i}].pricing must be an object.`);
      }
      for (const key of ["cacheRead", "cacheWrite", "output"] as const) {
        const v = p[key];
        if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
          throw badRequest(`models[${i}].pricing.${key} must be a non-negative number.`);
        }
      }
      entry.pricing = {
        cacheRead: p.cacheRead as number,
        cacheWrite: p.cacheWrite as number,
        output: p.output as number,
      };
    }
    // The promotion stored for this row (null clears it); the service checks the range.
    if (m.discount !== undefined) {
      if (m.discount !== null && typeof m.discount !== "number") {
        throw badRequest(`models[${i}].discount must be null or a number above 0 and below 1.`);
      }
      entry.discount = m.discount;
    }
    if (m.apiKey !== undefined) {
      if (typeof m.apiKey !== "string" || m.apiKey.length === 0) {
        throw badRequest(`models[${i}].apiKey must be a non-empty string.`);
      }
      entry.apiKey = m.apiKey;
    }
    if (m.clearApiKey !== undefined) {
      if (typeof m.clearApiKey !== "boolean") {
        throw badRequest(`models[${i}].clearApiKey must be a boolean.`);
      }
      entry.clearApiKey = m.clearApiKey;
    }
    if (m.baseUrl !== undefined) {
      if (m.baseUrl !== null && typeof m.baseUrl !== "string") {
        throw badRequest(`models[${i}].baseUrl must be a string or null.`);
      }
      entry.baseUrl = m.baseUrl as string | null;
    }
    return entry;
  });
  const req: ModelsUpdateRequest = { models };
  if (body.defaultModel !== undefined) {
    req.defaultModel = parseRef(body.defaultModel, "defaultModel");
  }
  if (body.visionModel !== undefined) {
    req.visionModel = parseRef(body.visionModel, "visionModel");
  }
  return req;
}

export function modelsRoutes(deps: ModelsRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();
  /** The balance reader and its 60 s cache, one per route group. */
  const balances = new ModelBalances({
    groupKey: (projectId, provider) =>
      deps.projectConfigService.getGroupBalanceKey(projectId, provider),
  });

  app.get("/", async (c) => {
    // Defensive id validation.
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    return c.json(await deps.projectConfigService.getModels(projectId));
  });

  app.put("/", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const req = parseModelsUpdate(await readJson(c));
    const res = await deps.projectConfigService.updateModels(projectId, req);
    modelConfigChanged(deps, projectId);
    return c.json(res);
  });

  // One entry of the caller's own user-level vault, written as this group's api_key. It exists
  // because the browser cannot do it: every user-vault response is masked, so the value is only
  // ever read here, server-side, and written straight into the Project's model config — which is
  // why the request names a key and not a value. Like the Agent-side assign, it is a COPY: the
  // group keeps what it was given, and a later edit of the global entry has to be assigned again.
  // Owner-only, like every other write to the model config; the page offers the action only for
  // groups whose rows share one endpoint (custom's, each reaching its own, is left out).
  app.post("/assign-user-key", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const provider = requireString(body, "provider", {
      minLen: 1,
      maxLen: 64,
      label: "provider",
    });
    const key = requireString(body, "key", { minLen: 1, maxLen: 128, label: "key" });
    const value = await deps.userVault.readEntry(c.var.user.userId, key);
    if (value === undefined) {
      throw badRequest(`Not in your user vault: ${key}.`);
    }
    const applied = await deps.projectConfigService.setGroupApiKey(projectId, provider, value);
    if (applied > 0) modelConfigChanged(deps, projectId);
    const res: ModelUserKeyAssignResponse = { applied };
    return c.json(res);
  });

  // A group's account balance (any member, like the table itself): the server asks the
  // vendor with the group's stored key, so the key never reaches the browser. A balance that
  // cannot be read is an answer (`ok: false` with a code), as a failed connectivity test is.
  // `force=1` is the page's refresh click and skips the 60 s cache.
  app.get("/balance", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const provider = c.req.query("provider") ?? "";
    if (provider === "" || provider.length > 64) {
      throw badRequest("provider must name a model group.");
    }
    const answer: ModelBalanceResponse = await balances.read(
      projectId,
      provider,
      c.req.query("force") === "1",
    );
    return c.json(answer);
  });

  // Narrow default-model switch (owner): flips the same top-level `default_model` the
  // whole-table PUT above maintains, without resending the table — project settings can
  // change the default without carrying credentials. The pair must name a configured
  // entry (400 otherwise, same rule as the whole-table route's defaultModel). No runtime
  // invalidation and no credentials_updated here: existing Sessions pin their model at
  // creation, and no credential changes. The machines DO hear of it — a Session started
  // over there without an explicit model runs on that machine's default, and the default
  // is part of what the sync carries.
  app.put("/default", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const ref: ModelRefDto = {
      provider: requireString(body, "provider", { minLen: 1, maxLen: 64 }),
      modelId: requireString(body, "modelId", { minLen: 1, maxLen: 200 }),
    };
    const defaultModel = await deps.projectConfigService.setDefaultModelRef(projectId, ref);
    void deps.machines.syncModelsEverywhere(projectId);
    return c.json({ defaultModel } satisfies DefaultModelResponse);
  });

  // Connectivity test (owner): the model reference `(provider, modelId)` is sent as a pair
  // in the request body; sends one minimal request using that model's config. May include
  // not-yet-saved apiKey / baseUrl / clientType — when the model isn't in the config yet
  // (adding a custom model), everything is taken from the request body.
  app.post("/test", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const req: ModelTestRequest = {
      provider: requireString(body, "provider", { minLen: 1, maxLen: 64 }),
      modelId: requireString(body, "modelId", { minLen: 1, maxLen: 200 }),
    };
    if (body.apiKey !== undefined) {
      if (typeof body.apiKey !== "string") throw badRequest("apiKey must be a string.");
      if (body.apiKey) req.apiKey = body.apiKey;
    }
    if (body.clearApiKey !== undefined) {
      if (typeof body.clearApiKey !== "boolean") throw badRequest("clearApiKey must be a boolean.");
      req.clearApiKey = body.clearApiKey;
    }
    if (body.speed !== undefined) {
      if (typeof body.speed !== "boolean") throw badRequest("speed must be a boolean.");
      req.speed = body.speed;
    }
    // null = explicit clear (test against the draft, don't fall back to the stored value); empty string is treated as null.
    if (body.baseUrl !== undefined) {
      if (body.baseUrl !== null && typeof body.baseUrl !== "string") {
        throw badRequest("baseUrl must be a string or null.");
      }
      req.baseUrl = body.baseUrl ? body.baseUrl : null;
    }
    if (body.clientType !== undefined) {
      if (typeof body.clientType !== "string") throw badRequest("clientType must be a string.");
      if (body.clientType) req.clientType = body.clientType;
    }
    if (body.fastMode !== undefined) {
      if (typeof body.fastMode !== "boolean") throw badRequest("fastMode must be a boolean.");
      req.fastMode = body.fastMode;
    }
    return c.json(await deps.projectConfigService.testModel(projectId, req));
  });

  // Protocol auto-detection (owner): probes which generic protocol client the base URL
  // serves — openai-responses, then ant-messages, then openai-chat — and returns the
  // first hit plus per-probe outcomes (see services/protocol-detect.ts). Cheap: each
  // probe is a minimal invalid request (no tokens billed). Like the connectivity test,
  // an optional paired reference lets a stored key back the probes without the frontend
  // ever seeing the plaintext.
  //
  // On the server fetching a caller-supplied URL: deliberate, and not a new capability.
  // /test already hands an arbitrary baseUrl to the provider SDK behind the same
  // owner-only guard, and in a self-hosted product pointing the server at an internal or
  // loopback inference endpoint is the feature (vLLM / Ollama / a LAN gateway), not the
  // attack — so no host allowlist. This route is the tighter of the two: it rejects
  // anything that is not an absolute http(s) URL, and reduces every answer to an outcome
  // enum plus an HTTP status, where /test surfaces the upstream message verbatim.
  app.post("/detect", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const req: ModelProtocolDetectRequest = {
      baseUrl: requireString(body, "baseUrl", { minLen: 1, maxLen: 2000 }),
    };
    if (!isHttpUrl(req.baseUrl)) throw badRequest("baseUrl must be an absolute http(s) URL.");
    if (body.apiKey !== undefined) {
      if (typeof body.apiKey !== "string") throw badRequest("apiKey must be a string.");
      if (body.apiKey) req.apiKey = body.apiKey;
    }
    if (body.clearApiKey !== undefined) {
      if (typeof body.clearApiKey !== "boolean") throw badRequest("clearApiKey must be a boolean.");
      req.clearApiKey = body.clearApiKey;
    }
    // The paired reference is optional (adding a not-yet-saved model has none); when
    // present, both fields are required so the stored-key lookup is unambiguous.
    if (body.provider !== undefined || body.modelId !== undefined) {
      req.provider = requireString(body, "provider", { minLen: 1, maxLen: 64 });
      req.modelId = requireString(body, "modelId", { minLen: 1, maxLen: 200 });
    }
    return c.json(await deps.projectConfigService.detectProtocol(projectId, req));
  });

  // Endpoint model listing (owner): given a base URL plus the protocol /detect reported,
  // returns every model id the endpoint serves (AgentHub's listModels() on the routed
  // client) so the add-group dialog can import a provider's whole listing in one go.
  // Owner-only and server-fetches-a-caller-URL for exactly the reasons /detect documents
  // above; like /detect, the reply is reduced to a DTO (ids / outcome flags / truncated
  // reason) and the key travels only in request headers upstream.
  app.post("/list", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const req: EndpointModelListRequest = {
      baseUrl: requireString(body, "baseUrl", { minLen: 1, maxLen: 2000 }),
      clientType: requireString(body, "clientType", { minLen: 1, maxLen: 64 }),
    };
    if (!isHttpUrl(req.baseUrl)) throw badRequest("baseUrl must be an absolute http(s) URL.");
    if (body.apiKey !== undefined) {
      if (typeof body.apiKey !== "string") throw badRequest("apiKey must be a string.");
      if (body.apiKey) req.apiKey = body.apiKey;
    }
    return c.json(await deps.projectConfigService.listEndpointModels(req));
  });

  /**
   * Vision capability probe (owner only). Body mirrors the connectivity test's, since the
   * probe is one real completion on the same credential — see detectVision. Owner-only for
   * the same reason as /test and /detect: it spends the Project's key.
   */
  app.post("/detect-vision", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = await readJson(c);
    const req: ModelVisionDetectRequest = {
      provider: requireString(body, "provider", { minLen: 1, maxLen: 64 }),
      modelId: requireString(body, "modelId", { minLen: 1, maxLen: 200 }),
    };
    if (body.apiKey !== undefined) {
      if (typeof body.apiKey !== "string") throw badRequest("apiKey must be a string.");
      if (body.apiKey) req.apiKey = body.apiKey;
    }
    if (body.clearApiKey !== undefined) {
      if (typeof body.clearApiKey !== "boolean") throw badRequest("clearApiKey must be a boolean.");
      req.clearApiKey = body.clearApiKey;
    }
    // null is meaningful (explicitly no base URL), so it is kept distinct from absent.
    if (body.baseUrl !== undefined) {
      if (body.baseUrl !== null && typeof body.baseUrl !== "string") {
        throw badRequest("baseUrl must be a string or null.");
      }
      req.baseUrl = body.baseUrl as string | null;
    }
    if (body.clientType !== undefined) {
      if (typeof body.clientType !== "string") throw badRequest("clientType must be a string.");
      if (body.clientType) req.clientType = body.clientType;
    }
    return c.json(await deps.projectConfigService.detectVision(projectId, req));
  });

  return app;
}