Files
Codeman/src/local-model/connect.ts
T

241 lines
11 KiB
TypeScript
Raw Normal View History

/**
* @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;
}