@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/wiki/almacen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"almacen.js","sourceRoot":"","sources":["../../../src/core/wiki/almacen.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dónde vive la wiki y cómo se indexa.\n *\n * En `<proyecto>/<configDir>/wiki/`: páginas en Markdown y un `citas.json` con\n * la huella de cada cita. Va dentro del proyecto y no en el agentDir a\n * propósito — es documentación del repositorio, debe poder versionarse y\n * revisarse en un pull request como cualquier otro fichero.\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { join, relative, resolve } from \"node:path\";\nimport { type Afirmacion, type Cita, extraerCitas, huellaDeTexto } from \"./citas.ts\";\n\nexport interface Wiki {\n\tversion: 1;\n\tafirmaciones: Afirmacion[];\n}\n\nconst VACIA: Wiki = { version: 1, afirmaciones: [] };\n\nexport function rutaWiki(cwd: string, configDirName: string): string {\n\treturn join(cwd, configDirName, \"wiki\");\n}\n\nexport function leerWiki(cwd: string, configDirName: string): Wiki {\n\tconst fichero = join(rutaWiki(cwd, configDirName), \"citas.json\");\n\tif (!existsSync(fichero)) return { ...VACIA };\n\ttry {\n\t\tconst datos = JSON.parse(readFileSync(fichero, \"utf8\")) as Wiki;\n\t\treturn Array.isArray(datos.afirmaciones) ? datos : { ...VACIA };\n\t} catch {\n\t\t// Un citas.json corrupto no puede impedir regenerar la wiki.\n\t\treturn { ...VACIA };\n\t}\n}\n\nexport function escribirWiki(cwd: string, configDirName: string, wiki: Wiki): void {\n\tconst dir = rutaWiki(cwd, configDirName);\n\tmkdirSync(dir, { recursive: true });\n\twriteFileSync(join(dir, \"citas.json\"), `${JSON.stringify(wiki, null, 2)}\\n`, \"utf8\");\n}\n\n/**\n * Lector de ficheros del proyecto, con la raíz cerrada.\n *\n * Una cita es texto que puede haber escrito un modelo. Sin esta comprobación,\n * `../../.ssh/id_rsa` en una página de la wiki haría que `wiki check` leyera\n * cualquier cosa del disco.\n */\nexport function lectorDelProyecto(cwd: string): (fichero: string) => string | null {\n\tconst raiz = resolve(cwd);\n\treturn (fichero) => {\n\t\tconst absoluta = resolve(raiz, fichero);\n\t\tconst dentro = relative(raiz, absoluta);\n\t\tif (dentro.startsWith(\"..\") || resolve(raiz, dentro) !== absoluta) return null;\n\t\ttry {\n\t\t\treturn readFileSync(absoluta, \"utf8\");\n\t\t} catch {\n\t\t\treturn null;\n\t\t}\n\t};\n}\n\n/**\n * Indexa las páginas Markdown: saca sus citas y les calcula la huella.\n *\n * Cada párrafo no vacío es una afirmación. Es una regla tonta a propósito: si\n * el troceado fuera listo, dos ejecuciones sobre el mismo texto podrían dar\n * afirmaciones distintas y el fichero de citas cambiaría sin que cambiara nada.\n */\nexport function indexarPaginas(cwd: string, configDirName: string): Wiki {\n\tconst dir = rutaWiki(cwd, configDirName);\n\tif (!existsSync(dir)) return { ...VACIA };\n\tconst leer = lectorDelProyecto(cwd);\n\tconst afirmaciones: Afirmacion[] = [];\n\n\tfor (const fichero of readdirSync(dir)\n\t\t.filter((f) => f.endsWith(\".md\"))\n\t\t.sort()) {\n\t\tconst contenido = readFileSync(join(dir, fichero), \"utf8\");\n\t\tconst parrafos = contenido\n\t\t\t.split(/\\n\\s*\\n/)\n\t\t\t.map((p) => p.trim())\n\t\t\t.filter(Boolean);\n\t\tparrafos.forEach((parrafo, i) => {\n\t\t\tconst citas: Cita[] = [];\n\t\t\tfor (const sinHuella of extraerCitas(parrafo)) {\n\t\t\t\tconst fuente = leer(sinHuella.fichero);\n\t\t\t\tif (fuente === null) continue;\n\t\t\t\tconst lineas = fuente.split(\"\\n\").slice(sinHuella.desde - 1, sinHuella.hasta);\n\t\t\t\tif (lineas.length === 0) continue;\n\t\t\t\tcitas.push({ ...sinHuella, huella: huellaDeTexto(lineas) });\n\t\t\t}\n\t\t\tafirmaciones.push({ id: `${fichero}#${i}`, texto: parrafo.slice(0, 400), citas });\n\t\t});\n\t}\n\treturn { version: 1, afirmaciones };\n}\n"]}

package/dist/core/wiki/citas.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Citas verificables para la wiki del repositorio.
+ *
+ * Una wiki generada por un modelo envejece mal: describe un código que ya no
+ * existe y nadie se entera hasta que alguien la sigue y pierde una tarde. La
+ * diferencia que buscamos no es generar mejor prosa, es que **cada afirmación
+ * lleve su cita a `fichero:línea` y se sepa cuándo deja de ser cierta**.
+ *
+ * Aquí vive esa parte. Es pura: recibe texto y contenidos de fichero, no toca
+ * disco ni llama a ningún modelo.
+ *
+ * La decisión que la hace útil en vez de molesta: si las líneas citadas
+ * **cambiaron**, la afirmación queda obsoleta; pero si solo se **movieron** —el
+ * mismo texto está más arriba o más abajo— la cita se reubica y la afirmación
+ * sigue viva. Sin eso, insertar un import al principio de un fichero invalidaría
+ * cada cita del fichero entero, la wiki daría cientos de falsos positivos y en
+ * dos días nadie volvería a mirarla.
+ */
+export interface Cita {
+    fichero: string;
+    /** 1-indexado e inclusivo, como lo escribe la gente. */
+    desde: number;
+    hasta: number;
+    /** Huella del texto citado cuando se escribió la afirmación. */
+    huella: string;
+}
+export interface Afirmacion {
+    id: string;
+    texto: string;
+    citas: Cita[];
+}
+export type EstadoCita = {
+    estado: "vigente";
+    cita: Cita;
+} | {
+    estado: "movida";
+    cita: Cita;
+    desde: number;
+    hasta: number;
+} | {
+    estado: "obsoleta";
+    cita: Cita;
+    motivo: string;
+};
+/**
+ * Huella del texto citado.
+ *
+ * Se normaliza el final de línea y los espacios al final de cada línea: un
+ * formateador que quita un espacio sobrante no cambia lo que el código dice, y
+ * marcar eso como obsoleto entrenaría a todo el mundo a ignorar los avisos.
+ * La indentación de la izquierda SÍ cuenta: en un lenguaje con bloques, mover
+ * algo de nivel sí cambia lo que hace.
+ */
+export declare function huellaDeTexto(lineas: string[]): string;
+/**
+ * Busca el texto citado en otro sitio del fichero.
+ *
+ * Devuelve la primera línea (1-indexada) donde encaja el bloque entero, o
+ * `null`. Es una búsqueda literal por bloques, no difusa: reubicar una cita
+ * sobre un parecido sería peor que declararla obsoleta, porque la afirmación
+ * pasaría a apuntar a un código que no es el suyo.
+ */
+export declare function buscarBloque(lineas: string[], huella: string, alto: number): number | null;
+/**
+ * Comprueba una cita contra el contenido actual del fichero.
+ *
+ * `contenido` es `null` si el fichero ya no existe.
+ */
+export declare function verificarCita(cita: Cita, contenido: string | null): EstadoCita;
+export interface EstadoAfirmacion {
+    afirmacion: Afirmacion;
+    citas: EstadoCita[];
+    /** Obsoleta si CUALQUIERA de sus citas lo está. Ver más abajo. */
+    obsoleta: boolean;
+}
+/**
+ * Comprueba una afirmación entera.
+ *
+ * Basta una cita obsoleta para marcarla: una afirmación apoyada en tres trozos
+ * de código de los que uno ya no dice lo que decía es, como mínimo,
+ * sospechosa. Exigir que fallen todas dejaría pasar justo el caso peligroso —
+ * la media verdad.
+ */
+export declare function verificarAfirmacion(afirmacion: Afirmacion, leer: (fichero: string) => string | null): EstadoAfirmacion;
+export interface ResumenWiki {
+    total: number;
+    vigentes: number;
+    movidas: number;
+    obsoletas: number;
+    sinCitas: number;
+    detalles: EstadoAfirmacion[];
+}
+export declare function verificarWiki(afirmaciones: Afirmacion[], leer: (fichero: string) => string | null): ResumenWiki;
+/**
+ * Reescribe las citas que solo se movieron.
+ *
+ * Devuelve las afirmaciones con las líneas actualizadas; las obsoletas se
+ * dejan intactas a propósito: arreglarlas requiere leer el código nuevo y
+ * decidir si la frase sigue siendo cierta, y eso no lo hace un `replace`.
+ */
+export declare function reubicarCitas(resumen: ResumenWiki): Afirmacion[];
+/** `fichero:12-30` o `fichero:12`. Es lo que la gente escribe a mano. */
+export declare function formatearCita(cita: Cita): string;
+/**
+ * Saca las citas de un texto en Markdown.
+ *
+ * Sin huella: quien escribe a mano no la conoce. La calcula quien indexa, que
+ * es el que tiene el fichero delante.
+ */
+export declare function extraerCitas(markdown: string): Array<Omit<Cita, "huella">>;
+//# sourceMappingURL=citas.d.ts.map

package/dist/core/wiki/citas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citas.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/citas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,IAAI;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,MAAM,UAAU,GACnB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACjC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAGtD;AAOD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CA2B9E;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,oEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACtC,gBAAgB,CAGlB;AAED,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,wBAAgB,aAAa,CAAC,YAAY,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,WAAW,CAiB/G;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,EAAE,CAOhE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEhD;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAQ1E","sourcesContent":["/**\n * Citas verificables para la wiki del repositorio.\n *\n * Una wiki generada por un modelo envejece mal: describe un código que ya no\n * existe y nadie se entera hasta que alguien la sigue y pierde una tarde. La\n * diferencia que buscamos no es generar mejor prosa, es que **cada afirmación\n * lleve su cita a `fichero:línea` y se sepa cuándo deja de ser cierta**.\n *\n * Aquí vive esa parte. Es pura: recibe texto y contenidos de fichero, no toca\n * disco ni llama a ningún modelo.\n *\n * La decisión que la hace útil en vez de molesta: si las líneas citadas\n * **cambiaron**, la afirmación queda obsoleta; pero si solo se **movieron** —el\n * mismo texto está más arriba o más abajo— la cita se reubica y la afirmación\n * sigue viva. Sin eso, insertar un import al principio de un fichero invalidaría\n * cada cita del fichero entero, la wiki daría cientos de falsos positivos y en\n * dos días nadie volvería a mirarla.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport interface Cita {\n\tfichero: string;\n\t/** 1-indexado e inclusivo, como lo escribe la gente. */\n\tdesde: number;\n\thasta: number;\n\t/** Huella del texto citado cuando se escribió la afirmación. */\n\thuella: string;\n}\n\nexport interface Afirmacion {\n\tid: string;\n\ttexto: string;\n\tcitas: Cita[];\n}\n\nexport type EstadoCita =\n\t| { estado: \"vigente\"; cita: Cita }\n\t| { estado: \"movida\"; cita: Cita; desde: number; hasta: number }\n\t| { estado: \"obsoleta\"; cita: Cita; motivo: string };\n\n/**\n * Huella del texto citado.\n *\n * Se normaliza el final de línea y los espacios al final de cada línea: un\n * formateador que quita un espacio sobrante no cambia lo que el código dice, y\n * marcar eso como obsoleto entrenaría a todo el mundo a ignorar los avisos.\n * La indentación de la izquierda SÍ cuenta: en un lenguaje con bloques, mover\n * algo de nivel sí cambia lo que hace.\n */\nexport function huellaDeTexto(lineas: string[]): string {\n\tconst normalizado = lineas.map((l) => l.replace(/\\s+$/, \"\")).join(\"\\n\");\n\treturn createHash(\"sha256\").update(normalizado).digest(\"hex\").slice(0, 16);\n}\n\nfunction extraer(lineas: string[], desde: number, hasta: number): string[] | null {\n\tif (desde < 1 || hasta < desde || hasta > lineas.length) return null;\n\treturn lineas.slice(desde - 1, hasta);\n}\n\n/**\n * Busca el texto citado en otro sitio del fichero.\n *\n * Devuelve la primera línea (1-indexada) donde encaja el bloque entero, o\n * `null`. Es una búsqueda literal por bloques, no difusa: reubicar una cita\n * sobre un parecido sería peor que declararla obsoleta, porque la afirmación\n * pasaría a apuntar a un código que no es el suyo.\n */\nexport function buscarBloque(lineas: string[], huella: string, alto: number): number | null {\n\tif (alto <= 0 || alto > lineas.length) return null;\n\tfor (let inicio = 0; inicio + alto <= lineas.length; inicio++) {\n\t\tif (huellaDeTexto(lineas.slice(inicio, inicio + alto)) === huella) return inicio + 1;\n\t}\n\treturn null;\n}\n\n/**\n * Comprueba una cita contra el contenido actual del fichero.\n *\n * `contenido` es `null` si el fichero ya no existe.\n */\nexport function verificarCita(cita: Cita, contenido: string | null): EstadoCita {\n\tif (contenido === null) {\n\t\treturn { estado: \"obsoleta\", cita, motivo: `el fichero ${cita.fichero} ya no existe` };\n\t}\n\tconst lineas = contenido.split(\"\\n\");\n\tconst alto = cita.hasta - cita.desde + 1;\n\n\tconst enSuSitio = extraer(lineas, cita.desde, cita.hasta);\n\tif (enSuSitio && huellaDeTexto(enSuSitio) === cita.huella) {\n\t\treturn { estado: \"vigente\", cita };\n\t}\n\n\t// Puede que solo se haya movido. Ver la cabecera: sin esto, un import nuevo\n\t// al principio invalidaría todas las citas del fichero.\n\tconst nuevoInicio = buscarBloque(lineas, cita.huella, alto);\n\tif (nuevoInicio !== null) {\n\t\treturn { estado: \"movida\", cita, desde: nuevoInicio, hasta: nuevoInicio + alto - 1 };\n\t}\n\n\treturn {\n\t\testado: \"obsoleta\",\n\t\tcita,\n\t\tmotivo:\n\t\t\tenSuSitio === null\n\t\t\t\t? `${cita.fichero} ya no llega a la línea ${cita.hasta}`\n\t\t\t\t: `las líneas ${cita.desde}-${cita.hasta} de ${cita.fichero} han cambiado`,\n\t};\n}\n\nexport interface EstadoAfirmacion {\n\tafirmacion: Afirmacion;\n\tcitas: EstadoCita[];\n\t/** Obsoleta si CUALQUIERA de sus citas lo está. Ver más abajo. */\n\tobsoleta: boolean;\n}\n\n/**\n * Comprueba una afirmación entera.\n *\n * Basta una cita obsoleta para marcarla: una afirmación apoyada en tres trozos\n * de código de los que uno ya no dice lo que decía es, como mínimo,\n * sospechosa. Exigir que fallen todas dejaría pasar justo el caso peligroso —\n * la media verdad.\n */\nexport function verificarAfirmacion(\n\tafirmacion: Afirmacion,\n\tleer: (fichero: string) => string | null,\n): EstadoAfirmacion {\n\tconst citas = afirmacion.citas.map((c) => verificarCita(c, leer(c.fichero)));\n\treturn { afirmacion, citas, obsoleta: citas.some((c) => c.estado === \"obsoleta\") };\n}\n\nexport interface ResumenWiki {\n\ttotal: number;\n\tvigentes: number;\n\tmovidas: number;\n\tobsoletas: number;\n\tsinCitas: number;\n\tdetalles: EstadoAfirmacion[];\n}\n\nexport function verificarWiki(afirmaciones: Afirmacion[], leer: (fichero: string) => string | null): ResumenWiki {\n\tconst detalles = afirmaciones.map((a) => verificarAfirmacion(a, leer));\n\treturn {\n\t\ttotal: detalles.length,\n\t\t// Exige al menos una cita: `[].every()` es true, así que sin este filtro\n\t\t// una afirmación sin respaldo se contaba como verificada — que es\n\t\t// exactamente la mentira que esta wiki existe para evitar.\n\t\tvigentes: detalles.filter(\n\t\t\t(d) => d.afirmacion.citas.length > 0 && !d.obsoleta && d.citas.every((c) => c.estado === \"vigente\"),\n\t\t).length,\n\t\tmovidas: detalles.filter((d) => !d.obsoleta && d.citas.some((c) => c.estado === \"movida\")).length,\n\t\tobsoletas: detalles.filter((d) => d.obsoleta).length,\n\t\t// Una afirmación sin cita no es documentación, es una opinión. Se cuenta\n\t\t// aparte para que se vea cuánta wiki no está respaldada por nada.\n\t\tsinCitas: detalles.filter((d) => d.afirmacion.citas.length === 0).length,\n\t\tdetalles,\n\t};\n}\n\n/**\n * Reescribe las citas que solo se movieron.\n *\n * Devuelve las afirmaciones con las líneas actualizadas; las obsoletas se\n * dejan intactas a propósito: arreglarlas requiere leer el código nuevo y\n * decidir si la frase sigue siendo cierta, y eso no lo hace un `replace`.\n */\nexport function reubicarCitas(resumen: ResumenWiki): Afirmacion[] {\n\treturn resumen.detalles.map(({ afirmacion, citas }) => ({\n\t\t...afirmacion,\n\t\tcitas: citas.map((estado) =>\n\t\t\testado.estado === \"movida\" ? { ...estado.cita, desde: estado.desde, hasta: estado.hasta } : estado.cita,\n\t\t),\n\t}));\n}\n\n/** `fichero:12-30` o `fichero:12`. Es lo que la gente escribe a mano. */\nexport function formatearCita(cita: Cita): string {\n\treturn cita.desde === cita.hasta ? `${cita.fichero}:${cita.desde}` : `${cita.fichero}:${cita.desde}-${cita.hasta}`;\n}\n\nconst PATRON_CITA = /([\\w./@-]+\\.\\w+):(\\d+)(?:-(\\d+))?/g;\n\n/**\n * Saca las citas de un texto en Markdown.\n *\n * Sin huella: quien escribe a mano no la conoce. La calcula quien indexa, que\n * es el que tiene el fichero delante.\n */\nexport function extraerCitas(markdown: string): Array<Omit<Cita, \"huella\">> {\n\tconst encontradas: Array<Omit<Cita, \"huella\">> = [];\n\tfor (const m of markdown.matchAll(PATRON_CITA)) {\n\t\tconst desde = Number(m[2]);\n\t\tconst hasta = m[3] ? Number(m[3]) : desde;\n\t\tif (desde >= 1 && hasta >= desde) encontradas.push({ fichero: m[1], desde, hasta });\n\t}\n\treturn encontradas;\n}\n"]}

package/dist/core/wiki/citas.js

@@ -0,0 +1,146 @@
+/**
+ * Citas verificables para la wiki del repositorio.
+ *
+ * Una wiki generada por un modelo envejece mal: describe un código que ya no
+ * existe y nadie se entera hasta que alguien la sigue y pierde una tarde. La
+ * diferencia que buscamos no es generar mejor prosa, es que **cada afirmación
+ * lleve su cita a `fichero:línea` y se sepa cuándo deja de ser cierta**.
+ *
+ * Aquí vive esa parte. Es pura: recibe texto y contenidos de fichero, no toca
+ * disco ni llama a ningún modelo.
+ *
+ * La decisión que la hace útil en vez de molesta: si las líneas citadas
+ * **cambiaron**, la afirmación queda obsoleta; pero si solo se **movieron** —el
+ * mismo texto está más arriba o más abajo— la cita se reubica y la afirmación
+ * sigue viva. Sin eso, insertar un import al principio de un fichero invalidaría
+ * cada cita del fichero entero, la wiki daría cientos de falsos positivos y en
+ * dos días nadie volvería a mirarla.
+ */
+import { createHash } from "node:crypto";
+/**
+ * Huella del texto citado.
+ *
+ * Se normaliza el final de línea y los espacios al final de cada línea: un
+ * formateador que quita un espacio sobrante no cambia lo que el código dice, y
+ * marcar eso como obsoleto entrenaría a todo el mundo a ignorar los avisos.
+ * La indentación de la izquierda SÍ cuenta: en un lenguaje con bloques, mover
+ * algo de nivel sí cambia lo que hace.
+ */
+export function huellaDeTexto(lineas) {
+    const normalizado = lineas.map((l) => l.replace(/\s+$/, "")).join("\n");
+    return createHash("sha256").update(normalizado).digest("hex").slice(0, 16);
+}
+function extraer(lineas, desde, hasta) {
+    if (desde < 1 || hasta < desde || hasta > lineas.length)
+        return null;
+    return lineas.slice(desde - 1, hasta);
+}
+/**
+ * Busca el texto citado en otro sitio del fichero.
+ *
+ * Devuelve la primera línea (1-indexada) donde encaja el bloque entero, o
+ * `null`. Es una búsqueda literal por bloques, no difusa: reubicar una cita
+ * sobre un parecido sería peor que declararla obsoleta, porque la afirmación
+ * pasaría a apuntar a un código que no es el suyo.
+ */
+export function buscarBloque(lineas, huella, alto) {
+    if (alto <= 0 || alto > lineas.length)
+        return null;
+    for (let inicio = 0; inicio + alto <= lineas.length; inicio++) {
+        if (huellaDeTexto(lineas.slice(inicio, inicio + alto)) === huella)
+            return inicio + 1;
+    }
+    return null;
+}
+/**
+ * Comprueba una cita contra el contenido actual del fichero.
+ *
+ * `contenido` es `null` si el fichero ya no existe.
+ */
+export function verificarCita(cita, contenido) {
+    if (contenido === null) {
+        return { estado: "obsoleta", cita, motivo: `el fichero ${cita.fichero} ya no existe` };
+    }
+    const lineas = contenido.split("\n");
+    const alto = cita.hasta - cita.desde + 1;
+    const enSuSitio = extraer(lineas, cita.desde, cita.hasta);
+    if (enSuSitio && huellaDeTexto(enSuSitio) === cita.huella) {
+        return { estado: "vigente", cita };
+    }
+    // Puede que solo se haya movido. Ver la cabecera: sin esto, un import nuevo
+    // al principio invalidaría todas las citas del fichero.
+    const nuevoInicio = buscarBloque(lineas, cita.huella, alto);
+    if (nuevoInicio !== null) {
+        return { estado: "movida", cita, desde: nuevoInicio, hasta: nuevoInicio + alto - 1 };
+    }
+    return {
+        estado: "obsoleta",
+        cita,
+        motivo: enSuSitio === null
+            ? `${cita.fichero} ya no llega a la línea ${cita.hasta}`
+            : `las líneas ${cita.desde}-${cita.hasta} de ${cita.fichero} han cambiado`,
+    };
+}
+/**
+ * Comprueba una afirmación entera.
+ *
+ * Basta una cita obsoleta para marcarla: una afirmación apoyada en tres trozos
+ * de código de los que uno ya no dice lo que decía es, como mínimo,
+ * sospechosa. Exigir que fallen todas dejaría pasar justo el caso peligroso —
+ * la media verdad.
+ */
+export function verificarAfirmacion(afirmacion, leer) {
+    const citas = afirmacion.citas.map((c) => verificarCita(c, leer(c.fichero)));
+    return { afirmacion, citas, obsoleta: citas.some((c) => c.estado === "obsoleta") };
+}
+export function verificarWiki(afirmaciones, leer) {
+    const detalles = afirmaciones.map((a) => verificarAfirmacion(a, leer));
+    return {
+        total: detalles.length,
+        // Exige al menos una cita: `[].every()` es true, así que sin este filtro
+        // una afirmación sin respaldo se contaba como verificada — que es
+        // exactamente la mentira que esta wiki existe para evitar.
+        vigentes: detalles.filter((d) => d.afirmacion.citas.length > 0 && !d.obsoleta && d.citas.every((c) => c.estado === "vigente")).length,
+        movidas: detalles.filter((d) => !d.obsoleta && d.citas.some((c) => c.estado === "movida")).length,
+        obsoletas: detalles.filter((d) => d.obsoleta).length,
+        // Una afirmación sin cita no es documentación, es una opinión. Se cuenta
+        // aparte para que se vea cuánta wiki no está respaldada por nada.
+        sinCitas: detalles.filter((d) => d.afirmacion.citas.length === 0).length,
+        detalles,
+    };
+}
+/**
+ * Reescribe las citas que solo se movieron.
+ *
+ * Devuelve las afirmaciones con las líneas actualizadas; las obsoletas se
+ * dejan intactas a propósito: arreglarlas requiere leer el código nuevo y
+ * decidir si la frase sigue siendo cierta, y eso no lo hace un `replace`.
+ */
+export function reubicarCitas(resumen) {
+    return resumen.detalles.map(({ afirmacion, citas }) => ({
+        ...afirmacion,
+        citas: citas.map((estado) => estado.estado === "movida" ? { ...estado.cita, desde: estado.desde, hasta: estado.hasta } : estado.cita),
+    }));
+}
+/** `fichero:12-30` o `fichero:12`. Es lo que la gente escribe a mano. */
+export function formatearCita(cita) {
+    return cita.desde === cita.hasta ? `${cita.fichero}:${cita.desde}` : `${cita.fichero}:${cita.desde}-${cita.hasta}`;
+}
+const PATRON_CITA = /([\w./@-]+\.\w+):(\d+)(?:-(\d+))?/g;
+/**
+ * Saca las citas de un texto en Markdown.
+ *
+ * Sin huella: quien escribe a mano no la conoce. La calcula quien indexa, que
+ * es el que tiene el fichero delante.
+ */
+export function extraerCitas(markdown) {
+    const encontradas = [];
+    for (const m of markdown.matchAll(PATRON_CITA)) {
+        const desde = Number(m[2]);
+        const hasta = m[3] ? Number(m[3]) : desde;
+        if (desde >= 1 && hasta >= desde)
+            encontradas.push({ fichero: m[1], desde, hasta });
+    }
+    return encontradas;
+}
+//# sourceMappingURL=citas.js.map

package/dist/core/wiki/citas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citas.js","sourceRoot":"","sources":["../../../src/core/wiki/citas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Citas verificables para la wiki del repositorio.\n *\n * Una wiki generada por un modelo envejece mal: describe un código que ya no\n * existe y nadie se entera hasta que alguien la sigue y pierde una tarde. La\n * diferencia que buscamos no es generar mejor prosa, es que **cada afirmación\n * lleve su cita a `fichero:línea` y se sepa cuándo deja de ser cierta**.\n *\n * Aquí vive esa parte. Es pura: recibe texto y contenidos de fichero, no toca\n * disco ni llama a ningún modelo.\n *\n * La decisión que la hace útil en vez de molesta: si las líneas citadas\n * **cambiaron**, la afirmación queda obsoleta; pero si solo se **movieron** —el\n * mismo texto está más arriba o más abajo— la cita se reubica y la afirmación\n * sigue viva. Sin eso, insertar un import al principio de un fichero invalidaría\n * cada cita del fichero entero, la wiki daría cientos de falsos positivos y en\n * dos días nadie volvería a mirarla.\n */\n\nimport { createHash } from \"node:crypto\";\n\nexport interface Cita {\n\tfichero: string;\n\t/** 1-indexado e inclusivo, como lo escribe la gente. */\n\tdesde: number;\n\thasta: number;\n\t/** Huella del texto citado cuando se escribió la afirmación. */\n\thuella: string;\n}\n\nexport interface Afirmacion {\n\tid: string;\n\ttexto: string;\n\tcitas: Cita[];\n}\n\nexport type EstadoCita =\n\t| { estado: \"vigente\"; cita: Cita }\n\t| { estado: \"movida\"; cita: Cita; desde: number; hasta: number }\n\t| { estado: \"obsoleta\"; cita: Cita; motivo: string };\n\n/**\n * Huella del texto citado.\n *\n * Se normaliza el final de línea y los espacios al final de cada línea: un\n * formateador que quita un espacio sobrante no cambia lo que el código dice, y\n * marcar eso como obsoleto entrenaría a todo el mundo a ignorar los avisos.\n * La indentación de la izquierda SÍ cuenta: en un lenguaje con bloques, mover\n * algo de nivel sí cambia lo que hace.\n */\nexport function huellaDeTexto(lineas: string[]): string {\n\tconst normalizado = lineas.map((l) => l.replace(/\\s+$/, \"\")).join(\"\\n\");\n\treturn createHash(\"sha256\").update(normalizado).digest(\"hex\").slice(0, 16);\n}\n\nfunction extraer(lineas: string[], desde: number, hasta: number): string[] | null {\n\tif (desde < 1 || hasta < desde || hasta > lineas.length) return null;\n\treturn lineas.slice(desde - 1, hasta);\n}\n\n/**\n * Busca el texto citado en otro sitio del fichero.\n *\n * Devuelve la primera línea (1-indexada) donde encaja el bloque entero, o\n * `null`. Es una búsqueda literal por bloques, no difusa: reubicar una cita\n * sobre un parecido sería peor que declararla obsoleta, porque la afirmación\n * pasaría a apuntar a un código que no es el suyo.\n */\nexport function buscarBloque(lineas: string[], huella: string, alto: number): number | null {\n\tif (alto <= 0 || alto > lineas.length) return null;\n\tfor (let inicio = 0; inicio + alto <= lineas.length; inicio++) {\n\t\tif (huellaDeTexto(lineas.slice(inicio, inicio + alto)) === huella) return inicio + 1;\n\t}\n\treturn null;\n}\n\n/**\n * Comprueba una cita contra el contenido actual del fichero.\n *\n * `contenido` es `null` si el fichero ya no existe.\n */\nexport function verificarCita(cita: Cita, contenido: string | null): EstadoCita {\n\tif (contenido === null) {\n\t\treturn { estado: \"obsoleta\", cita, motivo: `el fichero ${cita.fichero} ya no existe` };\n\t}\n\tconst lineas = contenido.split(\"\\n\");\n\tconst alto = cita.hasta - cita.desde + 1;\n\n\tconst enSuSitio = extraer(lineas, cita.desde, cita.hasta);\n\tif (enSuSitio && huellaDeTexto(enSuSitio) === cita.huella) {\n\t\treturn { estado: \"vigente\", cita };\n\t}\n\n\t// Puede que solo se haya movido. Ver la cabecera: sin esto, un import nuevo\n\t// al principio invalidaría todas las citas del fichero.\n\tconst nuevoInicio = buscarBloque(lineas, cita.huella, alto);\n\tif (nuevoInicio !== null) {\n\t\treturn { estado: \"movida\", cita, desde: nuevoInicio, hasta: nuevoInicio + alto - 1 };\n\t}\n\n\treturn {\n\t\testado: \"obsoleta\",\n\t\tcita,\n\t\tmotivo:\n\t\t\tenSuSitio === null\n\t\t\t\t? `${cita.fichero} ya no llega a la línea ${cita.hasta}`\n\t\t\t\t: `las líneas ${cita.desde}-${cita.hasta} de ${cita.fichero} han cambiado`,\n\t};\n}\n\nexport interface EstadoAfirmacion {\n\tafirmacion: Afirmacion;\n\tcitas: EstadoCita[];\n\t/** Obsoleta si CUALQUIERA de sus citas lo está. Ver más abajo. */\n\tobsoleta: boolean;\n}\n\n/**\n * Comprueba una afirmación entera.\n *\n * Basta una cita obsoleta para marcarla: una afirmación apoyada en tres trozos\n * de código de los que uno ya no dice lo que decía es, como mínimo,\n * sospechosa. Exigir que fallen todas dejaría pasar justo el caso peligroso —\n * la media verdad.\n */\nexport function verificarAfirmacion(\n\tafirmacion: Afirmacion,\n\tleer: (fichero: string) => string | null,\n): EstadoAfirmacion {\n\tconst citas = afirmacion.citas.map((c) => verificarCita(c, leer(c.fichero)));\n\treturn { afirmacion, citas, obsoleta: citas.some((c) => c.estado === \"obsoleta\") };\n}\n\nexport interface ResumenWiki {\n\ttotal: number;\n\tvigentes: number;\n\tmovidas: number;\n\tobsoletas: number;\n\tsinCitas: number;\n\tdetalles: EstadoAfirmacion[];\n}\n\nexport function verificarWiki(afirmaciones: Afirmacion[], leer: (fichero: string) => string | null): ResumenWiki {\n\tconst detalles = afirmaciones.map((a) => verificarAfirmacion(a, leer));\n\treturn {\n\t\ttotal: detalles.length,\n\t\t// Exige al menos una cita: `[].every()` es true, así que sin este filtro\n\t\t// una afirmación sin respaldo se contaba como verificada — que es\n\t\t// exactamente la mentira que esta wiki existe para evitar.\n\t\tvigentes: detalles.filter(\n\t\t\t(d) => d.afirmacion.citas.length > 0 && !d.obsoleta && d.citas.every((c) => c.estado === \"vigente\"),\n\t\t).length,\n\t\tmovidas: detalles.filter((d) => !d.obsoleta && d.citas.some((c) => c.estado === \"movida\")).length,\n\t\tobsoletas: detalles.filter((d) => d.obsoleta).length,\n\t\t// Una afirmación sin cita no es documentación, es una opinión. Se cuenta\n\t\t// aparte para que se vea cuánta wiki no está respaldada por nada.\n\t\tsinCitas: detalles.filter((d) => d.afirmacion.citas.length === 0).length,\n\t\tdetalles,\n\t};\n}\n\n/**\n * Reescribe las citas que solo se movieron.\n *\n * Devuelve las afirmaciones con las líneas actualizadas; las obsoletas se\n * dejan intactas a propósito: arreglarlas requiere leer el código nuevo y\n * decidir si la frase sigue siendo cierta, y eso no lo hace un `replace`.\n */\nexport function reubicarCitas(resumen: ResumenWiki): Afirmacion[] {\n\treturn resumen.detalles.map(({ afirmacion, citas }) => ({\n\t\t...afirmacion,\n\t\tcitas: citas.map((estado) =>\n\t\t\testado.estado === \"movida\" ? { ...estado.cita, desde: estado.desde, hasta: estado.hasta } : estado.cita,\n\t\t),\n\t}));\n}\n\n/** `fichero:12-30` o `fichero:12`. Es lo que la gente escribe a mano. */\nexport function formatearCita(cita: Cita): string {\n\treturn cita.desde === cita.hasta ? `${cita.fichero}:${cita.desde}` : `${cita.fichero}:${cita.desde}-${cita.hasta}`;\n}\n\nconst PATRON_CITA = /([\\w./@-]+\\.\\w+):(\\d+)(?:-(\\d+))?/g;\n\n/**\n * Saca las citas de un texto en Markdown.\n *\n * Sin huella: quien escribe a mano no la conoce. La calcula quien indexa, que\n * es el que tiene el fichero delante.\n */\nexport function extraerCitas(markdown: string): Array<Omit<Cita, \"huella\">> {\n\tconst encontradas: Array<Omit<Cita, \"huella\">> = [];\n\tfor (const m of markdown.matchAll(PATRON_CITA)) {\n\t\tconst desde = Number(m[2]);\n\t\tconst hasta = m[3] ? Number(m[3]) : desde;\n\t\tif (desde >= 1 && hasta >= desde) encontradas.push({ fichero: m[1], desde, hasta });\n\t}\n\treturn encontradas;\n}\n"]}

package/dist/core/workflows/agent-runner.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AgentRunner — subagente del Ada Intelligence Engine.
+ *
+ * Un subagente es una sesión del SDK (AgentSessionRuntime via createAgentSession)
+ * con: modelo resuelto (spec/tier/fallback), tools configuradas, cwd (base o
+ * worktree), instructions opcionales y límites (timeout, retries). El runner
+ * captura la respuesta final, el structured output (schema typebox con fallback
+ * a extracción de prosa) y el usage real (tokens/coste).
+ *
+ * La creación de la sesión es inyectable (createSession) para tests con fakes.
+ */
+import type { TSchema } from "typebox";
+import type { AgentSession } from "../agent-session.ts";
+import type { ToolDefinition } from "../extensions/types.ts";
+import type { AgentRunOptions, AgentRunResult, AgentUsage, WorkflowErrorCode } from "./types.ts";
+export interface SubagentSession {
+    session: AgentSession;
+    dispose(): void;
+    getUsage(): AgentUsage;
+}
+export type CreateSubagentSession = (options: {
+    cwd: string;
+    agentDir: string;
+    modelSpec?: string;
+    tools?: string[];
+    customTools?: ToolDefinition[];
+    sessionName?: string;
+    instructions?: string;
+}) => Promise<SubagentSession>;
+export interface AgentRunnerOptions {
+    agentDir: string;
+    createSession: CreateSubagentSession;
+    /** Limiter compartido del run (concurrency). */
+    limiter: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Contador global de agentes del run (maxAgents). */
+    agentCounter: {
+        count: number;
+    };
+    /** Techo de agentes por run (`workflows.maxAgentsPerRun`). */
+    maxAgents: number;
+    retries?: number;
+    agentTimeoutMs?: number | null;
+}
+/** Hash de identidad del agente para el journal (prompt+model+phase+schema+stableKey). */
+export declare function agentIdentityHash(options: {
+    prompt: string;
+    model?: string;
+    tier?: string;
+    phase?: string;
+    stableKey?: string;
+    schema?: TSchema | undefined;
+}): string;
+/** Extraer el texto de una respuesta (string o content array). */
+export declare function messageText(content: unknown): string;
+/** Extraer JSON del texto (para structured output fallback). */
+export declare function extractJson(text: string): unknown | undefined;
+/**
+ * Allowlist de tools del subagente.
+ *
+ * Desenreda un bug latente: `options.tools` son tools EXTRA (web_search…) y se
+ * pasaban a la vez como `customTools` y como allowlist, de modo que pedir una
+ * tool extra ESTRECHABA el permiso en silencio a solo esa — un agente que pedía
+ * `web_search` perdía `read`/`bash`/`edit`/`write` sin que nadie lo notara.
+ * Ahora las extra se SUMAN a la base, que es lo que el nombre siempre prometió.
+ */
+export declare function resolveAllowedTools(options: {
+    readOnly?: boolean;
+    web?: boolean;
+    browser?: boolean;
+    tools?: Array<{
+        name: string;
+    }>;
+}): string[];
+export declare class AgentRunner {
+    private agentDir;
+    private createSession;
+    private limiter;
+    private agentCounter;
+    private maxAgents;
+    private retries;
+    private agentTimeoutMs;
+    constructor(options: AgentRunnerOptions);
+    run<T = unknown>(options: AgentRunOptions): Promise<AgentRunResult<T> | null>;
+    private runOnce;
+}
+/** Tipos re-exportados para el index. */
+export type { WorkflowErrorCode };
+//# sourceMappingURL=agent-runner.d.ts.map

package/dist/core/workflows/agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../src/core/workflows/agent-runner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * AgentRunner — subagente del Ada Intelligence Engine.\n *\n * Un subagente es una sesión del SDK (AgentSessionRuntime via createAgentSession)\n * con: modelo resuelto (spec/tier/fallback), tools configuradas, cwd (base o\n * worktree), instructions opcionales y límites (timeout, retries). El runner\n * captura la respuesta final, el structured output (schema typebox con fallback\n * a extracción de prosa) y el usage real (tokens/coste).\n *\n * La creación de la sesión es inyectable (createSession) para tests con fakes.\n */\n\nimport { createHash } from \"node:crypto\";\nimport type { TextContent } from \"@earendil-works/pi-ai\";\nimport type { TSchema } from \"typebox\";\nimport type { AgentSession, AgentSessionEvent } from \"../agent-session.ts\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport { validarConReintentos } from \"./contrato/validador.ts\";\nimport { BufferDeHallazgos, crearHerramientaYield, ensamblarResultadoIncremental } from \"./contrato/yield.ts\";\nimport type { AgentRunOptions, AgentRunResult, AgentUsage, WorkflowErrorCode } from \"./types.ts\";\nimport { WorkflowError } from \"./types.ts\";\nimport { createWorktree, finalizeWorktree, type Worktree } from \"./worktree.ts\";\n\nexport interface SubagentSession {\n\tsession: AgentSession;\n\tdispose(): void;\n\tgetUsage(): AgentUsage;\n}\n\nexport type CreateSubagentSession = (options: {\n\tcwd: string;\n\tagentDir: string;\n\tmodelSpec?: string;\n\ttools?: string[];\n\tcustomTools?: ToolDefinition[];\n\tsessionName?: string;\n\tinstructions?: string;\n}) => Promise<SubagentSession>;\n\nexport interface AgentRunnerOptions {\n\tagentDir: string;\n\tcreateSession: CreateSubagentSession;\n\t/** Limiter compartido del run (concurrency). */\n\tlimiter: <T>(fn: () => Promise<T>) => Promise<T>;\n\t/** Contador global de agentes del run (maxAgents). */\n\tagentCounter: { count: number };\n\t/** Techo de agentes por run (`workflows.maxAgentsPerRun`). */\n\tmaxAgents: number;\n\tretries?: number;\n\tagentTimeoutMs?: number | null;\n}\n\n/** Hash de identidad del agente para el journal (prompt+model+phase+schema+stableKey). */\nexport function agentIdentityHash(options: {\n\tprompt: string;\n\tmodel?: string;\n\ttier?: string;\n\tphase?: string;\n\tstableKey?: string;\n\tschema?: TSchema | undefined;\n}): string {\n\tconst canonical = JSON.stringify({\n\t\tprompt: options.prompt,\n\t\tmodel: options.model ?? null,\n\t\ttier: options.tier ?? null,\n\t\tphase: options.phase ?? null,\n\t\tstableKey: options.stableKey ?? null,\n\t\tschema: options.schema ? JSON.stringify(options.schema) : null,\n\t});\n\treturn createHash(\"sha256\").update(canonical).digest(\"hex\");\n}\n\n/** Extraer el texto de una respuesta (string o content array). */\nexport function messageText(content: unknown): string {\n\tif (typeof content === \"string\") return content;\n\tif (!Array.isArray(content)) return \"\";\n\treturn content\n\t\t.filter((b): b is TextContent => typeof b === \"object\" && b !== null && (b as { type?: string }).type === \"text\")\n\t\t.map((b) => b.text ?? \"\")\n\t\t.join(\"\\n\")\n\t\t.trim();\n}\n\n/** Extraer JSON del texto (para structured output fallback). */\nexport function extractJson(text: string): unknown | undefined {\n\tconst cleaned = text\n\t\t.replace(/```json\\s*/g, \"\")\n\t\t.replace(/```/g, \"\")\n\t\t.trim();\n\tconst start = cleaned.indexOf(\"{\");\n\tconst end = cleaned.lastIndexOf(\"}\");\n\tif (start === -1 || end === -1) return undefined;\n\ttry {\n\t\treturn JSON.parse(cleaned.slice(start, end + 1));\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Tools por defecto de un subagente (espejo de sdk.ts:263), MÁS `yield`\n * siempre — es la tool de entrega incremental (ver contrato/yield.ts) y no es\n * un permiso adicional: reportar un hallazgo no lee ni escribe nada que las\n * tools base ya no autoricen. Un subagente que nunca la llama se comporta\n * exactamente como antes.\n */\nconst SUBAGENT_DEFAULT_TOOLS = [\"read\", \"bash\", \"edit\", \"write\", \"yield\"];\n/**\n * Mínimo privilegio: leer y buscar, nada de escribir ni ejecutar. `yield`\n * también aquí — un agente de solo lectura cuyo trabajo ES encontrar cosas\n * necesita poder reportarlas.\n */\nconst SUBAGENT_READONLY_TOOLS = [\"read\", \"grep\", \"find\", \"ls\", \"yield\"];\n/** Red: nunca implícitas, ni siquiera bajo `readOnly`. Ver resolveAllowedTools. */\nconst WEB_TOOL_NAMES = [\"web_search\", \"web_fetch\"];\n/** Navegador: opt-in aparte de `web`. Conducir un navegador no es leer una URL. */\nconst BROWSER_TOOL_NAMES = [\n\t\"browser_open\",\n\t\"browser_navigate\",\n\t\"browser_read\",\n\t\"browser_click\",\n\t\"browser_type\",\n\t\"browser_screenshot\",\n\t\"browser_viewport\",\n\t\"browser_close\",\n];\n\n/**\n * Allowlist de tools del subagente.\n *\n * Desenreda un bug latente: `options.tools` son tools EXTRA (web_search…) y se\n * pasaban a la vez como `customTools` y como allowlist, de modo que pedir una\n * tool extra ESTRECHABA el permiso en silencio a solo esa — un agente que pedía\n * `web_search` perdía `read`/`bash`/`edit`/`write` sin que nadie lo notara.\n * Ahora las extra se SUMAN a la base, que es lo que el nombre siempre prometió.\n */\nexport function resolveAllowedTools(options: {\n\treadOnly?: boolean;\n\tweb?: boolean;\n\tbrowser?: boolean;\n\ttools?: Array<{ name: string }>;\n}): string[] {\n\tconst base = options.readOnly ? SUBAGENT_READONLY_TOOLS : SUBAGENT_DEFAULT_TOOLS;\n\tconst extras = (options.tools ?? []).map((t) => t.name);\n\t// El acceso a red es opt-in aunque `web_fetch` sea \"de lectura\": leer la web\n\t// no es leer el disco. Un subagente con red es una vía de salida para lo que\n\t// haya leído, así que el script tiene que pedirlo por su nombre.\n\tconst web = options.web ? WEB_TOOL_NAMES : [];\n\t// `browser` no se hereda de `web`: descargar una URL y conducir un navegador\n\t// con sesión, formularios y capturas no son el mismo permiso.\n\tconst navegador = options.browser ? BROWSER_TOOL_NAMES : [];\n\treturn [...new Set([...base, ...web, ...navegador, ...extras])];\n}\n\nexport class AgentRunner {\n\tprivate agentDir: string;\n\tprivate createSession: CreateSubagentSession;\n\tprivate limiter: AgentRunnerOptions[\"limiter\"];\n\tprivate agentCounter: AgentRunnerOptions[\"agentCounter\"];\n\tprivate maxAgents: number;\n\tprivate retries: number;\n\tprivate agentTimeoutMs: number | null;\n\n\tconstructor(options: AgentRunnerOptions) {\n\t\tthis.agentDir = options.agentDir;\n\t\tthis.createSession = options.createSession;\n\t\tthis.limiter = options.limiter;\n\t\tthis.agentCounter = options.agentCounter;\n\t\tthis.maxAgents = options.maxAgents;\n\t\tthis.retries = options.retries ?? 3;\n\t\tthis.agentTimeoutMs = options.agentTimeoutMs ?? null;\n\t}\n\n\tasync run<T = unknown>(options: AgentRunOptions): Promise<AgentRunResult<T> | null> {\n\t\treturn this.limiter(async () => {\n\t\t\tif (this.agentCounter.count >= this.maxAgents) {\n\t\t\t\tthrow new WorkflowError(\n\t\t\t\t\t\"WORKFLOW_MAX_AGENTS\",\n\t\t\t\t\t`Límite de agentes del run alcanzado (${this.maxAgents}). Súbelo con el ajuste workflows.maxAgentsPerRun.`,\n\t\t\t\t\t{ recoverable: false },\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.agentCounter.count++;\n\n\t\t\tlet attempt = 0;\n\t\t\tlet lastError: Error | undefined;\n\t\t\tfor (; attempt <= this.retries; attempt++) {\n\t\t\t\tconst signal = options.signal;\n\t\t\t\tif (signal?.aborted) return null;\n\t\t\t\ttry {\n\t\t\t\t\treturn await this.runOnce<T>(options, signal);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (signal?.aborted) return null;\n\t\t\t\t\tif (isAbortError(error) || isTimeoutError(error)) throw error;\n\t\t\t\t\tlastError = error instanceof Error ? error : new Error(String(error));\n\t\t\t\t\tif (attempt >= this.retries) break;\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError) throw lastError;\n\t\t\treturn null;\n\t\t});\n\t}\n\n\tprivate async runOnce<T>(options: AgentRunOptions, signal?: AbortSignal): Promise<AgentRunResult<T> | null> {\n\t\t// Timeout combinado: el del agente + el del run.\n\t\tconst timeoutMs = options.timeoutMs ?? this.agentTimeoutMs;\n\t\tlet timeoutTimer: ReturnType<typeof setTimeout> | undefined;\n\t\tconst timeout = new Promise<never>((_resolve, reject) => {\n\t\t\tif (timeoutMs === null) return;\n\t\t\ttimeoutTimer = setTimeout(() => {\n\t\t\t\treject(\n\t\t\t\t\tnew WorkflowError(\"WORKFLOW_AGENT_TIMEOUT\", `Agent timed out after ${timeoutMs}ms`, {\n\t\t\t\t\t\trecoverable: false,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}, timeoutMs);\n\t\t});\n\n\t\tconst baseCwd = options.cwd ?? process.cwd();\n\t\t// Aislamiento git: los agentes con escritura que corren en paralelo\n\t\t// editaban el MISMO checkout y se pisaban en silencio. El nombre es\n\t\t// determinista (isolationKey = runId:callIndex) para que un resume\n\t\t// reencuentre el mismo worktree. Fuera de un repo git hace no-op.\n\t\tlet worktree: Worktree | null = null;\n\t\tlet finalized: { branch?: string; kept: boolean } | undefined;\n\t\tconst worktreeMessage = `ada: ${options.label ?? options.isolationKey ?? \"agent\"}`;\n\t\tif (options.isolation === \"worktree\") {\n\t\t\tworktree = await createWorktree(baseCwd, options.isolationKey ?? options.label ?? \"agent\");\n\t\t}\n\n\t\tlet subagent: SubagentSession | null = null;\n\t\t// Hallazgos entregados por `yield` durante ESTE intento. Sobreviven aunque\n\t\t// el subagente se descarrile más abajo — ese es el motivo de que exista.\n\t\tconst buffer = new BufferDeHallazgos();\n\t\ttry {\n\t\t\tsubagent = await this.createSession({\n\t\t\t\tcwd: worktree?.cwd ?? baseCwd,\n\t\t\t\tagentDir: this.agentDir,\n\t\t\t\tmodelSpec: options.model ?? (options.tier ? `tier:${options.tier}` : undefined),\n\t\t\t\ttools: resolveAllowedTools(options),\n\t\t\t\tcustomTools: [...(options.tools ?? []), crearHerramientaYield({ buffer, onEntrega: options.onYield })],\n\t\t\t\tsessionName: options.label ? `workflow:${options.label}` : undefined,\n\t\t\t\tinstructions: options.instructions,\n\t\t\t});\n\t\t\tconst session = subagent.session;\n\n\t\t\tconst lastAssistantText: string[] = [];\n\t\t\tconst unsubscribe = session.subscribe((event: AgentSessionEvent) => {\n\t\t\t\tif (event.type === \"message_end\" && event.message.role === \"assistant\") {\n\t\t\t\t\tconst text = messageText(event.message.content);\n\t\t\t\t\tif (text) lastAssistantText.push(text);\n\t\t\t\t}\n\t\t\t});\n\n\t\t\tconst sessionId = () =>\n\t\t\t\t(session as { sessionManager?: { getSessionId?: () => string } }).sessionManager?.getSessionId?.();\n\t\t\tlet textoFinal = \"\";\n\t\t\ttry {\n\t\t\t\ttry {\n\t\t\t\t\tawait Promise.race([session.sendUserMessage(options.prompt), timeout]);\n\t\t\t\t\tawait Promise.race([session.waitForIdle(), timeout]);\n\t\t\t\t\tif (signal?.aborted) return null;\n\n\t\t\t\t\ttextoFinal = lastAssistantText.length > 0 ? lastAssistantText[lastAssistantText.length - 1] : \"\";\n\t\t\t\t\tlet result: T | null = null;\n\t\t\t\t\tlet validacion: AgentRunResult<T>[\"validacion\"];\n\n\t\t\t\t\tif (options.schema) {\n\t\t\t\t\t\tconst resultado = await validarConReintentos<T>({\n\t\t\t\t\t\t\tesquema: options.schema,\n\t\t\t\t\t\t\ttextoInicial: textoFinal,\n\t\t\t\t\t\t\tmaxReintentos: options.maxReintentosValidacion ?? 2,\n\t\t\t\t\t\t\textraer: extractJson,\n\t\t\t\t\t\t\tpedirCorreccion: async (mensaje) => {\n\t\t\t\t\t\t\t\tawait Promise.race([session.sendUserMessage(mensaje), timeout]);\n\t\t\t\t\t\t\t\tawait Promise.race([session.waitForIdle(), timeout]);\n\t\t\t\t\t\t\t\tif (lastAssistantText.length > 0) textoFinal = lastAssistantText[lastAssistantText.length - 1];\n\t\t\t\t\t\t\t\treturn textoFinal;\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t});\n\t\t\t\t\t\tresult = resultado.datos;\n\t\t\t\t\t\tvalidacion = {\n\t\t\t\t\t\t\tvalido: resultado.valido,\n\t\t\t\t\t\t\tintentos: resultado.intentos,\n\t\t\t\t\t\t\treparado: resultado.reparado,\n\t\t\t\t\t\t\terrores: resultado.errores,\n\t\t\t\t\t\t};\n\t\t\t\t\t} else {\n\t\t\t\t\t\tresult = (textoFinal.length > 0 ? textoFinal : null) as unknown as T;\n\t\t\t\t\t}\n\n\t\t\t\t\t// Consolidar el worktree ANTES de devolver: si solo lo retirásemos, los\n\t\t\t\t\t// cambios sin commitear del agente se perderían y el aislamiento no\n\t\t\t\t\t// habría servido de nada. La rama sobrevive para que un humano la\n\t\t\t\t\t// mergee; no hay auto-merge a propósito.\n\t\t\t\t\tif (worktree && !finalized) {\n\t\t\t\t\t\tfinalized = await finalizeWorktree(worktree, worktreeMessage);\n\t\t\t\t\t}\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult,\n\t\t\t\t\t\ttext: textoFinal,\n\t\t\t\t\t\tusage: subagent.getUsage(),\n\t\t\t\t\t\tsessionId: sessionId(),\n\t\t\t\t\t\tworktreeBranch: finalized?.branch,\n\t\t\t\t\t\t...(validacion ? { validacion } : {}),\n\t\t\t\t\t\t...(buffer.longitud > 0 ? { hallazgos: buffer.todos() } : {}),\n\t\t\t\t\t} as AgentRunResult<T>;\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// YIELD FINAL FORZADO. El subagente se descarriló (timeout, error del\n\t\t\t\t\t// SDK, lo que sea) EN CUALQUIER PUNTO del intercambio — incluida la\n\t\t\t\t\t// ronda de corrección de esquema. Si ya había entregado hallazgos con\n\t\t\t\t\t// `yield`, eso NO se pierde: es justo lo que este contrato existe para\n\t\t\t\t\t// evitar (\"lo más importante\", según la tarea).\n\t\t\t\t\t//\n\t\t\t\t\t// Sin hallazgos que salvar esto es un fallo real (\"no pude\", no \"no\n\t\t\t\t\t// hay\") y se propaga tal cual — mismo comportamiento que antes de este\n\t\t\t\t\t// cambio, para no enmascarar errores genuinos con un resultado vacío.\n\t\t\t\t\t//\n\t\t\t\t\t// Un abort (`signal.aborted`) NUNCA entra en el yield final forzado,\n\t\t\t\t\t// aunque haya hallazgos: cancelar significa \"para del todo\", igual que\n\t\t\t\t\t// ya hacía el camino de éxito (línea de arriba, `if (signal?.aborted)\n\t\t\t\t\t// return null`) con un resultado completo y válido. Si esto cambiara,\n\t\t\t\t\t// el workflow trataría una cancelación como un resultado parcial\n\t\t\t\t\t// utilizable y seguiría a la siguiente fase con datos a medias.\n\t\t\t\t\tif (signal?.aborted || buffer.longitud === 0) throw error;\n\t\t\t\t\tconst motivo = error instanceof Error ? error.message : String(error);\n\t\t\t\t\tif (worktree && !finalized) {\n\t\t\t\t\t\tfinalized = await finalizeWorktree(worktree, worktreeMessage);\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tresult: ensamblarResultadoIncremental(buffer) as unknown as T,\n\t\t\t\t\t\ttext: textoFinal,\n\t\t\t\t\t\tusage: subagent.getUsage(),\n\t\t\t\t\t\tsessionId: sessionId(),\n\t\t\t\t\t\tworktreeBranch: finalized?.branch,\n\t\t\t\t\t\tdescarrilado: true,\n\t\t\t\t\t\tmotivoDescarrile: motivo,\n\t\t\t\t\t\thallazgos: buffer.todos(),\n\t\t\t\t\t} as AgentRunResult<T>;\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tunsubscribe();\n\t\t\t}\n\t\t} finally {\n\t\t\tif (timeoutTimer) clearTimeout(timeoutTimer);\n\t\t\tsubagent?.dispose();\n\t\t\t// Camino de error/abort sin hallazgos que salvar: el return no llegó a\n\t\t\t// consolidar, pero el trabajo parcial del agente también merece\n\t\t\t// sobrevivir para poder inspeccionarlo — y hay que soltar el worktree\n\t\t\t// igualmente.\n\t\t\tif (worktree && !finalized) {\n\t\t\t\tfinalized = await finalizeWorktree(worktree, worktreeMessage);\n\t\t\t}\n\t\t}\n\t}\n}\n\nfunction isAbortError(error: unknown): boolean {\n\treturn error instanceof Error && error.name === \"AbortError\";\n}\n\nfunction isTimeoutError(error: unknown): boolean {\n\treturn error instanceof WorkflowError && error.code === \"WORKFLOW_AGENT_TIMEOUT\";\n}\n\n/** Tipos re-exportados para el index. */\nexport type { WorkflowErrorCode };\n"]}