talos-code 0.0.1 → 0.2.0

package/vendor/harness-ui/src/local-runtime-llama-server.mjs

@@ -0,0 +1,244 @@
+import { parseRuntimeEventEnvelope } from './local-runtime-events.mjs';
+import { createStreamPartitioner } from './stream-partition.mjs';
+
+export class LlamaServerRuntimeError extends Error {
+  constructor(message, code = 'RUNTIME_FAILED') {
+    super(message);
+    this.name = 'LlamaServerRuntimeError';
+    this.code = code;
+  }
+}
+
+function runtimeInvalid(message) {
+  return new LlamaServerRuntimeError(message, 'RUNTIME_INVALID');
+}
+
+function envelope({ runId, turnId, seq, type, runtimeId = 'llama.cpp', ...payload }, now) {
+  return parseRuntimeEventEnvelope({ runId, turnId, runtimeId, seq, at: now().toISOString(), type, ...payload });
+}
+
+async function readText(response) {
+  return typeof response.text === 'function' ? response.text() : '';
+}
+
+async function* sseEvents(response) {
+  if (!response.body || typeof response.body.getReader !== 'function') throw new LlamaServerRuntimeError('SSE body is missing', 'RUNTIME_SSE_INVALID');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let finished = false;
+  try {
+    while (!finished) {
+      const { value, done } = await reader.read();
+      buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done });
+      const lines = buffer.split(/\r?\n/u);
+      buffer = lines.pop() ?? '';
+      for (const line of lines) {
+        if (!line.startsWith('data:')) continue;
+        const data = line.slice(5).trim();
+        if (data === '') continue;
+        if (data === '[DONE]') { finished = true; break; }
+        try { yield JSON.parse(data); } catch { yield { __invalid: true }; }
+      }
+      if (done) break;
+    }
+    if (buffer.startsWith('data:')) {
+      const data = buffer.slice(5).trim();
+      if (data && data !== '[DONE]') {
+        try { yield JSON.parse(data); } catch { yield { __invalid: true }; }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+}
+
+export function createLlamaServerRuntime({ supervisor, fetchImpl = fetch, now = () => new Date() } = {}) {
+  if (!supervisor || typeof supervisor.status !== 'function') throw new LlamaServerRuntimeError('supervisor is required', 'RUNTIME_MISCONFIGURED');
+  const activeRequests = new Map();
+
+  function baseUrl() {
+    const status = supervisor.status();
+    if (!status.baseUrl || status.state !== 'ready') throw new LlamaServerRuntimeError('runtime is not ready', 'RUNTIME_NOT_READY');
+    return status.baseUrl;
+  }
+
+  async function jsonRequest(path) {
+    const response = typeof supervisor.request === 'function'
+      ? await supervisor.request(path, { headers: { Accept: 'application/json' } })
+      : await fetchImpl(`${baseUrl()}${path}`, { headers: { Accept: 'application/json' } });
+    if (!response.ok) throw new LlamaServerRuntimeError(`runtime returned HTTP ${response.status}`, 'RUNTIME_HTTP_ERROR');
+    try { return await response.json(); } catch { throw new LlamaServerRuntimeError('runtime returned invalid JSON', 'RUNTIME_RESPONSE_INVALID'); }
+  }
+
+  async function probe() {
+    return jsonRequest('/props');
+  }
+
+  /**
+   * L'id del modello effettivamente caricato adesso, o `null` se non c'è
+   * nessun runtime pronto.
+   *
+   * ⛔ 02/9 — serve a `inspectModel()` per NON attribuire l'`n_ctx` osservato
+   * a un modello diverso da quello che lo ha prodotto. Si legge dal
+   * supervisore (codice nostro, lo stesso valore che finisce in `--alias`) e
+   * non da un campo indovinato dentro `/props`: llama.cpp ne espone di
+   * simili, ma un nome di campo dedotto invece che verificato è già costato
+   * tre difetti su questo stesso sottosistema il 02/9.
+   */
+  function loadedModelId() {
+    try {
+      const stato = supervisor.status();
+      return stato?.state === 'ready' && typeof stato.modelId === 'string' && stato.modelId !== ''
+        ? stato.modelId
+        : null;
+    } catch { return null; }
+  }
+
+  async function listModels() {
+    const body = await jsonRequest('/v1/models');
+    if (!Array.isArray(body?.data)) throw new LlamaServerRuntimeError('runtime model list is invalid', 'RUNTIME_RESPONSE_INVALID');
+    return body.data;
+  }
+
+  /** ⛔ `options` viaggia intero, `contextLength` compreso: era qui che si perdeva. */
+  async function load(options) {
+    return supervisor.start(options);
+  }
+
+  async function unload() {
+    return supervisor.stop();
+  }
+
+  async function health() {
+    return supervisor.health();
+  }
+
+  async function metrics() {
+    const response = typeof supervisor.request === 'function'
+      ? await supervisor.request('/metrics', { headers: { Accept: 'text/plain' } })
+      : await fetchImpl(`${baseUrl()}/metrics`, { headers: { Accept: 'text/plain' } });
+    if (!response.ok) throw new LlamaServerRuntimeError(`runtime returned HTTP ${response.status}`, 'RUNTIME_HTTP_ERROR');
+    return readText(response);
+  }
+
+  async function* generateStream({ runId, turnId, modelId, messages, reasoning, reasoningFormat, parseToolCalls = false, maxTokens = 512, signal, requestId } = {}) {
+    if (typeof runId !== 'string' || runId.trim() === '' || typeof turnId !== 'string' || turnId.trim() === '' || typeof modelId !== 'string' || modelId.trim() === '' || !Array.isArray(messages)) throw runtimeInvalid('stream request is invalid');
+    const controller = new AbortController();
+    if (signal?.aborted) controller.abort(signal.reason);
+    const combinedSignal = signal && typeof AbortSignal.any === 'function' ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    if (signal && typeof AbortSignal.any !== 'function') signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    if (requestId) activeRequests.set(requestId, controller);
+    let response;
+    try {
+      combinedSignal.throwIfAborted();
+      const body = { model: modelId, messages, stream: true, max_tokens: Number.isInteger(maxTokens) && maxTokens > 0 ? maxTokens : 512 };
+      if (reasoning?.effort) body.reasoning_effort = reasoning.effort;
+      if (reasoningFormat) body.reasoning_format = reasoningFormat;
+      if (parseToolCalls) body.parse_tool_calls = true;
+      const requestOptions = {
+          method: 'POST',
+          headers: { Accept: 'text/event-stream', 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+          signal: combinedSignal,
+        };
+      response = typeof supervisor.request === 'function'
+        ? await supervisor.request('/v1/chat/completions', requestOptions)
+        : await fetchImpl(`${baseUrl()}/v1/chat/completions`, requestOptions);
+      if (!response.ok) throw new LlamaServerRuntimeError(`runtime returned HTTP ${response.status}: ${await readText(response)}`, 'RUNTIME_HTTP_ERROR');
+      let seq = 0;
+      const pendingTools = new Set();
+      const toolsByIndex = new Map();
+      const toolsById = new Map();
+      // A valid JSON prefix is not a completed call (e.g. "1" then "2").
+      // Join and validate once, at finish_reason or ordinary stream EOF.
+      // Aborted/failed readers never reach the final flush.
+      const flushNativeTools = function* () {
+        for (const tool of pendingTools) {
+          combinedSignal.throwIfAborted();
+          let event;
+          try {
+            event = envelope({ runId, turnId, seq, type: 'tool_call', id: tool.id,
+              name: tool.names.join(''), arguments: tool.arguments.join('') }, now);
+          } catch (error) {
+            if (error?.code !== 'LOCAL_RUNTIME_INVALID') throw error;
+            event = envelope({ runId, turnId, seq, type: 'error', code: 'TOOL_CALL_MALFORMED',
+              message: `malformed tool call ${tool.id}`, retryable: false }, now);
+          }
+          seq++;
+          yield event;
+        }
+        pendingTools.clear();
+        toolsByIndex.clear();
+        toolsById.clear();
+      };
+      let taggedEvents = [];
+      const taggedContent = createStreamPartitioner({
+        onText: (value) => taggedEvents.push({ type: 'text', value }),
+        onReasoning: (value) => taggedEvents.push({ type: 'reasoning', value }),
+        onToolCall: (value) => taggedEvents.push({ type: 'tool_call', ...value }),
+      });
+      const flushTaggedEvents = function* () {
+        const events = taggedEvents;
+        taggedEvents = [];
+        for (const event of events) {
+          if (event.type === 'tool_call') {
+            yield envelope({ runId, turnId, seq: seq++, type: 'tool_call', id: event.id || `tagged-tool-${seq}`, name: event.name, arguments: typeof event.arguments === 'string' ? event.arguments : JSON.stringify(event.arguments ?? {}) }, now);
+          } else {
+            yield envelope({ runId, turnId, seq: seq++, type: event.type, value: event.value }, now);
+          }
+        }
+      };
+      for await (const chunk of sseEvents(response)) {
+        combinedSignal.throwIfAborted();
+        if (chunk.__invalid) {
+          yield envelope({ runId, turnId, seq: seq++, type: 'error', code: 'RUNTIME_SSE_INVALID', message: 'runtime emitted malformed SSE JSON', retryable: false }, now);
+          continue;
+        }
+        const choice = chunk.choices?.[0];
+        const delta = choice?.delta;
+        if (!delta) {
+          if (choice?.finish_reason != null) yield* flushNativeTools();
+          continue;
+        }
+        const reasoningDelta = delta.reasoning_content ?? delta.reasoning;
+        if (typeof reasoningDelta === 'string' && reasoningDelta !== '') yield envelope({ runId, turnId, seq: seq++, type: 'reasoning', value: reasoningDelta }, now);
+        if (typeof delta.content === 'string' && delta.content !== '') {
+          taggedContent.push(delta.content);
+          yield* flushTaggedEvents();
+        }
+        for (const call of delta.tool_calls ?? []) {
+          // OpenAI-style deltas normally supply id/name only in the first
+          // fragment; index remains stable. Keep id-only legacy streams too.
+          const index = Number.isInteger(call.index) && call.index >= 0 ? call.index : null;
+          const hasId = call.id !== undefined && call.id !== null;
+          const tool = (index !== null ? toolsByIndex.get(index) : undefined)
+            ?? (hasId ? toolsById.get(call.id) : undefined)
+            ?? { id: call.id ?? String(index ?? pendingTools.size), names: [], arguments: [] };
+          pendingTools.add(tool);
+          if (index !== null) toolsByIndex.set(index, tool);
+          if (hasId) { tool.id = call.id; toolsById.set(call.id, tool); }
+          if (call.function?.name != null) tool.names.push(call.function.name);
+          if (call.function?.arguments != null) tool.arguments.push(call.function.arguments);
+        }
+        if (choice.finish_reason != null) yield* flushNativeTools();
+      }
+      combinedSignal.throwIfAborted();
+      taggedContent.finish();
+      yield* flushTaggedEvents();
+      yield* flushNativeTools();
+      yield envelope({ runId, turnId, seq: seq++, type: 'done' }, now);
+    } finally {
+      if (requestId) activeRequests.delete(requestId);
+    }
+  }
+
+  function cancel(requestId) {
+    const controller = activeRequests.get(requestId);
+    if (!controller) return false;
+    controller.abort();
+    return true;
+  }
+
+  return Object.freeze({ probe, loadedModelId, listModels, load, unload, generateStream, cancel, health, metrics });
+}

package/vendor/harness-ui/src/local-runtime-probe.mjs

@@ -0,0 +1,401 @@
+/**
+ * Unisce cartella e file del manifest. ⛔ Non usa `node:path.join`: i
+ * percorsi del manifest sono relativi e sempre con `/` (validati così da
+ * `local-model-store.mjs`), e su Windows `join` li riscriverebbe con `\`,
+ * cambiando una stringa che il chiamante potrebbe confrontare. Il
+ * chiamante ci antepone la radice assoluta con il join vero.
+ */
+function joinPosix(cartella, file) {
+  return `${String(cartella).replace(/[/\\]+$/u, '')}/${String(file).replace(/^[/\\]+/u, '')}`;
+}
+
+export class LocalRuntimeProbeError extends Error {
+  constructor(message, code = 'LOCAL_RUNTIME_PROBE_FAILED') {
+    super(message);
+    this.name = 'LocalRuntimeProbeError';
+    this.code = code;
+  }
+}
+
+const unknown = () => ({ state: 'unknown', value: null });
+const fact = (state, value) => ({ state, value });
+const positiveInteger = (value) => Number.isSafeInteger(value) && value > 0;
+
+function observedString(value) {
+  return typeof value === 'string' && value.trim() !== '' ? fact('observed', value) : unknown();
+}
+
+function observedBoolean(value) {
+  return typeof value === 'boolean' ? fact('observed', value) : unknown();
+}
+
+function validateHeader(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || value.magic !== 'GGUF' || value.version !== 3
+    || !positiveInteger(value.trainedContext)
+    || !positiveInteger(value.estimatedWorkingBytes)) {
+    throw new LocalRuntimeProbeError('GGUF header is invalid', 'MODEL_HEADER_INVALID');
+  }
+  return value;
+}
+
+function parseTokensPerSecond(value) {
+  if (typeof value !== 'string') return unknown();
+  for (const line of value.split(/\r?\n/u)) {
+    const match = line.match(/^llamacpp:predicted_tokens_seconds(?:\{[^}]*\})?\s+([^\s]+)$/u);
+    const number = match ? Number(match[1]) : NaN;
+    if (Number.isFinite(number) && number >= 0) return fact('observed', number);
+  }
+  return unknown();
+}
+
+export function createLocalRuntimeProbe({
+  runtime,
+  modelStore,
+  readHeader,
+  measureMachine,
+  now = () => new Date(),
+  clockMs = () => performance.now(),
+} = {}) {
+  if (!runtime || typeof runtime.probe !== 'function' || typeof runtime.generateStream !== 'function'
+    || !modelStore || typeof modelStore.inspect !== 'function'
+    || typeof readHeader !== 'function' || typeof measureMachine !== 'function') {
+    throw new LocalRuntimeProbeError('probe dependencies are invalid', 'LOCAL_RUNTIME_PROBE_MISCONFIGURED');
+  }
+
+  async function readRuntimeProps() {
+    try {
+      const props = await runtime.probe();
+      if (!props || typeof props !== 'object' || Array.isArray(props)) throw new Error('invalid response');
+      return props;
+    } catch (error) {
+      if (error instanceof LocalRuntimeProbeError) throw error;
+      throw new LocalRuntimeProbeError(`runtime probe failed: ${error?.message || 'unknown error'}`, 'RUNTIME_PROBE_FAILED');
+    }
+  }
+
+  /**
+   * @param {string} modelId
+   * @param {{contextTokens?: number}} [opzioni] `contextTokens` = il contesto
+   *   per cui si vuole la stima di memoria. ⛔ Assente = si usa quello
+   *   ADDESTRATO, che per un modello a contesto lungo è enormemente più
+   *   grande di quello che si userà davvero (sul Qwen3 27B: 262.144 token
+   *   invece dei 65.536 richiesti, un fattore 4 di sovrastima). `fit()` lo
+   *   passa sempre; resta opzionale per non rompere chi chiama
+   *   `inspectModel` da solo per sapere cosa dichiara il file.
+   */
+  async function inspectModel(modelId, { contextTokens } = {}) {
+    const manifest = await modelStore.inspect(modelId);
+    if (!manifest) throw new LocalRuntimeProbeError(`model ${modelId} not found`, 'MODEL_NOT_FOUND');
+    if (manifest.state !== 'ready') throw new LocalRuntimeProbeError(`model ${modelId} is not ready`, 'MODEL_NOT_READY');
+
+    let header;
+    try {
+      /*
+       * ⛔⛔⛔ 02/9 (sera) — QUI si passava `manifest.path` da solo, e
+       * `manifest.path` è la CARTELLA del modello, non il file: il lettore
+       * riceveva una directory e falliva sempre con
+       * `MODEL_HEADER_UNREADABLE`. Il difetto è mio, del collegamento
+       * scritto stamattina, e non era emerso perché i test iniettano un
+       * `readHeader` finto (a cui il percorso non importa) e sulla macchina
+       * non c'era NESSUN modello registrato con cui provarlo dal vivo:
+       * è saltato fuori solo dopo aver reimportato due GGUF veri.
+       * ⇒ Il percorso si compone qui, dove si conosce la forma del
+       * manifest (cartella + primo file), esattamente come già faceva
+       * `load` in `server.mjs`; la radice assoluta la mette il chiamante,
+       * che è l'unico a conoscerla.
+       */
+      const file = Array.isArray(manifest.files) ? manifest.files[0] : null;
+      if (!file || typeof file.path !== 'string') throw new LocalRuntimeProbeError(`model ${modelId} has no file to inspect`, 'MODEL_HEADER_UNREADABLE');
+      header = validateHeader(await readHeader(joinPosix(manifest.path, file.path)));
+    } catch (error) {
+      if (error instanceof LocalRuntimeProbeError) throw error;
+      throw new LocalRuntimeProbeError(`cannot read model header: ${error?.message || 'unknown error'}`, 'MODEL_HEADER_UNREADABLE');
+    }
+
+    /*
+     * ⛔⛔ 02/9 (sera) — `readRuntimeProps()` LANCIA se il runtime locale
+     * non risponde, e faceva abortire tutta `inspectModel`: `/fit`
+     * rispondeva `RUNTIME_PROBE_FAILED` anche quando aveva già letto
+     * l'header e poteva dire cose vere su spazio, memoria e contesto
+     * addestrato. Incoerente col disegno di questo stesso file: tutto ciò
+     * che segue è GIÀ scritto per degradare (`unknown()`,
+     * `observedBoolean(caps?.…)`), e `fit()` ha lo stato `unknown` con
+     * motivo `context` esattamente per questo caso.
+     * ⇒ Un runtime spento non è un errore della lettura: è un fatto NON
+     * OSSERVATO, e si dichiara come tale invece di rifiutare la risposta.
+     * ⛔ `qualify()` resta severo: chiede `fit()` compatibile e con
+     * `unknown` si ferma da solo — un giro di generazione vero senza
+     * runtime non deve neanche essere tentato.
+     */
+    let props = {};
+    let raggiungibile = true;
+    try {
+      props = await readRuntimeProps();
+    } catch (error) {
+      if (!(error instanceof LocalRuntimeProbeError) || error.code !== 'RUNTIME_PROBE_FAILED') throw error;
+      raggiungibile = false;
+    }
+    /*
+     * ⛔⛔⛔ L'`n_ctx` È DEL MODELLO CARICATO, NON DELLA MACCHINA — 02/9.
+     *
+     * Il difetto, trovato dal vivo e non leggendo: con un runtime acceso su
+     * un modello, la riga di OGNI ALTRO modello mostrava come «contesto
+     * disponibile» l'`n_ctx` di quello caricato. `/props` descrive la
+     * sessione in corso, non la macchina: quel numero è vero solo per il
+     * modello che l'ha prodotto. Un 262k caricato faceva sembrare enorme il
+     * contesto di un 4k, e un 4k caricato faceva bocciare per contesto un
+     * modello che ne ha 262k — cioè l'errore in ENTRAMBE le direzioni.
+     *
+     * ⭐ Ricerca 02/9: llama.cpp tiene i due numeri separati proprio perché
+     * sono cose diverse — `n_ctx` (quello caricato) contro `n_ctx_train`
+     * (quello del modello) — e stampa un avviso quando divergono
+     * («n_ctx_per_seq (4096) < n_ctx_train (8192)»). Noi ne usavamo uno solo
+     * per rispondere a due domande.
+     *
+     * ⇒ L'osservazione vale solo per il modello caricato. Per gli altri il
+     * runtime NON HA OSSERVATO NIENTE, e `unknown()` è la risposta onesta:
+     * quando quel modello verrà caricato avrà il contesto suo. ⛔ Non è un
+     * ripiego pessimista — è la differenza fra «non lo so» e «so che è
+     * questo», la stessa che regge tutto il resto di questo file.
+     */
+    /*
+     * `null` = nessun runtime pronto (e allora `props` è vuoto, quindi si
+     * ricade su `unknown()` da sé) oppure un adattatore che non sa ancora
+     * rispondere. In entrambi i casi non c'è un modello ALTRO a cui
+     * attribuire il numero, che è la cosa da impedire.
+     */
+    const caricato = typeof runtime.loadedModelId === 'function' ? runtime.loadedModelId() : null;
+    const parlaDiQuestoModello = caricato === null || caricato === manifest.id;
+    const runtimeTokens = props.default_generation_settings?.n_ctx;
+    const runtimeContext = parlaDiQuestoModello && positiveInteger(runtimeTokens)
+      ? fact('observed', runtimeTokens)
+      : unknown();
+    const caps = props.chat_template_caps;
+    return {
+      modelId: manifest.id,
+      format: { state: 'observed', magic: 'GGUF', version: 3 },
+      storageBytes: { state: 'declared', value: manifest.bytes },
+      /*
+       * ⛔ 02/9 (sera) — si stima sul contesto RICHIESTO quando il lettore
+       * espone il costo per token; senza quel dato (header vecchio o file
+       * che non dichiara le teste) si ricade sulla stima del file, che usa
+       * il contesto addestrato. Il tetto è il contesto addestrato: chiedere
+       * più di quanto il modello sa fare non costa più memoria, semmai è il
+       * controllo sul contesto a bocciarlo, e con un motivo suo.
+       */
+      workingMemoryBytes: {
+        state: 'declared',
+        // ⛔ Math.ceil come nel lettore: il consumatore a valle pretende interi.
+        value: (Number.isSafeInteger(header.kvCacheBytesPerToken) && Number.isSafeInteger(contextTokens) && contextTokens > 0)
+          ? Math.ceil((header.estimatedWorkingBytes - header.kvCacheBytesPerToken * header.trainedContext)
+            + header.kvCacheBytesPerToken * Math.min(contextTokens, header.trainedContext))
+          : header.estimatedWorkingBytes,
+      },
+      context: {
+        trainedTokens: fact('declared', header.trainedContext),
+        runtimeTokens: runtimeContext,
+        effectiveTokens: runtimeContext.state === 'observed'
+          ? fact('observed', Math.min(header.trainedContext, runtimeContext.value))
+          : fact('declared', header.trainedContext),
+      },
+      /*
+       * ⛔⛔⛔ E NON È SOLO IL CONTESTO — scoperto allargando la cura, 02/9.
+       *
+       * `chat_template` e `chat_template_caps` arrivano dallo STESSO `/props`,
+       * e descrivono anch'essi la sessione in corso. Con un modello caricato,
+       * la riga di un altro modello dichiarava il suo template e il suo
+       * supporto agli attrezzi — cioè rispondeva «sì, chiama gli attrezzi»
+       * per un modello che potrebbe non saperlo fare. È il difetto più grave
+       * dei due, perché una capacità inventata si scopre solo a metà di una
+       * sessione agentica.
+       * ⇒ Stessa regola del contesto: se non è il modello caricato, il
+       * runtime non ha osservato NIENTE di lui.
+       */
+      runtime: { reachable: raggiungibile, servingThisModel: parlaDiQuestoModello, servingModelId: caricato },
+      template: parlaDiQuestoModello && typeof props.chat_template === 'string' && props.chat_template !== ''
+        ? fact('observed', true)
+        : unknown(),
+      capabilities: parlaDiQuestoModello ? {
+        tools: observedBoolean(caps?.supports_tools),
+        toolCalls: observedBoolean(caps?.supports_tool_calls),
+        systemRole: observedBoolean(caps?.supports_system_role),
+      } : { tools: unknown(), toolCalls: unknown(), systemRole: unknown() },
+      backend: observedString(props.backend),
+      build: observedString(props.build),
+      observedAt: now().toISOString(),
+    };
+  }
+
+  async function measureBackend() {
+    const props = await readRuntimeProps();
+    return {
+      backend: observedString(props.backend),
+      thermal: unknown(),
+      observedAt: now().toISOString(),
+    };
+  }
+
+  async function fit(modelId, { profile = 'agent', contextTokens = profile === 'agent' ? 65_536 : 4_096 } = {}) {
+    if (!['agent', 'chat'].includes(profile) || !positiveInteger(contextTokens)) {
+      throw new LocalRuntimeProbeError('fit request is invalid', 'FIT_INVALID');
+    }
+    // ⛔ Il contesto RICHIESTO arriva fin qui: è quello per cui la memoria va stimata.
+    const inspection = await inspectModel(modelId, { contextTokens });
+    let machine;
+    try {
+      machine = await measureMachine();
+    } catch {
+      return { modelId, profile, state: 'unknown', reason: 'measurement', inspection };
+    }
+    const storageAvailable = machine?.storage?.allocatableBytes;
+    const memoryAvailable = machine?.memory?.freeBytes;
+    const base = {
+      modelId,
+      profile,
+      context: { requestedTokens: contextTokens, availableTokens: inspection.context.effectiveTokens.value },
+      storage: { requiredBytes: inspection.storageBytes.value, availableBytes: storageAvailable ?? null },
+      memory: { requiredBytes: inspection.workingMemoryBytes.value, availableBytes: memoryAvailable ?? null },
+      inspection,
+    };
+    if (!Number.isSafeInteger(storageAvailable) || !Number.isSafeInteger(memoryAvailable)) return { ...base, state: 'unknown', reason: 'measurement' };
+    if (inspection.storageBytes.value > storageAvailable) return { ...base, state: 'blocked', reason: 'storage' };
+    if (inspection.workingMemoryBytes.value > memoryAvailable) return { ...base, state: 'blocked', reason: 'memory' };
+    /*
+     * ⛔ Il cancello del contesto guarda la RAGGIUNGIBILITÀ, non l'osservazione.
+     *
+     * Prima leggeva `runtimeTokens.state !== 'observed'`, e finché quel campo
+     * conteneva l'`n_ctx` di chiunque fosse caricato le due cose coincidevano.
+     * Da quando il numero è attribuito al modello giusto, non coincidono più:
+     * un modello NON caricato ha `runtimeTokens` sconosciuto per costruzione,
+     * e con la vecchia riga ogni riga della lista sarebbe diventata «non lo
+     * so» — cioè la lista avrebbe smesso di rispondere alla sola domanda per
+     * cui esiste (*ci sta, prima di caricarlo?*).
+     *
+     * ⇒ Il caso che quella riga voleva prendere resta preso, e per intero: se
+     * il runtime non risponde non si sa niente né del contesto né del
+     * template. Se invece risponde ma sta servendo un altro modello, il
+     * contesto ADDESTRATO lo dichiara l'header — che è un fatto del modello,
+     * non della sessione — e il profilo agente si ferma comunque poco sotto,
+     * sul cancello delle capacità, che ora è sconosciuto per lo stesso motivo.
+     */
+    if (!inspection.runtime.reachable) return { ...base, state: 'unknown', reason: 'context' };
+    if (inspection.context.effectiveTokens.value < contextTokens) {
+      return { ...base, state: profile === 'agent' && inspection.context.effectiveTokens.value < 65_536 ? 'chat-only' : 'blocked', reason: 'context' };
+    }
+    if (profile === 'agent') {
+      const capabilityValues = Object.values(inspection.capabilities);
+      if (capabilityValues.some(({ state }) => state !== 'observed')) return { ...base, state: 'unknown', reason: 'capabilities' };
+      if (capabilityValues.some(({ value }) => value !== true)) return { ...base, state: 'chat-only', reason: 'template' };
+    }
+    return { ...base, state: 'compatible', reason: 'fits' };
+  }
+
+  /**
+   * ⭐⭐⭐ LA STIMA PRIMA DELLO SCARICAMENTO — 03/9, richiesta dell'owner:
+   * «badge e pulsanti per misurare in tempo reale se quel modello e
+   * quantizzazione entrano e girano nel pc».
+   *
+   * ## Perché non è `fit()`
+   *
+   * `fit()` legge l'header GGUF dal disco: sa strati, teste e contesto
+   * addestrato, quindi calcola la cache del contesto al byte. Qui il file
+   * **non c'è ancora** — è una variante su Hugging Face — e l'unica cosa
+   * nota è quanto pesa. Fingere lo stesso verdetto sarebbe inventare.
+   *
+   * ## Cosa dichiara, e cosa NON dichiara
+   *
+   * ⛔ Questa è una **soglia inferiore**, non un totale: copre i PESI e
+   * basta. La cache del contesto si somma sopra e non è calcolabile senza
+   * l'header (serve `n_kv_heads` × `head_dim` × strati). Perciò:
+   *  · se già i pesi non ci stanno, **non ci sta**, ed è un fatto;
+   *  · se i pesi ci stanno, si è detto solo che i pesi ci stanno.
+   * Il campo `basis: 'weights-only'` viaggia con la risposta proprio perché
+   * chi la mostra non possa dimenticarsene.
+   *
+   * ⭐ Ricerca 03/9 (LM Studio, tech-insider/insiderllm): il concorrente
+   * etichetta ogni quantizzazione con la memoria stimata e una scala a
+   * badge (giallo = offload parziale, rosso = non entra), e ha
+   * `lms load --estimate-only`. La stima prima dello scaricamento è una
+   * capacità affermata, non un'invenzione nostra — ma nessuno dei due
+   * dichiara che è una soglia inferiore, e noi sì.
+   *
+   * ⛔ Stessa `measureMachine()` e stesso vocabolario di stati/motivi di
+   * `fit()`: due verdetti sulla stessa schermata scritti con parole diverse
+   * insegnano a non fidarsi di nessuno dei due.
+   */
+  async function estimateFit({ bytes, contextTokens = null } = {}) {
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+      throw new LocalRuntimeProbeError('estimate request is invalid', 'FIT_INVALID');
+    }
+    if (contextTokens !== null && !positiveInteger(contextTokens)) {
+      throw new LocalRuntimeProbeError('estimate request is invalid', 'FIT_INVALID');
+    }
+    let machine;
+    try {
+      machine = await measureMachine();
+    } catch {
+      return { bytes, basis: 'weights-only', state: 'unknown', reason: 'measurement', storage: { requiredBytes: bytes, availableBytes: null }, memory: { requiredBytes: bytes, availableBytes: null }, observedAt: now().toISOString() };
+    }
+    const storageAvailable = machine?.storage?.allocatableBytes;
+    const memoryAvailable = machine?.memory?.freeBytes;
+    const base = {
+      bytes,
+      basis: 'weights-only',
+      contextTokens,
+      storage: { requiredBytes: bytes, availableBytes: Number.isSafeInteger(storageAvailable) ? storageAvailable : null },
+      memory: { requiredBytes: bytes, availableBytes: Number.isSafeInteger(memoryAvailable) ? memoryAvailable : null },
+      observedAt: now().toISOString(),
+    };
+    if (!Number.isSafeInteger(storageAvailable) || !Number.isSafeInteger(memoryAvailable)) return { ...base, state: 'unknown', reason: 'measurement' };
+    // ⛔ Il disco per primo, e con parole sue: lo spazio si libera, la memoria no.
+    if (bytes > storageAvailable) return { ...base, state: 'blocked', reason: 'storage' };
+    if (bytes > memoryAvailable) return { ...base, state: 'blocked', reason: 'memory' };
+    // Stessa soglia dichiarata di `fit()` lato UI: sopra il 90% del libero è «al limite».
+    if (bytes > memoryAvailable * 0.9) return { ...base, state: 'tight', reason: 'memory' };
+    return { ...base, state: 'compatible', reason: 'fits' };
+  }
+
+  async function qualify({ modelId, consent, profile = 'agent', contextTokens = profile === 'agent' ? 65_536 : 4_096 } = {}) {
+    if (consent !== true) throw new LocalRuntimeProbeError('qualification requires explicit consent', 'PROBE_CONSENT_REQUIRED');
+    const fitResult = await fit(modelId, { profile, contextTokens });
+    if (fitResult.state !== 'compatible') throw new LocalRuntimeProbeError(`model fit is ${fitResult.state}`, 'MODEL_NOT_COMPATIBLE');
+
+    const startedAt = clockMs();
+    let firstTokenAt = null;
+    let completed = false;
+    for await (const event of runtime.generateStream({
+      runId: `qualification-${modelId}`,
+      turnId: 'qualification',
+      modelId,
+      messages: [{ role: 'user', content: 'Reply with OK.' }],
+      parseToolCalls: false,
+    })) {
+      if (firstTokenAt === null && (event.type === 'text' || event.type === 'reasoning')) firstTokenAt = clockMs();
+      if (event.type === 'error') throw new LocalRuntimeProbeError(event.message || 'qualification stream failed', 'PROBE_GENERATION_FAILED');
+      if (event.type === 'done') completed = true;
+    }
+    const endedAt = clockMs();
+    if (!completed || firstTokenAt === null) throw new LocalRuntimeProbeError('qualification produced no complete response', 'PROBE_GENERATION_INCOMPLETE');
+
+    let tokensPerSecond = unknown();
+    if (typeof runtime.metrics === 'function') {
+      try { tokensPerSecond = parseTokensPerSecond(await runtime.metrics()); } catch { /* metric remains unknown */ }
+    }
+    return {
+      modelId,
+      state: 'qualified',
+      backend: fitResult.inspection.backend,
+      build: fitResult.inspection.build,
+      contextTokens: fitResult.context.availableTokens,
+      performance: {
+        ttftMs: fact('observed', Math.max(0, firstTokenAt - startedAt)),
+        tokensPerSecond,
+      },
+      durationMs: Math.max(0, endedAt - startedAt),
+      measuredAt: now().toISOString(),
+    };
+  }
+
+  return Object.freeze({ inspectModel, measureBackend, fit, estimateFit, qualify });
+}