utn-mcp 0.2.1 → 0.6.7

package/README.md

@@ -6,6 +6,10 @@ Este es el Model Context Protocol server NO OFICIAL de la UTN. Con él podrás p
 - *"¿Qué avisó la profesora de Física esta semana?"*
 - *"Resumime la guía de la unidad 3 de Sistemas Operativos."*
 - *"Pasame el link para bajar el apunte de calorimetría."*
+- *"¿Qué nota me pusieron en el TP1 y qué me corrigieron?"*
+- *"Preguntá en el foro de consultas si el parcial incluye la unidad 4."*
+- *"Anotame en el grupo 6."*
+- *"Agendame el recuperatorio del 14 a las 18."*
 
 El agente recorre el aula como lo harías vos: entra al curso, mira los foros y abre los archivos que hagan falta.
 
@@ -16,6 +20,14 @@ El agente recorre el aula como lo harías vos: entra al curso, mira los foros y
 | `aula_open` | Entra a un curso, un módulo, un foro o una discusión. Cada respuesta trae las direcciones de lo que hay adentro y de un nivel más arriba, así el agente navega sin perderse. |
 | `aula_read_file` | Lee un archivo del aula, por partes cuando es largo. |
 | `aula_get_site_info` | Datos de tu usuario en el aula virtual. |
+| `aula_forum_post` | Abre un hilo en un foro o responde en una discusión. |
+| `aula_forum_edit_post` | Edita una publicación tuya. |
+| `aula_forum_delete_post` | Borra una publicación tuya. |
+| `aula_choice_answer` | Responde una elección o te anota en un grupo. |
+| `aula_send_message` | Manda un mensaje privado a un docente o compañero. |
+| `aula_calendar_add_event` | Agrega un recordatorio a tu calendario del aula. |
+
+Al abrir una tarea, `aula_open` muestra si la entregaste, cuándo vence y la devolución con la nota. Las tools que escriben le piden al agente que te muestre lo que va a hacer y espere tu confirmación.
 
 ### Archivos que puede leer
 - **PDF**: el texto, página por página. Los **escaneados** se mandan como imagen de cada página, y el agente los lee igual.

package/build/aula-virtual/client/client.js

@@ -1,4 +1,4 @@
-import { callWs } from "./moodle-api.js";
+import { callWs, MoodleError } from "./moodle-api.js";
 export function getSiteInfo(session) {
     return callWs(session, "core_webservice_get_site_info");
 }
@@ -20,15 +20,147 @@ export function getCourseSections(session, courseId, cmid) {
 }
 // --- Foros ---
 /** Cuántas discusiones trae una página del índice de un foro. */
-export const POR_PAGINA = 50;
+export const PAGE_SIZE = 50;
 /**
  * Discusiones de un foro, las más recientes primero. Moodle manda el mensaje completo de la
  * primera publicación de cada una; el que lee decide si lo recorta.
  */
 export function getForumDiscussions(session, forumid, page = 0) {
-    return callWs(session, "mod_forum_get_forum_discussions", { forumid, page, perpage: POR_PAGINA });
+    return callWs(session, "mod_forum_get_forum_discussions", { forumid, page, perpage: PAGE_SIZE });
 }
 /** Publicaciones de una discusión, incluidas las respuestas. */
 export function getDiscussionPosts(session, discussionid) {
     return callWs(session, "mod_forum_get_discussion_posts", { discussionid });
 }
+/** Si el usuario puede abrir un hilo en el foro, con el grupo que le toque. */
+export async function canAddDiscussion(session, forumid) {
+    const { status } = await callWs(session, "mod_forum_can_add_discussion", { forumid });
+    return status;
+}
+/** Abre un hilo. Moodle elige solo el grupo del usuario si el foro es por grupos. */
+export async function addDiscussion(session, forumid, subject, message) {
+    const { discussionid } = await callWs(session, "mod_forum_add_discussion", {
+        forumid,
+        subject,
+        message,
+    });
+    return discussionid;
+}
+/** Responde a una publicación, que puede ser la primera de la discusión. */
+export async function addDiscussionPost(session, postid, subject, message) {
+    const { postid: newPostId } = await callWs(session, "mod_forum_add_discussion_post", {
+        postid,
+        subject,
+        message,
+    });
+    return newPostId;
+}
+/** Edita una publicación propia; con asunto vacío Moodle deja el que tenía. */
+export async function updateDiscussionPost(session, postid, subject, message) {
+    await callWs(session, "mod_forum_update_discussion_post", { postid, subject, message });
+}
+/** Borra una publicación; si es la primera, se va la discusión entera. */
+export async function deletePost(session, postid) {
+    await callWs(session, "mod_forum_delete_post", { postid });
+}
+// --- Tareas ---
+/** Las tareas de un curso con su configuración: fechas y qué tipos de entrega aceptan. */
+export async function getAssignments(session, courseId) {
+    const { courses } = await callWs(session, "mod_assign_get_assignments", { "courseids[0]": courseId });
+    return courses[0]?.assignments ?? [];
+}
+/** Estado de la entrega del usuario y, si ya la corrigieron, la devolución. */
+export function getSubmissionStatus(session, assignid) {
+    return callWs(session, "mod_assign_get_submission_status", { assignid });
+}
+// --- Elecciones (choice) y selección de grupos (choicegroup) ---
+export async function getChoices(session, courseId) {
+    const { choices } = await callWs(session, "mod_choice_get_choices_by_courses", {
+        "courseids[0]": courseId,
+    });
+    return choices;
+}
+export async function getChoiceOptions(session, choiceid) {
+    const { options } = await callWs(session, "mod_choice_get_choice_options", {
+        choiceid,
+    });
+    return options;
+}
+export async function submitChoiceResponse(session, choiceid, optionIds) {
+    const params = { choiceid };
+    optionIds.forEach((id, i) => (params[`responses[${i}]`] = id));
+    await callWs(session, "mod_choice_submit_choice_response", params);
+}
+export async function deleteChoiceResponses(session, choiceid) {
+    await callWs(session, "mod_choice_delete_choice_responses", { choiceid });
+}
+export async function getChoicegroupOptions(session, choicegroupid) {
+    const { userid } = await getSiteInfo(session);
+    const { options } = await callWs(session, "mod_choicegroup_get_choicegroup_options", {
+        choicegroupid,
+        userid,
+    });
+    return options;
+}
+/**
+ * El plugin lee `responses` si la actividad deja un solo grupo y `choicegroup_<id>: "true"` si deja
+ * varios, y la configuración no se puede consultar: mandamos las dos formas y él usa la que le sirve.
+ * Con varios grupos, los que no vienen marcados se quitan.
+ */
+export async function submitChoicegroupResponse(session, choicegroupid, optionIds) {
+    const data = [
+        { name: "responses", value: String(optionIds[0]) },
+        ...optionIds.map((id) => ({ name: `choicegroup_${id}`, value: "true" })),
+    ];
+    const params = { choicegroupid };
+    data.forEach((d, i) => {
+        params[`data[${i}][name]`] = d.name;
+        params[`data[${i}][value]`] = d.value;
+    });
+    await callWs(session, "mod_choicegroup_submit_choicegroup_response", params);
+}
+export async function deleteChoicegroupResponses(session, choicegroupid) {
+    await callWs(session, "mod_choicegroup_delete_choicegroup_responses", { choicegroupid });
+}
+// --- Mensajes ---
+/** Nombre de otro usuario, visto desde el usuario logueado, o null si no existe. */
+export async function getMemberName(session, userId) {
+    const { userid } = await getSiteInfo(session);
+    let members;
+    try {
+        members = await callWs(session, "core_message_get_member_info", {
+            referenceuserid: userid,
+            "userids[0]": userId,
+        });
+    }
+    catch (e) {
+        // Con un id que no existe, Moodle 5.1 no devuelve vacío: revienta con un error de PHP.
+        if (e instanceof MoodleError)
+            return null;
+        throw e;
+    }
+    const m = members.find((x) => x.id === userId && !x.isdeleted);
+    return m?.fullname ?? null;
+}
+/** Manda un mensaje privado. Moodle no tira excepción si falla: devuelve `msgid: -1` y el motivo. */
+export async function sendInstantMessage(session, touserid, html) {
+    const [res] = await callWs(session, "core_message_send_instant_messages", { "messages[0][touserid]": touserid, "messages[0][text]": html, "messages[0][textformat]": 1 });
+    if (!res || res.msgid === -1)
+        throw new MoodleError(res?.errormessage || "Moodle no aceptó el mensaje.");
+    return res.msgid;
+}
+// --- Calendario ---
+/** Crea un evento personal: solo lo ve el usuario. */
+export async function createUserEvent(session, event) {
+    const { events } = await callWs(session, "core_calendar_create_calendar_events", {
+        "events[0][name]": event.name,
+        "events[0][description]": event.description,
+        "events[0][format]": 1,
+        "events[0][eventtype]": "user",
+        "events[0][timestart]": event.timestart,
+        "events[0][timeduration]": event.timeduration,
+    });
+    if (!events[0])
+        throw new MoodleError("Moodle no creó el evento.");
+    return events[0].id;
+}

package/build/aula-virtual/client/moodle-api.js

@@ -37,11 +37,11 @@ export async function callWs(session, wsfunction, params = {}) {
 export async function fetchFile(session, url, maxBytes) {
     let token = await session.getToken();
     for (let attempt = 0;; attempt++) {
-        const conToken = new URL(url);
-        conToken.searchParams.set("token", token);
+        const withToken = new URL(url);
+        withToken.searchParams.set("token", token);
         let res;
         try {
-            res = await fetch(conToken, { signal: AbortSignal.timeout(60_000) });
+            res = await fetch(withToken, { signal: AbortSignal.timeout(60_000) });
         }
         catch (e) {
             throw new MoodleError(`No se pudo bajar el archivo: ${e.message}`);
@@ -57,27 +57,27 @@ export async function fetchFile(session, url, maxBytes) {
         }
         if (!res.ok || !res.body)
             throw new MoodleError(`HTTP ${res.status} al bajar el archivo`);
-        return { bytes: await leerConLimite(res, maxBytes), contentType };
+        return { bytes: await readWithLimit(res, maxBytes), contentType };
     }
 }
 /** Lee el cuerpo cortando apenas pasa el límite, sin esperar a bajarlo entero. */
-async function leerConLimite(res, maxBytes) {
-    const limite = `El archivo pesa más de ${Math.round(maxBytes / 1024 / 1024)} MB; es demasiado para leerlo.`;
+async function readWithLimit(res, maxBytes) {
+    const tooBig = `El archivo pesa más de ${Math.round(maxBytes / 1024 / 1024)} MB; es demasiado para leerlo.`;
     if (Number(res.headers.get("content-length")) > maxBytes) {
         await res.body?.cancel();
-        throw new MoodleError(limite);
+        throw new MoodleError(tooBig);
     }
-    const partes = [];
+    const chunks = [];
     let total = 0;
-    for await (const parte of res.body) {
-        total += parte.length;
+    for await (const chunk of res.body) {
+        total += chunk.length;
         if (total > maxBytes)
-            throw new MoodleError(limite);
-        partes.push(parte);
+            throw new MoodleError(tooBig);
+        chunks.push(chunk);
     }
     const bytes = new Uint8Array(total);
     let i = 0;
-    for (const p of partes) {
+    for (const p of chunks) {
         bytes.set(p, i);
         i += p.length;
     }

package/build/aula-virtual/format/actions.js

@@ -0,0 +1,159 @@
+import { textToHtml } from "../../shared/html.js";
+import { addDiscussion, addDiscussionPost, createUserEvent, deleteChoiceResponses, deleteChoicegroupResponses, deletePost, getChoiceOptions, getChoicegroupOptions, getDiscussionPosts, getMemberName, sendInstantMessage, submitChoiceResponse, submitChoicegroupResponse, updateDiscussionPost, } from "../client/client.js";
+import { AULA_BASE_URL } from "../client/constants.js";
+import { toOption } from "./activities.js";
+import { discussionAddr, formatAddress, parseAddress } from "./address.js";
+import { isoDate } from "./fields.js";
+import { findModule } from "./navigate.js";
+// --- Foros ---
+/**
+ * Con la dirección de un foro abre un hilo; con la de una discusión responde. Así el modelo no elige
+ * entre dos operaciones: la dirección que ya tiene dice cuál es.
+ */
+export async function postToForum(session, rawAddress, message, subject, replyTo) {
+    const address = parseAddress(rawAddress);
+    if (address.level === "module") {
+        const { module } = await findModule(session, address.courseId, address.cmid);
+        if (module.modname !== "forum") {
+            throw new Error(`"${rawAddress}" no es un foro, es un módulo de tipo ${module.modname}.`);
+        }
+        if (!subject?.trim())
+            throw new Error("Para abrir un hilo hace falta un `asunto`.");
+        const discussionId = await addDiscussion(session, module.instance, subject.trim(), textToHtml(message));
+        return { publicado: "hilo nuevo", direccion: discussionAddr(address.courseId, address.cmid, discussionId) };
+    }
+    if (address.level === "discussion") {
+        const { posts } = await getDiscussionPosts(session, address.discussionId);
+        const parent = replyTo
+            ? findPost(posts, replyTo, rawAddress)
+            : posts.find((p) => p.parentid === null && !p.isdeleted);
+        if (!parent)
+            throw new Error(`La discusión ${rawAddress} no tiene publicaciones a las que responder.`);
+        if (!parent.capabilities.reply) {
+            throw new Error("No podés responder en esta discusión: está cerrada o el foro no deja responder.");
+        }
+        const postId = await addDiscussionPost(session, parent.id, subject?.trim() || parent.replysubject, textToHtml(message));
+        return { publicado: "respuesta", direccion: formatAddress(address), id: postId, respuestaA: parent.id };
+    }
+    throw new Error(`Para publicar hace falta la dirección de un foro (/curso/{id}/mod/{cmid}) o de una discusión ` +
+        `(/curso/{id}/mod/{cmid}/disc/{id}); "${rawAddress}" no es ninguna de las dos.`);
+}
+export async function editForumPost(session, rawAddress, postId, message, subject) {
+    const { address, post } = await findPostAt(session, rawAddress, postId);
+    if (!post.capabilities.edit) {
+        throw new Error("No podés editar esta publicación: no es tuya o ya pasó el tiempo para editarla.");
+    }
+    // Asunto vacío: Moodle deja el que tenía.
+    await updateDiscussionPost(session, postId, subject?.trim() ?? "", textToHtml(message));
+    return { editado: true, direccion: formatAddress(address), id: postId };
+}
+export async function deleteForumPost(session, rawAddress, postId) {
+    const { address, post } = await findPostAt(session, rawAddress, postId);
+    if (!post.capabilities.delete) {
+        throw new Error("No podés borrar esta publicación: no es tuya, tiene respuestas o ya pasó el tiempo.");
+    }
+    await deletePost(session, postId);
+    const isFirst = post.parentid === null;
+    return {
+        borrado: true,
+        id: postId,
+        // Borrar la primera publicación se lleva la discusión entera.
+        discusionBorrada: isFirst || undefined,
+        direccion: isFirst ? undefined : formatAddress(address),
+    };
+}
+async function findPostAt(session, rawAddress, postId) {
+    const address = parseAddress(rawAddress);
+    if (address.level !== "discussion") {
+        throw new Error(`Hace falta la dirección de la discusión donde está la publicación; "${rawAddress}" no lo es.`);
+    }
+    const { posts } = await getDiscussionPosts(session, address.discussionId);
+    return { address, post: findPost(posts, postId, rawAddress) };
+}
+function findPost(posts, postId, rawAddress) {
+    const post = posts.find((p) => p.id === postId && !p.isdeleted);
+    if (!post) {
+        throw new Error(`La publicación ${postId} no está en ${rawAddress}. Los ids salen de abrir la discusión con aula_open.`);
+    }
+    return post;
+}
+// --- Elecciones y selección de grupos ---
+/** Deja elegidas exactamente `optionIds`; vacío borra la respuesta. Devuelve cómo quedó. */
+export async function answerChoice(session, rawAddress, optionIds) {
+    const address = parseAddress(rawAddress);
+    if (address.level !== "module")
+        throw new Error(`"${rawAddress}" no es la dirección de un módulo.`);
+    const { module } = await findModule(session, address.courseId, address.cmid);
+    const api = CHOICE_APIS[module.modname];
+    if (!api) {
+        throw new Error(`"${rawAddress}" es un módulo de tipo ${module.modname}; solo se puede elegir en choice y choicegroup.`);
+    }
+    const current = await api.options(session, module.instance);
+    for (const id of optionIds) {
+        const option = current.find((o) => o.id === id);
+        if (!option) {
+            throw new Error(`No existe la opción ${id}. Las válidas son: ${current.map((o) => o.id).join(", ")}.`);
+        }
+        if (option.disabled && !option.checked) {
+            throw new Error(`La opción ${id} (${option.text ?? option.name}) está completa o deshabilitada.`);
+        }
+    }
+    if (optionIds.length)
+        await api.submit(session, module.instance, optionIds);
+    else
+        await api.clear(session, module.instance);
+    const after = await api.options(session, module.instance);
+    const chosen = after.filter((o) => o.checked).map((o) => o.id);
+    const matches = chosen.length === optionIds.length && optionIds.every((id) => chosen.includes(id));
+    return {
+        elegidas: chosen,
+        // Pasa cuando la actividad deja una sola opción y se pidieron varias.
+        aviso: matches ? undefined : "Moodle no dejó exactamente las opciones pedidas; `elegidas` es lo que quedó.",
+        opciones: after.map(toOption),
+    };
+}
+const CHOICE_APIS = {
+    choice: { options: getChoiceOptions, submit: submitChoiceResponse, clear: deleteChoiceResponses },
+    choicegroup: {
+        options: getChoicegroupOptions,
+        submit: submitChoicegroupResponse,
+        clear: deleteChoicegroupResponses,
+    },
+};
+// --- Mensajes ---
+export async function sendMessage(session, userId, message) {
+    // Se busca antes el nombre: un id equivocado le mandaría el mensaje a otra persona sin que nadie lo note.
+    const name = await getMemberName(session, userId);
+    if (!name) {
+        throw new Error(`No existe el usuario ${userId}. El id sale del \`autorId\` de un foro abierto con aula_open.`);
+    }
+    await sendInstantMessage(session, userId, textToHtml(message));
+    return { enviado: true, para: name };
+}
+// --- Calendario ---
+/** Exige la zona horaria: el servidor hosteado no está en la hora de Argentina y adivinarla corre el evento. */
+const HAS_TIMEZONE = /(Z|[+-]\d{2}:?\d{2})$/i;
+export async function addCalendarEvent(session, event) {
+    const start = new Date(event.start);
+    if (!HAS_TIMEZONE.test(event.start.trim()) || Number.isNaN(start.getTime())) {
+        throw new Error(`Fecha inválida: "${event.start}". Usá ISO 8601 con zona horaria, por ejemplo "2026-10-14T18:00:00-03:00".`);
+    }
+    const timestart = Math.floor(start.getTime() / 1000);
+    const timeduration = Math.round((event.durationMinutes ?? 0) * 60);
+    const name = event.name.trim();
+    const id = await createUserEvent(session, {
+        name,
+        description: event.description ? textToHtml(event.description) : "",
+        timestart,
+        timeduration,
+    });
+    return {
+        creado: true,
+        id,
+        nombre: name,
+        inicio: isoDate(timestart),
+        fin: timeduration ? isoDate(timestart + timeduration) : undefined,
+        // Para que el usuario lo vea en el calendario del aula.
+        url: `${AULA_BASE_URL}/calendar/view.php?view=day&time=${timestart}`,
+    };
+}

package/build/aula-virtual/format/activities.js

@@ -0,0 +1,101 @@
+import { htmlToText } from "../../shared/html.js";
+import { getAssignments, getChoiceOptions, getChoicegroupOptions, getChoices, getSubmissionStatus, } from "../client/client.js";
+import { isoDate, toFile } from "./fields.js";
+const SUBMISSION_STATUS_LABELS = {
+    new: "sin entregar",
+    draft: "borrador",
+    submitted: "enviada",
+    reopened: "reabierta",
+};
+/** La entrega del usuario (o la de su grupo): qué acepta la tarea, qué subió y la devolución si la hay. */
+export async function viewSubmission(session, courseId, module) {
+    const [assignments, status] = await Promise.all([
+        getAssignments(session, courseId),
+        getSubmissionStatus(session, module.instance),
+    ]);
+    const assignment = assignments.find((a) => a.cmid === module.id);
+    const attempt = status.lastattempt;
+    // En las entregas grupales la individual queda vacía; la que cuenta es la del grupo.
+    const submission = attempt?.teamsubmission ?? attempt?.submission;
+    const config = (plugin, name) => assignment?.configs.find((c) => c.subtype === "assignsubmission" && c.plugin === plugin && c.name === name)
+        ?.value;
+    const accepts = [];
+    if (config("file", "enabled") === "1") {
+        accepts.push({
+            tipo: "archivos",
+            maximo: Number(config("file", "maxfilesubmissions")) || undefined,
+            tamanioMaximo: Number(config("file", "maxsubmissionsizebytes")) || undefined,
+            extensiones: config("file", "filetypeslist") || undefined,
+        });
+    }
+    if (config("onlinetext", "enabled") === "1") {
+        accepts.push({ tipo: "texto en línea", limitePalabras: Number(config("onlinetext", "wordlimit")) || undefined });
+    }
+    const feedback = status.feedback;
+    return {
+        estado: submission ? (SUBMISSION_STATUS_LABELS[submission.status] ?? submission.status) : "sin entregar",
+        grupal: assignment?.teamsubmission === 1 || undefined,
+        // Moodle crea la entrega vacía al abrir la tarea: su fecha no dice nada hasta que hay algo subido.
+        modificada: (submission?.status !== "new" && isoDate(submission?.timemodified)) || undefined,
+        abre: isoDate(assignment?.allowsubmissionsfromdate) || undefined,
+        vence: isoDate(assignment?.duedate) || undefined,
+        prorroga: isoDate(attempt?.extensionduedate) || undefined,
+        cierreDefinitivo: isoDate(assignment?.cutoffdate) || undefined,
+        acepta: accepts.length ? accepts : undefined,
+        // Con borradores, lo subido no cuenta hasta confirmar el envío.
+        requiereConfirmarEnvio: assignment?.submissiondrafts === 1 || undefined,
+        requiereDeclaracion: assignment?.requiresubmissionstatement === 1 || undefined,
+        puedeEditar: attempt?.canedit ?? false,
+        puedeEnviar: attempt?.cansubmit || undefined,
+        bloqueada: attempt?.locked || undefined,
+        ...pluginContent(submission?.plugins),
+        devolucion: feedback
+            ? {
+                calificacion: feedback.gradefordisplay || undefined,
+                fecha: isoDate(feedback.gradeddate),
+                ...pluginContent(feedback.plugins),
+            }
+            : undefined,
+    };
+}
+/** Los archivos y textos de una entrega o devolución, sin los plugins vacíos. */
+function pluginContent(plugins = []) {
+    const files = plugins.flatMap((p) => p.fileareas?.flatMap((a) => a.files ?? []) ?? []);
+    const texts = plugins
+        .flatMap((p) => p.editorfields ?? [])
+        .map((e) => htmlToText(e.text))
+        .filter(Boolean);
+    return {
+        archivos: files.length ? files.map(toFile) : undefined,
+        texto: texts.length ? texts.join("\n\n") : undefined,
+    };
+}
+export async function viewChoice(session, courseId, module) {
+    const [choices, options] = await Promise.all([
+        getChoices(session, courseId),
+        getChoiceOptions(session, module.instance),
+    ]);
+    const choice = choices.find((c) => c.coursemodule === module.id);
+    return {
+        multiple: choice?.allowmultiple || undefined,
+        puedeCambiar: choice?.allowupdate,
+        abre: isoDate(choice?.timeopen) || undefined,
+        cierra: isoDate(choice?.timeclose) || undefined,
+        opciones: options.map(toOption),
+    };
+}
+/** El plugin no expone si deja cambiar o elegir varios grupos: eso lo dice la descripción o el error al elegir. */
+export async function viewChoicegroup(session, module) {
+    const options = await getChoicegroupOptions(session, module.instance);
+    return { opciones: options.map(toOption) };
+}
+export function toOption(o) {
+    return {
+        id: o.id,
+        texto: o.text ?? o.name,
+        elegida: o.checked || undefined,
+        deshabilitada: o.disabled || undefined,
+        cupo: o.maxanswers || undefined,
+        anotados: o.countanswers,
+    };
+}

package/build/aula-virtual/format/address.js

@@ -0,0 +1,52 @@
+export const ROOT = "/";
+export const courseAddr = (courseId) => `/curso/${courseId}`;
+export const moduleAddr = (courseId, cmid) => `/curso/${courseId}/mod/${cmid}`;
+export const discussionAddr = (courseId, cmid, discussionId) => `/curso/${courseId}/mod/${cmid}/disc/${discussionId}`;
+const FORMATS = [
+    "/",
+    "/curso/{courseId}",
+    "/curso/{courseId}/mod/{cmid}",
+    "/curso/{courseId}/mod/{cmid}/disc/{discussionId}",
+].join(", ");
+const PATTERN = /^\/curso\/(\d+)(?:\/mod\/(\d+)(?:\/disc\/(\d+))?)?$/;
+export function parseAddress(raw) {
+    const path = raw.trim().replace(/\/+$/, "") || "/";
+    if (path === "/")
+        return { level: "root" };
+    const m = PATTERN.exec(path);
+    if (!m)
+        throw new Error(`Dirección inválida: "${raw}". Formatos válidos: ${FORMATS}`);
+    const [, course, cmid, disc] = m;
+    const courseId = Number(course);
+    if (!cmid)
+        return { level: "course", courseId };
+    if (!disc)
+        return { level: "module", courseId, cmid: Number(cmid) };
+    return { level: "discussion", courseId, cmid: Number(cmid), discussionId: Number(disc) };
+}
+/** La dirección en texto, tal como la ve el modelo. */
+export function formatAddress(address) {
+    switch (address.level) {
+        case "root":
+            return ROOT;
+        case "course":
+            return courseAddr(address.courseId);
+        case "module":
+            return moduleAddr(address.courseId, address.cmid);
+        case "discussion":
+            return discussionAddr(address.courseId, address.cmid, address.discussionId);
+    }
+}
+/** La dirección de un nivel más arriba, o null si ya estamos en la raíz. */
+export function parentOf(address) {
+    switch (address.level) {
+        case "root":
+            return null;
+        case "course":
+            return ROOT;
+        case "module":
+            return courseAddr(address.courseId);
+        case "discussion":
+            return moduleAddr(address.courseId, address.cmid);
+    }
+}

package/build/aula-virtual/format/fields.js

@@ -0,0 +1,14 @@
+import { userFacingUrl } from "./files.js";
+/** Los timestamps de Moodle (segundos) en ISO; 0 o vacío es "sin fecha". */
+export const isoDate = (seconds) => seconds ? new Date(seconds * 1000).toISOString() : null;
+export function toFile(f) {
+    return {
+        nombre: f.filename,
+        ruta: f.filepath || undefined,
+        tamanio: f.filesize,
+        mimetype: f.mimetype,
+        modificado: isoDate(f.timemodified),
+        // Sirve para pasársela al usuario y también para leerlo con aula_read_file.
+        url: userFacingUrl(f.fileurl),
+    };
+}

package/build/aula-virtual/format/files.js

@@ -0,0 +1,89 @@
+import { openDocument, UnsupportedFormat } from "../../shared/documents/index.js";
+import { AULA_BASE_URL } from "../client/constants.js";
+import { fetchFile } from "../client/moodle-api.js";
+const ORIGIN = new URL(AULA_BASE_URL).origin;
+const WS_PATH = "/webservice/pluginfile.php/";
+const WEB_PATH = "/pluginfile.php/";
+/** Cuánto se devuelve por llamada, en caracteres de texto. */
+const BUDGET_CHARS = 30_000;
+/** Lo que cuesta una página como imagen (~1.600 tokens), medido en caracteres de texto. */
+const IMAGE_COST_CHARS = 6_000;
+/** El más grande que hay hoy en los cursos pesa 12 MB. */
+const MAX_BYTES = 30 * 1024 * 1024;
+/**
+ * Moodle devuelve las URLs del web service, que piden token. Al usuario le sirve la misma ruta sin
+ * `/webservice`, que se abre con la sesión de su navegador. Es la única que mostramos: el token no
+ * sale nunca del servidor.
+ */
+export function userFacingUrl(fileurl) {
+    return fileurl.replace(`${ORIGIN}${WS_PATH}`, `${ORIGIN}${WEB_PATH}`);
+}
+/**
+ * Acepta cualquiera de las dos formas y devuelve la del web service. Solo archivos del aula: con
+ * cualquier otra URL estaríamos mandando el token del usuario a donde diga el modelo.
+ */
+function downloadUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`URL inválida: "${url}". Usá la \`url\` de un archivo tal como la devuelve aula_open.`);
+    }
+    const path = u.pathname.startsWith(WS_PATH) ? u.pathname : u.pathname.startsWith(WEB_PATH) ? WS_PATH + u.pathname.slice(WEB_PATH.length) : null;
+    if (u.origin !== ORIGIN || !path) {
+        throw new Error(`Solo se pueden leer archivos del aula virtual (${ORIGIN}${WEB_PATH}...).`);
+    }
+    u.pathname = path;
+    u.searchParams.delete("token");
+    u.searchParams.delete("wstoken");
+    return u;
+}
+/** Baja un archivo del aula y devuelve desde la parte `from` tantas como entren en el presupuesto. */
+export async function readAulaFile(session, url, from = 1) {
+    const download = downloadUrl(url);
+    const fileName = decodeURIComponent(download.pathname.split("/").pop() ?? "");
+    const forUser = userFacingUrl(download.href);
+    const { bytes } = await fetchFile(session, download, MAX_BYTES);
+    let doc;
+    try {
+        doc = await openDocument(bytes, fileName);
+    }
+    catch (e) {
+        if (e instanceof UnsupportedFormat) {
+            throw new Error(`${e.message} El usuario lo puede bajar desde ${forUser}`);
+        }
+        throw e;
+    }
+    try {
+        if (from > doc.total) {
+            throw new Error(`"${fileName}" termina en ${doc.unit} ${doc.total}; se pidió desde ${from}.`);
+        }
+        const parts = [];
+        let spent = 0;
+        let n = from;
+        for (; n <= doc.total; n++) {
+            const part = await doc.part(n);
+            const cost = "text" in part ? part.text.length : IMAGE_COST_CHARS;
+            // Siempre al menos una parte, aunque sola se pase del presupuesto.
+            if (parts.length > 0 && spent + cost > BUDGET_CHARS)
+                break;
+            parts.push({ ...part, number: n });
+            spent += cost;
+        }
+        return {
+            archivo: fileName,
+            formato: doc.format,
+            unidad: doc.unit,
+            total: doc.total,
+            desde: from,
+            hasta: n - 1,
+            siguiente: n <= doc.total ? n : undefined,
+            urlParaUsuario: forUser,
+            parts,
+        };
+    }
+    finally {
+        await doc.close();
+    }
+}