xonecode 0.38.44 → 0.39.2

package/dist/core/ports.d.ts

@@ -0,0 +1,1034 @@
+/**
+ * Los puertos: todo lo caro entra por aquí, con su doble determinista al lado.
+ *
+ * La regla dura: los puertos se PASAN al construir, nunca se importan dentro de quien
+ * los usa. Es lo que hace que el lazo completo se recorra sin API, sin red y sin
+ * CloudStudio — la propiedad que sostiene los tests offline del laboratorio.
+ *
+ * Este fichero es TypeScript puro: no importa langchain, langgraph, deepagents, MCP,
+ * Ink ni React. La frontera está probada en `core/imports.test.ts`.
+ */
+import type { Proveedor } from "./modelos.js";
+import type { ClaseDeTrabajo, Esfuerzo, Pensamiento } from "./esfuerzo.js";
+import type { ConsumoDeTurno, ConsumoPorModelo } from "./actos.js";
+import type { EstadoDeVerificador, VeredictoDeTarea } from "./entrega.js";
+import type { HallazgoDelTurno } from "./events.js";
+import type { LineaDeDiff } from "./diff.js";
+import type { ConectorParaElAgente, ToolConEsquema } from "./conectores.js";
+import { type FamiliaDeFuente, type Peso } from "./fuentes.js";
+import type { ContextoRemoto, EstructuraRemota } from "./cloudstudio.js";
+import type { ComentarioDelGestor, DescripcionDelProyecto, EstadoDelGestor, FichaDelGestor, GestorDeTareasPort, NuevaTareaEnElGestor, OpcionesDePendientes, ProyectoEncontrado, TareaDelGestor, TransicionDelGestor, Vinculo } from "./gestorDeTareas.js";
+/**
+ * La marca de «esto es un doble», y por qué es un Symbol y no un booleano.
+ *
+ * En el harness Python equivalente el flag `verifier_is_stub` no es un campo que alguien
+ * rellene: es una propiedad derivada de la CLASE del objeto. La diferencia importa —
+ * un booleano se puede olvidar, o poner a false sobre un doble, y entonces los tres
+ * avisos de honestidad callan justo cuando más falta hacen.
+ *
+ * Aquí la traducción fiel es una marca que solo los dobles llevan: un puerto real no
+ * puede fingir que no lo es porque no la tiene, y un doble no puede quitársela sin
+ * editar su propia definición.
+ */
+export declare const ES_DOBLE: unique symbol;
+/**
+ * Acepta objeto O función: en JS una función también es un objeto en tiempo de ejecución
+ * y puede llevar una propiedad-symbol igual que cualquier otro. Hace falta para
+ * `cli/consola.ts#ejecutarTurnoGuionizado` — un `EjecutorDeTurno` es un tipo función, no
+ * una clase con instancia, y es SIEMPRE de pega (todo turno que pasa por ahí usa
+ * `new AgenteGuionizado()`), así que la marca vive en la función exportada y no en un
+ * booleano en quien la invoca (`web/servidor/vestibulo.ts#volcar`).
+ */
+export declare function esDoble(puerto: unknown): boolean;
+/** Una tool publicada por un servidor MCP, reducida a lo que xonecode necesita. */
+export interface ToolInfo {
+    nombre: string;
+    descripcion: string;
+    /** Coste aproximado en tokens de prompt. Se mide, no se estima. */
+    tokens: number;
+}
+export interface CatalogoMcp {
+    cloudstudio: ToolInfo[];
+    ide: ToolInfo[];
+}
+/** El acceso al proyecto del cliente, que vive en CloudStudio y se habla por MCP. */
+export interface McpPort {
+    catalogo(): Promise<CatalogoMcp>;
+    invocar(tool: string, args: Record<string, unknown>): Promise<unknown>;
+    cerrar(): Promise<void>;
+}
+export interface SkillInfo {
+    nombre: string;
+    descripcion: string;
+    tokens: number;
+}
+/** Las skills de XOne: el catálogo y el contenido. */
+export interface SkillsPort {
+    catalogo(): SkillInfo[];
+    cargar(nombre: string): string;
+}
+/**
+ * Un agente de otro producto —Claude Code, Codex— corriendo sobre la carpeta del proyecto.
+ *
+ * Es un PUERTO por la razón de siempre y una más. La de siempre: `npm test` no puede
+ * necesitar una clave, una conexión ni un binario instalado, así que lo que lanza un proceso
+ * hijo entra por aquí y en los tests entra el doble. La otra: ni `xoneAgent.ts` ni
+ * `turnoReal.ts` pueden saber que Claude Code existe, exactamente igual que no saben que
+ * existe CloudStudio — las tools remotas no se inyectan en el agente, las ejecuta quien
+ * está fuera.
+ *
+ * **El hijo SÍ puede escribir, y cada escritura pasa por una autorización.** El gancho es
+ * `canUseTool` del SDK: recibe la tool con su entrada entera y contesta permitir o denegar,
+ * y es **asíncrono y en NUESTRO proceso**, así que se puede esperar ahí a que alguien decida
+ * sin que el hijo se entere — que es lo que durante meses pareció imposible. El obstáculo
+ * que se declaraba aquí era real pero de otra pieza: el HITL de xonecode son `interrupt()`
+ * de LangGraph, y reanudar uno reejecuta el nodo desde el principio, o sea relanzaría el
+ * proceso hijo. La salida es no usar `interrupt()` para esto: la decisión se pide por
+ * `PoliticaDeEscrituraExterna`, el proceso hijo sigue vivo esperando, y el nodo del grafo
+ * no se reejecuta nunca.
+ *
+ * Lo que NO cambia es la dirección del fallo. Sin política no hay escritura
+ * (`agent/subagentes/subagenteExterno.ts` deniega), lo que no se entiende se deniega, y las guardas de
+ * ruta del proyecto se vuelven a aplicar sobre la ruta absoluta del hijo
+ * (`agent/subagentes/escrituraExterna.ts`): sus `Write`/`Edit` van al disco directos, así que
+ * `permisosDe`, el `virtualMode` y las vistas aplanadas no los alcanzan.
+ */
+export interface SubagenteExternoPort {
+    /**
+     * Si el motor se puede usar de verdad: el paquete está instalado y su CLI existe.
+     * Se pregunta ANTES de montarlo para no ofrecerle al orquestador un especialista que va a
+     * fallar en cuanto lo elija — un botón muerto, pero en el grafo.
+     */
+    disponible(motor: MotorExterno): Promise<boolean>;
+    /** Una tarea autocontenida entra, la respuesta final sale. Sin sesión ni continuidad. */
+    correr(peticion: PeticionExterna): Promise<string>;
+}
+export type MotorExterno = "claude-code" | "codex" | "opencode";
+/**
+ * Lo que un agente EXTERNO consumió en una ejecución, tal y como ÉL lo reporta.
+ *
+ * Viaja 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 — la misma razón
+ * por la que un artefacto se anuncia por un evento y no dentro del texto.
+ *
+ * La CACHÉ va aparte de la entrada, igual que en `vendor/tokenTracking.ts`: meterla dentro
+ * inflaría la cifra que se enseña, y tenerlas separadas es lo que permite decir la verdad
+ * sin tener que elegir una de las dos.
+ */
+export interface ConsumoExterno extends ConsumoDeSesion {
+    motor: MotorExterno;
+    /**
+     * Por modelo, si el motor lo dice (Claude Code trae `modelUsage` por id). Ausente: todo es del
+     * modelo que se le PIDIÓ, o del motor si no se pidió ninguno.
+     */
+    porModelo?: Record<string, ConsumoDeSesion>;
+}
+/** Tokens de entrada, de salida y de caché. La caché aparte, por lo de arriba. */
+export interface ConsumoDeSesion {
+    entrada: number;
+    salida: number;
+    cache: number;
+}
+/**
+ * Lo consumido por una sesión, en DOS cuentas que no se suman entre ellas.
+ *
+ * `modelo` son los tokens del grafo —contra la clave de API del usuario— y `externo` los de
+ * un agente de otro producto —contra su suscripción—. Sumar TOKENS de las dos es defendible
+ * (un token es un token); sumar su COSTE no lo es, y tenerlas separadas deja que quien las
+ * pinte decida sin tener que mentir en ninguna dirección.
+ */
+export interface ConsumoDeSesionPorCuenta {
+    modelo: ConsumoDeSesion;
+    externo: ConsumoDeSesion;
+    /**
+     * Cuánto ocupa la ventana AHORA: la entrada de la ÚLTIMA llamada, no la suma.
+     *
+     * Va aquí porque viaja con lo demás y cambia en los mismos instantes, pero contesta otra
+     * pregunta: los acumulados dicen lo que la sesión HA costado y esto dice cuánto margen
+     * queda antes de que el historial desborde — la cifra que avisa de que toca resumir. Es
+     * la misma separación que `vendor/tokenTracking.ts` hace entre sus acumulados y
+     * `contexto`, y la que la barra del terminal ya pinta como dos cosas.
+     */
+    contexto: number;
+    /** Lo mismo, por modelo (`core/actos.ts#ConsumoPorModelo`). Ausente = este motor no lo mide. */
+    porModelo?: ConsumoPorModelo;
+}
+/**
+ * El consumo vivo de una sesión, en la forma que se PERSISTE (`ConsumoDeTurno`).
+ *
+ * Son las mismas cifras con otro nombre en la ventana: lo que aquí se llama `contexto` es un
+ * nivel que se mide al cerrar el turno, y allí se llama `ventana` porque es lo que ocupaba
+ * el historial. Se traduce en una función CON NOMBRE, y no con un literal donde se use, por
+ * la razón de siempre en este repo: una regla de producción compuesta dentro de un cierre
+ * que los tests doblan deja de estar probada y pasa a estar solo escrita.
+ *
+ * Copia las cuentas en vez de reenviarlas: lo que se guarda en el `.jsonl` no puede
+ * compartir objeto con el tracker vivo, o el siguiente turno lo movería por debajo.
+ *
+ * **Un `contexto` de cero sale SIN `ventana`**, y no es una comodidad: es la diferencia entre
+ * «no se midió» y «midió cero». El ejecutor declara `contexto: number`, así que un turno que no
+ * pudo leer la ventana llega con un cero, y estamparlo escribiría en el `.jsonl` una medición
+ * que nadie hizo — con una consecuencia concreta: `consumoDeLosActos` se queda con la última
+ * ventana que CONSTA, así que ese cero falso borraría el nivel que sí midió el turno anterior,
+ * que es justo lo que su regla dice que no puede pasar. Cero no es un nivel: un historial con
+ * turnos dentro nunca ocupa nada.
+ */
+export declare function consumoPersistible(c: ConsumoDeSesionPorCuenta): ConsumoDeTurno;
+/**
+ * La vuelta: lo que se guardó en un `fin`, en la forma que el cable ya manda.
+ *
+ * `ventana` ausente —una sesión sin ninguna medición de contexto, o escrita por una versión
+ * anterior— vuelve como `contexto: 0`, que es «no consta» y no «cero tokens»: quien pinta ya
+ * distingue los dos casos por el `> 0` de siempre, y por eso el cero es la traducción
+ * honesta de una ausencia.
+ */
+export declare function consumoDeLaSesion(c: ConsumoDeTurno): ConsumoDeSesionPorCuenta;
+/**
+ * Una tool que un agente EXTERNO ha usado, para contarla mientras trabaja
+ * (`core/entrelazar.ts`). `agente` es el nombre de su `.md` —el de `PeticionExterna.agente`— y es
+ * OBLIGATORIO a propósito: son tres motores los que lo rellenan, y con el campo opcional uno que
+ * se lo dejara saldría con todo en verde y sus tools sin dueño.
+ */
+export interface ToolDeUnHijo {
+    nombre: string;
+    detalle?: string;
+    agente: string;
+}
+export interface PeticionExterna {
+    /**
+     * Escribe en la traza de herramientas (con «Depurar»): cada `Bash` del hijo —pedido, ejecutado, permitido o denegado— y
+     * lo que salió, y cada tool denegada con su motivo. Ausente = sin traza. Medido en Windows: «node: command not found»
+     * solo se supo por lo que el hijo CONTÓ, no por la traza.
+     */
+    trazar?: (datos: Readonly<Record<string, string | number | boolean | undefined>>) => void;
+    motor: MotorExterno;
+    /** La carpeta del proyecto: el hijo trabaja ahí y en ningún otro sitio. */
+    cwd: string;
+    /** El prompt del subagente (`core/agentes.ts#promptDeAgente`), con las reglas de XOne. */
+    instrucciones: string;
+    /** La tarea que le encarga el orquestador. */
+    tarea: string;
+    /**
+     * Con qué modelo del PRODUCTO corre el hijo. Ausente = el que él use por su cuenta.
+     *
+     * Medido: el SDK de Claude Code acepta `options.model` —y documenta los alias `opus`,
+     * `sonnet`, `haiku`, `fable`— y el `ThreadStartParams` de Codex acepta `model`, cuyos
+     * valores da su propio `model/list`. Antes esto no se pasaba y el `.md` que lo llevara se
+     * rechazaba, con el argumento de que ahí el modelo lo elige el agente; era falso.
+     */
+    modelo?: string;
+    /**
+     * Si el papel de este agente escribe: sale de `soloLectura` de su `.md` y nada más.
+     *
+     * Es la primera de dos puertas y no la única: con esto en `true`, cada escritura pasa
+     * además por la `PoliticaDeEscrituraExterna` de la sesión y por las guardas de ruta. En
+     * `false` no se le pregunta a nadie — un agente de solo lectura no propone escrituras.
+     */
+    permitirEscritura: boolean;
+    /**
+     * El nombre del agente, para poder decir QUIÉN pide la escritura.
+     *
+     * Viaja porque la petición de aprobación lo pinta en su campo `origen`, igual que el
+     * `[dev]` que `hitlDe` mete en la descripción de un interrupt: la tool es la misma para
+     * todos los especialistas, así que sin esto el diff diría «alguien quiere escribir».
+     */
+    agente: string;
+    /**
+     * La cancelación del turno. Abortada, el motor MATA a su hijo y `correr` rechaza: pulsar Parar
+     * no puede dejar un Claude Code o un Codex vivo escribiendo el proyecto con el turno ya
+     * cerrado. Opcional: sin ella el hijo acaba por su cuenta o por su tope, que es lo de antes.
+     */
+    senal?: AbortSignal;
+    /**
+     * La EJECUCIÓN que se le concede, solo a un agente con `ejecucion: true` en su `.md` y solo en
+     * Claude Code (`core/comandoExterno.ts`). Ausente —cualquier otro— es que `Bash` se deniega.
+     */
+    ejecucion?: EjecucionExterna;
+    /**
+     * Las carpetas de ESTA sesión que el hijo puede LEER aunque no ejecute (artefactos y hotswap): el orquestador le pasa la
+     * maqueta y las capturas por ahí. Medido en Maset: un analista sin ellas contestó «no he podido leer la maqueta».
+     */
+    lecturas?: readonly string[];
+    /**
+     * Cuánto razona el hijo: el `esfuerzo` de su `.md`, que Claude Code recibe como `effort`. Medido en Maset: el
+     * desarrollador en Opus pasaba 17 de sus 18 minutos generando (razonamiento incluido) y uno usando herramientas.
+     * Ausente = el que use Claude Code por su cuenta. Codex y OpenCode no lo reciben.
+     */
+    esfuerzo?: Esfuerzo;
+    /**
+     * Las skills de su `.md` que EXISTEN (`repartirSkills(...).suyas`), por su nombre a secas. Claude Code solo ve y usa
+     * éstas (`skills` del SDK, con el prefijo del plugin): sin la lista veía también las del usuario. Ausente = ninguna.
+     */
+    skills?: readonly string[];
+}
+/** Lo que un agente externo con ejecución puede correr y leer, y con qué entorno. */
+export interface EjecucionExterna {
+    /** Los scripts que puede correr, por su NOMBRE: los ejecutables de sus skills. */
+    scripts: readonly string[];
+    /**
+     * El entorno del hijo: el de NUESTRA shell (`entornoDeShell`) — sin nuestras claves de API, con
+     * los `scripts/` en el PATH y las variables de la sesión (artefactos, hotswap, dispositivo).
+     * Medido: el Bash de Claude Code lo respeta, y autentica con su login sin la clave.
+     */
+    entorno: Record<string, string>;
+    /**
+     * Las carpetas FUERA del proyecto que puede leer, en disco: las de artefactos y hotswap de ESTA
+     * sesión, donde sus scripts dejan las capturas y lo que no cabe. Viven bajo `.xonecode/`, que
+     * sigue denegada entera.
+     */
+    lecturas: readonly string[];
+    /**
+     * SOLO en Windows: la ruta de cada script, por su nombre. Allí un script sin extensión no se lanza por su nombre (ni
+     * shebang ni bit de ejecución), así que la segunda llave REESCRIBE la llamada a `node '<ruta>' args`
+     * (`comandoExterno.ts#comandoConNode`). Medido en una máquina Windows de un usuario: el hijo no tenía ningún script
+     * y el `device-controller`, con nuestra shell, sí los corría con `node.exe "<ruta>"`. Ausente fuera de Windows.
+     */
+    rutasConNode?: Readonly<Record<string, string>>;
+    /** Con `rutasConNode`: el Node ABSOLUTO con que se lanzan (el del servidor), porque en el Git Bash del hijo `node` puede no estar en el PATH. */
+    nodeDelServidor?: string;
+}
+/**
+ * Una escritura que un agente EXTERNO quiere hacer, tal y como se le enseña a quien decide.
+ *
+ * La ruta es la VIRTUAL —desde la raíz del proyecto— y no la de la máquina: es la que una
+ * persona reconoce y la única que puede viajar por el cable, que puede ir por un túnel.
+ */
+export interface EscrituraExternaPedida {
+    agente: string;
+    ruta: string;
+    /** El antes y el después, ya en líneas. Vacío si no se pudo componer: se pregunta igual. */
+    lineas: LineaDeDiff[];
+}
+/**
+ * Quién autoriza una escritura de un agente externo. **Fail-closed por TIPO**, el mismo
+ * patrón que `core/cloudstudio.ts#PoliticaDeAprobacion` para la subida: no se puede montar
+ * un agente externo que escriba sin decir quién decide, y quien la rellena es una decisión
+ * de PIEL y no del motor.
+ *
+ * Las dos implementaciones existen ya y son las de `pedirAprobacion`, traducidas por
+ * `agent/subagentes/escrituraExterna.ts#politicaDeAprobacionExterna`: la interactiva enseña el diff y
+ * espera —con plazo, y naciendo rechazada—, y la autónoma de una tarea de fondo concede
+ * porque la autorización fue crear la tarea, lo anuncia con los nombres y lo apunta en
+ * `Tarea.autorizadas`.
+ *
+ * **Toma una LISTA y contesta UNA vez, porque hay un motor que decide así.** Medido contra
+ * `codex app-server` (0.152.1): un `item/fileChange/requestApproval` puede traer varios
+ * ficheros —«añade una línea a uno.txt y a dos.txt» llegó como un solo item con dos
+ * `changes`— y se contesta con un único `decision`, o sea que Codex los aplica todos o
+ * ninguno. Con una escritura por llamada solo quedaban dos salidas, y las dos mienten:
+ * preguntar N veces por algo que no se puede conceder a medias (el humano aprueba el
+ * primero, rechaza el segundo, y el primero tampoco se escribe), o enseñar un fichero y
+ * escribir dos. `pedirAprobacion` ya era una lista de pendientes con sus dos mapas: la que
+ * se quedaba corta era esta. Claude Code pasa la suya de un elemento, que es exactamente lo
+ * que su `canUseTool` decide cada vez.
+ *
+ * **Se concede solo si TODAS vienen aprobadas**: una sola negativa es un NO al conjunto, que
+ * es la dirección segura y además la única que el protocolo de Codex sabe expresar.
+ */
+export type PoliticaDeEscrituraExterna = (escrituras: readonly EscrituraExternaPedida[]) => Promise<boolean>;
+export type Papel = "rapido" | "trabajo" | "afilado";
+/**
+ * La fábrica de modelos, por PAPEL y no por nombre.
+ *
+ * Se reparte por papel porque es la palanca de coste: una sola pregunta de solo lectura
+ * midió 213.895 tokens de entrada y 11 llamadas al modelo. El papel que corre en TODOS
+ * los turnos arranca en `rapido`, y se sube solo con una medición delante.
+ */
+export interface ModelosPort {
+    /**
+     * El `esfuerzo` es OPCIONAL en los dos métodos, y esa opcionalidad es la que mantiene
+     * el cambio en una línea: `ModeloGuionizado` y cualquier doble con menos parámetros
+     * siguen encajando en esta interfaz, igual que pasa con `fase?` y `razonamiento?` en
+     * `Piel`. Ausente = no se manda el parámetro, que es lo que hacía este harness entero
+     * hasta ahora.
+     *
+     * Quien decide si un nivel es aplicable NO es quien llama: es
+     * `core/esfuerzo.ts#esfuerzoAplicable`, contra el modelo que de verdad resuelve el
+     * papel. Pasar aquí un `xhigh` para un modelo que no lo admite tiene que acabar en un
+     * parámetro omitido y no en un 400, y el único sitio que conoce las dos mitades —el
+     * nivel elegido y el modelo resuelto— está dentro.
+     */
+    paraPapel(papel: Papel, esfuerzo?: Esfuerzo, clase?: ClaseDeTrabajo, pensamiento?: Pensamiento): unknown;
+    /**
+     * Un modelo CONCRETO, «proveedor/modelo», para el subagente que fija el suyo
+     * (`core/agentes.ts`). Los papeles no sirven para esto: son tres funciones del turno
+     * —rápido, trabajo, afilado— y un agente que quiere correr con Claude no está pidiendo
+     * un papel, está pidiendo ese modelo. Lanza si el texto no es un `proveedor/modelo`
+     * válido, que es lo que hace que un error de escritura en un `.md` se vea.
+     */
+    paraModelo(id: string, esfuerzo?: Esfuerzo, clase?: ClaseDeTrabajo, pensamiento?: Pensamiento): unknown;
+    /** Qué modelo concreto resuelve cada papel, para que `describe` lo pueda enseñar. */
+    descripcion(): Record<Papel, string>;
+    /**
+     * El `proveedor/modelo` que resuelve ese papel, a secas: con qué id se APUNTA el consumo de una
+     * llamada (`ConsumoPorModelo`). Opcional para que los dobles no cambien; ausente, el consumo va a
+     * nombre del papel.
+     */
+    idDePapel?(papel: Papel): string;
+}
+/** Modelo normalizado publicado por un proveedor, sin detalles de su cliente. */
+export interface ModeloDisponible {
+    proveedor: Proveedor;
+    id: string;
+    nombre?: string;
+    contexto?: number;
+}
+/** Catálogo offline de modelos disponibles por proveedor. */
+export interface CatalogoModelosPort {
+    listar(proveedor: Proveedor): Promise<ModeloDisponible[]>;
+}
+/**
+ * Un hallazgo del verificador. La forma NO es de diseño: es la que emite
+ * `xone-simulator validate --json` (xone-linter 1.4.0), medida contra un proyecto real.
+ *
+ * Tres cosas que la medición corrigió respecto al primer borrador, y las tres importan:
+ *
+ * 1. **`linea` es OPCIONAL.** `SourceLocation` la declara `line?: number`
+ *    (`xone-linter/src/model/XoneModel.ts:3`) y en la corrida medida NINGÚN hallazgo la
+ *    traía. Con un `linea: number` obligatorio, el adaptador tendría que inventarse un 0
+ *    — y un número inventado en un informe de hechos es exactamente la mentira que este
+ *    diseño existe para no contar.
+ * 2. **Las severidades son TRES**, no dos: `error | warning | info`
+ *    (`xone-linter/src/validator/ValidationResult.ts:3`). Colapsar `info` en `warning`
+ *    es una decisión de producto que nadie ha tomado.
+ * 3. **Se llama `code`, no `regla`**, y se conserva su nombre. El vocabulario del
+ *    verificador es el que viaja al ejecutor como brief de reparación y al juez como
+ *    hecho; traducirlo aquí obliga a destraducirlo en los dos sitios.
+ */
+export interface Hallazgo {
+    code: string;
+    severidad: "error" | "warning" | "info";
+    mensaje: string;
+    /** Ruta ABSOLUTA tal como la da el simulador. Opcional: no todo hallazgo tiene fichero. */
+    fichero?: string;
+    linea?: number;
+    columna?: number;
+}
+export interface InformeVerificacion {
+    verde: boolean;
+    hallazgos: Hallazgo[];
+    /**
+     * La copia que se midió era de edad desconocida: se INTENTÓ traerla de CloudStudio y no
+     * se pudo. Viaja DENTRO del informe y no en una bitácora aparte porque el informe es lo
+     * que se mueve —al ejecutor como brief, al juez como hecho, al `--json` de quien lo
+     * consuma— y ninguno de los tres lee la bitácora.
+     *
+     * Es un TERCER estado, no una variante de «no hay copia»: «nadie la ha traído» es
+     * honesto, «se creía que sí y no» produce hallazgos con código, fichero y línea de otra
+     * versión del proyecto.
+     */
+    copiaVieja?: boolean;
+}
+/**
+ * La huella de un hallazgo, para detectar NO-PROGRESO: la misma huella dos veces seguidas
+ * significa que reparar no está avanzando, y se bloquea ANTES de agotar el presupuesto.
+ *
+ * Ignora el mensaje a propósito: lleva nombres interpolados que varían sin que el problema
+ * cambie. Y tolera la ausencia de línea, que es el caso normal según la medición.
+ */
+export declare function huella(h: Hallazgo): string;
+/** El verificador determinista. Establece HECHOS: no opina y no auto-corrige. */
+export interface VerifierPort {
+    verificar(rutaProyecto: string): Promise<InformeVerificacion>;
+}
+/**
+ * Lo que se le cuenta al juez de QA de una tarea, y **nada más que esto**.
+ *
+ * El encargo es el brief, y el resto son HECHOS que ya midió alguien: qué ficheros se
+ * autorizó escribir (nombres relativos) y cómo acabó el verificador con sus hallazgos —
+ * que es lo que `InformeVerificacion` ya declara que viaja «al juez como hecho». Ni un
+ * byte de contenido de ningún fichero: el juez decide si el trabajo hace lo que se pedía,
+ * y para eso no hace falta abrir nada. Es la misma regla que gobierna los eventos de
+ * dominio, aplicada al único sitio nuevo por donde podría escaparse.
+ */
+export interface CasoDeJuez {
+    encargo: string;
+    /** La raíz del proyecto de la tarea. Está aquí para que el papel `afilado` se resuelva con
+     *  la MISMA precedencia que en cualquier otro sitio —proyecto sobre global—: en la consola
+     *  web `FuentesDeEleccion.proyecto` no se rellena nunca (el vestíbulo sirve muchos
+     *  proyectos y las fuentes se construyen una vez al arrancar), así que hay que preguntarle
+     *  al disco POR LA RAÍZ, igual que `cloudstudioDelProyecto`. Se queda en el host: no viaja
+     *  por el cable. */
+    raiz: string;
+    /** Lo que la tarea AUTORIZÓ escribir, relativo a la raíz. Ver `Tarea.autorizadas`: es
+     *  una PISTA de lo que tocó, no la verdad sobre el disco (esa la tiene git). */
+    autorizadas: readonly string[];
+    /** Cómo acabó el verificador, si se sabe. `no-corrio` se le DICE: un juez que no sabe
+     *  que nadie midió juzgaría sobre un hecho que no existe. */
+    verificador?: EstadoDeVerificador;
+    /** Los del REPARTO: los que caen en ficheros que este turno tocó, más los que no dicen en
+     *  qué fichero (inatribuibles, y ese es el lado conservador). Ver `preexistentes`. */
+    hallazgos?: readonly HallazgoDelTurno[];
+    /** Cuántos quedaron FUERA del reparto, o sea en ficheros que este turno no tocó. Sin este
+     *  número, `hallazgos` se lee como si fuera todo lo que el simulador vio y como si todo
+     *  fuera del turno — medido: el juez concluyó de dos avisos que el agente había modificado
+     *  ficheros JavaScript. Ausente es «no se midió»; `0` es «no había ningún otro». */
+    preexistentes?: number;
+    /** QUÉ cambió en el proyecto, según GIT: las rutas RELATIVAS del diff de la sesión contra
+     *  su «antes» (`corredorDeTareas.ts#revisionConGit`). Es el único HECHO sobre el disco que
+     *  llega hasta aquí — `autorizadas` es la intención del agente—, y va como lista y no como
+     *  booleano a propósito: todo el modo de fallo medido del juez era «no puedo comprobar la
+     *  existencia ni el contenido de X», y el hecho fichero a fichero lo quita de raíz.
+     *  **Ausente y vacía no son lo mismo**: ausente es «no se pudo preguntar a git» y `[]` es
+     *  «git dice que no cambió nada». Colapsarlas inventaría un cargo o lo taparía. */
+    cambiados?: readonly string[];
+    /** Lo que dieron las comprobaciones VISUALES del turno, medido por el harness (`ResultadoDeTurno.comprobacionesVisuales`).
+     *  Ausente = no hubo ninguna: y entonces «no consta» sí es la verdad. */
+    comprobacionesVisuales?: readonly string[];
+}
+/**
+ * El juez de QA: una de las DOS piezas que ocupan el sitio que dejó el modal de aprobación
+ * cuando las tareas pasaron a aplicar sus escrituras (§0 del diseño). La otra es el
+ * verificador, que ya corre dentro del turno.
+ *
+ * Es un PUERTO por la razón de siempre —`npm test` no puede necesitar una clave ni una
+ * conexión— y usa el papel `afilado`, que en `core/modelos.ts` está RESERVADO al juez.
+ *
+ * **No tiene doble, y es a propósito.** El modo offline lo cubre el propio papel: por
+ * omisión `afilado` resuelve a Ollama local, que es una consola usable sin red externa. Un
+ * doble aquí solo podría contestar «verde» o «rojo» sin haber juzgado nada, y de este
+ * veredicto depende que una tarea se dé por terminada: exactamente lo que `ES_DOBLE`
+ * existe para impedir. Que no se pueda usar es fallo del ENTORNO y se dice como tal.
+ */
+export interface JuezDeTareaPort {
+    juzgar(caso: CasoDeJuez): Promise<VeredictoDeTarea>;
+}
+/**
+ * Lo que se le da al aumentador para redactar el encargo, y nada más.
+ *
+ * **El árbol del proyecto NO está aquí, a propósito**: sería contexto por gastar en una
+ * llamada cuyo trabajo es redactar, no analizar. Lo que hay es lo que una persona necesitaría
+ * para escribir el encargo por su cuenta.
+ */
+export interface PeticionDeTarea {
+    /** Lo que escribió la persona, tal cual. */
+    texto: string;
+    /**
+     * La pantalla de Stitch ELEGIDA para la tarea (con el proyecto de Stitch): el encargo la nombra con sus ids y no busca
+     * otra. Ausente = no se eligió ninguna.
+     */
+    pantallaDeStitch?: {
+        name: string;
+        titulo: string;
+        proyecto?: string;
+    };
+    /**
+     * El proyecto para el que es la tarea. La `raiz` está aquí por lo MISMO que en
+     * `CasoDeJuez`: el papel `trabajo` se resuelve con la precedencia de siempre —proyecto
+     * sobre global— y en la consola web `FuentesDeEleccion.proyecto` no se rellena nunca, así
+     * que hay que preguntarle al disco POR LA RAÍZ. Se queda en el host: no viaja por el cable.
+     */
+    proyecto: {
+        nombre: string;
+        raiz: string;
+        rama?: string;
+    };
+    /** Nombres y tipos de los adjuntos, NUNCA su contenido: la redacción tiene que poder decir
+     *  para qué sirve cada uno, y para eso basta el nombre. */
+    adjuntos: readonly {
+        nombre: string;
+        mime?: string;
+    }[];
+    /** La memoria del proyecto, si existe (`.xonecode/memoria.md`). El árbol entero sería
+     *  contexto por gastar; esto son las decisiones que ya se tomaron. */
+    memoria?: string;
+    /**
+     * Los CONECTORES del proyecto que llegan al agente, por su nombre («Stitch»). Medido en Maset: sin saberlo, el
+     * aumentador convirtió «la pantalla de Stish» en «búscala en el repo y, si no está, PARA», y la tarea no hizo nada.
+     */
+    conectores?: readonly string[];
+}
+/**
+ * Convierte la petición de un humano en un ENCARGO que una tarea autónoma pueda ejecutar.
+ *
+ * Existe como puerto por las dos razones de siempre, y aquí la segunda es la que manda:
+ * `npm test` sigue sin red ni clave, y **el fallo tiene que ser recuperable**. Si no hay
+ * modelo, la tarea se encola con el texto original y se DICE — perder lo que una persona
+ * acaba de escribir porque un modelo no contestó sería lo peor que puede hacer esa ventana.
+ *
+ * A diferencia del juez (`JuezDeTareaPort`, que no tiene doble a propósito), este SÍ lo
+ * tiene: de un veredicto del juez depende que una tarea se dé por terminada, y un doble que
+ * conteste «verde» sin juzgar es exactamente lo que `ES_DOBLE` existe para impedir; de un
+ * encargo augmentado no depende ninguna afirmación — lo lee una persona y lo edita antes de
+ * encolar.
+ */
+export interface AumentadorPort {
+    augmentar(peticion: PeticionDeTarea): Promise<string>;
+}
+export declare class McpVacio implements McpPort {
+    readonly [ES_DOBLE] = true;
+    catalogo(): Promise<CatalogoMcp>;
+    invocar(tool: string): Promise<unknown>;
+    cerrar(): Promise<void>;
+}
+export declare class SkillsEnMemoria implements SkillsPort {
+    private readonly contenido;
+    readonly [ES_DOBLE] = true;
+    constructor(contenido?: Record<string, string>);
+    catalogo(): SkillInfo[];
+    cargar(nombre: string): string;
+}
+export declare class ModeloGuionizado implements ModelosPort {
+    private readonly respuestas;
+    readonly [ES_DOBLE] = true;
+    constructor(respuestas?: string[]);
+    paraPapel(): unknown;
+    /** El mismo guion venga por papel o por id: el modo offline no distingue modelos, y
+     *  fingir que sí obligaría a los tests a saber qué modelo pide cada agente. */
+    paraModelo(): unknown;
+    descripcion(): Record<Papel, string>;
+}
+/**
+ * El doble del aumentador: devuelve el texto original, DICIENDO que no lo redactó nadie.
+ *
+ * La marca `[DOBLE]` no es adorno y es la misma disciplina que `McpVacio` y
+ * `SkillsEnMemoria`: este texto se le enseña a una persona en la ventana de crear —para que
+ * lo edite— y después se le manda al agente, así que sin la marca pasaría por una redacción
+ * de verdad. Con `--guion` es lo que se monta, que es exactamente el caso que la marca
+ * describe.
+ *
+ * La plantilla entra por parámetro para que un test pueda afirmar sobre el paso de datos sin
+ * la marca de por medio.
+ */
+export declare class AumentadorGuionizado implements AumentadorPort {
+    private readonly plantilla;
+    readonly [ES_DOBLE] = true;
+    constructor(plantilla?: (t: string) => string);
+    augmentar(peticion: PeticionDeTarea): Promise<string>;
+}
+/**
+ * El doble: contesta sin lanzar ningún proceso.
+ *
+ * `disponible` devuelve `false` por omisión a propósito. Un doble que dijera que sí haría
+ * que los tests recorrieran la rama de «hay Claude Code» sin haberlo, que es justo la
+ * mentira que `ES_DOBLE` existe para impedir — y el modo offline enseñaría un especialista
+ * que no puede correr.
+ */
+export declare class SubagenteExternoGuionizado implements SubagenteExternoPort {
+    private readonly hay;
+    private readonly respuesta;
+    readonly [ES_DOBLE] = true;
+    constructor(hay?: boolean, respuesta?: string);
+    disponible(): Promise<boolean>;
+    correr(peticion: PeticionExterna): Promise<string>;
+}
+/** Catálogo determinista para recorrer la CLI sin red ni credenciales. */
+export declare class CatalogoModelosEnMemoria implements CatalogoModelosPort {
+    private readonly porProveedor;
+    readonly [ES_DOBLE] = true;
+    constructor(porProveedor?: Partial<Record<Proveedor, ModeloDisponible[]>>);
+    listar(proveedor: Proveedor): Promise<ModeloDisponible[]>;
+}
+/**
+ * Verificador que siempre dice verde.
+ *
+ * Peligroso a propósito: es el doble que más miente si nadie lo declara, porque un verde
+ * falso deja pasar código roto. Por eso lleva la marca y por eso `describe` lo canta.
+ */
+export declare class StubVerifier implements VerifierPort {
+    readonly [ES_DOBLE] = true;
+    verificar(): Promise<InformeVerificacion>;
+}
+/** Verificador con guion, para recorrer el lazo de reparación sin LLM: [rojo, rojo, verde]. */
+export declare class VerifierGuionizado implements VerifierPort {
+    private readonly guion;
+    readonly [ES_DOBLE] = true;
+    private i;
+    constructor(guion: InformeVerificacion[]);
+    verificar(): Promise<InformeVerificacion>;
+}
+/**
+ * El proyecto del cliente en CloudStudio.
+ *
+ * Modela lo MEDIDO contra el servidor, no lo que sería cómodo: el proyecto abierto es
+ * estado de sesión que caduca (`abrir` se repite), la rama activa solo se sabe por
+ * `contexto`, y la descarga completa es un ZIP entero que jamás pasa por el transcript.
+ */
+export interface CloudStudioPort {
+    abrir(nombre: string): Promise<void>;
+    contexto(): Promise<ContextoRemoto>;
+    /** Devuelve el ZIP en base64. Puede fallar por un fichero roto en Studio. */
+    descargarZip(): Promise<string>;
+    estructura(directorio?: string): Promise<EstructuraRemota>;
+    leerTexto(ruta: string): Promise<string>;
+    escribirTexto(ruta: string, contenido: string): Promise<void>;
+    borrarTexto(ruta: string): Promise<void>;
+    subirBinario(ruta: string, datos: Uint8Array): Promise<void>;
+    ramas(): Promise<string[]>;
+    cambiarRama(nombre: string): Promise<void>;
+}
+export interface OpcionesCloudStudioEnMemoria {
+    rama?: string;
+    textos?: Record<string, string>;
+    binarios?: Record<string, number>;
+    /** Motivo con el que `descargarZip` rechaza; ausente = el ZIP funciona. */
+    zipFalla?: string;
+    /**
+     * Motivo con el que `contexto` rechaza; ausente = se puede leer la rama activa.
+     *
+     * No es un capricho de test: medido contra CloudStudio, `studio_get_context` revienta
+     * para algunos proyectos —con el proyecto abierto y con el resto de tools contestando
+     * bien sobre ese mismo proyecto—, y sin poder reproducirlo aquí la tolerancia de
+     * `agent/cloudstudio/ramaActiva.ts` no tendría dónde probarse.
+     */
+    contextoFalla?: string;
+    /** Tope de entradas por llamada, para reproducir el truncado del servidor real. */
+    topeEstructura?: number;
+    /** ZIP ya fabricado (por el test, fuera de la frontera) para que `descargarZip` lo devuelva. */
+    zipBase64?: string;
+    /**
+     * Lo que el servidor GUARDA de un texto escrito, por ruta: los N primeros caracteres. Es el
+     * corte que se ha visto en ficheros subidos a Studio (sin reproducir todavía), y sin poder
+     * fabricarlo aquí la relectura de `agent/cloudstudio/subida.ts` no tendría qué detectar.
+     */
+    textoRecortadoA?: Record<string, number>;
+    /** Motivo con el que `leerTexto` rechaza DESPUÉS de una escritura (la relectura que comprueba). */
+    relecturaFalla?: string;
+    /** Motivo con el que `subirBinario` rechaza. */
+    binarioFalla?: string;
+    /**
+     * El `switch` contesta bien pero la rama activa NO cambia: `contexto` sigue diciendo la de
+     * antes. Es la razón de comprobar la rama antes de subir, en vez de fiarse del `switch`.
+     */
+    cambiarRamaNoSurteEfecto?: boolean;
+}
+/** El proyecto remoto en memoria: recorre el flujo entero sin red ni credenciales. */
+export declare class CloudStudioEnMemoria implements CloudStudioPort {
+    private readonly opciones;
+    readonly [ES_DOBLE] = true;
+    /** Lo escrito, para poder afirmar sobre ello en los tests. */
+    readonly escrituras: Array<{
+        tipo: "texto";
+        ruta: string;
+        bytes: number;
+    } | {
+        tipo: "binario";
+        ruta: string;
+        bytes: number;
+    } | {
+        tipo: "borrado";
+        ruta: string;
+    }>;
+    private abierto;
+    private ramaActual;
+    /**
+     * Los textos del servidor, que las escrituras MODIFICAN: la subida relee lo que escribió, y
+     * un doble que no guardara lo escrito haría fallar esa relectura en todos los tests. Campo
+     * PROPIO (no del prototipo), para que los envoltorios `Object.create` + `Object.assign` de
+     * los tests compartan el mismo mapa por referencia.
+     */
+    readonly textos: Record<string, string>;
+    /** Las rutas escritas en esta vida del doble: solo esas relee con `relecturaFalla`. */
+    private readonly escritas;
+    constructor(opciones?: OpcionesCloudStudioEnMemoria);
+    abrir(nombre: string): Promise<void>;
+    private exigirAbierto;
+    contexto(): Promise<ContextoRemoto>;
+    descargarZip(): Promise<string>;
+    estructura(directorio?: string): Promise<EstructuraRemota>;
+    leerTexto(ruta: string): Promise<string>;
+    escribirTexto(ruta: string, contenido: string): Promise<void>;
+    borrarTexto(ruta: string): Promise<void>;
+    subirBinario(ruta: string, datos: Uint8Array): Promise<void>;
+    ramas(): Promise<string[]>;
+    cambiarRama(nombre: string): Promise<void>;
+}
+/** Un gestor de tareas en memoria: lo que el servidor y el cliente prueban sin red. Apunta lo ESCRITO. */
+export declare class GestorDeTareasEnMemoria implements GestorDeTareasPort {
+    private readonly datos;
+    readonly [ES_DOBLE] = true;
+    readonly transicionesAplicadas: {
+        clave: string;
+        transicion: string;
+    }[];
+    readonly comentariosAplicados: {
+        clave: string;
+        texto: string;
+    }[];
+    /** Lo que se le pidió CREAR, en orden. */
+    readonly creadas: {
+        proyecto: string;
+        titulo: string;
+        descripcion: string;
+    }[];
+    constructor(datos?: {
+        sitios?: {
+            id: string;
+            nombre: string;
+            url?: string;
+        }[];
+        proyectos?: Record<string, {
+            clave: string;
+            nombre: string;
+        }[]>;
+        tareas?: FichaDelGestor[];
+        transiciones?: Record<string, TransicionDelGestor[]>;
+        /** El nombre visible de quien tiene la sesión del conector: lo que `mias` compara con `asignado`. */
+        yo?: string;
+        /**
+         * IXCODE-15, la forma de Notion: con `encontrados`, el doble BUSCA proyectos (y sin él no
+         * tiene el método, como Jira); con `descripciones`, DESCRIBE cada uno por su `proyecto`
+         * —y entonces `vincular` comprueba con esto y no con `proyectos(sitio)`—. Uno que no esté
+         * en la tabla se describe con un motivo.
+         */
+        encontrados?: ProyectoEncontrado[];
+        descripciones?: Record<string, DescripcionDelProyecto>;
+        /**
+         * Con él, el doble CREA tareas: cada una con clave `<prefijo>-<n>` (n empieza en 1), que entra en `tareas` en
+         * la categoría `por-hacer` para que `ficha` la encuentre. Sin él no tiene el método, como un gestor que no crea.
+         * `crearFalla` hace que crear lance con ese motivo.
+         */
+        creaConPrefijo?: string;
+        crearFalla?: string;
+        /** Con él, el doble LEE comentarios (por clave; una clave ausente no tiene ninguno). Sin él no tiene el método. */
+        comentarios?: Record<string, ComentarioDelGestor[]>;
+        /** Con él, el doble da los estados del flujo. Sin él no tiene el método. */
+        estados?: EstadoDelGestor[];
+    });
+    /** Solo existen si los datos los piden: su AUSENCIA es la forma de Jira, y el servidor la mira. */
+    readonly buscarProyectos?: (texto: string) => Promise<ProyectoEncontrado[]>;
+    readonly describirProyecto?: (v: Vinculo) => Promise<DescripcionDelProyecto>;
+    readonly crear?: (v: Vinculo, nueva: NuevaTareaEnElGestor) => Promise<TareaDelGestor>;
+    readonly comentarios?: (v: Vinculo, clave: string) => Promise<ComentarioDelGestor[]>;
+    readonly estados?: (v: Vinculo) => Promise<EstadoDelGestor[]>;
+    sitios(): Promise<{
+        id: string;
+        nombre: string;
+        url?: string;
+    }[]>;
+    proyectos(sitio: string): Promise<{
+        clave: string;
+        nombre: string;
+    }[]>;
+    pendientes(_v: Vinculo, texto?: string, opciones?: OpcionesDePendientes): Promise<{
+        clave: string;
+        etiqueta?: string;
+        titulo: string;
+        estado: string;
+        categoria: import("./gestorDeTareas.js").CategoriaDeTarea;
+        asignado?: string;
+        url?: string;
+    }[]>;
+    ficha(_v: Vinculo, clave: string): Promise<FichaDelGestor>;
+    transiciones(_v: Vinculo, clave: string): Promise<TransicionDelGestor[]>;
+    transicionar(_v: Vinculo, clave: string, transicion: string): Promise<void>;
+    comentar(_v: Vinculo, clave: string, texto: string): Promise<void>;
+}
+/**
+ * De dónde salen los iconos (IXCODE-18): Iconify, por la red. Un puerto porque `npm test` no
+ * puede necesitar una conexión, y porque la tool que lo usa (`agent/grafo/buscarIcono.ts`) no
+ * puede saber si hay red.
+ *
+ * **Lanza ante cualquier fallo**, con un mensaje que no lleva la URL ni el cuerpo remoto: quien
+ * lo llama (la tool) lo DEVUELVE como texto, porque una excepción se lleva el turno y el
+ * agente no reintenta. Ni `svg` ni `buscar` inventan nada cuando la red falta.
+ */
+export interface IconosPort {
+    /** Ids `prefijo:nombre`, ya con forma de id. Vacío es «no hay», no un fallo. */
+    buscar(consulta: string, opciones: {
+        limite: number;
+        prefijo?: string;
+    }): Promise<string[]>;
+    /** El SVG con el color y la altura ya cocidos (`core/iconos.ts#urlDeSvg`). */
+    svg(id: string, opciones: {
+        color: string;
+        tamano: number;
+    }): Promise<string>;
+}
+/**
+ * El doble: un catálogo fijo, sin red. Genera un SVG mínimo con el color y el tamaño pedidos, así
+ * que un test ve que llegaron a quien había que llegar. `fallo` simula la red caída.
+ */
+export declare class IconosEnMemoria implements IconosPort {
+    private readonly ids;
+    private readonly fallo?;
+    readonly [ES_DOBLE] = true;
+    readonly peticiones: Array<{
+        id: string;
+        color: string;
+        tamano: number;
+    }>;
+    constructor(ids?: readonly string[], fallo?: string | undefined);
+    buscar(consulta: string, opciones: {
+        limite: number;
+        prefijo?: string;
+    }): Promise<string[]>;
+    svg(id: string, opciones: {
+        color: string;
+        tamano: number;
+    }): Promise<string>;
+}
+/**
+ * De dónde salen las fuentes: Google Fonts, por la red. Un puerto por lo mismo que `IconosPort`:
+ * `npm test` no puede necesitar una conexión, y la tool (`agent/grafo/fuentesDeGoogle.ts`) no
+ * puede saber si hay red.
+ *
+ * **Lanza ante cualquier fallo**, con un mensaje sin URL ni cuerpo remoto; la tool lo DEVUELVE
+ * como texto. Ninguna operación inventa una familia ni un fichero cuando la red falta.
+ */
+export interface FuentesPort {
+    /** Las familias que encajan (`core/fuentes.ts#buscarEnCatalogo`). Vacío es «no hay», no un fallo. */
+    buscar(consulta: string, limite: number): Promise<FamiliaDeFuente[]>;
+    /** La familia con ese nombre EXACTO, o `undefined` si el catálogo no la tiene. */
+    familia(nombre: string): Promise<FamiliaDeFuente | undefined>;
+    /** Los bytes del `.ttf` estático de ese estilo, ya comprobados (`esTrueType`, tope de tamaño). */
+    ttf(familia: string, peso: Peso, cursiva: boolean): Promise<Uint8Array>;
+}
+/**
+ * El doble: un catálogo fijo, sin red. El `.ttf` son 16 bytes con la firma TrueType y el nombre del
+ * estilo detrás, así que un test ve qué se pidió. `fallo` simula la red caída.
+ */
+export declare class FuentesEnMemoria implements FuentesPort {
+    private readonly familias;
+    private readonly fallo?;
+    readonly [ES_DOBLE] = true;
+    readonly peticiones: Array<{
+        familia: string;
+        peso: Peso;
+        cursiva: boolean;
+    }>;
+    constructor(familias?: readonly FamiliaDeFuente[], fallo?: string | undefined);
+    buscar(consulta: string, limite: number): Promise<FamiliaDeFuente[]>;
+    familia(nombre: string): Promise<FamiliaDeFuente | undefined>;
+    ttf(familia: string, peso: Peso, cursiva: boolean): Promise<Uint8Array>;
+}
+/**
+ * Los conectores MCP, tal como los ve una SESIÓN del agente. Lo implementa el MISMO
+ * `ServicioDeConectores` de Ajustes y del gestor de tareas —uno por proceso: una segunda
+ * instancia no vería la autorización que Ajustes tiene a medias y pisaría su verificador PKCE—,
+ * así que aquí no se construye nada: se pasa.
+ *
+ * Todo LANZA con una frase sin URL ni cuerpo remoto; quien lo llama (la tool) lo DEVUELVE como
+ * texto, porque una excepción se lleva el turno.
+ */
+export interface ConectoresPort {
+    /** Los conectores que ESTE proyecto usa en el chat (`core/conectores.ts#conectoresParaElAgente`). */
+    delProyecto(raiz: string): ConectorParaElAgente[];
+    tools(id: string): Promise<ToolConEsquema[]>;
+    llamar(id: string, nombre: string, args: Record<string, unknown>, opciones?: {
+        topeMs?: number;
+    }): Promise<string>;
+}
+/** El doble: conectores fijos, sin red. `llamadas` deja ver qué llegó; `fallo` simula la red caída. */
+export declare class ConectoresEnMemoria implements ConectoresPort {
+    private readonly conectores;
+    private readonly fallo?;
+    readonly [ES_DOBLE] = true;
+    readonly llamadas: Array<{
+        id: string;
+        nombre: string;
+        args: Record<string, unknown>;
+        topeMs?: number;
+    }>;
+    constructor(conectores?: Record<string, {
+        nombre: string;
+        tools: ToolConEsquema[];
+        respuesta?: string;
+    }>, fallo?: string | undefined);
+    delProyecto(): ConectorParaElAgente[];
+    tools(id: string): Promise<ToolConEsquema[]>;
+    llamar(id: string, nombre: string, args: Record<string, unknown>, opciones?: {
+        topeMs?: number;
+    }): Promise<string>;
+}
+/**
+ * El puente de la sesión remota: un WebSocket SALIENTE y cifrado hacia `xonecode-server`.
+ * Mensajes en CLARO por esta interfaz: el cifrado vive en la implementación real
+ * (`agent/remoto/puenteWebSocket.ts`), que es la única que carga el paquete del puente.
+ */
+export type EstadoDelPuente = {
+    estado: "abierta";
+    url: string;
+} | {
+    estado: "reconectando";
+} | {
+    estado: "cerrada";
+    motivo?: string;
+};
+export interface EscuchasDelPuente {
+    alEstado(estado: EstadoDelPuente): void;
+    alPresencia(moviles: readonly string[]): void;
+    alMensaje(de: string, mensaje: unknown): void;
+}
+export interface CanalRemoto {
+    /** `para` ausente = a todos los móviles. */
+    enviar(para: string | undefined, mensaje: unknown): Promise<void>;
+    /**
+     * Cierra la sala. La promesa se resuelve cuando el relé ya cerró el socket (con tope): por la
+     * vía ngrok el «cerrada» al móvil viaja por el MISMO túnel, y matarlo antes lo perdía.
+     */
+    cerrar(): Promise<void>;
+}
+export interface PuenteRemotoPort {
+    abrir(servidor: string, escuchas: EscuchasDelPuente): Promise<CanalRemoto>;
+}
+/** El doble: deja al test hacer de servidor y de móviles, y apunta lo enviado. */
+export declare class PuenteRemotoEnMemoria implements PuenteRemotoPort {
+    readonly [ES_DOBLE] = true;
+    readonly aperturas: string[];
+    readonly enviados: {
+        para: string | undefined;
+        mensaje: unknown;
+    }[];
+    cerrados: number;
+    /**
+     * Un registro POR canal abierto: el real tiene sockets viejos que aún pueden hablar tras
+     * cerrarse o reemplazarse, y sin poder disparar eventos de uno viejo ese fallo no se probaría.
+     */
+    readonly canales: {
+        servidor: string;
+        escuchas: EscuchasDelPuente;
+        cerrado: boolean;
+        enviados: {
+            para: string | undefined;
+            mensaje: unknown;
+        }[];
+    }[];
+    abrir(servidor: string, escuchas: EscuchasDelPuente): Promise<CanalRemoto>;
+    private ultimo;
+    /** Lo que haría el servidor real; sin índice, sobre el canal MÁS RECIENTE. */
+    abierta(url?: string, canal?: number): void;
+    presencia(...moviles: string[]): void;
+    presenciaDe(canal: number, ...moviles: string[]): void;
+    delMovil(de: string, mensaje: unknown): void;
+    cerrada(motivo?: string, canal?: number): void;
+    reconectando(canal?: number): void;
+}
+/**
+ * El túnel de la vía «ngrok» de la sesión remota: un puente LOCAL más un ngrok que lo publica.
+ * La implementación real (`agent/remoto/tunelNgrok.ts`) entra por opción, como el puente; aquí
+ * solo la forma. Un fallo LANZA con un texto de `core/tunel.ts#MOTIVOS_DEL_TUNEL`, nunca con lo
+ * que diga ngrok.
+ */
+export interface TunelAbierto {
+    /** La dirección del puente por el túnel: `wss://<publica>/ws`. */
+    servidor: string;
+    /** Mata ngrok y cierra el puente local. Idempotente. */
+    cerrar(): Promise<void>;
+    /** Si el túnel se cae solo (ngrok sale): una vez, con un texto fijo. */
+    alCaer(f: (motivo: string) => void): void;
+}
+export interface TunelPort {
+    abrir(o: {
+        dominio?: string;
+    }): Promise<TunelAbierto>;
+}
+/** El doble: apunta aperturas y cierres, y deja al test elegir la dirección, un fallo o la caída. */
+export declare class TunelEnMemoria implements TunelPort {
+    readonly [ES_DOBLE] = true;
+    readonly aperturas: {
+        dominio?: string;
+    }[];
+    cerrados: number;
+    /** El `servidor` que devuelve la próxima apertura. */
+    servidor: string;
+    /** Con valor, la próxima apertura LANZA con este motivo (y se consume). */
+    fallo: string | undefined;
+    /** Un registro por túnel abierto: cerrado o caído ya no avisa, como el real. */
+    private readonly tuneles;
+    abrir(o: {
+        dominio?: string;
+    }): Promise<TunelAbierto>;
+    /** Lo que haría ngrok al salir solo; sin índice, el túnel MÁS RECIENTE. Una vez por túnel. */
+    caer(motivo: string, tunel?: number): void;
+}