feat(local-model): GET /api/local-model and the harness facts

The read-only route behind the recommendation, and the one module that reads
the CLI registry for it.

- harness-facts.ts: one fact per catalogue harness row, resolved in the CLI
  registry at call time: the registry's label, `installed` from the existing
  availability probe (asked once per build), `installable` for a stock CLI
  whose install command for this platform needs no administrator rights, and
  `acceptsModelId`, the test a custom model launch applies to the model id.
  A row whose CLI is unknown, disabled or has no custom model mechanism gets
  no fact. No CLI id is compared with a literal.
- routes/local-model-routes.ts: answers { hardware, recommendation,
  catalogUpdated } in the usual envelope and reformats nothing. Admin only in
  multi-user mode (403), checked before anything is probed. A failed probe is
  an answer (200, the hardware's `source` says what was read); a 500 is left
  for a fault in the catalogue, the harness facts or recommend(). It writes no
  file and reads no setting.

Tests: test/local-model-harness-facts.test.ts,
test/routes/local-model-routes.test.ts (app.inject(), no port; the temp HOME
is byte-identical before and after the requests).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-11-06 16:27:49 +01:00
1 parent 92c20fe572
commit 34e95ceb62
4 files changed
+942 -29

No files matched your search

+153 -18
View File
@@ -3,28 +3,163 @@
* 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.
*
* SKELETON: the exported signature is final, the body is not written yet. `buildHarnessFacts()`
* will, for every `LocalHarnessEntry` of the catalogue:
* - resolve its `cli` in the CLI registry AT CALL TIME (never in a module-level constant), and
* leave out a row whose CLI is unknown, disabled, or has no custom model mechanism
* (`capabilities.customModelInjection.kind` is `unsupported`);
* - report `label` from the registry entry and `installed` from the same probe the other
* routes use;
* - report `installable` only for a CLI that is not installed and whose install command for
* this platform needs no administrator rights (not one that starts with `brew` or `sudo`);
* - supply `acceptsModelId`, the same test a custom model launch applies to the model id
* before anything is written (the launch spec's model pattern).
* `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
* command for this platform needs no administrator rights (`installCommandNeedsAdmin()`).
* Stock only, because the install runner never executes a custom entry's command;
* - supplies `acceptsModelId` (`cliAcceptsCustomModelId()`), the test a custom model launch
* applies to the model id before anything is written.
*
* Rules:
* - 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.
* - 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.
*/
import type { HarnessFact, LocalModelCatalog } from '../types.js';
import type { CliEntry } from '../config/cli-registry/types.js';
import { matchesPattern } from '../config/cli-registry/patterns.js';
import { getCli, resolveInstallCommandForPlatform } from '../config/cli-registry/registry.js';
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>;
/** The install command the registry holds for this platform. Read as text, never run. */
installCommandFor: (entry: CliEntry) => string | undefined;
}
export const defaultHarnessFactsDeps: HarnessFactsDeps = {
getCli,
probeInstalled: async () => {
const stockAvailability = await probeStockCliAvailability();
return (entry) => isCliEntryInstalled(entry, stockAvailability);
},
installCommandFor: resolveInstallCommandForPlatform,
};
/**
* 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;
}
}
/** One fact per catalogue harness that resolves in the CLI registry, in catalogue order. */
export async function buildHarnessFacts(catalog: LocalModelCatalog): Promise<HarnessFact[]> {
void catalog;
throw new Error('not implemented: buildHarnessFacts');
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)}`);
}
let installable = false;
if (!installed && entry.stock) {
const command = resolved.installCommandFor(entry);
installable = command !== undefined && command.trim() !== '' && !installCommandNeedsAdmin(command);
}
facts.push({
cli: row.cli,
label: entry.label,
installed,
installable,
acceptsModelId: (modelId: string) => cliAcceptsCustomModelId(entry, modelId),
});
}
return facts;
}