xonecode 0.38.44 → 0.39.4

package/dist/agent/subagentes/subagenteExterno.d.ts

@@ -0,0 +1,169 @@
+/**
+ * El adaptador que lanza un agente de OTRO producto sobre la carpeta del proyecto.
+ *
+ * Dos motores, y cada uno por su camino porque no se parecen en nada. **Claude Code** va
+ * por su SDK oficial (`@anthropic-ai/claude-agent-sdk`) y se le deniegan las escrituras con
+ * `canUseTool`, un callback nuestro. **Codex** va por su `app-server --stdio`
+ * (`subagenteCodex.ts`), y ahí la denegación la hace el SANDBOX del sistema operativo
+ * (`sandbox: "read-only"`) — que es más fuerte, porque no depende de que el modelo colabore.
+ * En los dos casos entra una tarea autocontenida y sale la respuesta final, y el hijo es una
+ * sesión del producto de verdad: su autenticación, sus ajustes y su modelo.
+ *
+ * **La escritura se CONCEDE por escritura, una por una.** El SDK trae `canUseTool`, un
+ * callback que recibe cada tool con su entrada entera y contesta permitir o denegar. Es
+ * asíncrono y corre en NUESTRO proceso, así que se puede esperar ahí a que alguien decida
+ * mientras el hijo sigue vivo — y eso es lo que hace innecesario el `interrupt()` de
+ * LangGraph, cuyo reanudado reejecuta el nodo y relanzaría el proceso hijo.
+ *
+ * Tres listas y no dos (`escrituraExterna.ts`): lectura, escritura y denegadas, con lo que
+ * no se reconoce denegado igual. Antes era `permitirEscritura || esDeLectura(nombre)`, o sea
+ * que el día que se concediera la escritura se concedía TODO — y `Bash` sola basta para
+ * escribir el proyecto entero saltándose la política, el diff y las guardas de ruta.
+ *
+ * El import del SDK es DINÁMICO a propósito: así `npm test` no lo carga nunca —los tests
+ * usan el doble del puerto— y una instalación sin el paquete sigue arrancando, con
+ * `disponible` contestando que no en vez de reventar al importar.
+ */
+import type { ConsumoExterno, MotorExterno, PeticionExterna, PoliticaDeEscrituraExterna, SubagenteExternoPort, ToolDeUnHijo } from "../../core/ports.js";
+/**
+ * La decisión sobre una tool del hijo. **Exportada para poder probarla**: es la regla de
+ * seguridad de toda esta integración, y probarla llamando al SDK exigiría lanzar un Claude
+ * Code de verdad en `npm test` — que es justo lo que este repo no consiente. Lo único que no
+ * es puro son el `realpath` y la lectura del disco, y los dos entran por parámetro.
+ *
+ * El orden importa y es el conservador:
+ * 1. **La clase de la tool** (`claseDeToolExterna`). Lo que no está en las dos listas
+ *    blancas se deniega, `Bash` y `WebFetch` incluidos y con escritura concedida.
+ * 2. **El papel.** Un agente de solo lectura no llega a la política: no hay nada que
+ *    preguntar sobre una escritura que su `.md` no autoriza.
+ * 3. **Las guardas de RUTA del proyecto** (`veredictoDeRuta`), y van ANTES de preguntar:
+ *    un modal cuyo único final posible es un rechazo enseña a aprobar sin mirar, que es la
+ *    misma razón por la que `seDetieneEn` no pregunta por un artefacto mal puesto.
+ * 4. **La política**, con el diff delante. Y sin política no hay escritura: fail-closed por
+ *    tipo, el patrón de `core/cloudstudio.ts#PoliticaDeAprobacion`.
+ *
+ * **Nada de aquí puede lanzar hacia el SDK.** El envoltorio de `correr` atrapa lo que
+ * escape y deniega: el comportamiento del SDK ante un `canUseTool` que revienta no está
+ * medido, y «no medido» no es una barrera.
+ */
+export declare function decisionDeTool(opciones: {
+    nombre: string;
+    entrada: Record<string, unknown>;
+    peticion: PeticionExterna;
+    /** Las del proyecto, para reconocer una vista aplanada. Vacío = ninguna conocida. */
+    ficheros: ReadonlySet<string>;
+    politica?: PoliticaDeEscrituraExterna;
+    /**
+     * El del SDK. Si aborta mientras se espera una decisión —el hijo se muere, su propio
+     * tope— la respuesta es DENEGAR en el acto en vez de seguir esperando el plazo entero.
+     *
+     * Sin esto había un «aprobé y no pasó nada»: el hijo ya no está, `pedirAprobacion` sigue
+     * esperando hasta diez minutos con el modal delante, la persona aprueba, y lo que resuelve
+     * es una promesa que ya nadie lee. Peor que un rechazo, porque se cree que se escribió.
+     */
+    signal?: AbortSignal;
+    real?: (ruta: string) => string;
+    leer?: (ruta: string) => string;
+    /** Las carpetas de las skills montadas: la MISMA lista que recibe el hook (`decisionDePreToolUse`). */
+    lecturasDeSkills?: readonly string[];
+}): Promise<PermisoDeTool>;
+type Trazar = PeticionExterna["trazar"];
+/** La salida de un `Bash` del hijo, a la traza: el tamaño y el error, si lo hay. Nunca lanza. */
+export declare function trazarSalidaDeBash(entrada: Record<string, unknown>, trazar: Trazar): void;
+/** Una tool del hijo que FALLÓ (`PostToolUseFailure`), a la traza, con su `error`. Nunca lanza. */
+export declare function trazarFalloDeTool(entrada: Record<string, unknown>, trazar: Trazar): void;
+/** Lo que `canUseTool` puede contestar. La forma la pone el SDK; se redeclara para no importarlo. */
+export type PermisoDeTool = {
+    behavior: "allow";
+    updatedInput?: Record<string, unknown>;
+} | {
+    behavior: "deny";
+    message: string;
+};
+/**
+ * El adaptador real, con quien autoriza dentro.
+ *
+ * **Las opciones son obligatorias aunque sus campos no lo sean**, y eso es deliberado: pedir
+ * el objeto obliga a pasar por cada llamador el día que esto cambie, y un campo ausente
+ * falla CERRADO —sin política no se escribe— en vez de abrir una puerta en silencio. Es la
+ * única dirección aceptable para el patrón de fallo que este repo ya ha medido siete veces:
+ * una composición que vive en un cierre que los tests doblan.
+ */
+export declare function crearSubagenteExterno(opciones: {
+    /**
+     * Quién autoriza cada escritura del hijo. Ausente = ninguna escritura, con su motivo.
+     *
+     * Lo pone quien monta la sesión porque es quien sabe QUIÉN está detrás: una consola de
+     * persona pasa su `pedirAprobacion` (el diff y la espera) y una tarea de fondo pasa el
+     * suyo, que concede porque la autorización fue crear la tarea. La traducción de uno al
+     * otro es `escrituraExterna.ts#politicaDeAprobacionExterna`.
+     */
+    aprobarEscritura?: PoliticaDeEscrituraExterna;
+    /**
+     * Los ficheros del proyecto, para reconocer una vista aplanada (`X.xml` con su `X.xne`).
+     *
+     * Es una FUNCIÓN y no una lista: el hijo escribe durante el turno, así que una lista
+     * congelada al construir la sesión no vería el `.xne` que se acaba de crear — y entonces
+     * su `.xml` aplanado dejaría de reconocerse como tal.
+     */
+    ficherosDelProyecto?: () => ReadonlySet<string>;
+    /**
+     * Qué está haciendo el hijo, MIENTRAS lo hace.
+     *
+     * Existe por un silencio medido en la pantalla del usuario: el hijo corre en otro proceso
+     * y ni una de sus tools cruza el stream del grafo, así que entre la línea de delegación y
+     * su respuesta final hay minutos sin nada que mirar — y una pantalla quieta se lee como
+     * que se ha colgado. Quien lo recibe lo mete en el MISMO flujo de eventos
+     * (`core/entrelazar.ts`), para que el colapsador lo agrupe como cualquier otra tool.
+     *
+     * Se llama desde el hook `PreToolUse`, que es el único punto por el que pasan TODAS: a
+     * `canUseTool` no llegan las lecturas, porque un `allow` del hook es una pre-aprobación y
+     * el callback ya no se consulta (medido).
+     */
+    alUsarTool?: (tool: ToolDeUnHijo) => void;
+    /**
+     * Lo que el hijo va CONTANDO mientras trabaja, para que se vea que trabaja.
+     *
+     * Hermano de `alUsarTool` y por el mismo motivo medido, que aquél solo resolvió a medias:
+     * entre una tool y la siguiente pueden pasar minutos, y en ese hueco no cruzaba NADA. La
+     * narración del hijo es continua y es la única señal de vida que hay.
+     */
+    alRazonar?: (texto: string) => void;
+    /**
+     * Lo que el hijo consumió, al terminar. Los TRES productos lo reportan y hasta ahora se
+     * tiraba entero (`agent/subagentes/consumoExterno.ts` explica de dónde sale cada uno).
+     *
+     * Va por su propio callback y no dentro de la respuesta porque son dos cosas distintas:
+     * la respuesta es lo que el especialista contesta, y esto es contabilidad.
+     */
+    alConsumir?: (consumo: ConsumoExterno) => void;
+}): SubagenteExternoPort;
+/**
+ * Lo que el especialista externo contesta cuando su motor FALLA —no arranca, se agota su tope—.
+ *
+ * Se devuelve como su respuesta y no se lanza, en los DOS motores que delegan en este puerto: en
+ * TrueForge una excepción en el modelo de un hijo se llevaría el turno entero (es la regla de las guardas: un rechazo se DEVUELVE), y el orquestador, que es
+ * quien decide qué hacer después, se quedaría sin saber qué pasó. Con esto lee que falló y por qué.
+ *
+ * **El motivo va SANEADO** (`mensajeSeguro`): el error de un producto que no arranca lleva la ruta
+ * de la máquina —«spawn /Users/…/codex ENOENT»—, y este texto lo lee el modelo, sale en el chat y se
+ * guarda en el `.jsonl`. Ninguna ruta de la máquina viaja por el cable.
+ */
+export declare function textoDeFalloExterno(motor: MotorExterno, error: unknown): string;
+/**
+ * Envuelve `correr` para que los hijos que ESCRIBEN pasen de uno en uno (ver `correr`, arriba);
+ * los de solo lectura no esperan a nadie. La cola sigue aunque uno falle: un hijo que revienta no
+ * bloquea al siguiente. Extraída y pura para poder probarla sin lanzar ningún producto.
+ */
+export declare function escritoresEnSerie(correr: (peticion: PeticionExterna) => Promise<string>): (peticion: PeticionExterna) => Promise<string>;
+/** Los que están cableados de verdad. Los tres, desde que OpenCode habla por ACP. */
+export declare const MOTORES_CABLEADOS: ReadonlySet<MotorExterno>;
+/**
+ * Las vistas aplanadas del proyecto: cada `X.xml` que tiene un `X.xne` al lado.
+ *
+ * Existe porque OpenCode guarda la LECTURA por PATRÓN y no por código —su permiso de lectura
+ * llega sin ruta—, y «un `.xml` con un `.xne` al lado» no es un patrón que se pueda escribir:
+ * hay que enumerarlas. En los otros dos motores esto lo decide `esVistaAplanada` en el momento.
+ */
+export declare function vistasAplanadasDe(ficheros: ReadonlySet<string>): string[];
+export {};

package/dist/agent/subagentes/subagenteOpencode.d.ts

@@ -0,0 +1,126 @@
+/**
+ * OpenCode como subagente: un turno contra `opencode acp`.
+ *
+ * **Todo lo de aquí está MEDIDO contra el binario real (opencode 1.18.27, 11-09-2026), no
+ * deducido.** De las tres superficies que ofrece —`run --format json`, el servidor HTTP de
+ * `serve`, y ACP— se usa **ACP** (Agent Client Protocol): es JSON-RPC 2.0 por línea sobre
+ * stdio, o sea el mismo molde que `subagenteCodex.ts`, y es la única de las tres que da un
+ * portón de permiso por stdio. `run` no lo tiene y `serve` es otro transporte entero.
+ *
+ * El baile: `initialize` → `session/new {cwd, mcpServers}` → `session/prompt {sessionId,
+ * prompt:[{type:"text"}]}`. Por el camino llegan `session/update` con el razonamiento, el
+ * texto, las tools y el consumo, y el agente nos hace peticiones —`session/request_permission`
+ * y las `fs/*`—.
+ *
+ * **Y da MÁS que los otros dos motores**: su petición de permiso trae la ruta y el antes y el
+ * después en el MISMO mensaje, así que no hace falta ni registro de items (Codex manda solo un
+ * `itemId`) ni parser de hunks. La traducción vive en `escrituraDeOpencode.ts`.
+ *
+ * ## Las TRES puertas por las que el proyecto podía mandar, y cómo se cierran
+ *
+ * Esto es lo que decide si esta integración se puede tener, y las tres están medidas contra un
+ * proyecto que las llevaba a la vez:
+ *
+ * 1. **Un `opencode.json` DEL PROYECTO pisa nuestra configuración.** Medido: leyó el `.env` y
+ *    soltó el secreto, corrió shell y escribió con CERO peticiones de permiso. Ese fichero
+ *    puede venir de CloudStudio — es la misma amenaza que `settingSources: ["user"]` cierra
+ *    para Claude Code.
+ * 2. **Un PLUGIN del proyecto** (`.opencode/plugin/*.ts`) **ejecuta código arbitrario** dentro
+ *    del proceso de opencode, y desde ahí engancha sus hooks. Medido con su control: sin la
+ *    variable corre; con ella, no.
+ * 3. **La configuración GLOBAL del usuario también nos pisa**, así que `OPENCODE_CONFIG` es el
+ *    eslabón débil y no se puede sostener nada encima: alguien con `edit: "allow"` en su
+ *    `~/.config` mataría la aprobación en silencio.
+ *
+ * Las tres se cierran con `OPENCODE_CONFIG_DIR` apuntando a una carpeta NUESTRA (que pasa a
+ * ser «la global», y por eso gana) más `OPENCODE_DISABLE_PROJECT_CONFIG=1`. Las credenciales
+ * del usuario siguen resolviendo: su `auth.json` vive en el directorio de DATOS y no en el de
+ * configuración, así que mudar éste no le desautentica. **`OPENCODE_CONFIG` no se usa**, a
+ * propósito: es el que pierde.
+ *
+ * ## Lo que NO se puede guardar, y está declarado
+ *
+ * **La LECTURA se guarda por PATRÓN y no por código**, que es más flojo que en Claude Code. El
+ * motivo está medido: la petición de permiso de un `kind: "read"` llega con `locations: []` y
+ * `rawInput: {}` —sin ruta—, así que no hay nada que pasarle a una guarda; la ruta solo aparece
+ * en el `tool_call_update` posterior, cuando el permiso ya se concedió. Con `edit` no pasa: ése
+ * sí trae ruta y diff. Así que queda entre los otros dos: mejor que Codex, que no puede guardar
+ * la lectura de ninguna forma, y peor que Claude Code, donde la decide `veredictoDeLectura`.
+ */
+import type { PeticionExterna, PoliticaDeEscrituraExterna, ToolDeUnHijo } from "../../core/ports.js";
+/**
+ * El binario. `OPENCODE_BIN` gana, igual que `CODEX_BIN` en el otro motor. En Windows se resuelve
+ * al `.exe` de verdad (`ejecutableParaLanzar`): el `opencode.cmd` de npm no se lanza sin shell.
+ */
+export declare function binarioDeOpencode(): string;
+/** La carpeta de configuración que gobernamos. Fuera del proyecto, a propósito. */
+export declare function carpetaDeConfigDeOpencode(base?: string): string;
+/**
+ * La configuración con la que corre el hijo. **Es pura y por eso se puede probar entera.**
+ *
+ * Lo que deniega, y por qué cada uno:
+ * - `bash`: medido, no lo deniega — **le quita la tool**: «No tengo un tool de shell en este
+ *   entorno». Es el análogo de la lista de tools denegadas del otro motor, y hace falta porque
+ *   un comando escribe el proyecto entero sin diff que mirar.
+ * - `webfetch` y `websearch`: sacan el proyecto de la máquina.
+ * - `external_directory`: escribir o leer fuera de la carpeta. Medido contra `/tmp`.
+ * - `task`: un hijo suyo sería una segunda superficie de permisos sin medir. Se abrirá cuando
+ *   se mida, no antes.
+ * - `question`: pregunta a una persona que aquí no hay.
+ * - `read`: una lista de patrones, porque su permiso no trae la ruta (ver la cabecera). Las
+ *   **vistas aplanadas entran una a una**, con su ruta, porque «es un `.xml` que tiene un
+ *   `.xne` al lado» no se puede escribir como un patrón — y si el agente las ve, edita el
+ *   fichero equivocado y el cambio se pierde en la siguiente compilación.
+ * - `edit`: `ask`, que es lo que hace que cada escritura pase por `pedirAprobacion`.
+ */
+export declare function configuracionDeOpencode(opciones: {
+    vistasAplanadas?: readonly string[];
+    modelo?: string;
+    /**
+     * Las CARPETAS que contienen skills —la del paquete y la global del usuario—, no una
+     * skill suelta. Vacío o ausente = no se emite la clave: una lista vacía en el fichero
+     * diría «ninguna», que es lo mismo pero deja escrito un ajuste que nadie puso.
+     */
+    skills?: readonly string[];
+}): string;
+/**
+ * El mensaje de error del motor, con el SIGUIENTE PASO detrás cuando se sabe cuál es.
+ *
+ * Medido en la pantalla del usuario: un subagente configurado con un modelo del **tier
+ * gratuito** de opencode fallaba dos veces seguidas con «OpenCode's free tier can only be
+ * used from within OpenCode», que es exacto y no dice qué hacer — y lo que hay que hacer no
+ * se adivina, porque el problema no está en el prompt ni en el proyecto sino en un campo del
+ * `.md` del subagente. Es la misma disciplina que `porQueNo` en la tool de navegación: a
+ * quien se le dice qué está mal sin decirle cómo se arregla, se lo inventa.
+ *
+ * **Se reconoce el texto del proveedor y no se traduce ni se sustituye**: el mensaje
+ * original se conserva entero, y lo nuestro se AÑADE. Si opencode cambia esa frase, lo que
+ * se pierde es el consejo, no el error — que es la dirección segura.
+ *
+ * Y el remedio **no nombra un modelo concreto**: cuál vale depende de qué credenciales tenga
+ * quien lo corre, y proponer uno que él no tiene sería mandarlo a otro callejón.
+ */
+export declare function conRemedio(mensaje: string): string;
+/** ¿Está el binario? Se pregunta lanzándolo, que es la única respuesta que no miente. */
+export declare function opencodeDisponible(): Promise<boolean>;
+export declare function correrOpencode(peticion: PeticionExterna, opciones?: {
+    alConsumir?: (consumo: {
+        entrada: number;
+        salida: number;
+        cache: number;
+    }) => void;
+    aprobar?: PoliticaDeEscrituraExterna;
+    ficheros?: () => ReadonlySet<string>;
+    /** Las vistas aplanadas del proyecto, con su ruta VIRTUAL, para denegarles la lectura. */
+    vistasAplanadas?: () => readonly string[];
+    real?: (ruta: string) => string;
+    alUsarTool?: (tool: ToolDeUnHijo) => void;
+    /** La casa de xonecode. Entra por parámetro porque esto escribe en disco. */
+    casa?: string;
+    /**
+     * El modelo cuando el `.md` no dice ninguno: el de Ajustes → Motores locales, leído en cada
+     * encargo. Sin ninguno de los dos, OpenCode elige solo uno de su tier gratuito, que no
+     * contesta fuera de su consola (medido). La prueba de Ajustes pasa por aquí igual.
+     */
+    modeloPorOmision?: () => string | undefined;
+}): Promise<string>;

package/dist/agent/tareas/aumentador.d.ts

@@ -0,0 +1,99 @@
+/**
+ * El AUMENTADOR: convierte la frase de una persona en un encargo que una tarea autónoma
+ * pueda ejecutar sola.
+ *
+ * **Por qué existe, y no es cosmético** (§7 del diseño): es lo que hace que
+ * «esperando feedback» sea raro en vez de constante. Una tarea autónoma que arranca de una
+ * frase ambigua se bloquea enseguida; una que arranca de un encargo revisado, no. Y en una
+ * tarea que va a escribir sin nadie delante, ejecutar algo que nadie ha leído es justo lo que
+ * la aprobación existía para evitar — así que el encargo **se le enseña a la persona para que
+ * lo edite antes de encolar**, y ese paso es el que ocupa el sitio del diff.
+ *
+ * Tres reglas, y la tercera es la que gobierna el prompt:
+ * - **Entra por PUERTO** (`core/ports.ts#AumentadorPort`) con un `invocar` inyectado, así
+ *   que `npm test` no le pregunta a ningún modelo. La producción monta `invocarParaAumentar`.
+ * - **Usa el papel `trabajo`**, no `rapido`: es una tarea de REDACCIÓN con el proyecto
+ *   delante, no una clasificación.
+ * - **El encargo describe un trabajo que se hace ENTERO sin volver a preguntar** — §0 del
+ *   diseño: una tarea aplica sus escrituras y la autorización fue el acto de crearla. Un
+ *   encargo redactado con un paso de aprobación humana por medio describe algo que no existe,
+ *   y el agente se quedaría esperando a alguien que no está.
+ *
+ * Y **el fallo es recuperable por diseño**: `ErrorDelAumentador` es un fallo del ENTORNO, y
+ * quien lo recoge encola la tarea con el texto original y lo dice. Perder lo que una persona
+ * acaba de escribir porque un modelo no contestó sería lo peor que puede hacer esa ventana.
+ */
+import type { AumentadorPort, ModelosPort, Papel, PeticionDeTarea } from "../../core/ports.js";
+/** El papel del aumentador. Redacción con el proyecto delante: `trabajo`. */
+export declare const PAPEL_DEL_AUMENTADOR: Papel;
+/**
+ * Cuánto encargo se guarda.
+ *
+ * De este texto salen tres cosas: el `<textarea>` que una persona edita, el `encargo` que se
+ * escribe en el índice de la cola (que lleva ya el encargo entero de cada tarea) y la
+ * petición del turno. Un modelo que se venga arriba puede contestar veinte kilobytes de
+ * prosa; el tope es generoso porque esto ES un documento con apartados —al contrario que el
+ * resumen del juez, que es una frase— pero existe, y cuando muerde se DICE en el propio
+ * texto: un encargo cortado en seco parecería que la persona lo dejó a medias.
+ */
+export declare const TOPE_DE_ENCARGO = 8000;
+/**
+ * No se pudo PREGUNTAR, o lo que contestó no es un encargo.
+ *
+ * Es fallo del ENTORNO y no del proyecto —la misma familia que `ErrorDelSimulador` y
+ * `ErrorDelJuezDeTarea`—, y es un tipo propio por lo mismo: quien lo recoge tiene que poder
+ * distinguirlo para encolar la tarea con el texto original en vez de dar el fallo por un
+ * encargo.
+ */
+export declare class ErrorDelAumentador extends Error {
+    constructor(motivo: string);
+}
+/** Cómo se le habla al modelo: un papel, un prompt y la RAÍZ con la que resolver el papel. */
+export type InvocarParaAumentar = (papel: Papel, prompt: string, raiz: string) => Promise<string>;
+/**
+ * El `invocar` de PRODUCCIÓN, sobre `ModelosPort`.
+ *
+ * Es hermano de `invocarConModelos` (`agent/tareas/juezDeTarea.ts`) y **no se reutiliza aquél a
+ * propósito**: su error dice «no se pudo consultar al juez de QA», que aquí sería falso — y
+ * ese mensaje es lo que la ventana de crear le enseña a una persona. Dos frases distintas
+ * para dos operaciones distintas; lo que sí es idéntico, porque es la regla del repo, es el
+ * reparto entre los dos sitios de envoltura:
+ *
+ * - **Construir** el modelo del papel falla ANTES de tocar la red y con un mensaje escrito
+ *   para leerse («falta la credencial para nvidia (NVIDIA_API_KEY); usa /provider nvidia»).
+ *   Ese mensaje SÍ se conserva: es la única línea que dice qué hacer.
+ * - **Llamar** es otra cosa: ahí los SDK devuelven el cuerpo remoto, y ahí van claves
+ *   redactadas y cabeceras. De esa solo se conserva el NOMBRE del error — la misma regla que
+ *   `ErrorCatalogoModelos`: nunca la clave ni el cuerpo remoto. No es ser opaco, es no
+ *   filtrar secretos.
+ */
+export declare function invocarParaAumentar(modelos: ModelosPort): InvocarParaAumentar;
+/**
+ * El prompt del aumentador.
+ *
+ * Lleva la petición, el proyecto y su rama, los adjuntos POR NOMBRE y la memoria del proyecto
+ * si existe. **No lleva la raíz** —es una ruta de la máquina, y está en la petición para
+ * resolver el papel `trabajo` contra el `config.json` del proyecto, no para el prompt— ni el
+ * árbol del proyecto, que sería contexto por gastar en una llamada cuyo trabajo es redactar.
+ *
+ * Y lo que le PROHÍBE es lo que este repo prohíbe en todas partes: inventarse nada de XOne
+ * (lo desconocido no da error, da un bug mudo) y dar por hecho un paso de aprobación humana
+ * que ya no existe.
+ */
+export declare function promptDelAumentador(peticion: PeticionDeTarea): string;
+/**
+ * El encargo tal como se guarda: sin caracteres de control, acotado, y nunca vacío.
+ *
+ * **Los saltos de línea y los tabuladores se conservan**, al contrario que en el resumen del
+ * juez (`unaFrase`): esto es un documento con apartados que se pinta en un `<textarea>`, no
+ * un rótulo de una tarjeta. Lo que se va es el resto de los controles, por lo mismo de
+ * siempre — acaban en el cable y en el índice.
+ *
+ * **Una respuesta vacía es un FALLO y no un encargo.** Encolar con el encargo en blanco
+ * mandaría al agente a trabajar sin nada que hacer; y el camino de reserva ya existe y es
+ * mejor: el texto original de la persona.
+ */
+export declare function encargoDeTexto(texto: string): string;
+export declare function crearAumentador(opciones: {
+    invocar: InvocarParaAumentar;
+}): AumentadorPort;

package/dist/agent/tareas/juezDeTarea.d.ts

@@ -0,0 +1,64 @@
+import type { JuezDeTareaPort, ModelosPort, Papel } from "../../core/ports.js";
+import type { VeredictoDeTarea } from "../../core/entrega.js";
+/** El papel del juez, y solo del juez. Ver `core/modelos.ts`. */
+export declare const PAPEL_DEL_JUEZ: Papel;
+/**
+ * Cuánto resumen se guarda. De aquí sale el `motivo` de la tarea, que se pinta en una
+ * tarjeta del kanban y viaja por el cable: 4 KB de prosa de un modelo llenan la columna
+ * entera, y este número es del mismo orden que el de `servidorDeImplementacion`, que acota
+ * a 60 el nombre que manda un servidor MCP. Aquí se admite más porque es una frase y no un
+ * rótulo.
+ */
+export declare const TOPE_DE_RESUMEN = 400;
+/** Cuántos hallazgos del juez se guardan, y cuánto cada uno. Por lo mismo de arriba. */
+export declare const TOPE_DE_HALLAZGOS = 10;
+/**
+ * No se pudo PREGUNTAR: no hay modelo, no hay clave, no hay red.
+ *
+ * Es fallo del entorno y no del proyecto, la misma familia que `ErrorDelSimulador`
+ * (`agent/turno/verificador.ts`), y por eso es un tipo propio: quien lo recoge tiene que poder
+ * distinguirlo de un veredicto para aparcar la tarea con el motivo correcto.
+ */
+export declare class ErrorDelJuezDeTarea extends Error {
+    constructor(motivo: string);
+}
+/** Cómo se le habla al modelo. Un papel y un prompt entran, su texto sale. */
+/**
+ * El tercer parámetro es la RAÍZ del proyecto de la tarea, y existe para que el papel
+ * `afilado` se resuelva con la precedencia de siempre —proyecto sobre global—. En la consola
+ * web nadie rellena `FuentesDeEleccion.proyecto`, así que sin esto un `config.json` de
+ * proyecto que apuntara el juez a otro modelo se ignoraba en silencio: un ajuste escrito que
+ * no hace nada, que en este repo es peor que no poder ponerlo.
+ */
+export type InvocarModelo = (papel: Papel, prompt: string, raiz: string) => Promise<string>;
+/**
+ * El `invocar` de PRODUCCIÓN, sobre `ModelosPort`.
+ *
+ * **Dos sitios de envoltura, y la diferencia entre ellos está medida.** Construir el modelo
+ * del papel falla ANTES de tocar la red y con un mensaje escrito para leerse: medido contra
+ * `agent/config/modelos.ts`, un `afilado` apuntado a un proveedor sin clave lanza «falta la
+ * credencial para nvidia (NVIDIA_API_KEY); usa /provider nvidia» —el nuestro— o «Anthropic
+ * API key not found» —el del SDK—, y ninguno de los dos lleva nada que no se pueda leer. Ese
+ * mensaje SÍ se conserva: es la única línea que dice qué hacer.
+ *
+ * La LLAMADA es otra cosa: ahí los SDK devuelven el cuerpo remoto, y ahí van claves
+ * redactadas y cabeceras («401 Incorrect API key provided: sk-…»). De esa solo se conserva
+ * el NOMBRE del error, que es la misma regla que `ErrorCatalogoModelos`: «nunca lleva la
+ * clave ni el cuerpo remoto». No es ser opaco, es no filtrar secretos.
+ */
+export declare function invocarConModelos(modelos: ModelosPort): InvocarModelo;
+/**
+ * El JSON de la respuesta, tolerando la valla de código.
+ *
+ * Los modelos contestan «Aquí va: ```json … ```» aunque se les pida solo el JSON, así que
+ * se busca el primer `{` y el último `}`. Lo que no parsee no es un error: es un veredicto
+ * `indeterminado`, que no es verde.
+ */
+export declare function objetoDe(texto: string): Record<string, unknown> | undefined;
+/** El veredicto tal como se guarda, o `indeterminado` diciendo por qué. */
+export declare function veredictoDeTexto(texto: string): VeredictoDeTarea;
+export declare function crearJuezDeTarea(opciones: {
+    invocar: InvocarModelo;
+}): JuezDeTareaPort;
+/** Cuánto de una respuesta del juez sin JSON se apunta: lo justo para ver qué hizo en vez de contestar. */
+export declare const TOPE_DE_RESPUESTA_APUNTADA = 600;

package/dist/agent/tareas/reflejoEnElGestor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * El REFLEJO de una tarea en background en su gestor (Jira, Notion…): cuando cambia de estado, el harness escribe en
+ * su ticket —EN CURSO al empezar; comentario de cierre y PROBAR al terminar—. Ver
+ * `docs/superpowers/specs/2026-10-15-tareas-desde-el-gestor-design.md`.
+ *
+ * **Un solo punto de entrada: el `guardar` del almacén.** Hay al menos cinco escritores de estado (el corredor al
+ * empezar y al aparcar, la reconciliación del arranque, terminar a mano, parar): engancharse a cada uno se olvida en el
+ * sexto. `conReflejoAlGuardar` envuelve el almacén, compara la cola de antes y la de después, y la regla PURA de
+ * `core/tareasEnElGestor.ts` dice qué escribir.
+ *
+ * **Fire-and-forget, con su propio `try`**: quien guarda (el corredor, una ruta) no espera a Jira ni se entera de un
+ * fallo. Lo que falla se APUNTA en el ticket de la tarea (`ticket.aviso`) y se pinta en su fila; lo que sale bien
+ * borra el aviso anterior. Los reflejos de un MISMO ticket van en cola: «empezar» y «cerrar» no se adelantan.
+ */
+import type { DatosDeCierre, GestorDeTareasPort } from "../../core/gestorDeTareas.js";
+import type { Tarea } from "../../core/tareas.js";
+import { type ReflejoPendiente } from "../../core/tareasEnElGestor.js";
+import type { TareasEnDisco } from "./tareasEnDisco.js";
+/** El almacén con el `guardar` vigilado: lo demás pasa tal cual. */
+export declare function conReflejoAlGuardar(disco: TareasEnDisco, reflejar: (pendientes: ReflejoPendiente[]) => void): TareasEnDisco;
+export interface OpcionesDelReflejo {
+    /** El gestor de un conector (la misma fábrica memoizada que usa el panel). */
+    gestorDe: (conector: string) => GestorDeTareasPort | undefined;
+    /** Lo que lleva el comentario de cierre de ESA tarea (ficheros, commits, verificador, última respuesta). */
+    datosDeCierre: (tarea: Tarea) => Promise<DatosDeCierre>;
+    /** Apunta (o borra, con `undefined`) el aviso del ticket de una tarea, sin tocar nada más. */
+    anotarAviso: (id: string, aviso: string | undefined) => void;
+    /** Un error del gestor como texto que puede cruzar el cable (sin correos, sin rutas, recortado). */
+    motivoDe: (error: unknown) => string;
+    informar?: (texto: string) => void;
+}
+/** La función que recibe `conReflejoAlGuardar`: lanza cada reflejo y devuelve el control en el acto. */
+export declare function crearReflejoEnElGestor(o: OpcionesDelReflejo): ((pendientes: ReflejoPendiente[]) => void) & {
+    enCurso: () => Promise<void>;
+};
+/** `anotarAviso` sobre el almacén: relee la cola y cambia SOLO `ticket.aviso` de esa tarea (el estado no se toca, así
+ *  que no vuelve a disparar ningún reflejo). Una tarea que ya no está (descartada) no se resucita. */
+export declare function anotarAvisoEnElDisco(disco: Pick<TareasEnDisco, "listar" | "guardar">): (id: string, aviso: string | undefined) => void;

package/dist/agent/tareas/sondeoDelGestor.d.ts

@@ -0,0 +1,49 @@
+import type { GestorDeTareasPort, VinculoGuardado } from "../../core/gestorDeTareas.js";
+import type { PeticionDeTarea } from "../../core/ports.js";
+import type { TareasEnDisco } from "./tareasEnDisco.js";
+/** Una copia local con su identidad y su vínculo (lo que sale de su `config.json`). */
+export interface CopiaConGestor {
+    proyecto: {
+        id: string;
+        raiz: string;
+        nombre: string;
+    };
+    vinculo: VinculoGuardado;
+}
+/** Lo que pasó en una pasada: lo que se hizo y lo que falló, por ticket. Para «Mirar ahora» y para la traza. */
+export interface ResultadoDelSondeo {
+    preparadas: string[];
+    lanzadas: string[];
+    fallos: {
+        clave?: string;
+        proyecto: string;
+        motivo: string;
+    }[];
+}
+export interface OpcionesDelSondeo {
+    /** Las copias locales con gestor vinculado. Se relee en cada pasada: el interruptor se cambia con todo en marcha. */
+    copias: () => CopiaConGestor[];
+    gestorDe: (conector: string) => GestorDeTareasPort | undefined;
+    /** El aumentador de «Nueva tarea»: amplía el encargo con el proyecto delante. Sin él, preparar no se hace. */
+    augmentar?: (p: {
+        texto: string;
+        proyecto: CopiaConGestor["proyecto"];
+        adjuntos: PeticionDeTarea["adjuntos"];
+    }) => Promise<string>;
+    /** La cola (la ENVUELTA: lo que se guarda aquí también se refleja en el gestor). */
+    cola: Pick<TareasEnDisco, "listar" | "guardar">;
+    /** Que el corredor mire la cola: una tarea lanzada arranca en el acto si puede. */
+    revisar: () => void;
+    /** Si este proceso es el que ejecuta las tareas. Sin cerrojo no se crea nada. */
+    esDueño: () => boolean;
+    motivoDe: (error: unknown) => string;
+    informar?: (texto: string) => void;
+    ahora?: () => Date;
+}
+export interface SondeoDelGestor {
+    /** Una pasada ya. Si hay otra en marcha, espera a esa y devuelve su resultado. */
+    mirar(): Promise<ResultadoDelSondeo>;
+    arrancar(): void;
+    parar(): void;
+}
+export declare function crearSondeoDelGestor(o: OpcionesDelSondeo): SondeoDelGestor;