talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/terminal-ws.mjs

@@ -0,0 +1,170 @@
+/**
+ * terminal-ws.mjs — il ponte WebSocket fra il registro di PTY vere
+ * (`pty-terminal.mjs`) e il browser. Ledger: `.claude/LEDGER-TERMINALE-REALE.md`.
+ *
+ * ⛔⛔ Nessuna porta nuova: l'upgrade avviene sullo STESSO `http.Server`
+ * già bindato solo su loopback (`config.host`, validato in
+ * `config.mjs`) — la WS eredita lo stesso perimetro di rete di ogni
+ * altra rotta di questo backend, zero superficie aggiunta.
+ *
+ * ⛔ Validazione Origin ESPLICITA prima di completare l'upgrade — un
+ * browser NON applica la same-origin policy alle WebSocket come la
+ * applica a `fetch`/XHR (rischio "cross-site WebSocket hijacking",
+ * guardia raccolta in ricerca prima di scrivere). Qui la shell aperta
+ * "non ha limiti" (owner, 28/8): il confine giusto da tenere stretto è
+ * il TRASPORTO, non la shell stessa.
+ */
+import { WebSocketServer } from 'ws';
+
+import { codificaFrame, decodificaFrame, TIPO_FRAME_CONTROLLO, TIPO_FRAME_DATI } from './pty-terminal.mjs';
+
+const PERCORSO_WS = '/api/v1/terminal/ws';
+
+function leggiCookieGrezzo(grezzo, nome) {
+  if (typeof grezzo !== 'string' || grezzo === '') return null;
+  for (const parte of grezzo.split(';')) {
+    const i = parte.indexOf('=');
+    if (i !== -1 && parte.slice(0, i).trim() === nome) return parte.slice(i + 1).trim();
+  }
+  return null;
+}
+
+/**
+ * ⭐⭐⭐ W1-01 (05/9) — `?id=` non è più il `sessionId`: è il **`terminalId`**,
+ * e una sessione può averne più d'uno.
+ *
+ * ⛔⛔⛔ Il parametro `risolviCartella` (che tornava SEMPRE una cartella, al
+ * peggio la prima configurata) è stato sostituito da `risolviScheda`, che ha
+ * il diritto di dire **no**: `null` ⇒ upgrade rifiutato, e nessuna PTY nasce.
+ * Prima di oggi un id sconosciuto non veniva respinto — cadeva sul primo
+ * progetto — quindi con un `terminalId` libero qualunque stringa avrebbe
+ * aperto una shell. È la forma esatta di **CVE-2026-59224** (Open WebUI,
+ * 2026): un id scelto dal client che decide a quale PTY ti attacchi. E il
+ * terminale è l'endpoint dove un buco non è un buco: **CVE-2026-39987**
+ * (Marimo, 2026) era `/terminal/ws`, l'unica WebSocket senza controllo
+ * d'autenticazione, cioè RCE pre-auth. Entrambe lette il 05/09/2026, fonti nel
+ * ledger `.claude/LEDGER-W1-01-SCHEDE-TERMINALE-2026-09-05.md`.
+ */
+export function creaGestoreTerminaleWs({ registro, originiConsentite, risolviScheda, token = null }, deps = {}) {
+  const WSS = deps.WebSocketServer ?? WebSocketServer;
+  const wss = new WSS({ noServer: true });
+
+  function gestisciUpgrade(req, socket, head) {
+    let url;
+    try {
+      url = new URL(req.url, 'http://localhost');
+    } catch {
+      socket.destroy();
+      return;
+    }
+    if (url.pathname !== PERCORSO_WS) {
+      socket.destroy();
+      return;
+    }
+    const origin = req.headers.origin;
+    if (origin && originiConsentite && !originiConsentite.has(origin)) {
+      socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    // ⭐ 04/9, W1-10 — stesso cancello a token di /api/*: senza il cookie talos_token l'upgrade è 401, la PTY non nasce nemmeno.
+    if (token && leggiCookieGrezzo(req.headers.cookie, 'talos_token') !== token) {
+      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    const id = url.searchParams.get('id');
+    if (typeof id !== 'string' || id.length === 0 || id.length > 200) {
+      socket.destroy();
+      return;
+    }
+    /*
+     * ⛔⛔⛔ 05/9, W1-01 — IL CANCELLO. Si chiede al registro delle schede
+     * PRIMA di completare l'upgrade: un `terminalId` che il server non ha
+     * creato (e che non è un `sessionId` vivo) riceve 403 e il socket muore
+     * QUI. ⛔ `registro.apri` non viene nemmeno sfiorato: la prova che conta
+     * non è lo status code, è che la PTY non nasca — ed è così che i test la
+     * misurano (contano gli spawn, non le risposte).
+     */
+    const scheda = risolviScheda(id);
+    if (!scheda) {
+      socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      collega(ws, scheda);
+    });
+  }
+
+  function collega(ws, scheda) {
+    /* ⛔ L'id e la cartella vengono dalla SCHEDA del registro, mai dalla query: il client nomina, il server decide. */
+    const id = scheda.terminalId;
+    /*
+     * ⭐⭐⭐ Il segnale «ripreso», PRIMA di qualunque byte.
+     *
+     * ⛔ Senza, il client non poteva sapere se la sua shell fosse sopravvissuta:
+     * il ponte rigioca il backlog sia quando riaggancia una PTY viva sia
+     * quando il reaper l'ha chiusa e ne nasce una nuova (backlog vuoto — che è
+     * anche l'aspetto di una shell viva che non ha ancora stampato niente).
+     * L'interfaccia era costretta a dire «riconnesso, non sappiamo se la shell
+     * è ancora quella». Lo stato dell'arte separa l'identità della CONNESSIONE
+     * da quella della SESSIONE e fa dichiarare al server se ha ripreso davvero
+     * (un pattern noto come "connection state recovery"; ricerca del 05/09/2026,
+     * websocket.org/guides/reconnection/).
+     *
+     * ⛔ Va PRIMA del backlog: chi legge deve sapere di che shell sono i byte
+     * che sta per ricevere, non scoprirlo dopo averli scritti a schermo.
+     *
+     * ⛔ Sicuro per il monolite congelato (`public/app.js`), verificato alla
+     * fonte: alla riga 7702 tratta solo `evento === 'uscita'` e ignora in
+     * silenzio ogni altro evento di controllo — nessun `else`, nessun crash.
+     */
+    const { voce, ripresa } = registro.apriDichiarando({ id, cartella: scheda.cartella });
+    /* 06/9 B1 — la scheda prende il nome della shell che il server ha scelto DAVVERO (`enforcement` di `sceltaShell`), non uno indovinato dal client. */
+    ws.send(codificaFrame(TIPO_FRAME_CONTROLLO, JSON.stringify({ evento: 'agganciato', ripreso: ripresa, shell: voce.enforcement ?? null, comando: voce.comando ?? null })));
+
+    // ⭐ Riconnessione (F5, o WS caduta): replay del backlog PRIMA di tornare live — stesso principio del Last-Event-ID già in uso per SSE, qui su una PTY invece che su un run agente.
+    for (const pezzo of voce.backlog) {
+      ws.send(codificaFrame(TIPO_FRAME_DATI, pezzo));
+    }
+
+    const ascolta = (evento) => {
+      if (ws.readyState !== ws.OPEN) return;
+      if (evento.tipo === 'dati') {
+        ws.send(codificaFrame(TIPO_FRAME_DATI, evento.dati));
+      } else if (evento.tipo === 'uscita') {
+        ws.send(codificaFrame(TIPO_FRAME_CONTROLLO, JSON.stringify({ evento: 'uscita', codice: evento.exitCode ?? null })));
+      }
+    };
+    voce.ascoltatori.add(ascolta);
+
+    ws.on('message', (dati) => {
+      const frame = decodificaFrame(dati);
+      if (!frame) return; // AL CONTRARIO: un frame vuoto/di tipo ignoto si scarta, mai un crash della connessione
+      if (frame.tipo === TIPO_FRAME_DATI) {
+        registro.scrivi(id, frame.payload.toString('utf8'));
+        return;
+      }
+      let comando;
+      try {
+        comando = JSON.parse(frame.payload.toString('utf8'));
+      } catch {
+        return;
+      }
+      if (comando?.tipo === 'resize' && Number.isInteger(comando.cols) && Number.isInteger(comando.rows)) {
+        registro.ridimensiona(id, comando.cols, comando.rows);
+      }
+    });
+
+    ws.on('close', () => {
+      voce.ascoltatori.delete(ascolta);
+      registro.segnaDisconnesso(id);
+    });
+
+    // ⛔ Un errore di trasporto non deve propagarsi come un'eccezione non gestita del processo server.
+    ws.on('error', () => { /* 'close' segue comunque, la pulizia avviene lì */ });
+  }
+
+  return { gestisciUpgrade };
+}

package/vendor/harness-ui/src/tool-forge-store.mjs

@@ -0,0 +1,299 @@
+/**
+ * tool-forge-store.mjs — FASE N, nono e ultimo sistema (30/8): Tool
+ * Forge, "fetta onesta" (owner, AskUserQuestion: "Fetta onesta
+ * (consigliato)"). Letto alla fonte PRIMA di disegnare: `mobile/src/
+ * lib/tools/dynamic/forgeRegistryRepository.ts` (269 righe, SQLite
+ * device-wide con versioning) — questo store è la traduzione onesta
+ * su file, come ogni altro store di questa fase: un file per tool
+ * installato, mai un database.
+ *
+ * ⭐⭐⭐ Tool Forge è GLOBALE, come Notes/Tasks/Memory — non PER-PROGETTO
+ * come Libreria/Deep Research. Verificato non presunto: le 8 capability
+ * che un tool forgiato può chiamare (tasks, notes, memory — vedi
+ * CAPACITA_FORGE nel kernel) operano TUTTE su store GLOBALI
+ * (.tasks-store, .notes-store, .memory-store) — un tool forgiato creato
+ * mentre si lavora sul progetto A deve restare disponibile e utile
+ * anche lavorando sul progetto B, esattamente come una nota o
+ * un'attività. Storage: `.tool-forge-store/<id>.json`, accanto a
+ * `.notes-store/`/`.tasks-store/`/`.memory-store/`.
+ *
+ * ⛔⛔⛔ `cartella` qui è SEMPRE la cartella FINALE, mai un genitore da
+ * suffissare — stesso contratto ESATTO di notes-store.mjs/
+ * tasks-store.mjs/memory-store.mjs (verificato leggendo notes-store.mjs
+ * riga per riga, non presunto: `elencaNote` fa `join(cartella, nome)`,
+ * MAI `join(cartella, CARTELLA_NOTE, nome)`). Il default REALE vive in
+ * session-registry.mjs (`cartellaForge = .../.tool-forge-store/`,
+ * GIÀ col suffisso) — un secondo `join(cartella, CARTELLA_FORGE)` qui
+ * dentro avrebbe prodotto un doppio annidamento
+ * (`.tool-forge-store/.tool-forge-store/`).
+ *
+ * ⛔⛔⛔ Bug reale trovato E corretto dal vivo (30/8), non da lettura: la
+ * prima versione di questo file FACEVA quel doppio join — un
+ * `tool_create` chiamato da un modello vero tornava "Created..." (il
+ * messaggio di successo, corretto) ma il file non appariva MAI in
+ * `.tool-forge-store/` (la cartella vera, controllata sul disco): la
+ * scrittura andava un livello più in profondità
+ * (`.tool-forge-store/.tool-forge-store/<id>.json`), mai controllata da
+ * nessun test perché ogni test di QUESTO file passava una `cartella`
+ * generica ("/tmp/x") che non rivelava la duplicazione — solo
+ * confrontando il contratto con notes-store.mjs (il precedente diretto)
+ * il difetto è emerso.
+ *
+ * ⛔⛔⛔ Ogni tool installato nasce SEMPRE `abilitato:false` — porto
+ * diretto del vincolo mobile ("installed but stays DISABLED until the
+ * user turns it on"). Abilitare/disabilitare NON è mai un tool del
+ * modello (verificato in toolControlCatalog.ts: tool_create è l'UNICO
+ * tool_* chat-facing su ENTRAMBE le piattaforme) — solo un'azione
+ * owner-facing dal pannello Capability hub, `abilitaToolForgiato` sotto.
+ *
+ * Stile DI: stesso pattern di notes-store.mjs — funzioni async con
+ * `deps` opzionali per i test, mai un vero filesystem mockato altrove.
+ */
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+
+export class ToolForgeStoreError extends Error {
+  constructor(message, code = 'FORGE_INVALID') {
+    super(message);
+    this.name = 'ToolForgeStoreError';
+    this.code = code;
+  }
+}
+
+/** Nome canonico della cartella globale — MAI usato per un join interno qui (vedi la doc di testa): solo documentazione/riferimento esterno, come CARTELLA_NOTE in notes-store.mjs. */
+export const CARTELLA_FORGE = '.tool-forge-store';
+/** Censito da forgeRegistryRepository.ts mobile (MAX_INSTALLED_TOOLS = 64) — non inventato. */
+export const MAX_TOOL_INSTALLATI = 64;
+
+function percorsoVoce(cartella, id) {
+  return join(cartella, `${id}.json`);
+}
+
+/**
+ * @returns {Promise<Array<object>>} — [] se la cartella non esiste
+ * ancora (mai un errore: nessun tool forgiato è uno stato onesto).
+ * Più recenti prime.
+ */
+export async function elencaToolForgiati({ cartella }, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let file;
+  try {
+    file = await readdirFn(cartella);
+  } catch {
+    return [];
+  }
+  const strumenti = [];
+  for (const nomeFile of file) {
+    if (!nomeFile.endsWith('.json')) continue;
+    try {
+      strumenti.push(JSON.parse(await readFileFn(join(cartella, nomeFile), 'utf8')));
+    } catch {
+      // ⛔ una voce corrotta non impedisce di vedere le altre — stesso principio di leggiRegistro (session-store.mjs).
+    }
+  }
+  strumenti.sort((a, b) => String(b.installatoAlle || '').localeCompare(String(a.installatoAlle || '')));
+  return strumenti;
+}
+
+/** @returns {Promise<object|null>} — null se l'id non esiste. */
+export async function leggiToolForgiato({ cartella, id }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  try {
+    return JSON.parse(await readFileFn(percorsoVoce(cartella, id), 'utf8'));
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return null;
+    throw new ToolForgeStoreError(`${id}: metadata presente ma illeggibile: ${errore.message}`, 'FORGE_READ_FAILED');
+  }
+}
+
+/**
+ * Installa un manifest GIÀ VALIDATO (dal chiamante, via
+ * validaManifestForge del kernel — questo store non rivalida, si
+ * fida del chiamante come library-store.mjs si fida di
+ * sanificaNomeLibreria). Rifiuta un id già esistente (porto diretto
+ * del messaggio mobile — v1 non ha un tool_update, un secondo
+ * tool_create sullo stesso id è sempre un conflitto, mai un
+ * aggiornamento silenzioso) e un registro pieno (porto diretto del
+ * messaggio mobile, MAX_TOOL_INSTALLATI censito non inventato).
+ */
+export async function installaToolForgiato({ cartella, manifest, capacita, azioni, rischio }, deps = {}) {
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  if (!manifest || typeof manifest.id !== 'string' || manifest.id.length === 0) {
+    throw new ToolForgeStoreError('a tool manifest needs an id', 'FORGE_INVALID');
+  }
+  let esistenti;
+  try {
+    esistenti = await readdirFn(cartella);
+  } catch {
+    esistenti = [];
+  }
+  if (esistenti.includes(`${manifest.id}.json`)) {
+    throw new ToolForgeStoreError(`a tool with id "${manifest.id}" already exists — pick a different id`, 'FORGE_VERSION_NOT_NEWER');
+  }
+  if (esistenti.filter((nome) => nome.endsWith('.json')).length >= MAX_TOOL_INSTALLATI) {
+    throw new ToolForgeStoreError('the tool registry on this device is full — remove an unused tool first', 'FORGE_REGISTRY_FULL');
+  }
+  await mkdirFn(cartella, { recursive: true });
+  const voce = {
+    id: manifest.id, manifest, capacita, azioni, rischio,
+    abilitato: false, installatoAlle: new Date().toISOString(),
+  };
+  await writeFileFn(percorsoVoce(cartella, manifest.id), JSON.stringify(voce, null, 2), 'utf8');
+  return voce;
+}
+
+/**
+ * L'UNICA mutazione owner-facing di questa fase (vedi la doc di testa
+ * sul perché) — mai chiamata da un tool del modello. `null` se l'id
+ * non esiste.
+ */
+export async function abilitaToolForgiato({ cartella, id, abilitato }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  let voce;
+  try {
+    voce = JSON.parse(await readFileFn(percorsoVoce(cartella, id), 'utf8'));
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return null;
+    throw new ToolForgeStoreError(`${id}: metadata presente ma illeggibile: ${errore.message}`, 'FORGE_READ_FAILED');
+  }
+  const aggiornata = { ...voce, abilitato: Boolean(abilitato) };
+  await writeFileFn(percorsoVoce(cartella, id), JSON.stringify(aggiornata, null, 2), 'utf8');
+  return aggiornata;
+}
+
+/** `null` se l'id non esiste già (idempotente, mai un'eccezione — stesso principio di eliminaVoce/eliminaRicerca). */
+export async function eliminaToolForgiato({ cartella, id }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const rmFn = deps.rmFn ?? fsp.rm;
+  try {
+    await readFileFn(percorsoVoce(cartella, id), 'utf8');
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return null;
+    throw new ToolForgeStoreError(`${id}: metadata presente ma illeggibile: ${errore.message}`, 'FORGE_READ_FAILED');
+  }
+  await rmFn(percorsoVoce(cartella, id), { force: true });
+  return { id };
+}
+
+
+/* M10-C — owner-managed revision history. The active <id>.json remains the only runtime source. */
+const OWNER_HISTORY_DIR = '.owner-versions';
+const OWNER_HISTORY_LIMIT = 10;
+const OWNER_AUDIT_LIMIT = 256;
+const OWNER_ID = /^[a-z0-9][a-z0-9_-]{2,63}$/;
+
+function ownerDir(cartella, id) { return join(cartella, OWNER_HISTORY_DIR, id); }
+function ownerVersionsDir(cartella, id) { return join(ownerDir(cartella, id), 'versions'); }
+function ownerMetaPath(cartella, id) { return join(ownerDir(cartella, id), 'meta.json'); }
+function ownerAuditPath(cartella, id) { return join(ownerDir(cartella, id), 'audit.jsonl'); }
+function ownerVersionPath(cartella, id, revision) { return join(ownerVersionsDir(cartella, id), revision + '.json'); }
+function validOwnerInput(id, revision) {
+  if (typeof id !== 'string' || !OWNER_ID.test(id)) throw new ToolForgeStoreError('owner-managed tool id is invalid', 'FORGE_INVALID');
+  if (!Number.isSafeInteger(revision) || revision < 1) throw new ToolForgeStoreError('owner revision must be a positive integer', 'FORGE_INVALID');
+}
+async function readOwnerMeta(cartella, id, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  try {
+    const value = JSON.parse(await readFileFn(ownerMetaPath(cartella, id), 'utf8'));
+    return { maxRevision: Number.isSafeInteger(value?.maxRevision) && value.maxRevision > 0 ? value.maxRevision : 0 };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { maxRevision: 0 };
+    throw new ToolForgeStoreError(`${id}: owner version metadata unreadable: ${error.message}`, 'FORGE_READ_FAILED');
+  }
+}
+async function appendOwnerAudit(cartella, id, event, deps = {}) {
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  await mkdirFn(ownerDir(cartella, id), { recursive: true });
+  let rows = [];
+  try { rows = (await readFileFn(ownerAuditPath(cartella, id), 'utf8')).split('\n').filter(Boolean).map((line) => JSON.parse(line)); }
+  catch (error) { if (error?.code !== 'ENOENT') throw new ToolForgeStoreError(`${id}: owner audit unreadable: ${error.message}`, 'FORGE_READ_FAILED'); }
+  rows.push(event);
+  rows = rows.slice(-OWNER_AUDIT_LIMIT);
+  await writeFileFn(ownerAuditPath(cartella, id), rows.map((row) => JSON.stringify(row)).join('\n') + '\n', 'utf8');
+}
+async function pruneOwnerVersions(cartella, id, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const rmFn = deps.rmFn ?? fsp.rm;
+  let names = [];
+  try { names = await readdirFn(ownerVersionsDir(cartella, id)); } catch { return; }
+  const revisions = names.map((name) => /^([1-9][0-9]*)\.json$/.exec(name)).filter(Boolean).map((match) => Number(match[1])).filter(Number.isSafeInteger).sort((a, b) => a - b);
+  for (const revision of revisions.slice(0, Math.max(0, revisions.length - OWNER_HISTORY_LIMIT))) await rmFn(ownerVersionPath(cartella, id, revision), { force: true });
+}
+
+/**
+ * Owner-only versioned install/update. This intentionally does NOT replace installaToolForgiato:
+ * model tool_create remains create-only and same-id conflicts forever.
+ */
+export async function installaVersioneToolForgiatoOwner({ cartella, revision, manifest, capacita, azioni, rischio, evidence }, deps = {}) {
+  validOwnerInput(manifest?.id, revision);
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const active = await leggiToolForgiato({ cartella, id: manifest.id }, deps);
+  if (active && active.ownerManaged !== true) throw new ToolForgeStoreError(`tool "${manifest.id}" exists with legacy/model provenance and cannot be silently adopted`, 'FORGE_OWNER_ADOPTION_REQUIRED');
+  if (!active) {
+    let existing = []; try { existing = await readdirFn(cartella); } catch {}
+    if (existing.filter((name) => name.endsWith('.json')).length >= MAX_TOOL_INSTALLATI) throw new ToolForgeStoreError('the tool registry on this device is full — remove an unused tool first', 'FORGE_REGISTRY_FULL');
+  }
+  const meta = await readOwnerMeta(cartella, manifest.id, deps);
+  const maxEver = Math.max(meta.maxRevision, Number.isSafeInteger(active?.ownerRevision) ? active.ownerRevision : 0);
+  if (revision <= maxEver) throw new ToolForgeStoreError(`owner revision ${revision} is not newer than max-ever revision ${maxEver}`, 'FORGE_VERSION_NOT_NEWER');
+  await mkdirFn(ownerVersionsDir(cartella, manifest.id), { recursive: true });
+  const at = new Date().toISOString();
+  const record = {
+    id: manifest.id, manifest, capacita: Array.isArray(capacita) ? capacita : [], azioni: Array.isArray(azioni) ? azioni : [],
+    rischio: typeof rischio === 'string' ? rischio : 'R1', abilitato: false, installatoAlle: at,
+    ownerManaged: true, ownerRevision: revision, evidence: evidence ?? null,
+  };
+  try { await writeFileFn(ownerVersionPath(cartella, manifest.id, revision), JSON.stringify(record, null, 2), { encoding: 'utf8', flag: 'wx' }); }
+  catch (error) { if (error?.code === 'EEXIST') throw new ToolForgeStoreError(`owner revision ${revision} already exists`, 'FORGE_VERSION_NOT_NEWER'); throw error; }
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoVoce(cartella, manifest.id), JSON.stringify(record, null, 2), 'utf8');
+  await writeFileFn(ownerMetaPath(cartella, manifest.id), JSON.stringify({ maxRevision: revision }, null, 2), 'utf8');
+  await appendOwnerAudit(cartella, manifest.id, { kind: active ? 'update' : 'install', revision, at }, deps);
+  await pruneOwnerVersions(cartella, manifest.id, deps);
+  return record;
+}
+
+export async function elencaVersioniToolForgiatoOwner({ cartella, id }, deps = {}) {
+  if (typeof id !== 'string' || !OWNER_ID.test(id)) throw new ToolForgeStoreError('owner-managed tool id is invalid', 'FORGE_INVALID');
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let names = []; try { names = await readdirFn(ownerVersionsDir(cartella, id)); } catch (error) { if (error?.code === 'ENOENT') return []; throw error; }
+  const revisions = names.map((name) => /^([1-9][0-9]*)\.json$/.exec(name)).filter(Boolean).map((match) => Number(match[1])).filter(Number.isSafeInteger).sort((a, b) => a - b);
+  const rows = [];
+  for (const revision of revisions) {
+    try { const value = JSON.parse(await readFileFn(ownerVersionPath(cartella, id, revision), 'utf8')); rows.push({ ...value, revision }); }
+    catch (error) { throw new ToolForgeStoreError(`${id} revision ${revision} unreadable: ${error.message}`, 'FORGE_READ_FAILED'); }
+  }
+  return rows;
+}
+
+export async function leggiAuditToolForgiatoOwner({ cartella, id }, deps = {}) {
+  if (typeof id !== 'string' || !OWNER_ID.test(id)) throw new ToolForgeStoreError('owner-managed tool id is invalid', 'FORGE_INVALID');
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  try { return (await readFileFn(ownerAuditPath(cartella, id), 'utf8')).split('\n').filter(Boolean).map((line) => JSON.parse(line)); }
+  catch (error) { if (error?.code === 'ENOENT') return []; throw new ToolForgeStoreError(`${id}: owner audit unreadable: ${error.message}`, 'FORGE_READ_FAILED'); }
+}
+
+export async function ripristinaVersioneToolForgiatoOwner({ cartella, id, revision }, deps = {}) {
+  validOwnerInput(id, revision);
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const active = await leggiToolForgiato({ cartella, id }, deps);
+  if (!active) throw new ToolForgeStoreError(`tool "${id}" does not exist`, 'FORGE_NOT_FOUND');
+  if (active.ownerManaged !== true) throw new ToolForgeStoreError(`tool "${id}" is not owner-managed`, 'FORGE_OWNER_ADOPTION_REQUIRED');
+  let snapshot;
+  try { snapshot = JSON.parse(await readFileFn(ownerVersionPath(cartella, id, revision), 'utf8')); }
+  catch (error) { if (error?.code === 'ENOENT') throw new ToolForgeStoreError(`owner revision ${revision} is not retained`, 'FORGE_VERSION_NOT_FOUND'); throw new ToolForgeStoreError(`${id} revision ${revision} unreadable: ${error.message}`, 'FORGE_READ_FAILED'); }
+  const restored = { ...snapshot, abilitato: false };
+  await writeFileFn(percorsoVoce(cartella, id), JSON.stringify(restored, null, 2), 'utf8');
+  await appendOwnerAudit(cartella, id, { kind: 'rollback', revision, at: new Date().toISOString() }, deps);
+  return restored;
+}

package/vendor/harness-ui/src/tool-schema-normalize.mjs

@@ -0,0 +1,100 @@
+/**
+ * Rendere JSON Schema uno schema che JSON Schema non è.
+ *
+ * ## Il guasto che l'ha fatto nascere, misurato
+ *
+ * Owner 03/9: «il modello locale dà errore, quindi non funziona». Il motore
+ * rispondeva:
+ *
+ *   HTTP 400 — Unable to generate parser for this template.
+ *   JSON schema conversion failed: Unrecognized schema: "string"
+ *   Unrecognized schema: "string"
+ *
+ * Due volte. Ed erano esattamente due: un manifest Forge in
+ * `.tool-forge-store/promemoria-trattativa.json` dichiara
+ *
+ *   { required: ['nome_contatto'],
+ *     properties: { nome_contatto: 'string', dettagli_contatto: 'string' } }
+ *
+ * cioè le proprietà come STRINGHE NUDE invece di `{ type: 'string' }`, e senza
+ * `type: 'object'` in testa. È un'abbreviazione comoda, ed è nostra: la scrive
+ * chi forgia un attrezzo. Solo che non è JSON Schema.
+ *
+ * ## Perché non si era mai visto
+ *
+ * OpenRouter non costruisce grammatiche: riceve lo schema, lo passa al
+ * modello come testo e non protesta. llama.cpp invece deve trasformarlo in
+ * GBNF per vincolare l'output, quindi lo legge davvero — e si ferma.
+ * ⇒ Il difetto era lì da sempre, e a scoprirlo è stato il primo motore che
+ * quello schema lo legge sul serio. ⛔ Non è «un limite del locale»: è una
+ * cosa rotta nostra che solo il locale è abbastanza severo da vedere.
+ *
+ * ⭐ Ricerca 03/9 (llama.cpp PR #17572; docs LLGuidance): il convertitore
+ * JSON-Schema→GBNF di llama.cpp copre un SOTTOINSIEME e rifiuta il resto con
+ * questo messaggio; upstream sta cambiando il 500 in 400 proprio per non far
+ * ritentare a vuoto. LLGuidance coprirebbe di più ma vuole Rust.
+ * ⭐ E il mobile aveva già scelto il principio giusto per lo stesso problema
+ * (`localToolPromptProtocol.ts`): il trasporto si sceglie dalle capacità
+ * MISURATE, «mai da un nome di file o da una famiglia indovinata».
+ *
+ * ## Cosa fa questo modulo, e cosa NON fa
+ *
+ * Espande le abbreviazioni verso il JSON Schema vero. ⛔ Non inventa vincoli
+ * e non butta via proprietà che non capisce: uno schema sconosciuto resta com'è
+ * e sarà il motore a dire la sua. Togliere in silenzio un parametro
+ * cambierebbe cosa il modello può chiedere, ed è peggio di un errore visibile.
+ */
+
+/** I nomi di tipo che JSON Schema conosce. Una stringa nuda che ne è uno è un'abbreviazione. */
+const TIPI_JSON = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
+
+/**
+ * @param {unknown} schema
+ * @returns {unknown} lo stesso schema, con le abbreviazioni espanse
+ */
+export function normalizzaSchemaAttrezzo(schema) {
+  // `'string'` → `{ type: 'string' }`. È l'abbreviazione che ha rotto tutto.
+  if (typeof schema === 'string') return TIPI_JSON.has(schema) ? { type: schema } : schema;
+  if (!schema || typeof schema !== 'object') return schema;
+  if (Array.isArray(schema)) return schema.map(normalizzaSchemaAttrezzo);
+
+  const uscita = { ...schema };
+  if (uscita.properties && typeof uscita.properties === 'object' && !Array.isArray(uscita.properties)) {
+    uscita.properties = Object.fromEntries(
+      Object.entries(uscita.properties).map(([nome, valore]) => [nome, normalizzaSchemaAttrezzo(valore)]),
+    );
+    /*
+     * ⛔ Un oggetto con `properties` ma senza `type` è la seconda metà della
+     * stessa abbreviazione: chi scrive `{ properties: {...} }` intende un
+     * oggetto, e il convertitore di grammatica non tira a indovinare.
+     */
+    if (uscita.type === undefined) uscita.type = 'object';
+  }
+  if (uscita.items !== undefined) uscita.items = normalizzaSchemaAttrezzo(uscita.items);
+  if (uscita.additionalProperties !== undefined && typeof uscita.additionalProperties !== 'boolean') {
+    uscita.additionalProperties = normalizzaSchemaAttrezzo(uscita.additionalProperties);
+  }
+  for (const combinatore of ['anyOf', 'oneOf', 'allOf']) {
+    if (Array.isArray(uscita[combinatore])) uscita[combinatore] = uscita[combinatore].map(normalizzaSchemaAttrezzo);
+  }
+  if (uscita.$defs && typeof uscita.$defs === 'object') {
+    uscita.$defs = Object.fromEntries(Object.entries(uscita.$defs).map(([k, v]) => [k, normalizzaSchemaAttrezzo(v)]));
+  }
+  if (uscita.definitions && typeof uscita.definitions === 'object') {
+    uscita.definitions = Object.fromEntries(Object.entries(uscita.definitions).map(([k, v]) => [k, normalizzaSchemaAttrezzo(v)]));
+  }
+  return uscita;
+}
+
+/**
+ * Uno schema di ingresso valido anche quando il manifest non ne dichiara uno.
+ * ⛔ `{}` vuoto è ammesso da JSON Schema ma non dice niente a una grammatica:
+ * meglio un oggetto senza proprietà, che è ciò che l'attrezzo intende.
+ */
+export function schemaIngressoAttrezzo(schema) {
+  if (schema === undefined || schema === null) return { type: 'object', properties: {} };
+  const normalizzato = normalizzaSchemaAttrezzo(schema);
+  if (!normalizzato || typeof normalizzato !== 'object' || Array.isArray(normalizzato)) return { type: 'object', properties: {} };
+  if (normalizzato.type === undefined && normalizzato.properties === undefined) return { ...normalizzato, type: 'object', properties: {} };
+  return normalizzato;
+}