mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-16 03:09:33 +01:00
POST /api/local-model/install, cancel, resume and runtime, and DELETE /api/local-model. The GET gains an `install` object the window polls. All of it is experimental and admin only in multi-user mode. One job of five steps (runtime, model, verify, agent, connect) driven by a pure reducer over explicit state, step and transition tables. One job at a time (409). The consent is bound to the size shown: `acknowledgedBytes` must be the server's own total (409 size-changed). A job a server restart interrupted comes back paused and never continues without a click. Every failure is a code with one next step. The model is judged against the budget the runtime measured before it is downloaded. A missing coding agent is installed with its stock command through the shared runner, audited. Connect writes one endpoint record under the reserved id through mutateCustomModelHosts() and switches customModelEndpointsEnabled on through mutateSettingsFile(), remembering the flag's value. The model's digest is stored and read again at boot and before every session start on that endpoint; a changed model refuses the launch. Remove answers 409 with the session names while a live session uses the endpoint, undoes the two writes first, restores the flag only when this feature switched it on and no other endpoint is saved, and deletes only inside local-model/. The coding agent stays. The server starts the runtime at boot when a model is installed and stops it at shutdown beside stopDeepSeekWeb(). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
242 lines
11 KiB
TypeScript
242 lines
11 KiB
TypeScript
/**
|
|
* @fileoverview Connecting the installed local model to Codeman, and undoing it: the endpoint
|
|
* record, the settings flag, and the checks around them.
|
|
*
|
|
* These are the ONLY two writes of the local model outside its own folder:
|
|
* 1. One record in `custom-model-hosts.json`, through `mutateCustomModelHosts()`:
|
|
* `{ id: 'local-ollama', label: 'This Mac', baseUrl: 'http://127.0.0.1:<port>',
|
|
* authStyle: 'bearer', models: [<id as /v1/models lists it>], defaultModelId,
|
|
* defaultContextLength: <the chosen context> }`, validated by `CustomModelHostSchema`
|
|
* before it is written. No `apiKey`. `defaultContextLength` is what reaches the coding
|
|
* agent as its context limit, because the runtime's model listing states none.
|
|
* 2. `customModelEndpointsEnabled: true` in `settings.json`, through `mutateSettingsFile()`.
|
|
* The value it had before is returned and kept in the state file.
|
|
*
|
|
* Rules:
|
|
* - The id is reserved. A record with it that this feature did not write is never
|
|
* overwritten: the connect step fails with `endpoint-id-taken`.
|
|
* - Both writes are idempotent, so a resumed job writes them again.
|
|
* - Undoing removes our record, and switches the flag off again only when this feature
|
|
* switched it on AND no other endpoint is saved.
|
|
* - The model's digest is compared again before a session starts and at boot
|
|
* (`compareModelDigest()`): a model that changed under the same name is not launched.
|
|
* - The record is MANAGED while the state file records it as ours (`isManagedLocalEndpoint()`):
|
|
* the endpoint routes then refuse to edit or delete it and the discovery sweep leaves it
|
|
* alone, so its `models` stays the one model the install job checked.
|
|
*/
|
|
|
|
import { mutateCustomModelHosts } from '../custom-model-hosts-writer.js';
|
|
import type { CustomModelHost } from '../custom-model-hosts.js';
|
|
import { getErrorMessage, type LocalModelErrorCode } from '../types.js';
|
|
import { CustomModelHostSchema } from '../web/schemas.js';
|
|
import { mutateSettingsFile } from '../web/settings-writer.js';
|
|
import { readLocalModelState } from './state-store.js';
|
|
|
|
/** The key of the settings flag that shows saved endpoints in the Run menu and runs the discovery sweep. */
|
|
const ENDPOINTS_FLAG = 'customModelEndpointsEnabled';
|
|
|
|
/** The id of the endpoint record this feature writes. Reserved: nobody else may use it. */
|
|
export const LOCAL_MODEL_ENDPOINT_ID = 'local-ollama';
|
|
/** The label of that record, what the Run menu shows in brackets. */
|
|
export const LOCAL_MODEL_ENDPOINT_LABEL = 'This Mac';
|
|
|
|
/** What the endpoint record is built from. */
|
|
export interface LocalEndpointInput {
|
|
/** The runtime's loopback port. */
|
|
port: number;
|
|
/** The model id exactly as the runtime's `/v1/models` lists it. */
|
|
modelId: string;
|
|
/** The chosen context length in tokens. */
|
|
context: number;
|
|
}
|
|
|
|
/** The endpoint record of the file header. Pure; the caller validates it with `CustomModelHostSchema`. */
|
|
export function buildLocalEndpointRecord(input: LocalEndpointInput): CustomModelHost {
|
|
return {
|
|
id: LOCAL_MODEL_ENDPOINT_ID,
|
|
label: LOCAL_MODEL_ENDPOINT_LABEL,
|
|
baseUrl: `http://127.0.0.1:${input.port}`,
|
|
authStyle: 'bearer',
|
|
models: [input.modelId],
|
|
defaultModelId: input.modelId,
|
|
defaultContextLength: input.context,
|
|
};
|
|
}
|
|
|
|
export interface ConnectLocalModelInput extends LocalEndpointInput {
|
|
/**
|
|
* True when the state file already records a connection of ours: an existing record with
|
|
* our id is then ours and is replaced. False: such a record is somebody else's.
|
|
*/
|
|
ours: boolean;
|
|
/**
|
|
* The flag's value before this feature first switched it on, when the state file already
|
|
* holds one. It is handed back unchanged, so a second connect cannot overwrite it with `true`.
|
|
*/
|
|
flagWasEnabled?: boolean;
|
|
}
|
|
|
|
/** How the connect step ended. */
|
|
export type ConnectResult =
|
|
| {
|
|
ok: true;
|
|
/** The value `customModelEndpointsEnabled` had before this feature switched it on. */
|
|
flagWasEnabled: boolean;
|
|
}
|
|
| { ok: false; code: Extract<LocalModelErrorCode, 'endpoint-id-taken' | 'connect-failed'>; detail?: string };
|
|
|
|
/**
|
|
* Writes the record and the flag. Idempotent. Never throws: a refused write is `connect-failed`
|
|
* with its message as `detail`.
|
|
*
|
|
* The record goes first, with the "is the id free" check in the same serialized step as the
|
|
* write, so a record that is somebody else's is found before anything is changed. Should the
|
|
* flag then fail to save, a record this call ADDED is taken out again: the pair is never left
|
|
* half done, and a later attempt starts from the same place.
|
|
*/
|
|
export async function connectLocalModel(input: ConnectLocalModelInput): Promise<ConnectResult> {
|
|
const parsed = CustomModelHostSchema.safeParse(buildLocalEndpointRecord(input));
|
|
if (!parsed.success) {
|
|
return { ok: false, code: 'connect-failed', detail: `The endpoint record is not valid: ${parsed.error.message}` };
|
|
}
|
|
const record: CustomModelHost = parsed.data;
|
|
|
|
let outcome: 'added' | 'replaced' | 'taken';
|
|
try {
|
|
outcome = await mutateCustomModelHosts<'added' | 'replaced' | 'taken'>((hosts) => {
|
|
const index = hosts.findIndex((host) => host.id === record.id);
|
|
if (index === -1) return { hosts: [...hosts, record], result: 'added' };
|
|
if (!input.ours) return { result: 'taken' };
|
|
const next = [...hosts];
|
|
next[index] = record;
|
|
return { hosts: next, result: 'replaced' };
|
|
});
|
|
} catch (err) {
|
|
return { ok: false, code: 'connect-failed', detail: getErrorMessage(err) };
|
|
}
|
|
if (outcome === 'taken') return { ok: false, code: 'endpoint-id-taken' };
|
|
|
|
let flagBefore: boolean;
|
|
try {
|
|
const { before } = await mutateSettingsFile((current) =>
|
|
current[ENDPOINTS_FLAG] === true ? undefined : { ...current, [ENDPOINTS_FLAG]: true }
|
|
);
|
|
flagBefore = before[ENDPOINTS_FLAG] === true;
|
|
} catch (err) {
|
|
if (outcome === 'added') await removeLocalEndpoint().catch(() => {});
|
|
return { ok: false, code: 'connect-failed', detail: getErrorMessage(err) };
|
|
}
|
|
return { ok: true, flagWasEnabled: input.flagWasEnabled ?? flagBefore };
|
|
}
|
|
|
|
/**
|
|
* Puts our record back when it is gone, and does nothing when a record with our id exists
|
|
* (it is never replaced here). For the start of the server while a model is installed: a
|
|
* config-backup restore can bring back an older endpoint store without our record while the
|
|
* model, the runtime and the state file stay. The settings flag is NOT touched: a person who
|
|
* switched it off meant to. Resolves true when the record was added. Never throws.
|
|
*/
|
|
export async function ensureLocalEndpoint(input: LocalEndpointInput): Promise<boolean> {
|
|
const parsed = CustomModelHostSchema.safeParse(buildLocalEndpointRecord(input));
|
|
if (!parsed.success) return false;
|
|
const record: CustomModelHost = parsed.data;
|
|
try {
|
|
return await mutateCustomModelHosts<boolean>((hosts) =>
|
|
hosts.some((host) => host.id === record.id) ? { result: false } : { hosts: [...hosts, record], result: true }
|
|
);
|
|
} catch {
|
|
// A store that must not be overwritten stays as it is; a session start then says what is wrong.
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/** Takes our record out of the store. Resolves with how many OTHER endpoints are saved. */
|
|
async function removeLocalEndpoint(): Promise<number> {
|
|
return mutateCustomModelHosts<number>((hosts) => {
|
|
const others = hosts.filter((host) => host.id !== LOCAL_MODEL_ENDPOINT_ID);
|
|
return others.length === hosts.length ? { result: others.length } : { hosts: others, result: others.length };
|
|
});
|
|
}
|
|
|
|
/** Moves our record to another port (the answer to "Use another port" once connected). A missing record is not an error. */
|
|
export async function moveLocalEndpoint(port: number): Promise<void> {
|
|
await mutateCustomModelHosts<void>((hosts) => {
|
|
const index = hosts.findIndex((host) => host.id === LOCAL_MODEL_ENDPOINT_ID);
|
|
if (index === -1) return { result: undefined };
|
|
const next = [...hosts];
|
|
next[index] = { ...next[index], baseUrl: `http://127.0.0.1:${port}` };
|
|
return { hosts: next, result: undefined };
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Removes our record, and restores the settings flag when this feature switched it on
|
|
* (`flagWasEnabled` is false) and no other endpoint is left. Idempotent.
|
|
*/
|
|
export async function disconnectLocalModel(input: { flagWasEnabled: boolean }): Promise<void> {
|
|
const othersLeft = await removeLocalEndpoint();
|
|
if (input.flagWasEnabled || othersLeft > 0) return;
|
|
await mutateSettingsFile((current) =>
|
|
current[ENDPOINTS_FLAG] === true ? { ...current, [ENDPOINTS_FLAG]: false } : undefined
|
|
);
|
|
}
|
|
|
|
/** Whether `id` is the reserved endpoint id. For the endpoint routes and the discovery sweep, which leave that record alone. */
|
|
export function isLocalModelEndpointId(id: string): boolean {
|
|
return id === LOCAL_MODEL_ENDPOINT_ID;
|
|
}
|
|
|
|
/**
|
|
* Whether the saved endpoint `id` is the record THIS feature wrote and still owns: the id is
|
|
* the reserved one and the state file records a connection under it. A record with the
|
|
* reserved id that somebody made by hand (before this feature, or while nothing is installed)
|
|
* is not managed, so its owner can still edit and delete it. Never throws.
|
|
*/
|
|
export async function isManagedLocalEndpoint(id: string): Promise<boolean> {
|
|
if (!isLocalModelEndpointId(id)) return false;
|
|
const state = await readLocalModelState();
|
|
return state.connection?.endpointId === id;
|
|
}
|
|
|
|
/**
|
|
* The names of the live sessions that use the endpoint `endpointId`, in the order given.
|
|
* Pure. What `DELETE /api/local-model` answers its 409 with.
|
|
*/
|
|
export function sessionNamesUsingEndpoint(
|
|
sessions: Iterable<{ name: string; customModel?: { endpointId: string } }>,
|
|
endpointId: string = LOCAL_MODEL_ENDPOINT_ID
|
|
): string[] {
|
|
const names: string[] = [];
|
|
for (const session of sessions) {
|
|
if (session.customModel?.endpointId === endpointId) names.push(session.name);
|
|
}
|
|
return names;
|
|
}
|
|
|
|
/**
|
|
* Compares the digest stored at install time with the one the runtime reports now. Pure.
|
|
* - `same`: launch.
|
|
* - `changed`: refuse (`model-changed`): the name now stands for other weights or another template.
|
|
* - `unknown`: one of the two is absent (the runtime does not answer, the model is gone).
|
|
* The caller refuses as well, with the reason it knows.
|
|
*/
|
|
export function compareModelDigest(
|
|
stored: string | undefined,
|
|
current: string | undefined
|
|
): 'same' | 'changed' | 'unknown' {
|
|
const a = normalizeDigest(stored);
|
|
const b = normalizeDigest(current);
|
|
if (!a || !b) return 'unknown';
|
|
return a === b ? 'same' : 'changed';
|
|
}
|
|
|
|
/** A digest as it is compared: lowercase hex, without the `sha256:` some listings put in front. */
|
|
function normalizeDigest(digest: string | undefined): string | undefined {
|
|
if (typeof digest !== 'string') return undefined;
|
|
const hex = digest
|
|
.trim()
|
|
.toLowerCase()
|
|
.replace(/^sha256:/, '');
|
|
return hex === '' ? undefined : hex;
|
|
}
|