brightspace-mcp-server 5.0.13 → 5.1.4

package/build/shared-runtime.js

@@ -0,0 +1,126 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { acquireProcessLock, AuthenticationInProgressError } from "./auth/auth-lock.js";
+import { log } from "./utils/logger.js";
+/** How long a shared runtime waits with no request in progress before it stops. */
+export const DEFAULT_IDLE_MS = 10 * 60_000;
+/** How long a starting runtime waits for a runtime that is starting or stopping to settle. */
+const CLAIM_WAIT_MS = 10_000;
+const STATE_FILE = "state.json";
+const OWNER_LOCK = "owner.lock";
+/**
+ * The directory one shared runtime lives in: one per account (inside its
+ * session directory), settings, and package version. Two chats share a
+ * runtime only when they would have built the same one themselves, and an
+ * upgraded package starts its own instead of talking to old code.
+ *
+ * The saved password and authenticator key play no part: the relay that picks
+ * the runtime loads its settings without reading the credential store (see
+ * loadConfig), and every sign-in reads them itself. A pasted access token or
+ * cookie is a high-entropy secret and is hashed like any other setting.
+ */
+export function runtimeDirectory(config, version) {
+    const { password: _password, totpUri: _totpUri, legacyBrowserStateMigrated: _perRun, ...settings } = config;
+    const identity = JSON.stringify({ version, settings });
+    const key = createHash("sha256").update(identity).digest("hex").slice(0, 32);
+    return path.join(config.sessionDir, "shared-runtime", key);
+}
+/** The published address in `dir`, or undefined when no runtime has published one. */
+export async function readRuntimeAddress(dir) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path.join(dir, STATE_FILE), "utf-8"));
+        if (typeof parsed.pid === "number" && typeof parsed.url === "string" && typeof parsed.token === "string") {
+            return { pid: parsed.pid, url: parsed.url, token: parsed.token };
+        }
+    }
+    catch {
+        // Missing, or caught mid-write by a reader; either way, nothing to use.
+    }
+    return undefined;
+}
+/**
+ * Serve `runtime` as the one shared runtime for `dir`, or resolve undefined
+ * when another runtime already serves it. Concurrent starts converge: the
+ * owner lock admits one, and the rest return once its address is published.
+ *
+ * The winner listens on a free 127.0.0.1 port behind a fresh random bearer
+ * token, publishes both in a 0600 state file, and stops after `idleMs` with
+ * no request in progress. A call waiting on MFA approval is a request in
+ * progress, so idleness never cuts one off. It unpublishes its address before
+ * it stops listening, so a chat arriving during shutdown starts a successor
+ * rather than finding a dead address.
+ */
+export async function serveSharedRuntime(runtime, { dir, idleMs }) {
+    const releaseLock = await claimOwnership(dir);
+    if (!releaseLock)
+        return undefined;
+    const stateFile = path.join(dir, STATE_FILE);
+    const token = randomBytes(32).toString("hex");
+    let idleTimer;
+    let stopping;
+    let server;
+    let markStopped;
+    const stopped = new Promise((done) => { markStopped = done; });
+    const stop = () => {
+        stopping ??= (async () => {
+            clearTimeout(idleTimer);
+            await fs.unlink(stateFile).catch(() => { });
+            await server?.close();
+            await releaseLock();
+            markStopped();
+        })();
+        return stopping;
+    };
+    const onActiveChange = (active) => {
+        clearTimeout(idleTimer);
+        if (active > 0 || stopping)
+            return;
+        idleTimer = setTimeout(() => {
+            log("INFO", `Shared runtime idle for ${Math.round(idleMs / 1000)}s; stopping`);
+            void stop();
+        }, idleMs);
+    };
+    try {
+        // Loaded here, not at the top: the relay in every chat imports this
+        // module for runtimeDirectory and must not pull in the server with it.
+        const { startHttpServer } = await import("./http-server.js");
+        server = await startHttpServer({ runtime, token, port: 0, onActiveChange });
+        const address = { pid: process.pid, url: server.url, token };
+        // Write then rename, so a reader never sees half a file.
+        const partial = `${stateFile}.${process.pid}.tmp`;
+        await fs.writeFile(partial, JSON.stringify(address), { mode: 0o600 });
+        await fs.rename(partial, stateFile);
+        onActiveChange(0);
+        return { address, stopped, stop };
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+}
+/**
+ * Take the owner lock for `dir`, waiting out a runtime that is starting or
+ * stopping. undefined when another live runtime has published its address.
+ */
+async function claimOwnership(dir) {
+    const deadline = Date.now() + CLAIM_WAIT_MS;
+    for (;;) {
+        try {
+            return await acquireProcessLock(path.join(dir, OWNER_LOCK), { mode: "exclusive" });
+        }
+        catch (error) {
+            if (!(error instanceof AuthenticationInProgressError))
+                throw error;
+        }
+        if (await readRuntimeAddress(dir) || Date.now() > deadline)
+            return undefined;
+        await delay(50);
+    }
+}

package/build/tools/download-dropbox-submission-file.js

@@ -15,7 +15,7 @@ import fs from "node:fs/promises";
 /** The refusal for a file over the disk download cap. */
 function tooLargeResponse(bytes) {
     return errorResponse(`File too large (${Math.round(bytes / 1024 / 1024)}MB). ` +
-        `Maximum allowed: ${DISK_MAX_FILE_SIZE / 1024 / 1024}MB`);
+        `Maximum allowed: ${DISK_MAX_FILE_SIZE / 1024 / 1024}MB`, "rejectedFile");
 }
 /**
  * Register download_dropbox_submission_file tool.
@@ -38,17 +38,17 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
             validateContentId(submissionId);
             validateContentId(fileId);
             if (!path.isAbsolute(downloadPath)) {
-                return errorResponse("downloadPath must be an absolute path (e.g., /Users/username/Downloads or C:\\Users\\username\\Downloads)");
+                return errorResponse("downloadPath must be an absolute path (e.g., /Users/username/Downloads or C:\\Users\\username\\Downloads)", "invalidInput");
             }
             try {
                 const stats = await fs.stat(downloadPath);
                 if (!stats.isDirectory()) {
-                    return errorResponse(`downloadPath is not a directory: ${downloadPath}`);
+                    return errorResponse(`downloadPath is not a directory: ${downloadPath}`, "destination");
                 }
             }
             catch (error) {
                 if (error?.code === "ENOENT") {
-                    return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                    return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
                 }
                 throw error;
             }
@@ -61,21 +61,21 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
                 const submission = allSubmissions.find((s) => s.Id === submissionId);
                 if (!submission) {
                     return errorResponse(`Submission ${submissionId} not found in folder ${folderId}. ` +
-                        "Use get_dropbox_submissions to list available submissions.");
+                        "Use get_dropbox_submissions to list available submissions.", "notFound");
                 }
                 targetFile = submission.Files.find((f) => f.FileId === fileId) ?? null;
                 if (!targetFile) {
                     const available = submission.Files.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ");
-                    return errorResponse(`File ID ${fileId} not found in submission ${submissionId}. Available files: ${available}`);
+                    return errorResponse(`File ID ${fileId} not found in submission ${submissionId}. Available files: ${available}`, "notFound");
                 }
             }
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
                     return errorResponse("Instructor or TA access required for this course. This tool downloads another user's " +
-                        "dropbox submission file, which Brightspace only grants to course staff.");
+                        "dropbox submission file, which Brightspace only grants to course staff.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
-                    return errorResponse(`Folder ${folderId} not found in course ${courseId}.`);
+                    return errorResponse(`Folder ${folderId} not found in course ${courseId}.`, "notFound");
                 }
                 throw error;
             }
@@ -90,10 +90,10 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
             }
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
-                    return errorResponse("Instructor or TA access required for this course. Brightspace refused this download.");
+                    return errorResponse("Instructor or TA access required for this course. Brightspace refused this download.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
-                    return errorResponse("File not found on the server. It may have been deleted.");
+                    return errorResponse("File not found on the server. It may have been deleted.", "notFound");
                 }
                 throw error;
             }

package/build/tools/download-file.js

@@ -32,7 +32,7 @@ function tooLargeResponse(bytes, downloadPath) {
         : "";
     // null: the body was cut off at the cap, so its full size is unknown.
     const size = bytes === null ? "over the limit" : `${Math.round(bytes / 1024 / 1024)}MB`;
-    return errorResponse(`File too large (${size}). Maximum allowed: ${maxFileSize(downloadPath) / 1024 / 1024}MB.${hint}`);
+    return errorResponse(`File too large (${size}). Maximum allowed: ${maxFileSize(downloadPath) / 1024 / 1024}MB.${hint}`, "rejectedFile");
 }
 /**
  * Maximum bytes of a file we'll embed inline in a tool response. Base64
@@ -108,7 +108,7 @@ function truncateForInline(text, max) {
 async function respondInline(buffer, originalFilename, customFilename) {
     const effectiveFilename = customFilename || originalFilename;
     if (buffer.length > INLINE_MAX_SIZE) {
-        return errorResponse(`File too large for inline delivery (${Math.round(buffer.length / 1024 / 1024)}MB, inline max ${INLINE_MAX_SIZE / 1024 / 1024}MB). Provide an absolute downloadPath to save it to disk instead.`);
+        return errorResponse(`File too large for inline delivery (${Math.round(buffer.length / 1024 / 1024)}MB, inline max ${INLINE_MAX_SIZE / 1024 / 1024}MB). Provide an absolute downloadPath to save it to disk instead.`, "rejectedFile");
     }
     // Enforces the same magic-byte allowlist as disk mode (secureStreamDownload calls
     // validateFileTypeOfFile internally); inline mode never writes to disk, so it has
@@ -275,10 +275,10 @@ export function registerDownloadFile(server, apiClient) {
             // Parse and validate input
             const { courseId, topicId, coursePath, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
             if (coursePath !== undefined && (topicId !== undefined || folderId !== undefined || newsId !== undefined || fileId !== undefined || source !== undefined)) {
-                return errorResponse("coursePath cannot be combined with topicId, folderId, newsId, fileId, or source.");
+                return errorResponse("coursePath cannot be combined with topicId, folderId, newsId, fileId, or source.", "invalidInput");
             }
             if (source !== undefined && (topicId !== undefined || newsId !== undefined || folderId === undefined || fileId === undefined)) {
-                return errorResponse("source requires folderId and fileId and cannot be combined with topicId or newsId.");
+                return errorResponse("source requires folderId and fileId and cannot be combined with topicId or newsId.", "invalidInput");
             }
             // Validate courseId
             validateContentId(courseId);
@@ -288,18 +288,18 @@ export function registerDownloadFile(server, apiClient) {
             if (downloadPath !== undefined) {
                 // Validate download path is absolute
                 if (!path.isAbsolute(downloadPath)) {
-                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)");
+                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)", "invalidInput");
                 }
                 // Validate download directory exists and is a directory
                 try {
                     const stats = await fs.stat(downloadPath);
                     if (!stats.isDirectory()) {
-                        return errorResponse(`Download path is not a directory: ${downloadPath}`);
+                        return errorResponse(`Download path is not a directory: ${downloadPath}`, "destination");
                     }
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
                     }
                     throw error;
                 }
@@ -308,7 +308,7 @@ export function registerDownloadFile(server, apiClient) {
             if (coursePath !== undefined) {
                 const filePath = parseCoursePath(coursePath, courseId, apiClient.origin);
                 if (typeof filePath !== "string")
-                    return errorResponse(filePath.error);
+                    return errorResponse(filePath.error, "invalidInput");
                 return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
             }
             else if (topicId !== undefined) {
@@ -329,7 +329,7 @@ export function registerDownloadFile(server, apiClient) {
                 return await downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename);
             }
             else {
-                return errorResponse("Either topicId (for content files), coursePath (for course files linked from a module description), both folderId and fileId (for submission files), or both newsId and fileId (for announcement attachments) must be provided");
+                return errorResponse("Either topicId (for content files), coursePath (for course files linked from a module description), both folderId and fileId (for submission files), or both newsId and fileId (for announcement attachments) must be provided", "invalidInput");
             }
         }
         catch (error) {
@@ -347,7 +347,7 @@ async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, c
     log("INFO", `Downloading course file: courseId=${courseId}, path=${filePath}`);
     const response = await apiClient.getPageRaw(`${QUICKLINK_PATH}?ou=${courseId}&type=coursefile&fileId=${encodeURIComponent(filePath)}`);
     if (!response) {
-        return errorResponse(`Course files are served only to a signed-in Brightspace web session, and there is no valid one: the session cookie is missing or has expired. Sign in again with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`);
+        return errorResponse(`Course files are served only to a signed-in Brightspace web session, and there is no valid one: the session cookie is missing or has expired. Sign in again with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`, "auth");
     }
     // A missing file or a refused one can come back as an ordinary Brightspace
     // web page with HTTP 200. That page is not the file, so it is never saved
@@ -367,11 +367,11 @@ async function downloadAssignmentAttachment(apiClient, courseId, folderId, fileI
     const folders = Array.isArray(raw) ? raw : raw?.Objects ?? [];
     const folder = folders.find((candidate) => candidate.Id === folderId && candidate.IsHidden !== true);
     if (!folder)
-        return errorResponse(`No visible assignment with id ${folderId} in course ${courseId}.`);
+        return errorResponse(`No visible assignment with id ${folderId} in course ${courseId}.`, "notFound");
     const attachments = folder.Attachments ?? [];
     const file = attachments.find((candidate) => candidate.FileId === fileId);
     if (!file)
-        return errorResponse(`File ID ${fileId} not found on this assignment. Available files: ${attachments.map((candidate) => `${candidate.FileName} (ID: ${candidate.FileId})`).join(", ")}`);
+        return errorResponse(`File ID ${fileId} not found on this assignment. Available files: ${attachments.map((candidate) => `${candidate.FileName} (ID: ${candidate.FileId})`).join(", ")}`, "notFound");
     if (file.Size > maxFileSize(downloadPath))
         return tooLargeResponse(file.Size, downloadPath);
     const response = await apiClient.getRaw(apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${fileId}`));
@@ -442,7 +442,7 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
     const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/mysubmissions/`);
     const submissions = await apiClient.get(submissionsPath);
     if (!submissions || submissions.length === 0) {
-        return errorResponse("No submissions found for this assignment. Upload a submission first.");
+        return errorResponse("No submissions found for this assignment. Upload a submission first.", "notFound");
     }
     // Find the file across every submission.
     //
@@ -463,7 +463,7 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
     }
     if (!submission || !file) {
         const available = submissions.flatMap((s) => s.Files ?? []);
-        return errorResponse(`File ID ${fileId} not found in submission. Available files: ${available.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
+        return errorResponse(`File ID ${fileId} not found in submission. Available files: ${available.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`, "notFound");
     }
     // Check file size before downloading
     if (file.Size > maxFileSize(downloadPath)) {
@@ -486,7 +486,7 @@ async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downl
     const attachments = newsItem?.Attachments ?? [];
     const file = attachments.find((f) => f.FileId === fileId);
     if (!file) {
-        return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
+        return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`, "notFound");
     }
     if (file.Size > maxFileSize(downloadPath)) {
         return tooLargeResponse(file.Size, downloadPath);

package/build/tools/get-calendar-events.js

@@ -28,7 +28,7 @@ export function registerGetCalendarEvents(server, apiClient, config) {
             if (windowEnd < windowStart) {
                 return errorResponse(from
                     ? `to (${to}) is before from (${from}). Pass a to that is on or after from.`
-                    : `to (${to}) is in the past, and from defaults to now. Pass from as well to look at past events.`);
+                    : `to (${to}) is in the past, and from defaults to now. Pass from as well to look at past events.`, "invalidInput");
             }
             const courses = await resolveCourses(apiClient, config, courseId);
             const results = await Promise.allSettled(courses.map((course) => fetchCourseCalendarEvents(apiClient, config.baseUrl, course, windowStart, windowEnd)));

package/build/tools/get-discussions.js

@@ -43,7 +43,7 @@ export function registerGetDiscussions(server, apiClient) {
             const { courseId, forumId, topicId } = GetDiscussionsSchema.parse(args);
             // topicId requires forumId
             if (topicId !== undefined && forumId === undefined) {
-                return errorResponse("topicId requires forumId. Provide both forumId and topicId to get posts for a specific topic.");
+                return errorResponse("topicId requires forumId. Provide both forumId and topicId to get posts for a specific topic.", "invalidInput");
             }
             // Specific topic — get posts
             if (forumId !== undefined && topicId !== undefined) {

package/build/tools/get-dropbox-feedback.js

@@ -32,7 +32,7 @@ export function registerGetDropboxFeedback(server, apiClient) {
             // lets a student read once it is released.
             const own = parsed.entityId === undefined;
             if (own && parsed.entityType === "group") {
-                return errorResponse("entityId is required when entityType is group.");
+                return errorResponse("entityId is required when entityType is group.", "invalidInput");
             }
             const entityType = parsed.entityType ?? "user";
             const entityId = parsed.entityId ?? await fetchCurrentUserId(apiClient);
@@ -47,7 +47,7 @@ export function registerGetDropboxFeedback(server, apiClient) {
                         ? "Brightspace refused this read of your own feedback; it has not been released yet, or " +
                             "this course does not expose it through the API. Check the assignment in Brightspace."
                         : "Instructor or TA access required for this course. Reading another user's grading " +
-                            "feedback is only granted to course staff; to read your own, omit entityType and entityId.");
+                            "feedback is only granted to course staff; to read your own, omit entityType and entityId.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({

package/build/tools/get-dropbox-folders.js

@@ -45,7 +45,7 @@ export function registerGetDropboxFolders(server, apiClient) {
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
                     return errorResponse("Instructor or TA access required for this course. This tool reads every student's " +
-                        "dropbox folder metadata, which Brightspace only grants to course staff.");
+                        "dropbox folder metadata, which Brightspace only grants to course staff.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({

package/build/tools/get-dropbox-submissions.js

@@ -55,7 +55,7 @@ export function registerGetDropboxSubmissions(server, apiClient) {
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
                     return errorResponse("Instructor or TA access required for this course. This tool reads every student's " +
-                        "dropbox submissions, which Brightspace only grants to course staff.");
+                        "dropbox submissions, which Brightspace only grants to course staff.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({

package/build/tools/get-dropbox-user-submissions.js

@@ -32,7 +32,7 @@ export function registerGetDropboxUserSubmissions(server, apiClient) {
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
                     return errorResponse("Instructor or TA access required for this course. This tool reads another user's " +
-                        "dropbox submissions, which Brightspace only grants to course staff.");
+                        "dropbox submissions, which Brightspace only grants to course staff.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({

package/build/tools/get-my-grades.js

@@ -106,7 +106,7 @@ export function registerGetMyGrades(server, apiClient, config) {
                         const url = gradebookUrl(config.baseUrl, courseId);
                         log("INFO", `get_my_grades: 403 for course ${courseId} - grade API access restricted`);
                         return errorResponse("Your institution restricts grade API access for this course. " +
-                            `View your grades directly in Brightspace: ${url}`);
+                            `View your grades directly in Brightspace: ${url}`, "permission");
                     }
                     // A pending sign-in is not an empty gradebook: the route never
                     // answered, so the result says so instead of reporting zero grades

package/build/tools/get-rubrics-for-object.js

@@ -32,7 +32,7 @@ export function registerGetRubricsForObject(server, apiClient) {
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
                     return errorResponse("Instructor or TA access required for this course. This tool reads dropbox rubric " +
-                        "metadata, which Brightspace only grants to course staff.");
+                        "metadata, which Brightspace only grants to course staff.", "permission");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({

package/build/tools/get-syllabus.js

@@ -119,17 +119,17 @@ export function registerGetSyllabus(server, apiClient) {
             // Validate downloadPath if provided
             if (downloadPath !== undefined) {
                 if (!path.isAbsolute(downloadPath)) {
-                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)");
+                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)", "invalidInput");
                 }
                 try {
                     const stats = await fs.stat(downloadPath);
                     if (!stats.isDirectory()) {
-                        return errorResponse(`Download path is not a directory: ${downloadPath}`);
+                        return errorResponse(`Download path is not a directory: ${downloadPath}`, "destination");
                     }
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
                     }
                     throw error;
                 }
@@ -169,7 +169,7 @@ export function registerGetSyllabus(server, apiClient) {
                     // Check Content-Length before downloading body
                     const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
                     if (contentLength > MAX_FILE_SIZE) {
-                        return errorResponse(`Attachment too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+                        return errorResponse(`Attachment too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`, "rejectedFile");
                     }
                     // Get filename from Content-Disposition header
                     const disposition = response.headers.get("Content-Disposition") ?? "";
@@ -182,7 +182,7 @@ export function registerGetSyllabus(server, apiClient) {
                     }
                     catch (error) {
                         if (error instanceof DownloadError && error.kind === "tooLarge") {
-                            return errorResponse(`Attachment too large (over ${MAX_FILE_SIZE / 1024 / 1024}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+                            return errorResponse(`Attachment too large (over ${MAX_FILE_SIZE / 1024 / 1024}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`, "rejectedFile");
                         }
                         throw error;
                     }

package/build/tools/get-video-transcript.js

@@ -53,6 +53,18 @@ async function followLtiLaunch(apiClient, path) {
  * worked around here: the way past it is the user's own browser, and the
  * result says plainly that nothing was read.
  */
+/** The dev activity log's category for a transcript the platform would not serve. */
+function transcriptErrorKind(reason) {
+    switch (reason) {
+        case "sign_in_required":
+        case "access_blocked":
+            return "providerBlocked";
+        case "unavailable":
+            return "notFound";
+        case "fetch_failed":
+            return "transport";
+    }
+}
 function transcriptRecovery(reason, videoUrl) {
     switch (reason) {
         case "sign_in_required":
@@ -158,7 +170,7 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
                 resolvedUrl = resolved.url;
             }
             else {
-                return errorResponse("Provide either videoUrl, or both courseId and topicId to look up the video from course content.");
+                return errorResponse("Provide either videoUrl, or both courseId and topicId to look up the video from course content.", "invalidInput");
             }
             // A relative /d2l/ link, or an absolute one on this Brightspace's own
             // origin, is requested as the user; any other origin never sees the session.
@@ -209,7 +221,7 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
             if ("failed" in outcome) {
                 // The message stays the first block, as it always was; the second
                 // carries the same failure in a shape a caller can branch on.
-                const failure = errorResponse(outcome.failed);
+                const failure = errorResponse(outcome.failed, transcriptErrorKind(outcome.reason));
                 failure.content.push({
                     type: "text",
                     text: JSON.stringify({

package/build/tools/tool-helpers.js

@@ -12,6 +12,7 @@ import { AUTH_COMMAND } from "../utils/commands.js";
 import { getUpdateNotice } from "../utils/update-checker.js";
 import { mfaShortcutTip } from "../utils/two-factor-shortcuts.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
+import { tagErrorKind, withErrorKind } from "../utils/error-kind.js";
 /**
  * Append an available-update notice to an already-built content array and
  * wrap it as a CallToolResult. This is the one place an update notice can
@@ -62,8 +63,8 @@ export function toolResponseWithNotice(data, notice) {
 /**
  * Wrap error message as MCP-compatible tool result
  */
-export function errorResponse(message) {
-    return {
+export function errorResponse(message, kind) {
+    const result = {
         content: [
             {
                 type: "text",
@@ -72,6 +73,8 @@ export function errorResponse(message) {
         ],
         isError: true,
     };
+    // The dev activity log records the category, never the message.
+    return kind ? tagErrorKind(result, kind) : result;
 }
 /**
  * What to tell the user for each way an automatic sign-in can fail.
@@ -228,6 +231,9 @@ export function authPendingNotice(error) {
 export function sanitizeError(error) {
     // Log full error to stderr for debugging (token redaction handled by logger)
     log("ERROR", "Tool error", error);
+    return withErrorKind(describeError(error), error);
+}
+function describeError(error) {
     // Authentication runs inside the tool call now, so its failures surface
     // here rather than from a dedicated auth tool. Checked first: the kind
     // carries guidance that the generic branches below would throw away.

package/build/utils/config.js

@@ -14,6 +14,7 @@ import { getStoredTotpUri } from "../auth/credential-store.js";
 import { canonicalUsername } from "../auth/username.js";
 import { normalizeTotpEnrollment } from "../auth/totp.js";
 import { migrateLegacyState } from "../auth/legacy-state.js";
+import { startupPhase } from "./startup-phase.js";
 /**
  * The saved settings, or null when there are none to use. A corrupt or
  * permission-denied config.json must not take the whole server down at
@@ -77,7 +78,7 @@ export function resolveSessionLocation() {
     const { sessionDir, sessionRoot } = resolveAccountLocation(readConfigStore());
     return { sessionDir, sessionRoot };
 }
-export async function loadConfig() {
+export async function loadConfig({ credentials = true } = {}) {
     dotenv.config({ quiet: true });
     const store = readConfigStore();
     // Code-entry and other interactive MFA methods need a visible browser.
@@ -125,7 +126,9 @@ export async function loadConfig() {
     const rawSessionCookie = readEnvSecret(process.env.D2L_SESSION_COOKIE, "D2L_SESSION_COOKIE");
     const envSessionCookie = rawSessionCookie ? parseSessionCookieEnv(rawSessionCookie) : undefined;
     const { baseUrl, username, sessionRoot, sessionDir } = resolveAccountLocation(store);
-    const password = passwordless ? undefined : await resolveStoredPassword(baseUrl, username, store);
+    const password = passwordless || !credentials
+        ? undefined
+        : await startupPhase("reading the saved password from the OS credential store", () => resolveStoredPassword(baseUrl, username, store));
     // Opt-in: only an enrollment the user deliberately saved makes the Entra
     // sign-in answer a verification-code challenge itself. With none, every MFA
     // challenge is handled exactly as before. The keyring entry is per account;
@@ -139,7 +142,9 @@ export async function loadConfig() {
         // an optional extra, and resolveStoredPassword above is already the place
         // that reports a locked or missing store, loudly, for the credential the
         // server genuinely cannot work without.
-        : username ? (await getStoredTotpUri(baseUrl, username).catch(() => null)) ?? undefined : undefined;
+        : username && credentials
+            ? (await startupPhase("reading the saved authenticator key from the OS credential store", () => getStoredTotpUri(baseUrl, username).catch(() => null))) ?? undefined
+            : undefined;
     const legacyMigration = sessionDir !== sessionRoot ? await migrateLegacyState(sessionRoot) : undefined;
     return {
         baseUrl,

package/build/utils/dev-activity.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { AUTH_PHASES } from "../auth/auth-phases.js";
+import { ERROR_KINDS, errorKind, resultErrorKind } from "./error-kind.js";
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -42,6 +43,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
         record.reason = fields.reason;
     if (AUTH_PHASES.includes(fields.phase ?? ""))
         record.phase = fields.phase;
+    if (ERROR_KINDS.includes(fields.errorKind ?? ""))
+        record.errorKind = fields.errorKind;
     try {
         mkdirSync(directory, { recursive: true, mode: 0o700 });
         const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);
@@ -77,16 +80,24 @@ export function trackToolActivity(server) {
         lastStart = started;
         return calls.run(context, async () => {
             let outcome = "error";
+            let kind;
             try {
                 const result = await callback(...args);
-                if (!result?.isError) {
+                if (result?.isError) {
+                    kind = resultErrorKind(result);
+                }
+                else {
                     outcome = "success";
                     lastSuccess = Date.now();
                 }
                 return result;
             }
+            catch (error) {
+                kind = errorKind(error);
+                throw error;
+            }
             finally {
-                write("tool_finished", { outcome, elapsedMs: Date.now() - started });
+                write("tool_finished", { outcome, errorKind: kind, elapsedMs: Date.now() - started });
             }
         });
     })));