xonecode 0.38.44 → 0.39.4

package/dist/agent/turno/resumenDeContexto.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Política de contexto del harness.
+ *
+ * DeepAgents usa 170k tokens cuando el proveedor no publica su ventana de contexto. Con
+ * Ollama eso retrasa demasiado la compresión y cada llamada reenvía lecturas ya resueltas.
+ * Este umbral es independiente del proveedor: limita el coste sin borrar el trabajo reciente.
+ */
+import { type FilesystemBackend } from "deepagents";
+import { createMiddleware } from "langchain";
+import { z } from "zod";
+import { HumanMessage } from "@langchain/core/messages";
+export declare const UMBRAL_RESUMEN_TOKENS = 32000;
+export declare const CONTEXTO_RECIENTE_TOKENS = 8000;
+/**
+ * El prompt del resumen, en CASTELLANO y pidiendo markdown.
+ *
+ * El de deepagents está en inglés, y el resumen no es un texto interno: se le enseña a la
+ * persona en su propio plegable («Resumen del contexto», ver `ETIQUETA_DEL_RESUMEN`). Medido en
+ * MyAllXOne: salía un `## Summary` / `**Task:**` / `Key facts established:` en mitad de una
+ * conversación en castellano. `{conversation}` es el hueco que la librería rellena.
+ *
+ * Lo que NO se le pide aquí es que conserve el encargo: eso lo hace el CÓDIGO
+ * (`conservarElEncargo`), porque un resumen que a veces lo pierde ya costó millones de tokens.
+ */
+export declare const PROMPT_DEL_RESUMEN = "Eres el encargado de resumir una conversaci\u00F3n de trabajo sobre una aplicaci\u00F3n XOne para que el agente pueda seguir sin releerla. Escribe EN CASTELLANO y en markdown legible (t\u00EDtulos cortos y listas), y recoge:\n1. Qu\u00E9 se est\u00E1 haciendo y para qu\u00E9.\n2. Los hechos ya comprobados, con fichero y l\u00EDnea cuando los haya.\n3. Las decisiones tomadas y lo que queda pendiente.\n\nS\u00E9 concreto y breve. No inventes nada que no est\u00E9 en la conversaci\u00F3n.\n\nConversaci\u00F3n a resumir:\n{conversation}\n\nResumen:";
+export declare function resumenDeContexto(backend: FilesystemBackend): import("langchain").AgentMiddleware<z.ZodObject<{
+    _summarizationSessionId: z.ZodOptional<z.ZodString>;
+    _summarizationEvent: z.ZodOptional<z.ZodObject<{
+        cutoffIndex: z.ZodNumber;
+        summaryMessage: z.ZodCustom<HumanMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>>, HumanMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>>>;
+        filePath: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[], readonly []>;
+/**
+ * Devuelve el ENCARGO a la conversación después de que el resumen se lo lleve.
+ *
+ * ## El fallo que cierra, medido offline el 17-09-2026
+ *
+ * Un turno real del usuario: el orquestador delegó una pregunta sobre si XOne servía para un
+ * CRM, el especialista dio 57 pasos y volvió con la respuesta de la pregunta **anterior** —«la
+ * ventana de inicio de mi app»—. El orquestador lo detectó y relanzó dos veces: 1,5M de tokens
+ * para una pregunta. El propio modelo dijo que «parece que trae una sesión antigua pegada», y
+ * esa hipótesis era falsa: los subagentes van en `handoff`, así que arrancan con el encargo y
+ * nada más, y aunque HEREDAN nuestro checkpointer, el namespace de cada `task` lleva el paso y
+ * el id del checkpoint dentro, así que no puede reanudar nada.
+ *
+ * Lo que pasa de verdad está en el middleware de resumen: al cruzar el umbral, los mensajes
+ * `[0, corte)` se sustituyen por UN resumen, y el mensaje 0 es justamente el encargo. `keep`
+ * solo conserva la COLA —no hay opción para el primero— y el prompt de resumen por omisión
+ * pide «temas, decisiones y contexto para continuar», no el encargo. O sea que a partir de los
+ * 32k el especialista sigue trabajando **sin la pregunta que le hicieron**, y contesta a lo que
+ * el resumen le deje entender. Medido en `resumenDeContexto.test.ts`.
+ *
+ * ## Por qué por CÓDIGO y no por `summaryPrompt`
+ *
+ * Se podría pedir en el prompt del resumen que conserve el encargo, y a veces lo haría. Un
+ * agente que pierde su encargo no contesta peor: contesta a otra cosa, y el coste de eso ya
+ * está medido en millones de tokens. Es la misma regla que hace que los avisos de honestidad
+ * sean código y no prompt (`core/bitacora.ts`).
+ *
+ * El encargo se saca del ESTADO, que el resumen no reescribe (guarda un `_summarizationEvent`
+ * y reconstruye la lista efectiva), así que ahí sigue intacto el mensaje 0. Y se reinserta solo
+ * si NO está: por debajo del umbral no hay nada que devolver y duplicarlo sería peor.
+ */
+export declare function conservarElEncargo(): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[], readonly []>;
+/**
+ * El resumen y la devolución del encargo, SIEMPRE juntos y en este orden.
+ *
+ * Van en una sola función porque separarlos es el fallo: el primero de la lista envuelve al
+ * siguiente, así que `conservarElEncargo` tiene que ver los mensajes YA resumidos — delante no
+ * habría nada que devolver. Montarlos a mano en dos sitios (el orquestador y cada especialista)
+ * es el patrón que en este repo ha fallado nueve veces: una composición de producción que vive
+ * en un cierre que los tests doblan, y que puede dejar de estar montada con todo en verde.
+ */
+export declare function resumenConEncargo(backend: FilesystemBackend): ReturnType<typeof createMiddleware>[];
+/**
+ * La marca que distingue, en el stream, la llamada del RESUMEN de la respuesta del agente.
+ *
+ * deepagents resume llamando al MISMO modelo del agente (`request.model`, que gana sobre el
+ * `model` de sus opciones) dentro del MISMO nodo, así que sus chunks llegaban al puente con el
+ * mismo namespace, el mismo nodo y ninguna etiqueta: indistinguibles de la respuesta. El puente
+ * los pintaba en el chat y el `.jsonl` los guardaba como un mensaje del asistente — medido en
+ * MyAllXOne, un `## Summary` en inglés a mitad de la conversación.
+ *
+ * Con la etiqueta, el puente los saca de la respuesta y los manda a su propio acto (`resumen`),
+ * que el cliente pliega como «Verificaciones» o «Permisos». Una ETIQUETA y no una heurística
+ * sobre el texto por la regla de siempre: la clase viaja como dato.
+ */
+export declare const ETIQUETA_DEL_RESUMEN = "xonecode:resumen";
+/**
+ * Cuántas llamadas al modelo puede gastar UN especialista en un encargo.
+ *
+ * Medido el 17-09-2026 con el banco: una pregunta de estructura se resuelve en 3-7 llamadas en
+ * TODO el turno, y la de capacidad —la clase cara— la terminó bien un modelo en 10. El que se
+ * descarriló llevaba 32 y subiendo cuando el reloj lo mató, y 57 en el turno que lo destapó.
+ *
+ * **No es un ahorro, es una frontera.** Un especialista hace una tarea específica con un
+ * encargo bien descrito; si necesita cuarenta llamadas, lo que falla es la delegación, y seguir
+ * dándole cuerda solo hace más cara la misma respuesta mala.
+ *
+ * ## Por qué ya no es 15: aquella medida era de PREGUNTAS, y no todos contestan preguntas
+ *
+ * Las cifras de arriba salieron del banco, que pregunta. Y a un especialista que además
+ * ESCRIBE no le valen: medido el 21-09-2026 sobre MyAllXOne con un encargo de desarrollo de
+ * varios pasos, `analyst-xone` se delegó dos veces, **agotó las 15 las dos veces y no escribió
+ * ni un fichero**. No se descarriló ni entendió mal el encargo —en sus llamadas 2 y 3 abrió
+ * `xone-spec-builder` y `xone-plan-builder`, o sea que sabía que tenía que dejar un plan—:
+ * se le fue el presupuesto ORIENTÁNDOSE, y la fase de escribir, que es el entregable, no
+ * llegó a empezar. `developer-xone` se quedó cortado en el mismo turno.
+ *
+ * Un tope calibrado sobre «leer y contestar» aplicado a «leer y ENTREGAR» corta el trabajo
+ * justo antes de que produzca algo, y encima en silencio: el síntoma es un plan que no
+ * existe, no un error. El número cubre una pasada entera de reconocimiento (~15, medido) más
+ * las lecturas de sus skills y los tres ficheros que deja: es un freno por encima de una
+ * entrega y no por debajo (y hoy está en 100, ver abajo).
+ *
+ * ## Y SUBIRLO NO BASTA — se probó el mismo día y hay que decirlo aquí
+ *
+ * Con 15 el analista gastaba 15 y no escribía; con 30 gastó **30 y tampoco escribió**, dos
+ * pasadas otra vez, y el turno costó un 30 % más (~950k → ~1,24M efectivos) para el mismo
+ * resultado: cero `write_file`, cero `/planes/`. **Expande el reconocimiento hasta llenar lo
+ * que le des** — con 30 llamadas se fue a `LoginColl`, `ContentTareas`, `ClientesCoord` y
+ * `basico.css` para un conversor de divisas.
+ *
+ * O sea que el presupuesto **no era la restricción que ataba**, y este número no es el
+ * arreglo de nada: lo que ata es que escribir está planteado como el ÚLTIMO paso, y eso se
+ * arregla donde vive esa instrucción (`agentesEnDisco.ts#PLAN_DE_DESARROLLO`), no aquí. Esto
+ * se queda porque una entrega no cabía en 15 y sigue sin caber; no porque cure el síntoma.
+ */
+export declare const TOPE_DE_LLAMADAS_DEL_ESPECIALISTA = 100;
+/**
+ * El de quien CONDUCE UN APARATO, que es otro trabajo y por eso otro número.
+ *
+ * El 15 de arriba se midió sobre especialistas que LEEN y contestan: ahí treinta llamadas
+ * significan que la delegación estaba mal escrita. Conducir no es eso — es un bucle de
+ * acto→observa donde cada paso (conectar, listar controles, pulsar, esperar, capturar,
+ * leer el log) es una llamada al modelo POR CONSTRUCCIÓN, y no hay encargo, por bien
+ * escrito que esté, que lo acorte.
+ *
+ * **Medido en un turno real** (MyAllXOne, «crear una opción nueva en el drawer»): el
+ * conductor se delegó SIETE veces en el mismo turno, cada una agotando su tope, ~94
+ * comandos en total. El tope no evitó el gasto: lo partió en siete arranques, y como los
+ * especialistas no comparten transcript, cada uno volvió a conectar y a orientarse desde
+ * cero. Un tope que se rodea re-delegando no acota nada, solo añade amnesia.
+ *
+ * Sigue habiendo tope, y por lo mismo de siempre: un bucle sin freno se come el turno. Lo
+ * que cambia es dónde está el freno — por encima de UNA navegación completa y no por
+ * debajo.
+ */
+export declare const TOPE_DE_LLAMADAS_DEL_CONDUCTOR = 150;
+/**
+ * El tope, NUESTRO y no el de la librería.
+ *
+ * `modelCallLimitMiddleware` cuenta bien y corta bien, pero lo que deja como respuesta es un
+ * `AIMessage` con su frase en inglés —«Model call limits exceeded: …»—, y el `task` de
+ * deepagents devuelve SOLO el último mensaje (`extractLastMessage`). O sea que quien delegó
+ * recibe esa frase y **las quince llamadas de trabajo se pierden**: medido el 19-09-2026,
+ * 100-160k de entrada por especialista devolviendo menos de 900 tokens. Esa es la razón de que
+ * el orquestador encadene al siguiente — no enruta mal, es que no recibe nada con lo que seguir.
+ *
+ * No se pudo arreglar por fuera: su `jumpTo: "end"` **cortocircuita todos los middlewares
+ * posteriores**, incluidos `afterAgent` y su propio reset del contador (medido contra la
+ * librería real con `FakeToolCallingModel` y `runLimit: 0`, ver el test). No hay dónde
+ * engancharse. Así que el contador, la decisión y el mensaje son de aquí: uno de cada, y el
+ * mensaje se compone en `core/` donde se puede probar sin librería.
+ *
+ * `exitBehavior` sigue siendo «terminar» y no «lanzar», por el argumento de siempre: con un
+ * error la delegación entera se cae y el orquestador se queda sin nada, que es como empieza el
+ * bucle de reintentos que costó 1,5M de tokens.
+ */
+export declare function topeDeLlamadas(limite?: number, alCortar?: () => void): ReturnType<typeof createMiddleware>;
+/**
+ * Cuántas TOOLS puede gastar un especialista en un encargo.
+ *
+ * El tope de llamadas al modelo acota los VIAJES; este acota **lo que se acumula**, que es lo
+ * que multiplica. Medido el 17-09-2026 en una conversación de tres preguntas: en la tercera, el
+ * consultor llegó a 43 resultados de tool metidos en su contexto, y como cada llamada al modelo
+ * reenvía todo lo anterior, la primera costó 5.264 tokens y la última 39.888 — 406k en total. No
+ * era un bucle: era la acumulación al cuadrado.
+ *
+ * ## Por qué ya no es 20, y qué NO cambia
+ *
+ * Aquel veinte era generoso contra la regla del CONSULTOR, que ya le pide «máximo tres
+ * referencias por pregunta y un `grep` por hipótesis». Pero el consultor contesta, y hay
+ * especialistas que ENTREGAN: medido el 21-09-2026, `analyst-xone` gastó su pasada entera
+ * inventariando (`glob *.xne`, `mappings.xne` paginado, `regex_search create table`, greps de
+ * `SqlManager`) y se quedó sin tools antes de escribir el plan — ver
+ * `TOPE_DE_LLAMADAS_DEL_ESPECIALISTA`, donde está la medida entera.
+ *
+ * Lo que NO cambia es el motivo por el que este tope existe, que es la acumulación y no el
+ * bucle: cada llamada reenvía todo lo anterior, así que esto sigue siendo cuadrático y sigue
+ * habiendo techo. El número nuevo cubre un reconocimiento completo más la escritura del
+ * entregable y se queda por debajo del orquestador; el 43 de aquel incidente sigue fuera.
+ *
+ * ## Por qué ya no es 35: el tope bloqueaba la ENTREGA (23-09-2026)
+ *
+ * Medido en MyAllXOne, «una calculadora a partir de una maqueta de Stitch»: el developer gastó
+ * 39, 39 y 49 tools en tres encargos y **ninguno escribió**. Con `continue`, al agotarse, el
+ * tope bloquea TODA tool que venga después, y eso incluye `write_file` y `edit_file`: el
+ * especialista explora hasta el techo y cuando va a crear el `.xne` se lo rechazan. Se pagaba
+ * el reconocimiento entero (1,17M de entrada solo el developer) y no salía nada; el
+ * orquestador lo leía como «se quedan sin turnos explorando» y re-delegaba, que es el mismo
+ * reconocimiento otra vez desde cero.
+ *
+ * **Así que deja de ser una economía y pasa a ser un GUARDA**, como el del orquestador: por
+ * encima de lo observado, para que no muerda en un encargo normal y solo pare uno desbocado.
+ * Lo que sigue acotando de verdad es el tope de LLAMADAS, que con tools en paralelo llega
+ * antes. **Y por eso ya no está por debajo del del orquestador**: esa relación tenía sentido
+ * mientras este número era un presupuesto de trabajo.
+ *
+ * La alternativa que se descartó, para no rediscutirla: excluir las escrituras del conteo
+ * (un middleware propio, porque el de langchain no sabe excluir). Arreglaba el bloqueo de la
+ * entrega sin tocar el número; se prefirió el tope alto, que es su criterio de siempre —los
+ * topes se ponen altos para que no muerdan—.
+ */
+export declare const TOPE_DE_TOOLS_DEL_ESPECIALISTA = 150;
+/**
+ * **`continue`, y NO `end`: son incompatibles con pedir varias tools a la vez.**
+ *
+ * Medido el 17-09-2026 en el primer turno con el tope puesto: «Cannot end execution with other
+ * tool calls pending. Found calls to: read_file, ls, grep». La documentación de langchain lo
+ * dice igual —`end` «raises NotImplementedError if there are multiple tool calls»— y nosotros le
+ * PEDIMOS al especialista que agrupe las lecturas independientes en un mismo mensaje, así que
+ * llegar al tope con varias en vuelo es el caso normal, no el raro.
+ *
+ * `continue` bloquea las que sobran con un mensaje de error y deja que el modelo termine: se
+ * queda sin más tools y contesta con lo que tiene, que es lo mismo que buscaba `end` pero sin
+ * romperse. `error` tumbaría la delegación entera, que es como empieza el bucle de reintentos.
+ *
+ * Dos reglas nuestras que vivían sin hablarse —«agrupa las tools» y «corta al llegar al tope»—
+ * y cuyo choque solo se ve corriendo. Por eso el test las ata juntas.
+ */
+export declare const SALIDA_DEL_TOPE_DE_TOOLS: "continue";
+/**
+ * Cuántas TOOLS puede gastar el ORQUESTADOR, y **es un guarda, no una economía**.
+ *
+ * ## Por qué NO lleva tope de LLAMADAS, y esto sí
+ *
+ * El argumento contra caparle las llamadas sigue en pie y es bueno: **el que contesta al
+ * usuario no puede quedarse a medias**. Pero ese argumento es sobre no cortarle la VOZ, y el
+ * tope de tools con `exitBehavior: "continue"` no corta nada — se queda sin más tools y
+ * contesta con lo que tenga. Le quita la pala, no la palabra.
+ *
+ * ## Por qué el número es ALTO, y qué NO es
+ *
+ * **No está puesto para ahorrar.** Medido el 19-09-2026 sobre turnos reales, el orquestador
+ * gasta 41 tools en un encargo visual normal —18 lecturas, 15 `grep`, 5 de navegación y 3
+ * delegaciones— y sus llamadas al modelo van de 14 a 49 según el turno. Esas lecturas SON el
+ * trabajo: recortarlas no abarata el turno, empeora la respuesta. Lo que abarata es quitarle la
+ * NECESIDAD de leer, que es lo que hacen `conHechosDelProyecto` y la operación `estilos` — y se
+ * está moviendo: la navegación pasó de 1-2 usos por turno a 5.
+ *
+ * Así que esto se sitúa POR ENCIMA de lo observado a propósito: no muerde en ningún turno
+ * medido y solo para uno desbocado. Es el mismo papel que `topeDeRondas` y el tope propio de
+ * los artefactos — «aquí no hay humano que frene el bucle»—, y por eso vive aquí y no en una
+ * medida de coste. Si algún día muerde en un turno normal, lo que hay que mirar es por qué ese
+ * turno necesitó 60 tools, no subir el número.
+ */
+export declare const TOPE_DE_TOOLS_DEL_ORQUESTADOR = 60;
+export declare function topeDeTools(limite?: number): import("langchain").AgentMiddleware<import("zod/v3").ZodObject<{
+    threadToolCallCount: import("zod/v3").ZodDefault<import("zod/v3").ZodRecord<import("zod/v3").ZodString, import("zod/v3").ZodNumber>>;
+    runToolCallCount: import("zod/v3").ZodDefault<import("zod/v3").ZodRecord<import("zod/v3").ZodString, import("zod/v3").ZodNumber>>;
+}, "strip", import("zod/v3").ZodTypeAny, {
+    threadToolCallCount: Record<string, number>;
+    runToolCallCount: Record<string, number>;
+}, {
+    threadToolCallCount?: Record<string, number> | undefined;
+    runToolCallCount?: Record<string, number> | undefined;
+}>, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[], readonly []>;

package/dist/agent/turno/resumenDeTool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * La LISTA BLANCA de la línea de estado: qué argumento de cada tool puede salir como
+ * `detalle` del evento `tool`.
+ *
+ * La regla dura está documentada en `core/events.ts`: ningún evento lleva argumentos de
+ * tool crudos, porque `write_file` lleva el contenido del fichero y una tool MCP lleva
+ * el bearer — enseñar el progreso no puede ser la forma de filtrar un secreto. Este
+ * módulo es la otra mitad de esa regla: no se FILTRA nada, se ELIGE a mano un campo por
+ * tool — una ruta o un patrón, nunca contenido — y lo que no está en la tabla no sale.
+ * Los nombres de campo son los de las tools de fichero de deepagents, verificados
+ * contra su dist (`file_path` con `path` normalizado, `pattern` en glob/grep).
+ */
+/** Valores escalares que una traza local puede conservar sin volcar contenido. */
+export type ParametrosSeguros = Record<string, string | number | boolean>;
+/**
+ * Campos permitidos por tool. Es una lista blanca deliberada: ni `content`,
+ * ni `old_string`/`new_string`, ni la descripción de `task` llegan a disco.
+ *
+ * Los parámetros de paginación y acotación son justo los que necesitamos para
+ * detectar una lectura masiva o una búsqueda mal afinada.
+ */
+export declare const CAMPOS_SEGUROS: Record<string, readonly string[]>;
+/** Argumentos acotados y seguros para la traza opt-in de diagnóstico. */
+/** Huella corta y estable de un texto. No reversible: solo sirve para comparar dos. */
+export declare function huellaDeTexto(texto: string): string;
+export declare function parametrosDe(nombre: string, args: unknown): ParametrosSeguros | undefined;
+/**
+ * El `detalle` de una llamada, o `undefined` si no hay nada permitido que contar.
+ *
+ * Los argumentos llegan como objeto o como cadena JSON (así viajan en las
+ * `tool_calls`); un JSON roto es una tool rota, no una excepción que tumbe el turno.
+ */
+export declare function detalleDe(nombre: string, args: unknown): string | undefined;

package/dist/agent/turno/rubrica.d.ts

@@ -0,0 +1,35 @@
+import { createMiddleware } from "langchain";
+import { type Calificacion, type EstadoDeRubrica } from "../../core/rubrica.js";
+/**
+ * Quién juzga. **Un PUERTO y no un modelo construido dentro**, que es la diferencia con el
+ * original de Python: así el bucle entero se prueba sin red y sin clave, que es el invariante
+ * que sostiene el diseño de este repo. Quien lo implemente con un modelo de verdad vive fuera.
+ *
+ * Recibe el transcript tal cual y la rúbrica. Devolver es obligatorio: si no puede juzgar, que
+ * lance — el bucle distingue «no cumple» de «no se pudo juzgar», y son dos cosas distintas.
+ */
+export type Calificador = (mensajes: readonly unknown[], rubrica: string) => Promise<Calificacion>;
+/**
+ * El bucle de rúbrica, portado del `RubricMiddleware` de deepagents (que está en su SDK de
+ * Python y no en el de JS).
+ *
+ * En la parada natural del agente —el modelo contesta sin pedir más tools— se juzga lo hecho
+ * contra la rúbrica. `necesita-revision` mete el comentario como mensaje y **salta de vuelta al
+ * modelo** (`jumpTo: "model"`, que el langchain de JS admite desde `afterAgent`); cualquier otro
+ * veredicto cierra.
+ *
+ * **Sin rúbrica no hace NADA**, igual que el original, y por eso se puede montar siempre: un
+ * turno normal no paga ni una llamada. Lo que decide si hay bucle es el dato, no una bandera.
+ *
+ * **Y a diferencia del original, un final no satisfecho SE DICE**: allí el estado vive en un
+ * campo privado y la última respuesta sigue siendo la del modelo —que puede estar afirmando que
+ * terminó—. Aquí se apila el aviso, que es la misma regla que hizo falta en el tope de llamadas.
+ *
+ * `alEvaluar` existe para que el harness pueda enseñarlo donde una persona lo vea: un mensaje
+ * apilado llega al transcript, pero no a la pantalla.
+ */
+export declare function middlewareDeRubrica(opciones: {
+    calificar: Calificador;
+    tope?: number;
+    alEvaluar?: (estado: EstadoDeRubrica, vuelta: number) => void;
+}): ReturnType<typeof createMiddleware>;

package/dist/agent/turno/sesionReal.d.ts

@@ -0,0 +1,89 @@
+/**
+ * El contrato de una sesión de turno real, que cumplen LOS DOS motores —deepagents
+ * (`turnoReal.ts#abrirSesionReal`) y TrueForge (`motores/trueforge/sesionTrueforge.ts`)—.
+ *
+ * Vive aparte, y no en `turnoReal.ts`, porque los dos lo necesitan y `turnoReal.ts` es quien
+ * elige el motor: si el contrato viviera allí, TrueForge tendría que importar a quien lo importa
+ * a él, que es el ciclo que había (`src/ciclos.test.ts` lo vigila).
+ */
+import type { Piel } from "../../core/turno.js";
+import type { Bitacora } from "../../core/bitacora.js";
+import type { ConsumoDeSesionPorCuenta, ModelosPort } from "../../core/ports.js";
+import type { ResultadoDeTurno } from "../../core/entrega.js";
+import type { TokenTracker } from "../../vendor/tokenTracking.js";
+import type { Cambio } from "./instantanea.js";
+/**
+ * Una sesión de turno real: varios turnos sobre el MISMO agente y el MISMO hilo.
+ *
+ * Es la extracción de `correrReal` (`cli/run.ts`), reescrita de disparo único a reutilizable:
+ * el agente, el checkpointer, el tracker y el `thread_id` viven en el cierre de
+ * `abrirSesionReal` y se conservan entre llamadas. Lo que cada `turno()` renueva es la foto
+ * del ANTES, porque el diff es del TURNO y no de la sesión: si la foto fuese una por sesión,
+ * el turno 3 reportaría también lo que escribió el turno 1.
+ */
+export interface SesionReal {
+    /**
+     * Un turno. Devuelve la bitácora, los cambios que dejó en el proyecto y **lo que hay que
+     * saber para decidir si el trabajo se puede dar por bueno** (`ResultadoDeTurno`).
+     *
+     * Esas tres últimas cosas —cómo acabó el verificador, cuántas escrituras quedaron sin
+     * aplicar y los hallazgos— no estaban, y su ausencia era una deuda MEDIDA: con las
+     * tareas de fondo aplicando escrituras solas, un turno se cortó por el tope de rondas
+     * con cuatro ficheros escritos, una escritura abandonada, el verificador sin correr ni
+     * una vez… y el kanban diciendo «terminada». La bitácora no sirve para esto: `corrio`
+     * responde si un nodo pasó, no con qué veredicto.
+     */
+    turno(peticion: string, piel: Piel): Promise<ResultadoDeTurno & {
+        bitacora: Bitacora;
+        cambios: Cambio[];
+        /** Se agotó el tope de rondas con aprobaciones sin resolver. */
+        cortadoPorTope: boolean;
+    }>;
+    /** Rehace el agente con modelos nuevos, CONSERVANDO el hilo. Para `/modelo`. */
+    cambiarModelos(modelos: ModelosPort): Promise<void>;
+    /** Abre un hilo nuevo. Para `/nuevo`. */
+    /**
+     * Abre un hilo nuevo. **Acepta el id** porque quien lo pide puede ya tener uno.
+     *
+     * Sin el parámetro había DOS ids para un mismo hilo: la consola generaba el suyo en su
+     * `/nuevo` y la sesión otro aquí, así que `/hilo` enseñaba un `thread_id` que no era el
+     * que usaba el grafo. Un identificador que no identifica es peor que no darlo.
+     */
+    nuevoHilo(id?: string): void;
+    /** Aborta de inmediato la llamada al modelo que está en curso, si la hay. */
+    cancelar(): void;
+    /** Lo que lleva consumido la sesión, en sus DOS cuentas (ver `ConsumoDeSesionPorCuenta`). */
+    consumo(): ConsumoDeSesionPorCuenta;
+    /** Se avisa en cada cambio de cualquiera de las dos. Devuelve cómo dejar de escuchar. */
+    alCambiarConsumo(oyente: () => void): () => void;
+    /**
+     * Termina la sesión: aborta lo que esté en curso y la deja inservible.
+     *
+     * Hace falta para CAMBIAR de proyecto (`web/servidor/vestibulo.ts`): la consola web abre
+     * una consola de proyecto a la vez, y cerrar la anterior es agotar sus `lineas` para que
+     * `correrConsola` retorne. Sin esto, un turno en vuelo mantendría el lazo dentro del
+     * `await` durante minutos y la apertura del proyecto siguiente se quedaría esperando.
+     *
+     * Qué libera y qué no, dicho entero porque una fuga callada es peor que una declarada:
+     * el `MemorySaver`, el agente construido y el tracker viven en el CIERRE de
+     * `abrirSesionReal` y no exponen ningún `close()` —no hay sockets ni descriptores, el
+     * cliente del modelo es por llamada—, así que se recogen con la referencia a la sesión
+     * en cuanto quien la abrió la suelta. Lo único que hay que soltar activamente es la
+     * llamada en curso, y eso es exactamente `cancelar()`. La bandera de cerrada existe para
+     * que un `turno()` tardío falle en vez de revivir un hilo que ya nadie mira.
+     */
+    cerrar(): void;
+    /**
+     * Añade una nota al turno EN MARCHA (IXCODE-4). Opcional: el ejecutor guionizado y
+     * `deepagents` no lo tienen.
+     */
+    agregarNota?(texto: string): void;
+    /**
+     * DETENER y replanificar el turno EN MARCHA (IXCODE-4): los especialistas cierran con su
+     * resumen y el orquestador replanifica con `texto`. Opcional: solo TrueForge lo tiene.
+     */
+    detener?(texto: string): void;
+    readonly tracker: TokenTracker;
+    /** El `thread_id` ACTUAL: tras `nuevoHilo()` cambia, y hay que leerlo, no cachearlo. */
+    readonly hilo: string;
+}

package/dist/agent/turno/textoDeTool.d.ts

@@ -0,0 +1,19 @@
+/**
+ * El contenido de un mensaje, como cadena.
+ *
+ * `JSON.stringify` es el último recurso y no el primero: para bloques de texto daría
+ * `[{"type":"text","text":"…"}]`, y el modelo tendría que desenterrar el contenido de
+ * su propio envoltorio en cada llamada.
+ */
+export declare function aTexto(contenido: unknown): string;
+/** ¿Es un `ToolMessage`? Se mira por las dos vías: el tipo de langchain y el campo. */
+export declare function esMensajeDeTool(msg: unknown): boolean;
+/**
+ * Convierte los `ToolMessage` de la petición, sin tocar el historial.
+ *
+ * Va en `wrapModelCall` y no en `beforeModel` a propósito: lo que hay que arreglar es lo
+ * que SE MANDA, no lo que se guarda. Reescribir el estado perdería el contenido
+ * estructurado para todo lo demás —el rastreo, un proveedor que sí lo acepte— por un
+ * problema de un solo conversor.
+ */
+export declare function middlewareTextoDeTool(): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[], readonly []>;