xonecode 0.38.44 → 0.39.2

package/dist/agent/cloudstudio/cloudstudioClient.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `CloudStudioPort` sobre el MCP real.
+ *
+ * La costura es una función `invocar`, no el `Client` del SDK: así los tests prueban el
+ * comportamiento —reapertura, desenvoltura, argumentos— sin red ni SDK. La sesión viva
+ * que produce ese `invocar` la construye `sesionCloudStudio` (`agent/cloudstudio/cloudstudioMcp.ts`);
+ * este módulo no abre nada por su cuenta.
+ */
+import type { CloudStudioPort } from "../../core/ports.js";
+export interface LlamadaMcp {
+    nombre: string;
+    argumentos: Record<string, unknown>;
+}
+export type Invocar = (nombre: string, argumentos: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Las pausas antes de cada reapertura cuando CloudStudio dice que no hay proyecto abierto:
+ * la primera inmediata y las siguientes, crecientes. Tres intentos en total, y ni uno más.
+ */
+export declare const PAUSAS_DE_REAPERTURA_MS: readonly [0, 1000, 3000];
+/**
+ * @param nombreDeProyecto El NOMBRE del proyecto, nunca su id. El servidor abre por nombre y
+ * rechaza el identificador («not found for user», medido), y este valor es el que usa la
+ * reapertura automática de `conSesion`. Pasarle el id daba un bucle sordo: se reabría con
+ * algo que el servidor no encuentra, la tool volvía a decir «no project is open», y el
+ * error hablaba de la tool y no del argumento equivocado.
+ */
+export declare function clienteCloudStudio(invocar: Invocar, nombreDeProyecto: string, 
+/** La pausa entre reaperturas. Por parámetro para que los tests no esperen de verdad. */
+esperar?: (ms: number) => Promise<void>): CloudStudioPort;

package/dist/agent/cloudstudio/cloudstudioMcp.d.ts

@@ -0,0 +1,414 @@
+/**
+ * Conexión MCP de CloudStudio.
+ *
+ * El endpoint protege sus tools con OAuth del IDS. Este adaptador realiza el flujo
+ * Authorization Code + PKCE que espera MCP Streamable HTTP: abre el navegador, recibe
+ * el callback en loopback y guarda el resultado SOLO en ~/.xonecode, nunca en el repo.
+ */
+import { type OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { Entorno } from "../../core/settings.js";
+/**
+ * Debe ser estable: el IDS registra el redirect_uri del cliente OAuth.
+ *
+ * Se exporta porque `cli/main.ts` necesita el mismo número para rechazar `--puerto 7634`
+ * en el servidor web (el callback de OAuth y la web no pueden compartir puerto). Antes
+ * había una copia literal en `main.ts` porque este valor era privado; una sola fuente
+ * evita que las dos constantes diverjan si el puerto cambia algún día.
+ */
+export declare const PUERTO_CALLBACK = 7634;
+/**
+ * El CloudStudio oficial. Vive aquí y no en `cli/consola.ts` (de donde se movió) porque
+ * es la dirección de un SERVIDOR, no un detalle de la piel de consola, y
+ * `adoptarLegadoSiProcede` —de este mismo fichero— la necesita para decidir si el fichero
+ * plano de antes de los entornos pertenece al oficial: `agent/` no puede importar de
+ * `cli/` (convención documentada en `agent/turno/turnoReal.ts`), así que si esto se hubiera
+ * quedado en `consola.ts` la migración habría tenido que duplicar el literal.
+ */
+export declare const URL_CLOUDSTUDIO_POR_OMISION = "https://mcp.xonewebstudio.com/mcp";
+/** Permisos mínimos para descubrir el catálogo MCP; no otorgan escritura ni ejecución. */
+export declare const SCOPES_CLOUDSTUDIO: readonly ["openid", "profile", "email", "offline_access", "mcp.read"];
+export declare const SCOPES_CLOUDSTUDIO_ESCRITURA: readonly ["openid", "profile", "email", "offline_access", "mcp.read", "mcp.write"];
+/** Un único consentimiento para el trabajo normal del agente; jamás incluye mcp.admin. */
+export declare const SCOPES_CLOUDSTUDIO_AGENTE: readonly ["openid", "profile", "email", "offline_access", "xonewebstudioapi", "mcp.read", "mcp.write", "mcp.execute", "mcp.branch"];
+/** El juego de credenciales de UN entorno. Es el `EstadoOAuth` plano de antes de que
+ *  hubiera más de un CloudStudio. */
+export type EstadoDeEntorno = {
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+    codeVerifier?: string;
+    /** Permisos concedidos junto al token; evita reautorizar si el servidor omite `scope`. */
+    scopes?: string[];
+};
+/** El id reservado para el fichero plano de antes de los entornos: ver `leerEstado`. */
+export declare const CLAVE_LEGADO = "legado";
+/**
+ * El fichero entero: un juego POR ENTORNO.
+ *
+ * Antes era un solo juego plano en la raíz del fichero, porque solo existía un
+ * CloudStudio. Con entornos registrables —los dos oficiales y el on-premise de un
+ * cliente— hace falta indexar: cerrar sesión en uno no puede tocar los tokens de los
+ * demás, así que cada entorno vive en su propia clave y una escritura solo toca la suya.
+ *
+ * La clave `legado` es el fichero plano de antes, ya envuelto. No se puede adivinar a
+ * qué entorno pertenecía —el formato viejo no guardaba la URL—, así que se conserva
+ * intacto hasta que `adoptarLegadoSiProcede` lo adopta al registrar el entorno de
+ * `URL_CLOUDSTUDIO_POR_OMISION`, la única URL que ese fichero pudo haber usado por
+ * omisión (si el usuario tecleó otra URL en el paso de alta, la migración automática no
+ * la alcanza y el fichero se queda en `legado` para siempre: no hay forma de saberlo).
+ */
+export type EstadoOAuth = {
+    version: 2;
+    porEntorno: Record<string, EstadoDeEntorno>;
+};
+/** Resultado reducido: los esquemas completos de tools no deben entrar en el transcript. */
+export interface ConexionCloudStudio {
+    url: string;
+    scopes: readonly string[];
+    herramientas: Array<{
+        nombre: string;
+        descripcion: string;
+    }>;
+    proyectos: Array<{
+        id: string;
+        nombre: string;
+    }>;
+    /**
+     * Cómo se llama a sí mismo el servidor MCP (el `serverInfo` del `initialize`). Ausente
+     * cuando no publica ninguno legible: entonces no se afirma nada — quien registra el
+     * entorno se queda con el nombre que dedujo de la URL.
+     */
+    servidor?: {
+        nombre: string;
+        version?: string;
+    };
+}
+export interface OpcionesCloudStudio {
+    /** Costura para tests y para no acoplar el agente a un navegador concreto. */
+    abrirNavegador?: (url: URL) => void;
+    /** Se muestra antes de abrir el navegador; útil también en sesiones SSH. */
+    informar?: (texto: string) => void;
+    /** Tope de espera de la vuelta del usuario desde el IDS. */
+    timeoutMs?: number;
+    rutaAuth?: string;
+    /** Scope elegido conscientemente por el comando o por una futura tool permitida. */
+    scopes?: readonly string[];
+    /**
+     * Qué entorno guarda/lee sus credenciales, dentro del fichero único indexado por
+     * entorno. Se cae a `legado` cuando no se indica: es el mismo juego que usaba el
+     * fichero plano de antes de que existieran entornos registrables, así que un
+     * llamador que todavía no conoce su id de entorno (el flujo de terminal de hoy;
+     * `cli/main.ts` no lo pasa) sigue leyendo y escribiendo exactamente donde lo hacía.
+     */
+    entornoId?: string;
+    /**
+     * A dónde mandar el navegador cuando la autorización SALE BIEN.
+     *
+     * La página del callback termina diciendo «Ya puedes volver a xonecode», que en la
+     * consola de terminal es cierto y en la web es una instrucción falsa: quien autorizó
+     * desde el navegador ya está donde tiene que estar, y lo que le hace falta es volver a
+     * SU pestaña. Con esta opción el callback responde un 302 a la URL de la web.
+     *
+     * El puerto del callback (7634) no se mueve: el IDS registra ese `redirect_uri`. Lo que
+     * cambia es lo que se contesta DESPUÉS de recibir el código, que el IDS no mira.
+     *
+     * El fallo NO redirige, a propósito: la web todavía no sabe nada del error —se entera
+     * por la promesa rechazada, y lo cuenta por su propio canal— así que mandarla allí
+     * enseñaría un vestíbulo en blanco en lugar del motivo. La página de error se queda, con
+     * un texto que no presupone terminal.
+     */
+    redirigirA?: string;
+}
+type DefinicionDeTool = {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+};
+/**
+ * Qué tool lista los proyectos. Primero los nombres conocidos, en orden; si ninguno está,
+ * una heurística conservadora: tiene que hablar de listar Y de proyectos, y no pedir
+ * argumentos. `studio_open_project` o `studio_download_project` no la superan a propósito
+ * — abrir el proyecto equivocado en el arranque es peor que no encontrar la tool.
+ */
+export declare function herramientaDeProyectos(tools: readonly DefinicionDeTool[]): DefinicionDeTool | undefined;
+/** Extrae solo una identidad visible; el resultado íntegro nunca va al transcript. */
+/**
+ * Un proyecto del listado remoto, con lo ÚNICO que se conserva de él.
+ *
+ * La respuesta de `studio_list_projects` trae bastante más —permisos (`rights`), el correo
+ * del propietario (`suser`), una tabla de `studiopermissions`— y nada de eso sale de aquí:
+ * esta función es el punto de estrangulamiento, y hay un test que compara las claves
+ * EXACTAS de lo que devuelve para que un «ya que estamos, llevemos también el correo» no
+ * cuele el de un compañero de camino.
+ *
+ * `compartido` y `ultimoAcceso` son las DOS excepciones que se añadieron a la mínima de
+ * siempre (`id`, `nombre`), y las dos por el mismo motivo: son datos del PROYECTO, no de una
+ * PERSONA. `compartido` es un booleano y no el correo de quien compartió; `ultimoAcceso` es
+ * la fecha (`last`) y no trae más contexto que ella. Las dos son opcionales a propósito:
+ * ausente significa «CloudStudio no lo dijo», que no es lo mismo que «no» / «nunca abierto».
+ */
+export interface ProyectoRemoto {
+    id: string;
+    nombre: string;
+    /** Compartido CONTIGO por otra persona. Ausente = el servidor no lo dijo. */
+    compartido?: boolean;
+    /** Fecha ISO del último acceso (`last`). Ausente = no consta — el fixture medido contra
+     *  el servidor real trae un proyecto sin este campo. */
+    ultimoAcceso?: string;
+}
+export declare function proyectosDeResultado(valor: unknown): ProyectoRemoto[];
+/** Dónde vive el estado OAuth cuando nadie inyecta otra ruta. Exportada porque
+ *  `web/servidor/vestibulo.ts` la necesita para `adoptarLegadoSiProcede`: una segunda copia
+ *  del literal es cómo divergen las rutas el día que una se corrige y la otra no. */
+export declare function rutaAuthPorDefecto(): string;
+/**
+ * Lee el fichero entero. Un formato SIN `version` es el plano de antes de los entornos:
+ * se envuelve como `{ version: 2, porEntorno: { legado: <plano> } }` **solo en memoria**
+ * — un arranque de solo lectura (`xonecode config`, `describe`) no puede reescribir el
+ * disco del usuario, así que la migración se materializa recién en la primera escritura
+ * (`guardarEstadoDeEntorno`, `adoptarLegadoSiProcede`), nunca aquí.
+ */
+export declare function leerEstado(ruta: string): EstadoOAuth;
+/**
+ * Un fichero de una versión futura y desconocida no se puede sobrescribir a ciegas: este
+ * código no sabe qué juegos de credenciales lleva dentro, y `leerEstado` lo trata como
+ * vacío para no tumbar un arranque de solo lectura. Escribir SOBRE ese vacío destruiría
+ * lo que hubiera. Un JSON corrupto (parse roto) es harina de otro costal —ya se
+ * sobrescribía así antes de que existieran los entornos, es el comportamiento actual que
+ * el enunciado pide no tocar— así que solo se bloquea la versión reconocible pero
+ * distinta de 2, nunca el texto irrecuperable.
+ */
+export declare class EstadoOAuthVersionIncompatible extends Error {
+}
+/**
+ * Sustituye el juego de credenciales de UN entorno y deja los demás tal cual estaban:
+ * lee el fichero entero, reemplaza solo `porEntorno[id]` y reescribe con la misma
+ * mecánica de temporal + `rename` de `guardarEstado` — es la que asegura 0600/0700 y que
+ * un fallo a mitad de escritura no deja el fichero truncado.
+ */
+export declare function guardarEstadoDeEntorno(ruta: string, id: string, datos: EstadoDeEntorno): void;
+/**
+ * Cierra sesión en UN entorno. Si no tenía nada guardado no hay nada que tocar: escribir
+ * de todos modos reescribiría el fichero entero (y su mtime) sin que haya cambiado nada
+ * observable.
+ */
+export declare function olvidarEntorno(ruta: string, id: string): void;
+/**
+ * Adopta `legado` como el juego del entorno recién registrado, y SOLO si su URL es la
+ * oficial por omisión — es la única URL que el fichero plano pudo haber usado sin que el
+ * usuario tecleara una distinta a mano (ver el comentario de `EstadoOAuth`). Si `legado`
+ * no existe, o ya hay algo guardado bajo `entorno.id`, no hace nada: no hay nada que
+ * migrar en el primer caso, y pisar un juego ya autenticado sería peor que dejar el
+ * plano huérfano en el segundo.
+ */
+export declare function adoptarLegadoSiProcede(ruta: string, entorno: Pick<Entorno, "id" | "url">): void;
+/**
+ * Abre una URL en el navegador del sistema. Exportada porque la consola web hace lo mismo
+ * al arrancar (`web/servidor/arranque.ts`) y tres `spawn` con la misma tabla de comandos
+ * en dos ficheros es cómo divergen.
+ *
+ * El `on("error")` no es decorativo: `spawn` de un comando que no existe —un contenedor
+ * sin `xdg-open`, un SSH sin escritorio— no lanza, EMITE `error`, y sin escucha eso es una
+ * excepción no capturada que se lleva el proceso por delante. Aquí abrir el navegador es
+ * siempre lo ACCESORIO: la URL ya está impresa, y el servidor tiene que seguir en pie.
+ */
+/**
+ * Con qué comando se abre una URL en cada sistema. PURA, y separada por eso mismo: el caso
+ * que se rompió no se podía probar desde un Mac sin sacarlo de aquí.
+ *
+ * **En Windows NO se usa `cmd /c start`, y ese era el fallo.** MEDIDO: en Windows el login
+ * de OAuth fallaba SIEMPRE con `invalid_request · The mandatory 'client_id' parameter is
+ * missing` (OpenIddict ID2029), y el navegador abría
+ * `…/connect/authorize?response_type=code` — cortado justo en el primer `&`.
+ *
+ * La causa es la combinación de dos reglas, ninguna de las dos nuestra: Node solo
+ * entrecomilla un argumento si lleva espacios, tabuladores o comillas, y la URL de
+ * autorización no lleva ninguno; y `cmd.exe` trata `&` como SEPARADOR DE COMANDOS. Así que
+ * la línea llegaba partida y `start` solo recibía hasta el primer `&` — se perdían
+ * `client_id`, `redirect_uri`, `code_challenge`, `scope` y `resource`, y el resto se
+ * intentaba ejecutar como comandos sueltos. En silencio, porque el `spawn` va con
+ * `stdio: "ignore"` y el `on("error")` se lo traga. El SDK pone `response_type` primero y
+ * `client_id` justo después (`client/auth.js`), que es por qué lo que sobrevivía era
+ * exactamente ese primer parámetro.
+ *
+ * `rundll32 url.dll,FileProtocolHandler` recibe la URL como **un solo argumento** y no pasa
+ * por ningún intérprete de comandos, así que la clase entera de fallo desaparece: ni `&`,
+ * ni `%VAR%`, ni comillas. La alternativa era seguir con `cmd` entrecomillando a mano y
+ * `windowsVerbatimArguments`, que arregla el `&` pero deja la URL a merced del resto de la
+ * sintaxis de `cmd` — se prefirió quitar el intérprete a aprender a escaparlo.
+ *
+ * macOS y Linux nunca lo tuvieron: `open` y `xdg-open` reciben la URL como argumento único
+ * y no hay shell de por medio.
+ */
+export declare function comandoParaAbrir(plataforma: NodeJS.Platform, url: URL): {
+    comando: string;
+    args: string[];
+};
+export declare function abrirEnSistema(url: URL): void;
+export declare const AVISO_DE_URL_DE_MCP = "la URL del MCP debe ser HTTPS \u2014solo se admite http:// en 127.0.0.1 o localhost, para un on-premise en desarrollo\u2014 y no puede incluir credenciales";
+/**
+ * La ÚNICA regla de qué URL de MCP vale, y por eso vive aquí y no en cada gate.
+ *
+ * Había tres puertas con dos criterios: el wizard del navegador aceptaba loopback,
+ * `vestibulo.ts#urlDeEntornoValida` exigía HTTPS y lo rechazaba, y esta función —la última,
+ * la que de verdad conecta— también. Registrar un entorno on-premise de desarrollo era
+ * imposible por la segunda, y aflojar solo la segunda habría dejado registrar uno que
+ * después fallaba al primer `conectarCloudStudio`: un alta que se puede escribir y no se
+ * puede usar es peor que el rechazo claro de hoy.
+ *
+ * Se resuelve por el lado PERMISIVO porque el caso existe —un CloudStudio on-premise
+ * levantado en local durante el desarrollo— y porque en loopback el texto plano no cruza
+ * ninguna red: es el mismo trato que ya se da al `redirect_uri` del callback de OAuth
+ * (`http://127.0.0.1:7634`) y a la propia consola web. Fuera de loopback, HTTPS y nada más.
+ * La copia del cliente (`apps/web/src/componentes/Wizard.tsx#urlDeEntornoAceptable`) dice
+ * lo mismo y no puede importar esta: lo prohíbe `src/web/frontera.test.ts`.
+ */
+export declare function urlDeMcpAceptable(valor: string): boolean;
+/**
+ * Qué se le contesta al navegador que vuelve del IDS.
+ *
+ * Sale del servidor y se prueba aparte porque montarlo exige el puerto 7634 —fijo, porque
+ * el IDS registra ese `redirect_uri`— y ahí no se puede escoger uno efímero: un test que
+ * atara el puerto real fallaría en cuanto alguien tuviera una autorización en curso.
+ */
+export declare function respuestaDeCallback(codigo: string | null, error: string | null, redirigirA?: string): {
+    estado: number;
+    cabeceras: Record<string, string>;
+    cuerpo: string;
+};
+/**
+ * Arranca el servidor HTTP local que recibe el `code` de la redirección, con su
+ * temporizador de espera. Se llama solo cuando `auth()` YA dijo `REDIRECT` —antes se
+ * llamaba SIEMPRE, incluso con un token guardado y válido que no iba a redirigir nunca—:
+ * MEDIDO, eso ocupaba el puerto 7634 fijo y armaba un temporizador de cinco minutos en
+ * cada llamada a `abrirCliente`, y dos llamadas seguidas o solapadas (dos conexiones del
+ * vestíbulo listando proyectos del mismo entorno, por ejemplo) chocaban por el mismo
+ * puerto sin que hiciera falta ningún login de verdad.
+ *
+ * **Un login nuevo SE QUEDA con el puerto, y ése es el arreglo.** El puerto es FIJO —el IDS
+ * registra el `redirect_uri`, así que no se puede esquivar eligiendo otro— y el plazo de
+ * espera es de cinco minutos. O sea que un login que no se completa (se cierra la pestaña,
+ * se cancela, falla) dejaba el 7634 cogido POR NOSOTROS todo ese rato, y cada reintento
+ * moría con `EADDRINUSE 127.0.0.1:7634` mientras el código caducaba al otro lado. MEDIDO en
+ * la consola web: el mismo proceso tenía a la vez su puerto y el 7634, y lo soltaba justo al
+ * cumplirse el plazo — de ahí que «se curara solo al rato», que es lo que lo disfrazaba de
+ * carrera entre procesos.
+ *
+ * Quien llega después gana porque es quien tiene a alguien delante: el pendiente es, por
+ * definición, el que nadie está mirando. Su promesa se RECHAZA con el motivo en vez de
+ * dejarse colgada, o el flujo viejo se quedaría esperando un código que ya no va a llegar.
+ *
+ * Lo que esto NO puede arreglar es que el puerto lo tenga OTRO proceso, y entonces se dice
+ * con esas palabras: un `EADDRINUSE` crudo manda a buscar un choque de puertos cuando lo
+ * que hay es otra consola autenticando.
+ */
+export declare function escucharCallback(timeoutMs: number, redirigirA?: string, 
+/** Solo para las pruebas: el real es fijo y lo impone el `redirect_uri` del IDS. */
+puerto?: number): Promise<{
+    codigo: Promise<string>;
+    cerrar: () => void;
+}>;
+/** Provider OAuth persistente, deliberadamente pequeño y compatible con el SDK MCP. */
+/**
+ * Exportada SOLO para poder probar `invalidateCredentials` —el gancho del que depende que
+ * el SDK sepa recuperarse de un token muerto— sin red ni navegador. Nadie fuera de este
+ * módulo la construye para usarla: quien abre sesión llama a `sesionCloudStudio` o a
+ * `conectarCloudStudio`, que la montan por dentro.
+ */
+export declare class ProviderCloudStudio implements OAuthClientProvider {
+    private readonly ruta;
+    /** El entorno cuyo juego de credenciales lee y escribe este provider: opera SOLO
+     *  sobre `porEntorno[entornoId]`, nunca sobre el fichero entero, para que abrir
+     *  sesión en un entorno no pueda pisar el juego de otro. */
+    private readonly entornoId;
+    private readonly alRedirigir;
+    private readonly scopes;
+    private estado;
+    private readonly metadata;
+    constructor(ruta: string, 
+    /** El entorno cuyo juego de credenciales lee y escribe este provider: opera SOLO
+     *  sobre `porEntorno[entornoId]`, nunca sobre el fichero entero, para que abrir
+     *  sesión en un entorno no pueda pisar el juego de otro. */
+    entornoId: string, redirectUrl: string, alRedirigir: (url: URL) => void, scopes: readonly string[]);
+    /** Solo esta clave se toca en el fichero, nunca `porEntorno` entero: es lo que hace
+     *  que abrir sesión en un entorno deje intactos los tokens de los demás. */
+    private guardar;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): OAuthClientInformationMixed | undefined;
+    saveClientInformation(info: OAuthClientInformationMixed): void;
+    tokens(): OAuthTokens | undefined;
+    saveTokens(tokens: OAuthTokens): void;
+    redirectToAuthorization(url: URL): void;
+    /**
+     * El gancho de recuperación del SDK, y no un extra: `auth()` (`client/auth.js`) atrapa
+     * `InvalidGrantError` —el refresh token muerto— e `InvalidClientError`, llama a esto y
+     * REINTENTA el flujo entero. Sin implementarlo, esa llamada es un no-op: el SDK reintenta
+     * con las mismas credenciales podridas, vuelve a fallar y lanza. O sea que un token
+     * caducado sin refresco válido era un fallo duro —«hay que borrar el fichero a mano»—
+     * cuando el propio SDK sabía volver a autenticar solo.
+     *
+     * Cada alcance borra LO SUYO y nada más, y se escribe en el acto: lo que se está
+     * arreglando es justo un estado a medias, y dejarlo en memoria sin guardar significaría
+     * que el siguiente arranque lo vuelve a leer del fichero.
+     */
+    invalidateCredentials(alcance: "all" | "client" | "tokens" | "verifier" | "discovery"): void;
+    saveCodeVerifier(verifier: string): void;
+    codeVerifier(): string;
+}
+/** El `invocar` que consume `clienteCloudStudio` (`agent/cloudstudio/cloudstudioClient.ts`).
+ *  Se define aquí por estructura, no por import, para no crear un ciclo entre los dos
+ *  módulos: ambos son adaptadores del mismo servidor pero no dependen entre sí. */
+export type InvocarMcp = (nombre: string, argumentos: Record<string, unknown>) => Promise<unknown>;
+/** Sesión MCP viva: `invocar` llama tools, `cerrar` libera el transporte. */
+export interface SesionCloudStudio {
+    invocar: InvocarMcp;
+    cerrar: () => Promise<void>;
+}
+/**
+ * Envuelve un `callTool` crudo del SDK en la función `invocar` que espera
+ * `clienteCloudStudio`. Separada de `sesionCloudStudio` para poder probar la conversión
+ * `isError → excepción` con un `callTool` falso, sin tocar OAuth ni el transporte: es la
+ * pieza de la que depende toda la reapertura de sesión en `agent/cloudstudio/cloudstudioClient.ts`,
+ * y una implementación que se limitara a `return callTool(...)` pasaría los tests de
+ * `clienteCloudStudio` igual de mal que los de aquí bien, si esto no se probara aparte.
+ */
+export declare function invocarSobre(callTool: (peticion: {
+    name: string;
+    arguments: Record<string, unknown>;
+}) => Promise<unknown>): InvocarMcp;
+/**
+ * Sesión MCP viva contra CloudStudio, para `clienteCloudStudio`
+ * (`agent/cloudstudio/cloudstudioClient.ts`): descarga, escribe y cambia de rama necesitan una
+ * conexión que sobreviva a más de una llamada, cosa que `conectarCloudStudio` no ofrece
+ * porque cierra el transporte en cuanto termina de mirar el catálogo.
+ */
+export declare function sesionCloudStudio(urlTexto: string, opciones?: OpcionesCloudStudio): Promise<SesionCloudStudio>;
+/**
+ * El nombre del servidor MCP, saneado, o `undefined` si no publica ninguno usable.
+ *
+ * Es texto que llega de fuera y acaba en `settings.json` y en la barra lateral, así que
+ * pasa por la misma disciplina que cualquier otro dato remoto de este fichero: se quita lo
+ * que no es imprimible (un `\n` o un `\r` en un nombre parte la línea de un log y disfraza
+ * lo que venga detrás), se colapsan los espacios y se acota. Lo que NUNCA sale de aquí es
+ * un identificador: el id del entorno se deduce del host y no de esto, porque el id es un
+ * segmento de ruta y el servidor no puede elegir carpetas en el disco de nadie.
+ *
+ * `title` antes que `name` porque es la convención de MCP: `title` es el nombre para leer y
+ * `name` el programático (`xone-cloudstudio`). Si no hay `title`, `name` es mejor que nada.
+ */
+export declare function servidorDeImplementacion(info: {
+    name?: unknown;
+    title?: unknown;
+    version?: unknown;
+} | undefined): {
+    nombre: string;
+    version?: string;
+} | undefined;
+/**
+ * Inicia (o reutiliza) OAuth, completa initialize y lista las tools disponibles.
+ * La conexión de tools al grafo vendrá después: esta función prueba la conexión sin
+ * incorporar los esquemas de todas las tools al prompt del agente.
+ */
+export declare function conectarCloudStudio(urlTexto: string, opciones?: OpcionesCloudStudio): Promise<ConexionCloudStudio>;
+export {};

package/dist/agent/cloudstudio/conexionDeServidor.d.ts

@@ -0,0 +1,37 @@
+import { type OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import { type InvocarMcp, type ProyectoRemoto } from "./cloudstudioMcp.js";
+/** Lo que se usa de un cliente MCP: lo justo para poder doblarlo en los tests. */
+export interface ClienteMcpMinimo {
+    listTools(): Promise<{
+        tools: {
+            name: string;
+            description?: string;
+            inputSchema?: unknown;
+        }[];
+    }>;
+    callTool(peticion: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface ConexionDeServidor {
+    invocar: InvocarMcp;
+    /** Los proyectos que ve el cliente de máquina. Se pregunta cada vez: no se cachea. */
+    proyectos(): Promise<ProyectoRemoto[]>;
+    cerrar(): Promise<void>;
+}
+export interface OpcionesDeConexionDeServidor {
+    url: string;
+    authProvider: OAuthClientProvider;
+    scopes?: readonly string[];
+    /** Costura de test: por omisión, `auth` del SDK. */
+    autorizar?: (provider: OAuthClientProvider, opciones: {
+        serverUrl: URL;
+        resourceMetadataUrl: URL;
+        scope: string;
+    }) => Promise<"AUTHORIZED" | "REDIRECT">;
+    /** Costura de test: por omisión, `Client` + `StreamableHTTPClientTransport` del SDK. */
+    conectar?: (url: URL, provider: OAuthClientProvider) => Promise<ClienteMcpMinimo>;
+}
+export declare function conectarStudioDeServidor(opciones: OpcionesDeConexionDeServidor): Promise<ConexionDeServidor>;

package/dist/agent/cloudstudio/conexionDeServidor.js

@@ -0,0 +1,63 @@
+// src/agent/cloudstudio/conexionDeServidor.ts
+/**
+ * Conexión a CloudStudio para un SERVIDOR: sin navegador, sin callback y sin fichero de estado.
+ *
+ * `sesionCloudStudio` (`cloudstudioMcp.ts`) está hecha para una persona delante: autoriza con
+ * código + PKCE, escucha un callback en un puerto fijo y guarda los tokens en
+ * `~/.xonecode/cloudstudio-oauth.json`. En un servidor no hay nadie que abra el navegador, y
+ * el IDS admite *client credentials* para un cliente de máquina. Esto es la otra puerta, y es
+ * un fichero APARTE a propósito: la de las personas no cambia ni una línea.
+ *
+ * El proveedor llega HECHO (`ClientCredentialsProvider` del SDK, o el que sea): aquí no se
+ * decide cómo se autentica nadie, solo se usa. Si aun así el proveedor pide redirigir, es que
+ * no es de máquina, y se dice en vez de quedarse esperando un callback que no llegará.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+import { AVISO_DE_URL_DE_MCP, SCOPES_CLOUDSTUDIO_AGENTE, herramientaDeProyectos, invocarSobre, proyectosDeResultado, urlDeMcpAceptable, } from "./cloudstudioMcp.js";
+async function conectarDeVerdad(url, provider) {
+    const cliente = new Client({ name: "xonecode-servidor", version: "1" });
+    const transporte = new StreamableHTTPClientTransport(url, { authProvider: provider });
+    try {
+        await cliente.connect(transporte);
+    }
+    catch (error) {
+        await transporte.close();
+        throw error;
+    }
+    return {
+        listTools: () => cliente.listTools(),
+        callTool: (p) => cliente.callTool(p),
+        close: () => transporte.close(),
+    };
+}
+export async function conectarStudioDeServidor(opciones) {
+    if (!urlDeMcpAceptable(opciones.url))
+        throw new Error(AVISO_DE_URL_DE_MCP);
+    const url = new URL(opciones.url);
+    const scopes = opciones.scopes ?? SCOPES_CLOUDSTUDIO_AGENTE;
+    const autorizar = opciones.autorizar ?? auth;
+    const resultado = await autorizar(opciones.authProvider, {
+        serverUrl: url,
+        resourceMetadataUrl: new URL("/.well-known/oauth-protected-resource", url.origin),
+        scope: scopes.join(" "),
+    });
+    if (resultado !== "AUTHORIZED") {
+        throw new Error("el proveedor pidió autorización interactiva: en un servidor hace falta un cliente de máquina (client credentials)");
+    }
+    const cliente = await (opciones.conectar ?? conectarDeVerdad)(url, opciones.authProvider);
+    return {
+        invocar: invocarSobre((peticion) => cliente.callTool(peticion)),
+        proyectos: async () => {
+            const listado = await cliente.listTools();
+            const definicion = herramientaDeProyectos(listado.tools);
+            if (definicion === undefined) {
+                throw new Error("CloudStudio no publicó ninguna herramienta de listado de proyectos");
+            }
+            return proyectosDeResultado(await cliente.callTool({ name: definicion.name, arguments: {} }));
+        },
+        cerrar: () => cliente.close(),
+    };
+}
+//# sourceMappingURL=conexionDeServidor.js.map

package/dist/agent/cloudstudio/conexionDeServidor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conexionDeServidor.js","sourceRoot":"","sources":["../../../src/agent/cloudstudio/conexionDeServidor.ts"],"names":[],"mappings":"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"}

package/dist/agent/cloudstudio/crearRama.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Crear una rama en Studio a partir de otra.
+ *
+ * `CloudStudioPort` no lo tiene a propósito: la consola sube a la MISMA rama de la que bajó, y
+ * nada de lo que hay hoy crea ramas. Quien trabaja de servidor (xonecode-copilot) sí lo
+ * necesita: hace la tarea en una rama de destino que puede no existir todavía. Va aparte y no
+ * en el puerto para que el puerto —y sus dobles— no cambien.
+ *
+ * Se reabre el proyecto al final por lo mismo que `cambiarRama`: una operación de ramas puede
+ * cerrar el proyecto en el servidor, y la siguiente llamada fallaría con «No project is open».
+ */
+import type { CloudStudioPort } from "../../core/ports.js";
+import type { InvocarMcp } from "./cloudstudioMcp.js";
+/** Devuelve `true` si la creó y `false` si ya existía. */
+export declare function crearRama(invocar: InvocarMcp, puerto: Pick<CloudStudioPort, "abrir" | "ramas">, proyecto: string, nueva: string, desde: string): Promise<boolean>;

package/dist/agent/cloudstudio/crearRama.js

@@ -0,0 +1,16 @@
+/** Devuelve `true` si la creó y `false` si ya existía. */
+export async function crearRama(invocar, puerto, proyecto, nueva, desde) {
+    await puerto.abrir(proyecto);
+    const antes = await puerto.ramas();
+    if (antes.includes(nueva))
+        return false;
+    if (!antes.includes(desde))
+        throw new Error(`la rama origen «${desde}» no existe`);
+    await invocar("studio_manage_branches", { operation: "create", branchName: nueva, targetBranch: desde });
+    await puerto.abrir(proyecto);
+    if (!(await puerto.ramas()).includes(nueva)) {
+        throw new Error(`Studio no creó la rama «${nueva}» (desde «${desde}»)`);
+    }
+    return true;
+}
+//# sourceMappingURL=crearRama.js.map

package/dist/agent/cloudstudio/crearRama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crearRama.js","sourceRoot":"","sources":["../../../src/agent/cloudstudio/crearRama.ts"],"names":[],"mappings":"AAeA,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAmB,EACnB,MAAgD,EAChD,QAAgB,EAChB,KAAa,EACb,KAAa;IAEb,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACnC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,aAAa,CAAC,CAAC;IACnF,MAAM,OAAO,CAAC,wBAAwB,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IACzG,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,aAAa,KAAK,IAAI,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/agent/cloudstudio/descarga.d.ts

@@ -0,0 +1,44 @@
+import type { CloudStudioPort } from "../../core/ports.js";
+import type { EstadoDeSync } from "../../core/cloudstudio.js";
+/** Bastante para que la espera de red se solape; poco para no parecer un ataque. */
+export declare const CONCURRENCIA = 6;
+export interface OpcionesDeDescarga {
+    puerto: CloudStudioPort;
+    raiz: string;
+    proyecto: {
+        id: string;
+        nombre: string;
+    };
+    /**
+     * La rama ORIGEN: de la que se baja. Sin fijarla aquí, `descargarProyecto` trae lo que
+     * sea que esté ACTIVO en la sesión de Studio —que no tiene por qué ser esta—, y una
+     * subida posterior firmaría ese contenido como si fuera de `ramaOrigen`, en silencio.
+     */
+    ramaOrigen: string;
+    informar?: (texto: string) => void;
+    /**
+     * Dejar la copia vacía ANTES de escribir la bajada (`gitSync.ts#vaciarCopia`). Se llama
+     * **solo con el zip ya en la mano**: si la descarga falla, la copia tiene que seguir como
+     * estaba, y vaciar primero la dejaría sin nada. Y **la vía fichero a fichero NO vacía**:
+     * trae solo los de texto, así que media bajada sobre una carpeta vacía sería perder los
+     * binarios — ahí se escribe encima, como siempre, y se dice.
+     */
+    vaciarAntes?: () => void;
+}
+export declare function rutaSyncJson(raiz: string): string;
+/**
+ * Borra del disco las vistas aplanadas y las quita de la lista de descargados.
+ *
+ * De colecciones solo se trabaja con el `.xne` y con `app.xml`: el `X.xml` lo REGENERA
+ * Studio. Hasta ahora solo se le ocultaba al agente con un Proxy; borrarlo de verdad hace
+ * que la regla valga también para el usuario, su editor y su `grep`.
+ *
+ * **El momento es lo que importa**: esto corre tras extraer y ANTES del commit de baseline
+ * (`prepararRepo`). Al revés, git vería esos `.xml` como borrados y —al haberse descargado,
+ * el candado no los frenaría— la primera subida los borraría EN STUDIO.
+ *
+ * Que no entren en `descargados` es el segundo cierre: aunque algún día alguien reordene
+ * las guardas de `planDeSubida`, el candado sigue impidiendo su borrado remoto.
+ */
+export declare function retirarVistasAplanadas(raiz: string, rutas: string[]): string[];
+export declare function descargarProyecto(opciones: OpcionesDeDescarga): Promise<EstadoDeSync>;