Merge feat/local-model-recommendation: recommend and install a local coding model on this Mac (experimental)

Conflicts resolved as on test/desktop-macbook: config/test-suites.ts keeps both browser tests (desktop-connect-page and local-model-ui), and the CLAUDE.md state-files line keeps #778's cli-installed entry with the local model's local-model.json and local-model/ entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-11-08 04:06:46 +01:00
commit e8a63ede00
80 files changed
+31268 -261

No files matched your search

+19 -212
View File
@@ -29,13 +29,8 @@
* write path (`registry-writer.ts` mirrors `custom-model-hosts.ts`).
*/
import { execFile, spawn } from 'node:child_process';
import { constants as fsConstants } from 'node:fs';
import { access } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { promisify } from 'node:util';
import type { FastifyInstance, FastifyRequest } from 'fastify';
import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from '../../types.js';
import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
import { getAuthUser, isAdmin, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
import { isMultiUserMode } from '../../config/multiuser.js';
import { listClis, resolveInstallCommandForPlatform } from '../../config/cli-registry/registry.js';
@@ -45,9 +40,18 @@ import { STOCK_CLIS } from '../../config/cli-registry/stock.js';
import type { CliEntry } from '../../config/cli-registry/types.js';
import { CliCustomEntrySchema, CliEnableSchema } from '../schemas.js';
import { appendAdminAudit } from '../admin-audit.js';
import { invalidateCliExecutableResolvers } from '../../utils/cli-executable-resolver.js';
import { invalidateCliResolverCache } from '../../utils/cli-resolver.js';
import { isCliEntryInstalled, probeStockCliAvailability } from '../../utils/cli-installed-probes.js';
import {
CLI_INSTALL_TIMEOUT_MS,
forgetResolvedCli,
runInstallCommand,
tryBeginCliInstall,
type CliInstallResult,
} from '../../cli-install-runner.js';
// The install runner lives in src/cli-install-runner.ts, shared with the local model install
// job. These two stay importable from here, where the route's tests take them from.
export { installEnv, npmGlobalPrefixWritable } from '../../cli-install-runner.js';
/**
* `cliManagementEnabled` defaults OFF, same reasoning as
@@ -78,17 +82,6 @@ export interface CliListItem {
installCommand?: string;
}
/**
* Forget every cached binary lookup for this CLI — the generic per-id resolver (which
* captures the entry's binaries when first built) and every underlying per-binary cache,
* success and negative-cache backoff alike. Called after anything that changes what is on
* disk or what the CLI's binary IS; see `invalidateCliExecutableResolvers`.
*/
function forgetResolvedCli(id: string, binaries: readonly string[]): void {
invalidateCliExecutableResolvers(binaries);
invalidateCliResolverCache(id);
}
const STOCK_IDS = new Set(STOCK_CLIS.map((e) => e.id as string));
/**
@@ -202,195 +195,6 @@ function nextOrder(): number {
return (orders.length ? Math.max(...orders) : 0) + 10;
}
/** Bounded execution: `PATH_INSTALL_TIMEOUT_MS`, output capped, process GROUP killed on timeout. */
const CLI_INSTALL_TIMEOUT_MS = 300_000;
/**
* Ids with an install running right now. A second request for the same id gets 409 rather
* than a second `curl | bash` or `npm install -g` racing the first over the same prefix.
*/
const installsInFlight = new Set<string>();
const execFileAsync = promisify(execFile);
/**
* True when `npm install -g` can write to this process's npm global prefix, or when that cannot
* be determined (then nothing is redirected: a wrong guess would move installs somewhere the
* user did not choose). `npm config get prefix` is asked rather than guessed from `process.execPath`
* because a user `.npmrc` / `NPM_CONFIG_PREFIX` can point it anywhere.
*
* Async so the server keeps serving while npm boots (130 to 240 ms), and killed with SIGKILL on
* timeout because `SIGTERM` alone leaves the wait running. A prefix that does not exist yet is
* judged by the nearest ancestor that does: npm creates the missing directories, so a user
* `.npmrc` pointing at `~/.npm-global` before it was made is not moved.
*/
export async function npmGlobalPrefixWritable(source: NodeJS.ProcessEnv): Promise<boolean> {
try {
const { stdout } = await execFileAsync('npm', ['config', 'get', 'prefix'], {
env: source,
encoding: 'utf8',
timeout: 5_000,
killSignal: 'SIGKILL',
});
const prefix = stdout.trim();
if (!prefix) return true;
// npm creates lib/node_modules under the prefix; walk up to the first directory that exists.
let dir = join(prefix, 'lib', 'node_modules');
for (;;) {
try {
await access(dir, fsConstants.W_OK);
return true;
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return false;
const parent = dirname(dir);
if (parent === dir) return false;
dir = parent;
}
}
} catch {
return true;
}
}
/**
* The server's environment minus every `CODEMAN_*` variable. An install script is third-party
* code, and those variables carry Codeman's own secrets and wiring (`CODEMAN_PASSWORD`, the
* data dir, the tmux socket), none of which an installer needs.
*
* It also points `NPM_CONFIG_PREFIX` at `$HOME/.local` so an `npm install -g` lands somewhere the
* server user can write and Codeman's resolvers already search (`~/.local/bin`):
* - inside the Docker Compose container (`CODEMAN_IN_CONTAINER=1`), so installs survive an image
* update (the image's own prefix is image content);
* - on a native install whose npm global prefix is not writable by the server user (a system node
* under `/usr`, installed by root). Without this `npm install -g` died with EACCES (exit 243),
* e.g. DeepSeek's `npm install -g @deepseek-ai/dsh`. An explicit `NPM_CONFIG_PREFIX` the
* operator set is respected, and so is a prefix that is writable (nvm, `~/.npm-global`, ...).
*/
export function installEnv(
source: NodeJS.ProcessEnv = process.env,
prefixWritable: (env: NodeJS.ProcessEnv) => boolean = () => true
): NodeJS.ProcessEnv {
const env: NodeJS.ProcessEnv = {};
for (const [key, value] of Object.entries(source)) {
if (!key.startsWith('CODEMAN_')) env[key] = value;
}
// ⚠️ In the Docker Compose deployment the image sets NPM_CONFIG_PREFIX=/opt/codeman-cli, which is IMAGE
// content: `Update-Codeman.sh` recreates the container and every CLI installed there (dsh, pi, ...)
// vanishes. HOME is the persistent bind mount and `~/.local/bin` is already on every resolver's search
// list, so npm-based installs are redirected there. curl|bash installers already target HOME.
if (source.CODEMAN_IN_CONTAINER === '1' && source.HOME) {
redirectNpmPrefix(env, source.HOME);
} else if (process.platform !== 'win32' && source.HOME && !source.NPM_CONFIG_PREFIX && !prefixWritable(env)) {
redirectNpmPrefix(env, source.HOME);
}
return env;
}
/**
* Point npm at `$HOME/.local`, dropping every spelling of the prefix key first. `npm run` exports a
* lowercase `npm_config_prefix`, npm reads `npm_config_*` case-insensitively, and when both spellings
* are present a `/bin/sh` that sorts its environment (bash) lets the older value win. The explicit
* operator guard in `installEnv` stays on the uppercase key only: npm always injects the lowercase one.
*/
function redirectNpmPrefix(env: NodeJS.ProcessEnv, home: string): void {
for (const key of Object.keys(env)) if (/^npm_config_prefix$/i.test(key)) delete env[key];
env.NPM_CONFIG_PREFIX = `${home}/.local`;
}
/**
* `installEnv` for this process, with the (async) npm prefix probe done first and only when the
* command runs npm at all: a `curl | bash` installer never pays for it.
*/
async function installEnvFor(command: string, source: NodeJS.ProcessEnv = process.env): Promise<NodeJS.ProcessEnv> {
const usesNpm = /\bnpm\b/.test(command);
const probeNeeded =
usesNpm &&
source.CODEMAN_IN_CONTAINER !== '1' &&
process.platform !== 'win32' &&
!!source.HOME &&
!source.NPM_CONFIG_PREFIX;
const writable = probeNeeded ? await npmGlobalPrefixWritable(installEnv(source)) : true;
return installEnv(source, () => writable);
}
interface InstallResult {
code: number | null;
output: string;
timedOut: boolean;
}
/**
* Runs a STOCK entry's already-vetted install command. `shell: true` is unavoidable here —
* the shipped commands are genuinely `curl | bash` / `npm install -g` one-liners — but this
* is NOT a reopening of the config-shell-text concern the registry's `shellToken` pattern
* exists to prevent: the string executed here is NEVER user input, only ever what is
* already hardcoded and reviewed in `stock.ts` (`resolveInstallCommandForPlatform`), and a
* CUSTOM entry can never reach this function at all — see the route's own guard below.
*/
async function runInstallCommand(command: string): Promise<InstallResult> {
const env = await installEnvFor(command);
return new Promise((resolve) => {
let child: ReturnType<typeof spawn>;
try {
child = spawn(command, {
shell: true,
stdio: ['ignore', 'pipe', 'pipe'],
// Own process group; the timeout below kills the whole tree by hand, mirroring
// the DeepSeek profile-install endpoint's own reasoning: an install command fans
// out into package-manager children, and spawn's own `timeout` option signals
// only the direct child, leaving survivors holding the pipes open forever.
detached: true,
env,
});
} catch (err) {
resolve({ code: null, output: `spawn failed: ${getErrorMessage(err)}`, timedOut: false });
return;
}
let output = '';
let timedOut = false;
let settled = false;
let killTimer: NodeJS.Timeout | undefined;
let reapTimer: NodeJS.Timeout | undefined;
const capture = (chunk: Buffer) => {
if (output.length < 16_384) output += chunk.toString('utf-8');
};
child.stdout?.on('data', capture);
child.stderr?.on('data', capture);
const killTree = (signal: NodeJS.Signals) => {
try {
if (child.pid) process.kill(-child.pid, signal);
} catch {
/* already gone */
}
};
const finish = (code: number | null) => {
if (settled) return;
settled = true;
clearTimeout(timer);
if (killTimer) clearTimeout(killTimer);
if (reapTimer) clearTimeout(reapTimer);
resolve({ code, output, timedOut });
};
const timer = setTimeout(() => {
timedOut = true;
killTree('SIGTERM');
killTimer = setTimeout(() => killTree('SIGKILL'), 3_000);
reapTimer = setTimeout(() => finish(null), 8_000);
}, CLI_INSTALL_TIMEOUT_MS);
child.on('error', (err) => {
output = `${output}\n${err.message}`;
finish(null);
});
child.on('close', (code) => finish(code));
});
}
export function registerCliRegistryRoutes(app: FastifyInstance): void {
// ---- Phase 2: read ----------------------------------------------------
// GET /api/clis — every registry entry, disabled ones included (this is an
@@ -461,6 +265,8 @@ export function registerCliRegistryRoutes(app: FastifyInstance): void {
// ---- Phase 4: auto-install (stock only) --------------------------------
// One install per id at a time (409 otherwise), and the script never sees CODEMAN_* env.
// Bounded execution (`CLI_INSTALL_TIMEOUT_MS`), output capped, process GROUP killed on
// timeout: all of that is `runInstallCommand()` in src/cli-install-runner.ts.
// POST /api/clis/:id/install — runs the entry's already-vetted install
// command. Separate endpoint from Phase 3's toggle: installing is a bigger
// action than a boolean flip and gets its own audit entry. Never auto-
@@ -488,15 +294,16 @@ export function registerCliRegistryRoutes(app: FastifyInstance): void {
return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `"${id}" has no install command for this platform`);
}
if (installsInFlight.has(id)) {
// ONE slot per id, shared with the local model install job (src/cli-install-runner.ts).
const release = tryBeginCliInstall(id);
if (!release) {
return createErrorResponse(ApiErrorCode.CONFLICT, `"${id}" is already being installed`);
}
installsInFlight.add(id);
let result: InstallResult;
let result: CliInstallResult;
try {
result = await runInstallCommand(command);
} finally {
installsInFlight.delete(id);
release();
}
// Even a failed or timed-out install may have left a binary behind, so forget the
// cached lookups either way: the next Run click or badge read probes afresh
+103 -34
View File
@@ -12,17 +12,34 @@
* connect time, redirects included — a save-time hostname check alone would
* let `models.example` resolve to 169.254.169.254 later. The endpoint is
* admin-configured, so this is defence in depth rather than the only gate.
*
* Every write of `custom-model-hosts.json` goes through `mutateCustomModelHosts()`
* (src/custom-model-hosts-writer.ts): the four writing routes and the re-discovery sweep run
* one at a time, each check ("the id is free", "the record still exists") inside the same
* serialized step as its write, and a file that does not parse is refused with 409 rather than
* overwritten. They used to read, change and write on their own, through one shared temp file
* name: a route and the sweep could tear the file, and the next writer then saved a list that
* held only its own record.
*
* The local model install (src/local-model/) keeps ONE record here under a reserved id
* (`LOCAL_MODEL_ENDPOINT_ID`). A new endpoint may not take that id. While the record is the
* managed one (`isManagedLocalEndpoint()`: the local model state file records it as ours) it
* is not edited, deleted or re-discovered from here: its `models` must stay the one model the
* install checked, and its `baseUrl` the port of the runtime Codeman supervises. It is changed
* and removed through the local model routes.
*/
import type { FastifyInstance, FastifyRequest } from 'fastify';
import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
import { ApiErrorCode, createErrorResponse, LOCAL_MODEL_INSTALL_LABELS, type ApiResponse } from '../../types.js';
import { isAdmin, parseBody, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
import { isMultiUserMode } from '../../config/multiuser.js';
import { getDataDir } from '../../config/instance.js';
import { isBlockedWebviewUrl } from '../webview-egress-policy.js';
import { egressBlockedReason, webviewFetch } from '../webview-egress.js';
import { CustomModelHostSchema, MAX_DISCOVERED_CONTEXT_TOKENS } from '../schemas.js';
import { readCustomModelHosts, writeCustomModelHosts, type CustomModelHost } from '../../custom-model-hosts.js';
import { readCustomModelHosts, type CustomModelHost } from '../../custom-model-hosts.js';
import { customModelHostsWriteErrorResponse, mutateCustomModelHosts } from '../../custom-model-hosts-writer.js';
import { isLocalModelEndpointId, isManagedLocalEndpoint } from '../../local-model/connect.js';
import type { CliEntry } from '../../config/cli-registry/types.js';
const CODEMAN_CONFIG_DIR = getDataDir();
@@ -795,20 +812,30 @@ export async function refreshAllCustomModelHosts(): Promise<void> {
const hosts = await readCustomModelHosts(dataDir);
for (const host of hosts) {
if (isBlockedWebviewUrl(host.baseUrl)) continue;
// The local model's own record keeps the one model its install checked: whatever else the
// runtime lists (a model somebody pulled through its port) must not become launchable.
if (await isManagedLocalEndpoint(host.id)) continue;
let result: DiscoveryResult;
try {
result = await discoverModels(host);
} catch {
continue; // unreachable this cycle — try again next tick, not fatal to the sweep
}
// Re-read + splice by id rather than reusing the array captured above: an
// admin editing or deleting an endpoint via the API mid-sweep must win,
// not be silently overwritten by a refresh that started before their change.
const current = await readCustomModelHosts(dataDir);
const index = current.findIndex((item) => item.id === host.id);
if (index === -1) continue; // deleted mid-sweep
current[index] = applyDiscoveredModels(current[index], result);
await writeCustomModelHosts(dataDir, current);
// Spliced by id inside the serialized writer, onto the list as it is THEN, rather than
// the array captured above: an admin editing or deleting an endpoint via the API mid-sweep
// must win, not be silently overwritten by a refresh that started before their change.
try {
await mutateCustomModelHosts<void>((current) => {
const index = current.findIndex((item) => item.id === host.id);
if (index === -1) return { result: undefined }; // deleted mid-sweep
current[index] = applyDiscoveredModels(current[index], result);
return { hosts: current, result: undefined };
}, dataDir);
} catch {
// A file that must not be overwritten (it does not parse) refuses every write of this
// sweep the same way. The writer logged why; nothing more can be saved this cycle.
return;
}
}
}
@@ -897,6 +924,18 @@ export async function detectCustomModelSwapDisplacements(
return displacements;
}
/** A write the serialized writer refused (the file does not parse) is 409 with the fix; any other failure stays in the envelope. */
function refusedHostsWrite(err: unknown, reply: { code: (n: number) => unknown }): ApiResponse<never> {
const response = customModelHostsWriteErrorResponse(err);
if (!response.success && response.errorCode === ApiErrorCode.CONFLICT) reply.code(409);
return response;
}
/** The answer to an edit or a delete of the record the local model install manages. */
function managedEndpointRefusal(): ApiResponse<never> {
return createErrorResponse(ApiErrorCode.INVALID_INPUT, LOCAL_MODEL_INSTALL_LABELS.endpointManaged);
}
export function registerCustomModelRoutes(app: FastifyInstance): void {
app.get('/api/model-endpoints', async (req): Promise<RedactedHost[]> => {
if (isMultiUserMode() && !isAdmin(req)) return [];
@@ -913,12 +952,19 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
}
const badDefault = invalidDefaultModel(host);
if (badDefault) return badDefault;
const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
if (hosts.some((item) => item.id === host.id)) {
return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Model endpoint already exists');
if (isLocalModelEndpointId(host.id)) {
return createErrorResponse(ApiErrorCode.INVALID_INPUT, LOCAL_MODEL_INSTALL_LABELS.endpointIdReserved);
}
try {
return await mutateCustomModelHosts<ApiResponse<{ host: RedactedHost }>>((hosts) => {
if (hosts.some((item) => item.id === host.id)) {
return { result: createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Model endpoint already exists') };
}
return { hosts: [...hosts, host], result: { success: true, data: { host: redactApiKey(host) } } };
}, CODEMAN_CONFIG_DIR);
} catch (err) {
return refusedHostsWrite(err, reply);
}
await writeCustomModelHosts(CODEMAN_CONFIG_DIR, [...hosts, host]);
return { success: true, data: { host: redactApiKey(host) } };
});
app.put('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ host: RedactedHost }>> => {
@@ -931,26 +977,37 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
}
const badDefault = invalidDefaultModel(incoming);
if (badDefault) return badDefault;
const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
const index = hosts.findIndex((item) => item.id === id);
if (index === -1) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
const host = applyDiscoveredFields(applyStoredApiKey(incoming, hosts[index]), hosts[index]);
const next = [...hosts];
next[index] = host;
await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
return { success: true, data: { host: redactApiKey(host) } };
if (await isManagedLocalEndpoint(id)) return managedEndpointRefusal();
try {
return await mutateCustomModelHosts<ApiResponse<{ host: RedactedHost }>>((hosts) => {
const index = hosts.findIndex((item) => item.id === id);
if (index === -1) return { result: createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found') };
const host = applyDiscoveredFields(applyStoredApiKey(incoming, hosts[index]), hosts[index]);
const next = [...hosts];
next[index] = host;
return { hosts: next, result: { success: true, data: { host: redactApiKey(host) } } };
}, CODEMAN_CONFIG_DIR);
} catch (err) {
return refusedHostsWrite(err, reply);
}
});
app.delete('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ id: string }>> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
const { id } = req.params as { id: string };
const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
await writeCustomModelHosts(
CODEMAN_CONFIG_DIR,
hosts.filter((item) => item.id !== id)
);
return { success: true, data: { id } };
if (await isManagedLocalEndpoint(id)) return managedEndpointRefusal();
try {
return await mutateCustomModelHosts<ApiResponse<{ id: string }>>((hosts) => {
const next = hosts.filter((item) => item.id !== id);
// Nothing to take out: the file is left as it is, and the answer is the same.
return next.length === hosts.length
? { result: { success: true, data: { id } } }
: { hosts: next, result: { success: true, data: { id } } };
}, CODEMAN_CONFIG_DIR);
} catch (err) {
return refusedHostsWrite(err, reply);
}
});
app.post(
@@ -966,12 +1023,12 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
if (isBlockedWebviewUrl(host.baseUrl)) {
return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Endpoint base URL is not allowed');
}
// The local model's own record is not probed: it lists the one model its install checked,
// and that list is the answer.
if (await isManagedLocalEndpoint(id)) return { success: true, data: { models: host.models ?? [] } };
let result: DiscoveryResult;
try {
const result = await discoverModels(host);
const next = [...hosts];
next[index] = applyDiscoveredModels(host, result);
await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
return { success: true, data: { models: result.models } };
result = await discoverModels(host);
} catch (err) {
const blocked = egressBlockedReason(err);
return createErrorResponse(
@@ -979,6 +1036,18 @@ export function registerCustomModelRoutes(app: FastifyInstance): void {
blocked ? `Endpoint refused: ${blocked}` : `Could not reach endpoint: ${describeFetchError(err)}`
);
}
try {
// Onto the record as it is NOW: the probe above took a moment, and an edit made
// meanwhile must not be replaced by the copy read before it.
return await mutateCustomModelHosts<ApiResponse<{ models: string[] }>>((current) => {
const at = current.findIndex((item) => item.id === id);
if (at === -1) return { result: createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found') };
current[at] = applyDiscoveredModels(current[at], result);
return { hosts: current, result: { success: true, data: { models: result.models } } };
}, CODEMAN_CONFIG_DIR);
} catch (err) {
return refusedHostsWrite(err, reply);
}
}
);
+1
View File
@@ -49,5 +49,6 @@ export {
type CustomModelSwapDisplacement,
} from './custom-model-routes.js';
export { registerCliRegistryRoutes, readCliManagementEnabled, type CliListItem } from './cli-registry-routes.js';
export { registerLocalModelRoutes } from './local-model-routes.js';
export { registerAgentSessionRoutes } from './agent-session-routes.js';
+306
View File
@@ -0,0 +1,306 @@
/**
* @fileoverview The local model routes: what this Mac is and which local model fits it
* (`GET /api/local-model`), and the verbs that install one, start and stop it and remove it.
*
* | Route | Body | Answer |
* |----------------------------------|-----------------------------|------------------------------------------------|
* | `GET /api/local-model` | none | `{ hardware, recommendation, catalogUpdated, install }` |
* | `POST /api/local-model/install` | `LocalModelInstallRequest` | the install view; 400, 409 |
* | `POST /api/local-model/cancel` | none | the install view; 409 |
* | `POST /api/local-model/resume` | `LocalModelResumeRequest` | the install view; 409 |
* | `POST /api/local-model/runtime` | `LocalModelRuntimeRequest` | the install view; 409 |
* | `DELETE /api/local-model` | `LocalModelRemoveRequest` | the install view; 409 |
*
* The GET is built from the hardware probe, the catalogue, the harness facts and the pure
* `recommend()`, plus the `install` object of the install service
* (`LocalModelService.view()`). Nothing is reformatted here: every size text and every
* sentence in the payload was chosen by the modules that produced it. There is no SSE event:
* the window polls the GET once a second while it is open.
*
* EXPERIMENTAL (docs/versioning-policy.md, "Experimental local model routes"): the routes and
* their payloads are outside the stable `/api/v1` contract. docs/api-reference.md says so in
* its section; keep the two in step, and drop both labels together.
*
* Rules:
* - Every route is admin only in multi-user mode (403), the same bar as `GET /api/doctor`:
* the GET names hardware of the host, and the verbs download and run a program, install a
* coding agent and write the server-wide settings. The gate runs before anything is probed,
* parsed or started.
* - The GET changes nothing a person asked to keep: it downloads nothing, installs nothing
* and writes no setting. Its one write is the service's own bookkeeping (a job a server
* restart interrupted is marked paused the first time anything looks at it).
* - A failed probe is an answer, never a 500. `readHardware()` reports a spawn that failed
* in the hardware's `source` (`os-fallback`), and a server that is not on macOS as
* `not-probed`; both go out as a 200 whose recommendation is verdict `none` or computed
* from what is known. Should the probe itself reject (it promises not to), the route logs
* it and answers with what `node:os` knows (`hardwareFromOs()`), under the same two
* `source` values.
* - A 500 is left for a fault that is not a probe: the catalogue, the harness facts or
* `recommend()` throwing. That is a bug, and it must not be dressed up as "no model fits".
* - A verb answers the view AFTER the verb. A refusal the service names is a 400 (the request
* is not a row the server offers) or a 409 whose `data` is the `LocalModelConflict`
* (`reason`, the sentence, and for `size-changed` the server's own total, for
* `sessions-open` the session names). A 400 the service names carries its sentence as
* `data.message` too, so the window prints it in its own language. A write of the settings
* or of the endpoint store that was refused (a file that does not parse) is a 409 without
* `data`, with the fix.
* - The verbs do the work in the install service; this file only gates, parses and maps.
* `DELETE`, `runtime` and `resume` look at the live sessions: they hand their names to the
* service, which refuses a removal, a stop and a change of port while one of them still
* uses the model.
* - Every dependency is injected (`LocalModelRouteDeps`), so a route test spawns nothing and
* does not need a Mac: it passes its own hardware, harness facts and service.
*/
import { arch, totalmem } from 'node:os';
import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
import {
ApiErrorCode,
createErrorResponse,
getErrorMessage,
type ApiResponse,
type HardwareFacts,
type HarnessFact,
type LocalModelCatalog,
type LocalModelConflict,
type LocalModelInstallView,
type LocalModelRefusal,
type LocalModelStatus,
type Recommendation,
type RecommendOptions,
} from '../../types.js';
import { getAuthUser, isAdmin, parseBody } from '../route-helpers.js';
import { isMultiUserMode } from '../../config/multiuser.js';
import { getLocalModelCatalog } from '../../config/local-model-catalog.js';
import {
CustomModelHostsWriteRefusedError,
customModelHostsWriteErrorResponse,
} from '../../custom-model-hosts-writer.js';
import { sessionNamesUsingEndpoint } from '../../local-model/connect.js';
import { formatGb, memClassGb } from '../../local-model/format.js';
import { readHardware } from '../../local-model/hardware.js';
import { buildHarnessFacts } from '../../local-model/harness-facts.js';
import {
formatInstallMessage,
getLocalModelService,
type LocalModelActor,
type LocalModelService,
type LocalModelVerbResult,
} from '../../local-model/install-job.js';
import { recommend } from '../../local-model/recommend.js';
import {
LocalModelInstallSchema,
LocalModelRemoveSchema,
LocalModelResumeSchema,
LocalModelRuntimeSchema,
} from '../schemas.js';
import { SettingsWriteRefusedError, settingsWriteErrorResponse } from '../settings-writer.js';
/** A live session as the DELETE needs it: its name, and the endpoint its model comes from. */
export interface LocalModelSessionLike {
name: string;
customModel?: { endpointId: string };
}
/** What the routes read of the server: its live sessions. */
export interface LocalModelRouteContext {
sessions: ReadonlyMap<string, LocalModelSessionLike>;
}
/** What the routes call. Each member defaults to the real module; a test overrides what it needs. */
export interface LocalModelRouteDeps {
readHardware: () => Promise<HardwareFacts>;
getCatalog: () => LocalModelCatalog;
buildHarnessFacts: (catalog: LocalModelCatalog) => Promise<HarnessFact[]>;
recommend: (
hw: HardwareFacts,
catalog: LocalModelCatalog,
harnessFacts: readonly HarnessFact[],
options?: RecommendOptions
) => Recommendation;
/** The install service. Looked up on every request, so the server's one service is built on first use. */
service: () => LocalModelService;
}
export const defaultLocalModelRouteDeps: LocalModelRouteDeps = {
readHardware: () => readHardware(),
getCatalog: getLocalModelCatalog,
buildHarnessFacts: (catalog) => buildHarnessFacts(catalog),
recommend,
service: getLocalModelService,
};
/**
* The hardware answer when the probe rejected: memory and architecture from `node:os`, and the
* `source` the probe itself uses for "nothing was read from sysctl" (`os-fallback` on macOS,
* `not-probed` anywhere else). Sizes go through the one formatter, like every other size.
*/
export function hardwareFromOs(): HardwareFacts {
const memBytes = totalmem();
return {
platform: process.platform,
arch: arch(),
memBytes,
memGb: formatGb(memBytes),
memClassGb: memClassGb(memBytes),
source: process.platform === 'darwin' ? 'os-fallback' : 'not-probed',
};
}
/** The 409 of a verb the service refused: the error envelope plus the conflict as `data`. */
export interface LocalModelConflictResponse {
success: false;
/** The conflict's sentence in English, its slots filled. */
error: string;
errorCode: ApiErrorCode;
data: LocalModelConflict;
}
/** The 400 (or 507) of a verb the service refused with a sentence: the error envelope plus that sentence as `data`. */
export interface LocalModelRefusalResponse {
success: false;
/** The sentence in English, its slots filled. */
error: string;
errorCode: ApiErrorCode;
data: LocalModelRefusal;
}
/** What a verb answers: the view after it, an error envelope, or a refusal that carries its sentence. */
export type LocalModelVerbResponse =
| ApiResponse<LocalModelInstallView>
| LocalModelConflictResponse
| LocalModelRefusalResponse;
/** 403 for a non-admin in multi-user mode, before anything else runs. `null`: go on. */
function adminOnly(req: FastifyRequest, reply: FastifyReply): ApiResponse<never> | null {
if (!isMultiUserMode() || isAdmin(req)) return null;
reply.code(403);
return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
}
function actorOf(req: FastifyRequest): LocalModelActor {
return { username: getAuthUser(req).username, ip: req.ip };
}
/** A verb's result as its HTTP answer. */
function respond(result: LocalModelVerbResult, reply: FastifyReply): LocalModelVerbResponse {
if (result.ok) return { success: true, data: result.view };
reply.code(result.status);
if (result.status !== 409) {
return {
success: false,
error: formatInstallMessage(result.message),
errorCode: result.status === 400 ? ApiErrorCode.INVALID_INPUT : ApiErrorCode.OPERATION_FAILED,
data: { message: result.message },
};
}
return {
success: false,
error: formatInstallMessage(result.conflict.message),
errorCode: ApiErrorCode.CONFLICT,
data: result.conflict,
};
}
/** Runs one verb. What the service did not name as a refusal: a refused config write is a 409 with the fix, anything else a 500. */
async function runVerb(
reply: FastifyReply,
verb: () => Promise<LocalModelVerbResult>
): Promise<LocalModelVerbResponse> {
try {
return respond(await verb(), reply);
} catch (err) {
if (err instanceof CustomModelHostsWriteRefusedError) {
reply.code(409);
return customModelHostsWriteErrorResponse(err);
}
if (err instanceof SettingsWriteRefusedError) {
reply.code(409);
return settingsWriteErrorResponse(err);
}
reply.code(500);
return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, `The local model request failed: ${getErrorMessage(err)}`);
}
}
export function registerLocalModelRoutes(
app: FastifyInstance,
ctx: LocalModelRouteContext,
deps: Partial<LocalModelRouteDeps> = {}
): void {
const resolved: LocalModelRouteDeps = { ...defaultLocalModelRouteDeps, ...deps };
app.get(
'/api/local-model',
async (req: FastifyRequest, reply: FastifyReply): Promise<ApiResponse<LocalModelStatus>> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
let hardware: HardwareFacts;
try {
hardware = await resolved.readHardware();
} catch (err) {
console.warn(`[local-model] The hardware probe failed, answering from node:os: ${getErrorMessage(err)}`);
hardware = hardwareFromOs();
}
try {
const catalog = resolved.getCatalog();
const harnessFacts = await resolved.buildHarnessFacts(catalog);
const service = resolved.service();
// The measured budget once the runtime reported it, and the runtime download that an
// install would still add: what turns the estimate into the figures of the consent.
const options = await service.recommendOptions();
const recommendation = resolved.recommend(hardware, catalog, harnessFacts, options);
const install = await service.view();
return { success: true, data: { hardware, recommendation, catalogUpdated: catalog.updated, install } };
} catch (err) {
reply.code(500);
return createErrorResponse(
ApiErrorCode.INTERNAL_ERROR,
`The local model recommendation failed: ${getErrorMessage(err)}`
);
}
}
);
app.post('/api/local-model/install', async (req, reply): Promise<LocalModelVerbResponse> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
const body = parseBody(LocalModelInstallSchema, req.body);
return runVerb(reply, () => resolved.service().install(body, actorOf(req)));
});
app.post('/api/local-model/cancel', async (req, reply): Promise<LocalModelVerbResponse> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
return runVerb(reply, () => resolved.service().cancel());
});
app.post('/api/local-model/resume', async (req, reply): Promise<LocalModelVerbResponse> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
const body = parseBody(LocalModelResumeSchema, req.body ?? {});
const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
return runVerb(reply, () => resolved.service().resume(body, actorOf(req), sessionNames));
});
app.post('/api/local-model/runtime', async (req, reply): Promise<LocalModelVerbResponse> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
const body = parseBody(LocalModelRuntimeSchema, req.body);
// Asked at the moment of the request, like the DELETE: a stop or a change of port leaves
// a live session calling an address nothing of ours holds.
const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
return runVerb(reply, () => resolved.service().runtime(body, sessionNames));
});
app.delete('/api/local-model', async (req, reply): Promise<LocalModelVerbResponse> => {
const denied = adminOnly(req, reply);
if (denied) return denied;
const body = parseBody(LocalModelRemoveSchema, req.body ?? {});
// Asked at the moment of the request: a session that started a second ago counts.
const sessionNames = sessionNamesUsingEndpoint(ctx.sessions.values());
return runVerb(reply, () => resolved.service().remove(body, sessionNames, actorOf(req)));
});
}
+16
View File
@@ -35,6 +35,7 @@ import {
isWorkingDirAllowedForUsername,
sessionCapacityMessage,
} from '../route-helpers.js';
import { getLocalModelService } from '../../local-model/install-job.js';
import { rebootRestoreRegistry } from '../reboot-restore-registry.js';
import { rejectAlreadyLive, type RebootRestoreEntry, type RebootRestoreRejection } from '../../reboot-restore.js';
import { clampEnvOverridesForOwner } from '../../session-env-clamp.js';
@@ -163,6 +164,21 @@ export function registerRebootRestoreRoutes(app: FastifyInstance, ctx: RebootRes
failures.push({ sessionId: entry.sessionId, reason: 'workspace-forbidden' });
continue;
}
// A session that ran on the model Codeman runs on this Mac is rebuilt only while that
// model can be started on: its own runtime is up and its digest is the one stored at
// install time. Asked before anything is built, like the two session routes; the
// session's own launch guard would refuse the start too, but only after the session
// exists. Every other endpoint, and a session without one, is answered `undefined`.
const savedModel = (entry.state as { __customModel?: { endpointId?: string; modelId?: string } }).__customModel;
if (savedModel && typeof savedModel.endpointId === 'string' && typeof savedModel.modelId === 'string') {
const refusal = await getLocalModelService().launchRefusalMessage(savedModel.endpointId, savedModel.modelId);
if (refusal) {
console.warn(`[reboot-restore] ${entry.sessionId} is not rebuilt: ${refusal}`);
// Left on offer: the model can be started (or installed again) and the click repeated.
failures.push({ sessionId: entry.sessionId, reason: 'local-model-not-ready' });
continue;
}
}
try {
const saved = entry.state;
const claudeModeConfig = await ctx.getClaudeModeConfig();
+11
View File
@@ -82,6 +82,7 @@ import {
CustomModelSelectionSchema,
} from '../schemas.js';
import { readCustomModelHosts, resolveCustomModelContextLength } from '../../custom-model-hosts.js';
import { getLocalModelService } from '../../local-model/install-job.js';
import { applyCustomModelInjection, removeConfigDir } from '../../custom-model-injection-apply.js';
import { buildCustomModelInjection } from '../../custom-model-injection.js';
import {
@@ -1783,6 +1784,11 @@ export function registerSessionRoutes(
if (!endpoint) {
return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
}
// The model Codeman runs on this Mac: only while its own runtime is up, and only the model
// that was installed, with the digest stored then (undefined for every other endpoint).
// Before anything is written or restarted.
const localModelRefusal = await getLocalModelService().launchRefusalMessage(endpoint.id, body.modelId);
if (localModelRefusal) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, localModelRefusal);
// Discovery's per-model figure wins; the endpoint's user-set default covers models
// whose size discovery could not determine (a gateway that states none, say). With
// neither, the existing "no override, CLI assumes its own default" behaviour stands.
@@ -4772,6 +4778,11 @@ export function registerSessionRoutes(
const cmHosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
const cmEndpoint = cmHosts.find((h) => h.id === customModel.endpointId);
if (!cmEndpoint) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
// See the dedicated route: the model Codeman runs on this Mac is launched only while its
// own runtime is up and its digest is the one stored at install time. Before any
// confirmation is asked for and before a session exists.
const cmLocalModelRefusal = await getLocalModelService().launchRefusalMessage(cmEndpoint.id, customModel.modelId);
if (cmLocalModelRefusal) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, cmLocalModelRefusal);
// Per-model discovery figure first, user-set endpoint default second, nothing third
// (see the dedicated route's own comment above).
const cmContextLength = resolveCustomModelContextLength(cmEndpoint, customModel.modelId);