Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/**
* Der Zustand des lokalen Modell-Sidecars, und was die Oberflaeche darueber
* sagen darf.
*
* Der Sidecar ist ein eigener Prozess: llama-server aus vendor/llama, gestartet
* ueber llm/start.sh, gebunden an 127.0.0.1:4141. Diese Datei startet nichts und
* kann nichts starten. Sie fragt und sie deutet, und das ist die ganze
* Architektur-Grenze aus ADR 0001: eine SPA ohne eigenes Backend darf keinen
* Prozess versprechen, den sie nicht anfassen kann.
*
* Drei Entscheidungen, die man sonst raten muesste:
*
* 1. **Aus heisst aus, nicht "leise".** Solange die Praeferenz aus ist oder eine
* Policy das LLM verbietet, faellt kein einziger fetch Richtung 4141. Kein
* Aufwaerm-Ping, keine "gibt es dich"-Probe beim Laden. Der Beweislauf misst
* genau diese Null am Netz-Mitschnitt, und ein einzelner Ping waere der
* Unterschied zwischen einem Opt-out und einem Schalter, der nur die Anzeige
* umfaerbt.
* 2. **Kein Prozess ist kein Fehler.** `not-running` ist der Normalfall nach dem
* Einschalten, nicht ein Ausfall: der Leser hat das Skript noch nicht
* gefahren. Die Oberflaeche nennt deshalb den konkreten Aufruf, statt eine
* rote Meldung zu zeigen, die nach einem Defekt aussieht.
* 3. **Die Zahlen kommen aus dem laufenden Prozess, nicht aus einer Tabelle.**
* Modell, Quantisierung, Kontext und Slots stehen in `/props`; die Groesse
* der geladenen Gewichte steht dort NICHT und wird darum aus `/v1/models`
* (`meta.size`) geholt und als "weights" benannt, nicht als
* Prozessspeicher. Eine im Code gepflegte Modellgroessen-Tabelle waere eine
* zweite Wahrheit neben dem Prozess, der die Datei wirklich geladen hat.
*
* ## Zwei Betriebsarten, und woran man sie unterscheidet (W10)
*
* llama-server kann als ROUTER ueber ein Cache-Verzeichnis laufen
* (`--models-dir`) statt mit einer festen Datei (`-m`). Nur im Router-Modus
* waehlt das Feld `model` einer Chat-Anfrage wirklich aus; ein Einzel-Server
* ignoriert ein fremdes `model` STILLSCHWEIGEND und antwortet mit dem Modell,
* das er ohnehin geladen hat (gemessen am 2026-08-29 an vendor/llama, Version
* 0.3.0-dev, build b1-90c26fc: die Anfrage mit `"model":"SomeOtherModel"` kam
* mit `"model":"models/MiniCPM5-1B-Q4_K_M.gguf"` und einem normalen Text
* zurueck, ohne Fehler und ohne Warnung).
*
* Genau darum wird die Betriebsart gelesen und nicht angenommen: eine Auswahl
* anzubieten, die stillschweigend nichts tut, waere die teuerste Sorte von
* Bedienelement. Das Merkmal ist `props.role === 'router'`; im Einzel-Modus
* fehlt das Feld ganz.
*
* Im Router-Modus sind die Zahlen in `/props` NICHT die des Modells: dort steht
* `model_path: "none"` und `n_ctx: 0`, weil der Router selbst keins geladen hat.
* Die Zahlen einer Instanz stehen in `/props?model=<id>`, und genau die werden
* dann geholt. Ohne diesen zweiten Weg wuerde die Statusleiste "ready: none"
* behaupten, waehrend ein Modell antwortet.
*/
/** Der Port des Sidecars. Fest, weil llm/start.sh ihn fest bindet. */
export const SIDECAR_PORT = 4141;
/** Der Ursprung, gegen den gefragt wird. Loopback und nichts sonst. */
export const SIDECAR_ORIGIN = `http://127.0.0.1:${SIDECAR_PORT}`;
/**
* Der Abstand zwischen zwei Proben, solange das LLM an ist.
*
* Drei Sekunden sind der Kompromiss aus zwei Groessen, die beide gemessen sind:
* ein 4B-Modell braucht auf dieser Maschine rund vier Sekunden bis
* `{"status":"ok"}`, und ein Leser, der eben `llm/start.sh` getippt hat, soll
* die Umschaltung sehen, ohne auf die Anzeige zu warten. Haeufiger zu fragen
* kostet einen Prozess, der ohnehin gerade ein Modell laedt, nur Aufmerksamkeit.
*/
export const SIDECAR_POLL_MS = 3000;
/**
* Die fuenf Lagen, in denen der Sidecar sein kann.
*
* `off` und `disabled-by-policy` sehen im Ergebnis gleich aus und sind es
* nicht: das erste ist die Entscheidung des Lesers und mit einem Klick
* umkehrbar, das zweite ist die Entscheidung des Projekts und mit keinem.
*/
export type SidecarState = 'off' | 'disabled-by-policy' | 'not-running' | 'starting' | 'ready';
/** Was ueber einen laufenden Sidecar bekannt ist. Alles davon kommt aus ihm selbst. */
export interface SidecarFacts {
/** Der Anzeigename, aus dem Dateinamen gekuerzt. Zum Beispiel `Qwen3.5-2B`. */
model: string;
/** Der Pfad, den der Prozess selbst nennt. Ungekuerzt. */
modelPath: string;
/** `Q4_K - Medium`, so wie der Prozess es schreibt. Leer, wenn er nichts sagt. */
quantization: string;
/** Das Kontextfenster dieses Laufs, in Token. */
contextTokens?: number;
/** Wofuer das Modell trainiert wurde, in Token. Nur zum Vergleich. */
trainedContextTokens?: number;
/** Wie viele Anfragen der Prozess parallel bedienen kann. */
slots?: number;
/** Die geladenen Gewichte in Byte, aus `/v1/models`. */
weightsBytes?: number;
/** Die Parameterzahl, aus `/v1/models`. */
parameters?: number;
}
/**
* Ein Modell, das der Prozess in seinem Cache-Verzeichnis fuehrt.
*
* Was hier steht, kommt aus `/v1/models` und aus nichts sonst. `meta` liefert
* der Server NUR fuer geladene Instanzen, also bleiben die Zahlen bei einem
* ungeladenen Modell leer. Sie aus dem Dateinamen zu schaetzen waere eine
* Angabe ueber eine Datei, die niemand geoeffnet hat.
*/
export interface CacheModel {
/** Die Kennung, mit der eine Anfrage dieses Modell waehlt. */
id: string;
/** Der Anzeigename, aus der Kennung gekuerzt. */
name: string;
/** Ob gerade eine Instanz davon laeuft. */
loaded: boolean;
/** Was der Prozess ueber die Lage sagt (`loaded`, `unloaded`). Leer, wenn nichts. */
status: string;
/** Die Datei in Byte. Nur bei geladenen Instanzen. */
weightsBytes?: number;
/** Die Parameterzahl. Nur bei geladenen Instanzen. */
parameters?: number;
/** Wofuer trainiert wurde, in Token. Nur bei geladenen Instanzen. */
trainedContextTokens?: number;
/** Das Kontextfenster dieser Instanz. Nur bei geladenen Instanzen. */
contextTokens?: number;
/** Die Quantisierung, so wie der Prozess sie schreibt. */
quantization?: string;
}
/** Eine Probe: die Lage plus, wenn es eine gibt, die Auskunft des Prozesses. */
export interface SidecarReading {
state: SidecarState;
facts?: SidecarFacts;
/**
* Ob der Prozess als Router ueber ein Cache-Verzeichnis laeuft.
*
* Die eine Angabe, an der haengt, ob eine Modellauswahl ueberhaupt wirkt.
* Siehe den Kopf dieser Datei.
*/
router: boolean;
/** Was `/v1/models` gelistet hat. Leer, solange niemand geantwortet hat. */
models: CacheModel[];
/** Was schiefging, wenn etwas schiefging. Leer im Normalfall. */
detail: string;
}
/** Nur das, was diese Datei von `fetch` braucht, damit ein Test es ersetzen kann. */
export type FetchLike = (input: string, init?: { signal?: AbortSignal }) => Promise<Response>;
/** Was der Aufrufer der Probe mitgeben kann. */
export interface ProbeOptions {
/**
* Die Modellwahl des Lesers, wenn er eine getroffen hat.
*
* Sie wirkt NUR im Router-Modus, und zwar an genau zwei Stellen: die Karte
* zeigt dann die Zahlen dieses Modells, und die Statusleiste nennt seinen
* Namen. Ob eine Chat-Anfrage sie mitschickt, entscheidet der Aufrufer und
* nicht diese Datei.
*/
model?: string;
}
// ------------------------------------------------------------------ Namen ---
/**
* Der Anzeigename eines Modells, aus seinem Dateinamen.
*
* `models/Qwen3.5-2B-Q4_K_M.gguf` wird zu `Qwen3.5-2B`. Gekuerzt wird nur, was
* nachweislich die Quantisierung benennt; alles andere bleibt stehen. Ein
* Kuerzungsversuch, der raet, wuerde aus einem Modellnamen frueher oder spaeter
* einen anderen machen, und der Name ist das, was der Leser gegen das ADR haelt.
*/
export function modelDisplayName(modelPath: string): string {
const base = modelPath.split('/').pop() ?? modelPath;
const withoutExtension = base.replace(/\.gguf$/i, '');
const withoutQuant = withoutExtension.replace(/[-_.](?:Q\d+_[A-Z0-9_]+|F16|F32|BF16)$/i, '');
return withoutQuant.length > 0 ? withoutQuant : base;
}
/** Byte in eine Zeile, die ein Mensch liest. Basis 1024, wie jeder Modell-Downloader. */
export function humanBytes(bytes: number): string {
if (!Number.isFinite(bytes) || bytes <= 0) {
return '';
}
const units = ['B', 'KB', 'MB', 'GB', 'TB'];
let value = bytes;
let unit = 0;
while (value >= 1024 && unit < units.length - 1) {
value /= 1024;
unit += 1;
}
return `${value >= 10 || unit === 0 ? Math.round(value) : value.toFixed(2)} ${units[unit]}`;
}
// -------------------------------------------------------------- Die Probe ---
function asRecord(value: unknown): Record<string, unknown> {
return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
}
function asNumber(value: unknown): number | undefined {
return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
}
function asString(value: unknown): string {
return typeof value === 'string' ? value : '';
}
/**
* Die Auskunft von `/props` lesen.
*
* Der Prozess antwortet mit weit mehr, als hier gebraucht wird (unter anderem
* dem ganzen Chat-Template). Gelesen wird nur, was die Oberflaeche zeigt, und
* jedes Feld einzeln: eine Antwort, der ein Feld fehlt, ist kein Grund, die
* anderen wegzuwerfen.
*/
export function readProps(payload: unknown): SidecarFacts {
const props = asRecord(payload);
const modelPath = asString(props['model_path']) || asString(props['model_alias']);
const settings = asRecord(props['default_generation_settings']);
const facts: SidecarFacts = {
model: modelDisplayName(modelPath),
modelPath,
quantization: asString(props['model_ftype']),
};
const contextTokens = asNumber(settings['n_ctx']);
if (contextTokens !== undefined) {
facts.contextTokens = contextTokens;
}
const slots = asNumber(props['total_slots']);
if (slots !== undefined) {
facts.slots = slots;
}
return facts;
}
/**
* Die Betriebsart aus `/props` lesen.
*
* Genau ein Feld, und die Abwesenheit ist die Auskunft: ein Einzel-Server
* schreibt `role` nicht. Siehe den Kopf dieser Datei.
*/
export function readsAsRouter(payload: unknown): boolean {
return asString(asRecord(payload)['role']) === 'router';
}
/**
* Die Liste aus `/v1/models`.
*
* Der Server antwortet im Router-Modus mit einem Eintrag je Datei des
* Cache-Verzeichnisses und im Einzel-Modus mit genau einem Eintrag, dessen `id`
* der Modellpfad ist. Beide Formen werden gleich gelesen: eine Liste mit einem
* Eintrag ist eine Liste.
*/
export function readModelList(payload: unknown): CacheModel[] {
const data = asRecord(payload)['data'];
if (!Array.isArray(data)) {
return [];
}
const out: CacheModel[] = [];
for (const entry of data) {
const record = asRecord(entry);
const id = asString(record['id']);
if (id.length === 0) {
continue;
}
const status = asRecord(record['status']);
const stateWord = asString(status['value']);
const meta = asRecord(record['meta']);
const model: CacheModel = {
id,
name: modelDisplayName(id),
// Ein Eintrag ohne `status` kommt aus dem Einzel-Modus, wo genau
// dieses eine Modell geladen IST. Ein `meta` gibt es nur fuer
// geladene Instanzen, also ist es hier das ehrlichere Merkmal.
loaded: stateWord.length > 0 ? stateWord === 'loaded' : Object.keys(meta).length > 0,
status: stateWord,
};
const size = asNumber(meta['size']);
if (size !== undefined) {
model.weightsBytes = size;
}
const params = asNumber(meta['n_params']);
if (params !== undefined) {
model.parameters = params;
}
const trained = asNumber(meta['n_ctx_train']);
if (trained !== undefined) {
model.trainedContextTokens = trained;
}
const context = asNumber(meta['n_ctx']);
if (context !== undefined) {
model.contextTokens = context;
}
const ftype = asString(meta['ftype']);
if (ftype.length > 0) {
model.quantization = ftype;
}
out.push(model);
}
return out;
}
/**
* Welches Modell die Karte zeigt, wenn der Router mehrere fuehrt.
*
* Die Wahl des Lesers, wenn sie noch in der Liste steht; sonst das Modell, das
* gerade geladen ist; sonst das erste. Der mittlere Fall ist der wichtige: er
* ist die Lage nach einem Neustart des Sidecars, in der die gespeicherte Wahl
* auf eine Datei zeigt, die aus dem Verzeichnis verschwunden ist. Eine Karte
* mit den Zahlen eines Modells, das es nicht mehr gibt, waere schlimmer als
* eine Karte mit denen des laufenden.
*/
export function activeModelOf(models: readonly CacheModel[], selected: string): CacheModel | undefined {
if (models.length === 0) {
return undefined;
}
return models.find((model) => model.id === selected)
?? models.find((model) => model.loaded)
?? models[0];
}
/**
* Die Groessenangaben aus `/v1/models` dazulegen.
*
* Ein zweites Werkzeug fuer zwei Zahlen, und das ist kein Versehen: `/props`
* fuehrt keine Speicherangabe. Die Alternative waere, die Dateigroesse aus einer
* Tabelle im Quelltext zu nehmen, und die stuende neben einem Prozess, der die
* Datei wirklich geladen hat. Schlaegt die Abfrage fehl, bleiben die beiden
* Felder leer und der Rest der Karte steht trotzdem.
*/
export function readModelMeta(payload: unknown): { weightsBytes?: number; parameters?: number; trainedContextTokens?: number } {
const data = asRecord(payload)['data'];
const first = Array.isArray(data) ? asRecord(data[0]) : {};
const meta = asRecord(first['meta']);
const out: { weightsBytes?: number; parameters?: number; trainedContextTokens?: number } = {};
const size = asNumber(meta['size']);
if (size !== undefined) {
out.weightsBytes = size;
}
const params = asNumber(meta['n_params']);
if (params !== undefined) {
out.parameters = params;
}
const trained = asNumber(meta['n_ctx_train']);
if (trained !== undefined) {
out.trainedContextTokens = trained;
}
return out;
}
/**
* Einmal fragen, wie es dem Sidecar geht.
*
* Der Weg ist genau der, den der Prozess anbietet: `/health` antwortet mit 200
* und `{"status":"ok"}`, sobald das Modell geladen ist, und waehrend des Ladens
* mit 503 und `Loading model` (beides an llama-server b10675 gemessen,
* verification/w5/sidecar.json). Eine abgelehnte Verbindung ist kein Fehler,
* sondern die Auskunft "da laeuft nichts".
*
* Diese Funktion wird NUR gerufen, wenn das LLM an ist. Der Aufrufer entscheidet
* das; hier steht keine Praeferenz und keine Policy, damit es genau eine Stelle
* gibt, an der ueber das Fragen entschieden wird.
*/
export async function probeSidecar(
fetchImpl: FetchLike,
origin = SIDECAR_ORIGIN,
options: ProbeOptions = {},
): Promise<SidecarReading> {
let health: Response;
try {
health = await fetchImpl(`${origin}/health`);
} catch (error) {
// Kein Prozess, kein Port, keine Antwort. Der erwartete Fall nach dem
// Einschalten und kein Grund fuer eine Fehlerfarbe.
return {
state: 'not-running',
router: false,
models: [],
detail: error instanceof Error ? error.message : String(error),
};
}
if (health.status === 503) {
return { state: 'starting', router: false, models: [], detail: '' };
}
if (!health.ok) {
return {
state: 'not-running',
router: false,
models: [],
detail: `GET /health antwortete mit ${health.status}`,
};
}
let facts: SidecarFacts;
let router: boolean;
try {
const props = await fetchImpl(`${origin}/props`);
if (!props.ok) {
throw new Error(`GET /props antwortete mit ${props.status}`);
}
const payload = await props.json();
router = readsAsRouter(payload);
facts = readProps(payload);
} catch (error) {
// Der Prozess lebt, sagt aber nicht, was er geladen hat. `ready` ohne
// Karte ist die ehrliche Lage; ein erfundener Modellname waere die
// teuerste Zeile dieses Panels.
return {
state: 'ready',
router: false,
models: [],
detail: `die Auskunft ueber das Modell war nicht lesbar: ${error instanceof Error ? error.message : String(error)}`,
};
}
let models: CacheModel[] = [];
try {
const payload = await (await fetchImpl(`${origin}/v1/models`)).json();
models = readModelList(payload);
if (!router) {
facts = { ...facts, ...readModelMeta(payload) };
}
} catch {
// Die Groessen fehlen dann, der Rest der Karte steht. Ein Panel, das
// wegen einer fehlenden Zahl gar nichts sagt, waere die schlechtere
// Antwort.
}
if (!router) {
return { state: 'ready', facts, router, models, detail: '' };
}
/*
* Im Router-Modus stehen die Zahlen einer Instanz und nicht die des
* Routers. `/props` hat gerade `model_path: "none"` und `n_ctx: 0` gemeldet;
* das ist die Wahrheit ueber den Router und eine Unwahrheit ueber das
* Modell, das antwortet. Es wird darum ein zweites Mal gefragt, mit der id
* daneben.
*/
const active = activeModelOf(models, options.model ?? '');
if (active === undefined) {
return {
state: 'ready',
router,
models,
detail: 'der Router fuehrt kein Modell in seinem Cache-Verzeichnis.',
};
}
try {
const scoped = await fetchImpl(`${origin}/props?model=${encodeURIComponent(active.id)}`);
if (!scoped.ok) {
throw new Error(`GET /props?model= antwortete mit ${scoped.status}`);
}
facts = readProps(await scoped.json());
} catch (error) {
/*
* Ein ungeladenes Modell hat noch keine Zahlen, und ein Router, der die
* id nicht kennt, antwortet mit 400. Beides ist kein Ausfall: der Name
* aus der Liste steht, die Zahlen fehlen, und der Grund steht daneben.
*/
facts = { model: active.name, modelPath: active.id, quantization: active.quantization ?? '' };
}
const listed = models.find((model) => model.id === active.id);
if (listed !== undefined) {
facts = {
...facts,
...(listed.weightsBytes === undefined ? {} : { weightsBytes: listed.weightsBytes }),
...(listed.parameters === undefined ? {} : { parameters: listed.parameters }),
...(listed.trainedContextTokens === undefined
? {}
: { trainedContextTokens: listed.trainedContextTokens }),
};
}
return { state: 'ready', facts, router, models, detail: '' };
}