talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/forge-contract.mjs

@@ -0,0 +1,221 @@
+/** Canonical, provider-neutral contract for user-authored forged tools. */
+const MAX_MANIFEST_BYTES = 65_536;
+const MAX_NODES = 64;
+const MAX_TRANSITIONS = 256;
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]+$/;
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype', '__defineGetter__', '__defineSetter__', '__lookupGetter__', '__lookupSetter__']);
+const READ_ONLY_ROOTS = new Set(['input', 'runtime']);
+const NODE_TYPES = ['capability', 'if', 'return', 'fail'];
+const CAPABILITIES = Object.freeze({
+  'tasks.list': { actions: ['read'], risk: 'R1' },
+  'tasks.create': { actions: ['write'], risk: 'R2' },
+  'tasks.setStatus': { actions: ['write'], risk: 'R2' },
+  'notes.list': { actions: ['read'], risk: 'R1' },
+  'notes.create': { actions: ['write'], risk: 'R2' },
+  'notes.update': { actions: ['write'], risk: 'R2' },
+  'memory.search': { actions: ['read'], risk: 'R2' },
+  'memory.create': { actions: ['write'], risk: 'R3' },
+});
+const RISK_ORDER = { R1: 1, R2: 2, R3: 3 };
+const ID_PATTERN = /^[a-z0-9][a-z0-9_-]{2,63}$/;
+
+function rawSegments(path) {
+  const normalized = path.startsWith('$.') ? path.slice(2) : path === '$' ? '' : path;
+  return normalized.split('.').filter(Boolean);
+}
+
+export function forgePathViolation(path, { writable = false } = {}) {
+  if (typeof path !== 'string') return 'must be a string';
+  const parts = rawSegments(path);
+  if (parts.length > 16) return 'path exceeds 16 segments';
+  for (const part of parts) {
+    if (part.length > 64) return `segment "${part}" exceeds 64 characters`;
+    if (!SAFE_SEGMENT.test(part)) return `segment "${part}" must be alphanumeric, "_" or "-" only`;
+    if (FORBIDDEN_SEGMENTS.has(part)) return `segment "${part}" is forbidden`;
+  }
+  if (writable && parts[0] && READ_ONLY_ROOTS.has(parts[0])) return `"${parts[0]}" is read-only; write to "state" instead`;
+  return null;
+}
+
+function isReference(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && typeof value.$ref === 'string';
+}
+
+function collectReferences(value, result = []) {
+  if (isReference(value)) { result.push(value.$ref); return result; }
+  if (Array.isArray(value)) { for (const item of value) collectReferences(item, result); return result; }
+  if (value && typeof value === 'object') { for (const item of Object.values(value)) collectReferences(item, result); }
+  return result;
+}
+
+function addReferenceDiagnostics(value, path, add) {
+  for (const reference of collectReferences(value)) {
+    const violation = forgePathViolation(reference);
+    if (violation) add(path, `unsafe $ref "${reference}": ${violation}`);
+  }
+}
+
+/**
+ * Validates the versioned forge manifest without any filesystem or process
+ * access. It returns diagnostics instead of throwing so the caller can show
+ * a useful explanation and avoid writing an unsafe manifest.
+ */
+export function validaManifestForgeLocale(manifest) {
+  const diagnostics = [];
+  const add = (path, message) => diagnostics.push(`${path}: ${message}`);
+  if (!manifest || typeof manifest !== 'object') return { ok: false, diagnostica: ['manifest: must be an object'] };
+  let bytes;
+  try { bytes = new TextEncoder().encode(JSON.stringify(manifest)).length; } catch { bytes = Number.POSITIVE_INFINITY; }
+  if (bytes > MAX_MANIFEST_BYTES) add('manifest', `exceeds ${MAX_MANIFEST_BYTES} bytes`);
+  if (typeof manifest.id !== 'string' || !ID_PATTERN.test(manifest.id)) add('id', 'must be a lowercase slug, 3-64 chars, a-z0-9_- only');
+  if (typeof manifest.title !== 'string' || manifest.title.length < 1 || manifest.title.length > 80) add('title', 'must be 1-80 characters');
+  if (typeof manifest.description !== 'string' || manifest.description.length < 1 || manifest.description.length > 400) add('description', 'must be 1-400 characters');
+  const flow = manifest.flow;
+  if (!flow || typeof flow !== 'object') { add('flow', 'is required'); return { ok: false, diagnostica: diagnostics }; }
+  if (typeof flow.entry !== 'string' || flow.entry.length === 0) add('flow.entry', 'is required');
+  if (!Array.isArray(flow.nodes) || flow.nodes.length === 0) add('flow.nodes', 'must be a non-empty array');
+  if (Array.isArray(flow.nodes) && flow.nodes.length > MAX_NODES) add('flow.nodes', `exceeds ${MAX_NODES} nodes`);
+  const maxTransitions = Number(flow.maxTransitions);
+  if (!Number.isFinite(maxTransitions) || maxTransitions < 1 || maxTransitions > MAX_TRANSITIONS) add('flow.maxTransitions', `must be 1-${MAX_TRANSITIONS}`);
+  if (!Array.isArray(flow.nodes)) return { ok: false, diagnostica: diagnostics };
+  const ids = new Set();
+  const capabilities = new Set();
+  for (const [index, node] of flow.nodes.entries()) {
+    const path = `flow.nodes[${index}]`;
+    if (!node || typeof node !== 'object' || typeof node.id !== 'string' || node.id.length === 0) { add(path, 'must have a non-empty "id"'); continue; }
+    if (ids.has(node.id)) add(path, `duplicate node id "${node.id}"`);
+    ids.add(node.id);
+    if (!NODE_TYPES.includes(node.type)) { add(`${path}.type`, `must be one of ${NODE_TYPES.join(', ')}`); continue; }
+    if (node.type === 'capability') {
+      if (typeof node.capability !== 'string' || !CAPABILITIES[node.capability]) add(`${path}.capability`, `must be one of ${Object.keys(CAPABILITIES).join(', ')}`);
+      else capabilities.add(node.capability);
+      if (typeof node.next !== 'string' || node.next.length === 0) add(`${path}.next`, 'is required');
+      addReferenceDiagnostics(node.input, `${path}.input`, add);
+      if (node.target !== undefined) {
+        const violation = typeof node.target !== 'string' ? 'must be a string path' : forgePathViolation(node.target, { writable: true });
+        if (violation) add(`${path}.target`, violation);
+      }
+    } else if (node.type === 'if') {
+      if (!node.condition || typeof node.condition !== 'object') add(`${path}.condition`, 'is required');
+      else { addReferenceDiagnostics(node.condition.left, `${path}.condition`, add); addReferenceDiagnostics(node.condition.right, `${path}.condition`, add); }
+      if (typeof node.then !== 'string' || node.then.length === 0) add(`${path}.then`, 'is required');
+      if (typeof node.else !== 'string' || node.else.length === 0) add(`${path}.else`, 'is required');
+    } else if (node.type === 'return') {
+      addReferenceDiagnostics(node.value, `${path}.value`, add);
+    } else if (node.type === 'fail') {
+      if (typeof node.code !== 'string' || node.code.length === 0) add(`${path}.code`, 'is required');
+      if (typeof node.message !== 'string' || node.message.length === 0) add(`${path}.message`, 'is required');
+    }
+  }
+  if (diagnostics.length > 0) return { ok: false, diagnostica: diagnostics };
+  for (const node of flow.nodes) {
+    for (const field of ['next', 'then', 'else']) {
+      if (typeof node[field] === 'string' && !ids.has(node[field])) return { ok: false, diagnostica: [`flow: "${node[field]}" (referenced by node "${node.id}".${field}) is not a node id`] };
+    }
+  }
+  if (!ids.has(flow.entry)) return { ok: false, diagnostica: [`flow.entry: "${flow.entry}" is not a node id`] };
+  const actions = new Set();
+  let risk = 'R1';
+  for (const capability of capabilities) {
+    const descriptor = CAPABILITIES[capability];
+    for (const action of descriptor.actions) actions.add(action);
+    if (RISK_ORDER[descriptor.risk] > RISK_ORDER[risk]) risk = descriptor.risk;
+  }
+  return { ok: true, diagnostica: [], capacita: [...capabilities], azioni: [...actions], rischio: risk };
+}
+
+export const FORGE_PREFISSO_NOME_TOOL = 'forge_';
+
+export function forgeReadPath(root, path) {
+  if (path === '$') return root;
+  let current = root;
+  for (const segment of rawSegments(path)) {
+    if (current === null || typeof current !== 'object') return undefined;
+    if (Array.isArray(current) && /^\d+$/.test(segment)) { current = current[Number(segment)]; continue; }
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+export function forgeWritePath(root, path, value) {
+  const violation = forgePathViolation(path, { writable: true });
+  if (violation) throw new Error(`TALOS_FORGE_PATH_UNSAFE:${violation}`);
+  const parts = rawSegments(path);
+  if (parts.length === 0) throw new Error('TALOS_FORGE_SET_ROOT_FORBIDDEN');
+  let current = root;
+  for (const part of parts.slice(0, -1)) {
+    const existing = current[part];
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) current[part] = Object.create(null);
+    current = current[part];
+  }
+  current[parts.at(-1)] = value;
+}
+
+export function forgeResolveExpression(expression, vars) {
+  if (isReference(expression)) return forgeReadPath(vars, expression.$ref);
+  if (Array.isArray(expression)) return expression.map((value) => forgeResolveExpression(value, vars));
+  if (expression && typeof expression === 'object') return Object.fromEntries(Object.entries(expression).map(([key, value]) => [key, forgeResolveExpression(value, vars)]));
+  return expression;
+}
+
+export function forgeEvaluateCondition(condition, vars) {
+  const left = forgeResolveExpression(condition.left, vars);
+  const right = forgeResolveExpression(condition.right, vars);
+  switch (condition.op) {
+    case 'eq': return Object.is(left, right);
+    case 'neq': return !Object.is(left, right);
+    case 'truthy': return Boolean(left);
+    case 'exists': return left !== undefined && left !== null;
+    case 'contains': return typeof left === 'string' ? left.includes(String(right ?? '')) : Array.isArray(left) ? left.some((value) => Object.is(value, right)) : false;
+    case 'gt': return typeof left === 'number' && typeof right === 'number' && left > right;
+    case 'gte': return typeof left === 'number' && typeof right === 'number' && left >= right;
+    case 'lt': return typeof left === 'number' && typeof right === 'number' && left < right;
+    case 'lte': return typeof left === 'number' && typeof right === 'number' && left <= right;
+    default: return false;
+  }
+}
+
+export async function eseguiFlowForgeLocale(manifest, input, { capacitaFn } = {}) {
+  if (typeof capacitaFn !== 'function') throw new Error('TALOS_FORGE_CAPABILITY_UNAVAILABLE');
+  const vars = Object.create(null);
+  vars.input = input;
+  vars.state = Object.create(null);
+  const trace = [];
+  const nodes = new Map(manifest.flow.nodes.map((node) => [node.id, node]));
+  let currentId = manifest.flow.entry;
+  let transitions = 0;
+  const limit = Number.isFinite(manifest.flow.maxTransitions) ? Math.min(manifest.flow.maxTransitions, MAX_TRANSITIONS) : MAX_TRANSITIONS;
+  const pathFailure = (error) => ({ status: 'failed', error: { code: 'TALOS_FORGE_PATH_UNSAFE', message: error instanceof Error ? error.message : String(error) }, trace });
+  while (true) {
+    transitions += 1;
+    if (transitions > limit) return { status: 'failed', error: { code: 'TALOS_FORGE_MAX_TRANSITIONS', message: 'The tool ran too many steps without finishing.' }, trace };
+    const node = nodes.get(currentId);
+    if (!node) return { status: 'failed', error: { code: 'TALOS_FORGE_NODE_MISSING', message: `Node "${currentId}" does not exist.` }, trace };
+    if (node.type === 'capability') {
+      let resolved;
+      try { resolved = forgeResolveExpression(node.input, vars); } catch (error) { return pathFailure(error); }
+      let result;
+      try { result = await capacitaFn(node.capability, resolved); } catch (error) { return { status: 'failed', error: { code: 'TALOS_FORGE_CAPABILITY_FAILED', message: `Capability "${node.capability}" failed: ${error instanceof Error ? error.message : String(error)}` }, trace }; }
+      trace.push({ node: node.id, type: 'capability', capability: node.capability });
+      if (node.target) { try { forgeWritePath(vars, node.target, result); } catch (error) { return pathFailure(error); } }
+      currentId = node.next;
+    } else if (node.type === 'if') {
+      let outcome;
+      try { outcome = forgeEvaluateCondition(node.condition, vars); } catch (error) { return pathFailure(error); }
+      trace.push({ node: node.id, type: 'if', result: outcome });
+      currentId = outcome ? node.then : node.else;
+    } else if (node.type === 'return') {
+      let output;
+      try { output = forgeResolveExpression(node.value, vars); } catch (error) { return pathFailure(error); }
+      trace.push({ node: node.id, type: 'return' });
+      return { status: 'succeeded', output, trace };
+    } else if (node.type === 'fail') {
+      trace.push({ node: node.id, type: 'fail' });
+      return { status: 'failed', error: { code: node.code, message: node.message }, trace };
+    } else {
+      return { status: 'failed', error: { code: 'TALOS_FORGE_NODE_TYPE_UNKNOWN', message: `Unknown node type "${node.type}".` }, trace };
+    }
+  }
+}
+

package/vendor/harness-ui/src/frequent-dirs.mjs

@@ -0,0 +1,134 @@
+/**
+ * frequent-dirs.mjs — owner, coda del piano `elegant-spinning-dongarra.md`:
+ * "nella lista file quando si crea una sessione, bisogna mettere directory
+ * più usate (tipo desktop downloads etc)". Solo LETTURA, solo suggerimenti:
+ * questo file non decide se una cartella è AMMESSA — quello resta
+ * `custom-task.mjs`/`avviaLibero` (permesso "Full access", vedi la sua doc
+ * sul perché niente denylist), qui si limita a proporre percorsi VERI e
+ * VERIFICATI, mai una scorciatoia verso il nulla.
+ *
+ * ⛔⛔⛔ 30/8, CORRETTO — owner dal vivo: "come mai non ho le cartelle più
+ * usate?" La prima versione (28/8) calcolava SOLO dalle cartelle utente
+ * standard di Windows (`os.homedir()`) — sempre le stesse tre, MAI la
+ * cronologia reale, quindi mai davvero "più usate". Ora la fonte PRIMARIA
+ * è `sessionRegistry.cartellePiuUsate()` (cronologia reale delle
+ * sessioni, aggregata in `session-registry.mjs`); le tre cartelle
+ * Windows standard restano SOLO il ripiego onesto per l'avvio a freddo
+ * (zero sessioni mai partite) — vedi `cartelleFrequenti()` sotto.
+ *
+ * ⛔ Deliberatamente SEPARATO da `config.mjs#parseCartelleProgetto`: quella
+ * è l'allowlist fissa dell'amministratore, validata fail-closed all'AVVIO
+ * del server. Questa è un elenco DINAMICO, calcolato a ogni richiesta —
+ * le due liste non si mescolano MAI: le cartelle frequenti sono solo
+ * suggerimenti per il campo "Full access" (percorso a piacere), non una
+ * seconda allowlist che aggirerebbe il permesso.
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { statSync } from 'node:fs';
+
+/**
+ * ⭐ Le stesse TRE cartelle che ogni file manager Windows mostra per
+ * default nella barra laterale ("Quick access") — non inventate, sono i
+ * nomi di cartella standard sotto il profilo utente su ogni installazione
+ * Windows moderna. Il ripiego onesto per l'avvio a freddo (nessuna
+ * cronologia reale ancora), MAI mescolate con essa — vedi doc di testa.
+ */
+const CANDIDATE = Object.freeze([
+  { etichetta: 'Desktop', sottocartella: 'Desktop' },
+  { etichetta: 'Download', sottocartella: 'Downloads' },
+  { etichetta: 'Documenti', sottocartella: 'Documents' },
+]);
+
+/**
+ * ⭐⭐⭐ 30/8 — owner dal vivo: "come mai non ho le cartelle più usate?"
+ * Le tre cartelle Windows standard sopra NON erano mai state "più usate"
+ * per davvero — erano SEMPRE le stesse, indipendentemente da cosa
+ * l'owner avesse effettivamente aperto. Ora la fonte VERA
+ * (`sessionRegistry.cartellePiuUsate()`, aggregata dalla cronologia reale
+ * delle sessioni) ha priorità; le cartelle Windows standard restano
+ * SOLO il ripiego onesto per l'avvio a freddo (zero sessioni mai
+ * partite) — mai sparire del tutto, mai fingere una cronologia che non
+ * c'è.
+ *
+ * @param {number} massimoRisultati — quante suggerirne al massimo (il campo è solo un aiuto, non un elenco esaustivo).
+ * @returns {Array<{percorso:string, conteggio:number, ultimaVolta:string}>}
+ */
+function candidatiDaCronologia(sessionRegistry, massimoRisultati) {
+  if (!sessionRegistry || typeof sessionRegistry.cartellePiuUsate !== 'function') return [];
+  return sessionRegistry.cartellePiuUsate().slice(0, massimoRisultati);
+}
+
+function cartellaReale(percorso, statSyncFn) {
+  try {
+    return statSyncFn(percorso).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function cartelleStandard({ homedirFn, statSyncFn }) {
+  const home = homedirFn();
+  return CANDIDATE.flatMap(({ etichetta, sottocartella }) => {
+    const percorso = join(home, sottocartella);
+    return cartellaReale(percorso, statSyncFn) ? [{ etichetta, percorso }] : [];
+  });
+}
+
+function chiavePercorso(percorso) {
+  return resolve(percorso).replace(/[\\/]+$/, '').toLocaleLowerCase('en-US');
+}
+
+/**
+ * @param {{homedirFn?: typeof homedir, statSyncFn?: typeof statSync, sessionRegistry?: {cartellePiuUsate: () => Array<{percorso:string, conteggio:number, ultimaVolta:string}>}}} [deps] — `sessionRegistry` opzionale: assente nei test che provano solo il ripiego Windows, sempre presente dal server reale (vedi http-app.mjs).
+ * @returns {Array<{etichetta:string, percorso:string}>} — SOLO le cartelle che esistono
+ *   davvero sul disco in questo momento, mai una candidata a occhio: una
+ *   cartella cancellata dall'owner (Download standard, o una copia
+ *   usa-e-getta del corpus benchmark ormai ripulita) non deve comparire
+ *   come scorciatoia verso il nulla.
+ */
+export function cartelleFrequenti({ homedirFn = homedir, statSyncFn = statSync, sessionRegistry } = {}) {
+  const MASSIMO = 6;
+  const daCronologia = candidatiDaCronologia(sessionRegistry, MASSIMO);
+  const trovate = [];
+  for (const { percorso } of daCronologia) {
+    if (!cartellaReale(percorso, statSyncFn)) continue;
+    // ⭐ etichetta = nome dell'ultima cartella nel percorso ("qa-visiva-harness-2026-08-30" da ...\projects\qa-visiva-harness-2026-08-30), stesso principio di nomeCartella lato client (app.js, split su [\\/]).
+    const etichetta = percorso.replace(/[/\\]+$/, '').split(/[/\\]/).pop() || percorso;
+    trovate.push({ etichetta, percorso });
+  }
+  if (trovate.length > 0) return trovate; // ⛔ cronologia reale disponibile: MAI mescolarla con Desktop/Downloads/Documenti sotto — quelle tre non sono "più usate", solo il ripiego a freddo.
+  return cartelleStandard({ homedirFn, statSyncFn });
+}
+
+/**
+ * Scelte rapide della workbench "Nuova sessione". A differenza del contratto
+ * storico `cartelleFrequenti()` (che resta identico), qui l'owner ha bisogno
+ * sia della cronologia vera sia delle cartelle standard realmente presenti.
+ * L'unione è solo presentazione: non crea una allowlist e non modifica i
+ * permessi della sessione.
+ *
+ * @returns {Array<{etichetta:string, percorso:string, tipo:'recent'|'known'}>}
+ */
+export function cartelleConsigliate({ homedirFn = homedir, statSyncFn = statSync, sessionRegistry } = {}) {
+  const trovate = [];
+  const viste = new Set();
+  for (const { percorso } of candidatiDaCronologia(sessionRegistry, 6)) {
+    if (!cartellaReale(percorso, statSyncFn)) continue;
+    const chiave = chiavePercorso(percorso);
+    if (viste.has(chiave)) continue;
+    viste.add(chiave);
+    trovate.push({
+      etichetta: percorso.replace(/[/\\]+$/, '').split(/[/\\]/).pop() || percorso,
+      percorso,
+      tipo: 'recent',
+    });
+  }
+  for (const { etichetta, percorso } of cartelleStandard({ homedirFn, statSyncFn })) {
+    const chiave = chiavePercorso(percorso);
+    if (viste.has(chiave)) continue;
+    viste.add(chiave);
+    trovate.push({ etichetta, percorso, tipo: 'known' });
+  }
+  return trovate;
+}

package/vendor/harness-ui/src/generated-image-store.mjs

@@ -0,0 +1,147 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+
+/**
+ * Durable local store for images produced by an agent run.
+ *
+ * The workspace copy remains the user-facing Library item. This store is the
+ * recovery copy: it is written atomically, carries a small JSON sidecar, and
+ * can be reopened by a fresh process after a server restart. No remote URL is
+ * retained as the image itself.
+ */
+export const GENERATED_IMAGE_MIME_TYPES = Object.freeze({
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+  'image/avif': 'avif',
+});
+
+const ID = /^[a-f0-9]{64}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+
+export class GeneratedImageStoreError extends Error {
+  constructor(message, code = 'TALOS_IMAGE_PERSIST_FAILED') {
+    super(message);
+    this.name = 'GeneratedImageStoreError';
+    this.code = code;
+  }
+}
+
+function asBytes(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  throw new GeneratedImageStoreError('image bytes are missing or invalid', 'TALOS_IMAGE_PERSIST_INVALID');
+}
+
+function validatePromptHash(value) {
+  if (value == null || value === '') return null;
+  if (typeof value !== 'string' || !SHA256.test(value)) throw new GeneratedImageStoreError('image prompt hash is invalid', 'TALOS_IMAGE_PERSIST_INVALID');
+  return value;
+}
+
+function validateSource(value) {
+  if (typeof value !== 'string' || value.trim() === '' || value.length > 512 || /[\0\r\n]/u.test(value)) {
+    throw new GeneratedImageStoreError('image source is invalid', 'TALOS_IMAGE_PERSIST_INVALID');
+  }
+  return value.trim();
+}
+
+function safeId({ bytes, source, promptHash }) {
+  const digest = createHash('sha256');
+  digest.update(bytes);
+  digest.update('\0');
+  digest.update(source);
+  digest.update('\0');
+  digest.update(promptHash ?? '');
+  return digest.digest('hex');
+}
+
+function parseMetadata(value, id) {
+  if (!value || typeof value !== 'object' || value.id !== id || typeof value.mimeType !== 'string' || !Object.hasOwn(GENERATED_IMAGE_MIME_TYPES, value.mimeType) || typeof value.source !== 'string' || (value.promptHash !== null && !SHA256.test(value.promptHash)) || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || !SHA256.test(value.sha256) || typeof value.createdAt !== 'string' || !Number.isFinite(Date.parse(value.createdAt))) {
+    throw new GeneratedImageStoreError('stored image metadata is invalid', 'TALOS_IMAGE_PERSIST_CORRUPT');
+  }
+  return structuredClone(value);
+}
+
+export function createGeneratedImageStore({ rootDir, fsImpl = {}, now = () => new Date() } = {}) {
+  if (typeof rootDir !== 'string' || !rootDir.trim() || !resolve(rootDir)) throw new GeneratedImageStoreError('generated image store root is invalid', 'TALOS_IMAGE_PERSIST_CONFIG_INVALID');
+  const fs = { mkdir, readFile, rename, rm, stat, writeFile, ...fsImpl };
+  const imageDir = resolve(rootDir);
+
+  const paths = (id, mimeType) => {
+    if (typeof id !== 'string' || !ID.test(id)) throw new GeneratedImageStoreError('stored image id is invalid', 'TALOS_IMAGE_PERSIST_INVALID');
+    const extension = GENERATED_IMAGE_MIME_TYPES[mimeType];
+    return {
+      bytes: join(imageDir, `${id}.${extension}`),
+      metadata: join(imageDir, `${id}.json`),
+    };
+  };
+
+  async function persistGeneratedImage({ bytes: rawBytes, mimeType, source, promptHash = null } = {}) {
+    const bytes = asBytes(rawBytes);
+    if (bytes.byteLength === 0) throw new GeneratedImageStoreError('empty image cannot be saved', 'TALOS_IMAGE_PERSIST_INVALID');
+    if (typeof mimeType !== 'string' || !Object.hasOwn(GENERATED_IMAGE_MIME_TYPES, mimeType)) throw new GeneratedImageStoreError('image format is not supported', 'TALOS_IMAGE_PERSIST_INVALID');
+    const normalizedSource = validateSource(source);
+    const normalizedPromptHash = validatePromptHash(promptHash);
+    const id = safeId({ bytes, source: normalizedSource, promptHash: normalizedPromptHash });
+    const destination = paths(id, mimeType);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    const metadata = {
+      schema: 'talos.generated-image.v1', id, mimeType, source: normalizedSource,
+      promptHash: normalizedPromptHash, bytes: bytes.byteLength, sha256, createdAt: now().toISOString(),
+    };
+    await fs.mkdir(imageDir, { recursive: true });
+    const temporaryBytes = `${destination.bytes}.tmp-${process.pid}-${randomUUID()}`;
+    const temporaryMetadata = `${destination.metadata}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+      await fs.writeFile(temporaryBytes, bytes, { flag: 'wx' });
+      await fs.writeFile(temporaryMetadata, `${JSON.stringify(metadata)}\n`, { encoding: 'utf8', flag: 'wx' });
+      await fs.rename(temporaryBytes, destination.bytes);
+      await fs.rename(temporaryMetadata, destination.metadata);
+    } catch (error) {
+      await fs.rm(temporaryBytes, { force: true }).catch(() => {});
+      await fs.rm(temporaryMetadata, { force: true }).catch(() => {});
+      // A deterministic id means a retry of the same response is safe: if a
+      // complete pair is already present, reopen and return it instead of
+      // pretending that the second write was a new image.
+      if (error?.code === 'EEXIST') {
+        const existing = await readGeneratedImage(id).catch(() => null);
+        if (existing?.sha256 === sha256 && existing.mimeType === mimeType) return existing;
+      }
+      throw new GeneratedImageStoreError(`image could not be saved safely: ${error?.message ?? String(error)}`);
+    }
+    return { ...metadata, path: destination.bytes };
+  }
+
+  async function readGeneratedImage(id) {
+    if (typeof id !== 'string' || !ID.test(id)) throw new GeneratedImageStoreError('stored image id is invalid', 'TALOS_IMAGE_PERSIST_INVALID');
+    let metadata;
+    try { metadata = parseMetadata(JSON.parse(await fs.readFile(join(imageDir, `${id}.json`), 'utf8')), id); }
+    catch (error) {
+      if (error instanceof GeneratedImageStoreError) throw error;
+      if (error?.code === 'ENOENT') throw new GeneratedImageStoreError('stored image was not found', 'TALOS_IMAGE_PERSIST_NOT_FOUND');
+      throw new GeneratedImageStoreError(`stored image metadata could not be read: ${error?.message ?? String(error)}`, 'TALOS_IMAGE_PERSIST_CORRUPT');
+    }
+    const destination = paths(id, metadata.mimeType);
+    let bytes;
+    try { bytes = await fs.readFile(destination.bytes); }
+    catch (error) { throw new GeneratedImageStoreError(`stored image bytes could not be read: ${error?.message ?? String(error)}`, 'TALOS_IMAGE_PERSIST_CORRUPT'); }
+    if (bytes.byteLength !== metadata.bytes || createHash('sha256').update(bytes).digest('hex') !== metadata.sha256) throw new GeneratedImageStoreError('stored image checksum does not match', 'TALOS_IMAGE_PERSIST_CORRUPT');
+    return { ...metadata, bytes: Buffer.from(bytes), path: destination.bytes };
+  }
+
+  async function removeGeneratedImage(id) {
+    const metadataPath = join(imageDir, `${id}.json`);
+    let metadata;
+    try { metadata = parseMetadata(JSON.parse(await fs.readFile(metadataPath, 'utf8')), id); }
+    catch (error) { if (error?.code === 'ENOENT') return false; throw error; }
+    await fs.rm(paths(id, metadata.mimeType).bytes, { force: true });
+    await fs.rm(metadataPath, { force: true });
+    return true;
+  }
+
+  return Object.freeze({ persistGeneratedImage, readGeneratedImage, removeGeneratedImage });
+}
+