2026-11-06 14:56:13 +01:00
|
|
|
/**
|
|
|
|
|
* @fileoverview What the server knows about each catalogue harness on this machine, for the
|
|
|
|
|
* local model recommendation. Server side: this is the one module of src/local-model/ that
|
|
|
|
|
* reads the CLI registry, so `recommend()` can stay pure and name no CLI.
|
|
|
|
|
*
|
2026-11-06 16:27:49 +01:00
|
|
|
* `buildHarnessFacts()` walks the catalogue's `harnesses` rows and, for every row:
|
|
|
|
|
* - resolves its `cli` in the CLI registry AT CALL TIME (never in a module-level constant),
|
|
|
|
|
* and leaves the row out when the CLI is unknown, disabled, or has no custom model
|
|
|
|
|
* mechanism (`capabilities.customModelInjection.kind` is `unsupported`);
|
|
|
|
|
* - reports `label` from the registry entry and `installed` from the same probe the page
|
|
|
|
|
* render and `GET /api/clis` use (`utils/cli-installed-probes.ts`), asked once per build;
|
|
|
|
|
* - reports `installable` only for a STOCK CLI that is not installed and whose install
|
2026-11-06 22:16:38 +01:00
|
|
|
* command for this platform needs no administrator rights (`installCommandNeedsAdmin()`),
|
|
|
|
|
* and then carries that command as `installCommand`, so the consent screen can print the
|
|
|
|
|
* literal text. The command is the COMPILED stock one (`stockInstallCommand()`), never the
|
|
|
|
|
* one a `clis.json` override supplies: it is exactly what the install job would run, and
|
|
|
|
|
* an override file must not be able to change that;
|
2026-11-06 16:27:49 +01:00
|
|
|
* - supplies `acceptsModelId` (`cliAcceptsCustomModelId()`), the test a custom model launch
|
|
|
|
|
* applies to the model id before anything is written.
|
2026-11-06 14:56:13 +01:00
|
|
|
*
|
|
|
|
|
* Rules:
|
2026-11-06 16:27:49 +01:00
|
|
|
* - No CLI id is compared with a literal here or anywhere: the id comes from the catalogue
|
|
|
|
|
* row and everything else from the registry entry it resolves to.
|
|
|
|
|
* - Read-only: nothing is installed, written or spawned beyond the existing availability
|
|
|
|
|
* probe. An install command is only read as text, never run.
|
|
|
|
|
* - Never throws: a probe that fails reads as "not installed" (with a warning in the log),
|
|
|
|
|
* and the registry's install data still answers `installable`.
|
|
|
|
|
*
|
|
|
|
|
* `cliAcceptsCustomModelId()` composes the two pure pieces the launch path itself calls
|
|
|
|
|
* (`buildCustomModelInjection()` and `matchesPattern()` on the entry's `model` launch param).
|
|
|
|
|
* The launch path keeps that composition inline at two sites in
|
|
|
|
|
* src/web/routes/session-routes.ts (the quick-start `customModel` branch and
|
|
|
|
|
* `POST /api/sessions/:id/custom-model`). A change to the rule there must be made here too,
|
|
|
|
|
* until the three share one helper.
|
2026-11-06 14:56:13 +01:00
|
|
|
*/
|
|
|
|
|
|
2026-11-06 16:27:49 +01:00
|
|
|
import type { CliEntry } from '../config/cli-registry/types.js';
|
|
|
|
|
import { matchesPattern } from '../config/cli-registry/patterns.js';
|
2026-11-06 22:16:38 +01:00
|
|
|
import { stockInstallCommand } from '../cli-install-runner.js';
|
|
|
|
|
import { getCli } from '../config/cli-registry/registry.js';
|
2026-11-06 16:27:49 +01:00
|
|
|
import { buildCustomModelInjection, type CustomModelEndpoint } from '../custom-model-injection.js';
|
|
|
|
|
import { isCliEntryInstalled, probeStockCliAvailability } from '../utils/cli-installed-probes.js';
|
|
|
|
|
import { getErrorMessage, type HarnessFact, type LocalModelCatalog } from '../types.js';
|
|
|
|
|
|
|
|
|
|
/** What `buildHarnessFacts()` reads. Each member defaults to the real module; a test overrides what it needs. */
|
|
|
|
|
export interface HarnessFactsDeps {
|
|
|
|
|
/** One CLI of the registry, looked up when the facts are built. */
|
|
|
|
|
getCli: (id: string) => CliEntry | undefined;
|
|
|
|
|
/**
|
|
|
|
|
* The availability probe, asked ONCE per build: it answers with a test for single entries.
|
|
|
|
|
* Under vitest the real probe is inert (it finds no CLI), so a test that cares about
|
|
|
|
|
* `installed` passes its own.
|
|
|
|
|
*/
|
|
|
|
|
probeInstalled: () => Promise<(entry: CliEntry) => boolean>;
|
2026-11-06 22:16:38 +01:00
|
|
|
/**
|
|
|
|
|
* The install command the install job would run for this CLI on this platform: the compiled
|
|
|
|
|
* stock command, `undefined` for a CLI that is not stock or has none here. Read as text,
|
|
|
|
|
* never run.
|
|
|
|
|
*/
|
2026-11-06 16:27:49 +01:00
|
|
|
installCommandFor: (entry: CliEntry) => string | undefined;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export const defaultHarnessFactsDeps: HarnessFactsDeps = {
|
|
|
|
|
getCli,
|
|
|
|
|
probeInstalled: async () => {
|
|
|
|
|
const stockAvailability = await probeStockCliAvailability();
|
|
|
|
|
return (entry) => isCliEntryInstalled(entry, stockAvailability);
|
|
|
|
|
},
|
2026-11-06 22:16:38 +01:00
|
|
|
installCommandFor: (entry) => stockInstallCommand(entry.id as string),
|
2026-11-06 16:27:49 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A command segment that starts with `sudo` or `brew`: at the start of the text, or after a
|
|
|
|
|
* pipe, `&&`, `||`, `;`, a line break or an opening parenthesis.
|
|
|
|
|
*/
|
|
|
|
|
const ADMIN_COMMAND = /(?:^|[;&|(\n])\s*(?:sudo|brew)(?=\s|$)/;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Whether an install command needs administrator rights, read off its text.
|
|
|
|
|
* - `sudo ...` asks for an administrator password.
|
|
|
|
|
* - `brew ...` needs Homebrew, and installing Homebrew needs an administrator (the same rule
|
|
|
|
|
* the installer's no-admin route applies to the CLI menu).
|
|
|
|
|
* `curl ... | bash` installers write into the home directory, and the install runner points an
|
|
|
|
|
* `npm install -g` at a prefix the server user can write, so neither counts.
|
|
|
|
|
*/
|
|
|
|
|
export function installCommandNeedsAdmin(command: string): boolean {
|
|
|
|
|
return ADMIN_COMMAND.test(command);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Stands in for a configured endpoint: the launch id a recipe forces depends on the model id alone. */
|
|
|
|
|
const PROBE_ENDPOINT: CustomModelEndpoint = {
|
|
|
|
|
id: 'local-model-probe',
|
|
|
|
|
label: 'local model probe',
|
|
|
|
|
baseUrl: 'http://127.0.0.1',
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Whether a custom model launch of this CLI would accept `modelId`.
|
|
|
|
|
*
|
|
|
|
|
* A CLI whose config alone cannot select the model gets the id forced onto its `model` launch
|
|
|
|
|
* param (the recipe's `launchModel` template). The argv engine DROPS a token that fails the
|
|
|
|
|
* param's pattern, which would start the CLI on its own default provider, so the launch path
|
|
|
|
|
* refuses such an id up front. This is that test: false when the forced value does not match
|
|
|
|
|
* the pattern, and false for a CLI with no custom model mechanism at all.
|
|
|
|
|
*/
|
|
|
|
|
export function cliAcceptsCustomModelId(entry: Pick<CliEntry, 'capabilities' | 'launch'>, modelId: string): boolean {
|
|
|
|
|
try {
|
|
|
|
|
const injection = buildCustomModelInjection(entry, PROBE_ENDPOINT, modelId);
|
|
|
|
|
if (injection.kind === 'unsupported') return false;
|
|
|
|
|
const forcedLaunchModel = injection.launchModel;
|
|
|
|
|
const modelSpec = entry.launch.params.model;
|
|
|
|
|
return !(
|
|
|
|
|
forcedLaunchModel !== undefined &&
|
|
|
|
|
modelSpec?.type === 'token' &&
|
|
|
|
|
!matchesPattern(modelSpec.pattern, forcedLaunchModel)
|
|
|
|
|
);
|
|
|
|
|
} catch {
|
|
|
|
|
// A recipe that cannot be rendered cannot be launched either.
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
}
|
2026-11-06 14:56:13 +01:00
|
|
|
|
|
|
|
|
/** One fact per catalogue harness that resolves in the CLI registry, in catalogue order. */
|
2026-11-06 16:27:49 +01:00
|
|
|
export async function buildHarnessFacts(
|
|
|
|
|
catalog: LocalModelCatalog,
|
|
|
|
|
deps: Partial<HarnessFactsDeps> = {}
|
|
|
|
|
): Promise<HarnessFact[]> {
|
|
|
|
|
const resolved: HarnessFactsDeps = { ...defaultHarnessFactsDeps, ...deps };
|
|
|
|
|
|
|
|
|
|
let isInstalled: (entry: CliEntry) => boolean;
|
|
|
|
|
try {
|
|
|
|
|
isInstalled = await resolved.probeInstalled();
|
|
|
|
|
} catch (err) {
|
|
|
|
|
console.warn(
|
|
|
|
|
`[local-model] The CLI availability probe failed, reading every harness as not installed: ${getErrorMessage(err)}`
|
|
|
|
|
);
|
|
|
|
|
isInstalled = () => false;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const facts: HarnessFact[] = [];
|
|
|
|
|
const seen = new Set<string>();
|
|
|
|
|
for (const row of catalog.harnesses) {
|
|
|
|
|
// The catalogue lists a CLI once; a second row for it adds nothing a fact could carry.
|
|
|
|
|
if (seen.has(row.cli)) continue;
|
|
|
|
|
seen.add(row.cli);
|
|
|
|
|
|
|
|
|
|
const entry = resolved.getCli(row.cli);
|
|
|
|
|
if (!entry || !entry.enabled) continue;
|
|
|
|
|
if (entry.capabilities.customModelInjection.kind === 'unsupported') continue;
|
|
|
|
|
|
|
|
|
|
let installed = false;
|
|
|
|
|
try {
|
|
|
|
|
installed = isInstalled(entry);
|
|
|
|
|
} catch (err) {
|
|
|
|
|
console.warn(`[local-model] Probing ${entry.label} failed, reading it as not installed: ${getErrorMessage(err)}`);
|
|
|
|
|
}
|
|
|
|
|
|
2026-11-06 22:16:38 +01:00
|
|
|
let installCommand: string | undefined;
|
2026-11-06 16:27:49 +01:00
|
|
|
if (!installed && entry.stock) {
|
|
|
|
|
const command = resolved.installCommandFor(entry);
|
2026-11-06 22:16:38 +01:00
|
|
|
if (command !== undefined && command.trim() !== '' && !installCommandNeedsAdmin(command)) {
|
|
|
|
|
installCommand = command;
|
|
|
|
|
}
|
2026-11-06 16:27:49 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
facts.push({
|
|
|
|
|
cli: row.cli,
|
|
|
|
|
label: entry.label,
|
|
|
|
|
installed,
|
2026-11-06 22:16:38 +01:00
|
|
|
installable: installCommand !== undefined,
|
|
|
|
|
...(installCommand !== undefined ? { installCommand } : {}),
|
2026-11-06 16:27:49 +01:00
|
|
|
acceptsModelId: (modelId: string) => cliAcceptsCustomModelId(entry, modelId),
|
|
|
|
|
});
|
|
|
|
|
}
|
|
|
|
|
return facts;
|
2026-11-06 14:56:13 +01:00
|
|
|
}
|