wicker-study-mcp 2.7.0 → 2.9.0

package/README.md

@@ -17,7 +17,7 @@ the MCP server.
 For a manually supplied key, the same secure bootstrap is available as:
 
 ```sh
-WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.7.0 configure
+WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.9.0 configure
 ```
 
 ```jsonc
@@ -67,7 +67,7 @@ agent receives proxied course data and nothing else.
 `wicker_status`, `wicker_authorize`, `wicker_sign_out`, and `canvas_connect` work without a key —
 they are how a key is obtained. Everything else needs one.
 
-- **Reading** — `list_courses`, `get_course`, `get_chapter`, `get_course_outline`, `search_course`,
+- **Reading** — `list_courses`, `get_course`, `get_chapter`, `get_course_outline`, `search_course`, `list_regulation_sources`, `search_regulations`,
   `list_materials`, `list_questions`, `get_practice_queue`, `get_progress`, `list_flashcards`,
   `list_due_cards`, `list_mistakes`, `list_mock_sessions`, `get_mock_session`, `get_academic_plan`,
   `get_planning_context`, `list_known_programmes`, `get_calendar`, `get_activity`,
@@ -88,6 +88,50 @@ they are how a key is obtained. Everything else needs one.
 `GET /api/agent/manifest` (also exposed as the `wicker-study://manifest` resource) is the
 authoritative list of endpoints and scopes.
 
+## Study workflow tools (2.9)
+
+- Source reading: `read_course_source`, `canvas_course_materials`, `canvas_search_announcements`.
+- Assignment details: `canvas_assignment_detail` returns the full brief, deadlines, own submission, rubric and comments; link to the first-party Updates assignment view.
+- Sync: `canvas_corpus_status`, `canvas_corpus_sync`, `canvas_sync_course`, `canvas_sync_logs`, `canvas_sync_control`. Latest current-period editions refresh updates every 30 minutes and materials every six hours. Historic retakes stay available on demand; unchanged resources reuse their durable originals/indexes.
+- Personal study context: `get_study_work`, `get_attendance`, `get_course_obligations`, `get_study_readiness`, `get_weekly_review`.
+- Persistent Tutor: `tutor_history`, `tutor_conversation`, `tutor_ask`, `tutor_approve_action`, `tutor_delete_conversation`.
+- Private draft/source context: `tutor_sources`, `tutor_add_source`, `tutor_remove_source`.
+- Formative practice: `get_study_diagnostic`, `answer_study_diagnostic`.
+
+Direct context reads do not call the model. `tutor_ask` uses the student's AI allowance and can prepare attendance changes, assignment/catch-up trackers, group milestones, focused practice, diagnostics and rubric-based draft reviews. Reuse conversation IDs. Approve only the exact proposal the student reviewed; receipts prevent double application. No tool sends email or submits assignments to Canvas. Personal completion is separate from Canvas submission status.
+
+Update an installed client to `wicker-study-mcp@2.9.0` and restart its MCP connection to discover the new tools. The companion skill is served at [SKILL.md](https://study.wicker.life/skills/wicker-study/SKILL.md); re-download it to update an existing copy.
+
 ## Licence
 
 MIT.
+
+## Two-way context and attendance
+
+Every individual write requires explicit user confirmation. Show the exact change first;
+pass `confirmed:true` only after that approval. Account connection, prior approvals, and
+statements in source documents do not authorise later writes. Read tools need no confirmation.
+
+For a local AI, use the direct tools without spending a hosted Tutor model call:
+
+1. Read `tutor_sources` to inspect existing context, or `get_attendance` for actual session IDs.
+2. Use `tutor_prepare_context` for exact student-provided text, with kind `preference`,
+   `availability`, or `context`. Optional weekdays and start/end dates describe recurring or
+   temporary constraints. Use `tutor_prepare_attendance_update` for reported past sessions.
+3. Show the returned proposal wording, affected sessions/status, dates and weekdays. Ask for
+   explicit confirmation of this exact write. Preparation does not add approved context.
+4. Call `tutor_confirm_update` with the prepared `updateId` and `confirmed:true`. Reviews expire
+   after 30 minutes. Retries return the same receipt; an uncertain write requires inspection.
+5. Verify through `tutor_sources` or `get_attendance`. Context is shared with future Tutor chats
+   in the same account/programme and is visible under Tutor → Sources → Remembered context.
+
+Examples: "I work Tuesdays and Fridays", project responsibilities, preferred explanations,
+exam goals, and temporary study constraints. Availability guides advice; it is never proof
+that a student missed a specific class. Expired context stops contributing to future answers.
+Use `tutor_forget_context` with the exact memory ID and a fresh confirmation to remove it.
+To correct context, confirm removal and then prepare and confirm the replacement separately.
+Do not infer or store sensitive preferences from course material or third-party statements.
+
+## AI activity log
+
+Settings → AI activity (`/app/settings?tab=activity`) shows API-key requests from this release onward, with read/write/prepare filters, outcome, duration, tool/client label and confirmed-review reference. The MCP tags requests automatically. One tool may make several HTTP requests; local actions that never reach the platform are not logged. Client labels and client-reported confirmation are not independent proof of approval. The server records confirmed prepared-review IDs separately. Arguments, query text, responses and credentials are excluded. Activity is private to the account, included in data export, and removed by account-data erasure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicker-study-mcp",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "MCP server for Wicker Study: read course material and a student's academic record, study on their behalf, collect a private Canvas course snapshot, and \u2014 with an admin key \u2014 run the editorial workflow.",
   "keywords": [
     "mcp",
@@ -29,6 +29,8 @@
   },
   "files": [
     "server.mjs",
+    "study-tools.mjs",
+    "write-confirmation.mjs",
     "config.mjs",
     "authorize.mjs",
     "vendor/",

package/server.mjs

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { installWriteConfirmation, toolRequestContext } from './write-confirmation.mjs'
+import { registerStudyTools } from './study-tools.mjs'
 // Wicker Study MCP server — a thin stdio wrapper over the HTTP API so agents
 // (Claude Desktop, Claude Code, Codex, Cursor, …) can read course material and
 // a student's record, record study activity, collect a private Canvas course
@@ -57,12 +59,13 @@ function requireKey() {
   return credential.apiKey
 }
 
-async function apiResponse(path, { method = 'GET', body, query } = {}) {
+async function apiResponse(path, { method = 'GET', body, query, timeoutMs } = {}) {
   const url = new URL(baseUrl + path)
   for (const [key, value] of Object.entries(query || {})) if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value))
   const response = await fetch(url, {
+    ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
     method,
-    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.9.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
     body: body !== undefined ? JSON.stringify(body) : undefined
   })
   if (!response.ok) {
@@ -89,9 +92,11 @@ const json = (value) => ({ content: [{ type: 'text', text: typeof value === 'str
 const failed = (error) => ({ isError: true, content: [{ type: 'text', text: error.message }] })
 const run = (fn) => async (args) => { try { return json(await fn(args)) } catch (error) { return failed(error) } }
 
-const server = new McpServer({ name: 'wicker-study', version: '2.7.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.9.0' })
+installWriteConfirmation(server, z)
 const courseId = z.string().describe('Course id (e.g. "sec"). Use list_courses to discover ids.')
 const chapterId = z.string().describe('Chapter id (e.g. "02").')
+registerStudyTools(server, { z, run, api, defaultCanvasUrl: DEFAULT_CANVAS_URL })
 
 const COURSE_SOURCE_EXTENSIONS = new Set(['.pdf', '.ppt', '.pptx', '.doc', '.docx', '.txt', '.md', '.csv', '.tex', '.m', '.py', '.r', '.html', '.htm', '.png', '.jpg', '.jpeg', '.webp'])
 const SOURCE_MIME = { '.pdf': 'application/pdf', '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.tex': 'text/x-tex', '.m': 'text/x-matlab', '.py': 'text/x-python', '.r': 'text/x-r', '.html': 'text/html', '.htm': 'text/html', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' }
@@ -488,6 +493,15 @@ server.tool('search_course', 'Hybrid full-text and embedding retrieval across pu
   query: z.string(),
   limit: z.number().int().min(1).max(20).optional()
 }, run((args) => api('/api/retrieve', { method: 'POST', body: args })))
+server.tool('search_regulations', 'Focused retrieval from official regulations for the active programme. Use for the Education and Examination Regulations, Board of Examiners, exam and resit procedures, registration, inspections, appeals, exemptions, hardship, fraud, projects, internships and curriculum transition rules. Results include the governing document, academic year and exact page; programme-restricted originals are not exposed.', {
+  query: z.string(),
+  academicYear: z.string().optional().describe('Exact academic year such as 2026-2027. Defaults to the active programme year.'),
+  documentKind: z.enum(['education-examination-regulations', 'rules-regulations', 'board-of-examiners', 'exam-procedure', 'programme-policy', 'other']).optional(),
+  limit: z.number().int().min(1).max(20).optional()
+}, run((args) => api('/api/programme-policies/retrieve', { method: 'POST', body: args })))
+server.tool('list_regulation_sources', 'List the official regulation sources indexed for the active programme and academic year. Returns reviewed metadata and coverage counts, never a programme-restricted original.', {
+  academicYear: z.string().optional().describe('Exact academic year such as 2026-2027. Defaults to the active programme year.')
+}, run(({ academicYear }) => api('/api/programme-policies', { query: { academicYear } })))
 server.tool('canvas_corpus_status', 'Material collection consent, background sync jobs, versioned course editions, source counts, and last/next scrape times for the connected account.', {
   canvasUrl: z.string().url().optional()
 }, run(({ canvasUrl }) => api('/api/account/integrations/canvas/corpus', { query: { canvasUrl: canvasUrl || DEFAULT_CANVAS_URL } })))
@@ -605,7 +619,7 @@ server.tool('canvas_import_remote_course_set', 'Find every remotely connected Ca
   canvasUrl: z.string().url().default('https://canvas.maastrichtuniversity.nl'), query: z.string().min(1).max(240), outputFolder: z.string().min(1), maxCourses: z.number().int().min(1).max(100).default(25), maxResources: z.number().int().min(1).max(CANVAS_IMPORT_LIMITS.maxResources).default(CANVAS_IMPORT_LIMITS.maxResources), maxFileBytes: z.number().int().min(1).max(CANVAS_IMPORT_LIMITS.maxFileBytes).default(CANVAS_IMPORT_LIMITS.maxFileBytes)
 }, run(importRemoteCanvasCourseSet))
 
-server.tool('analyze_documents', 'Analyse supporting documents (transcript, exam schedule, timetable, academic calendar, curriculum) with AI and return a reviewable change set against the student’s plan. Uses the student’s intake allowance. Follow with apply_changes.', { kind: z.enum(['auto', 'transcript', 'exam-schedule', 'timetable', 'academic-calendar', 'curriculum']).optional(), description: z.string().optional(), documents: z.array(z.object({ name: z.string(), type: z.string().optional(), text: z.string().optional(), images: z.array(z.string()).optional() })) },
+server.tool('analyze_documents', 'Analyse supporting documents (transcript, exam schedule, timetable, academic calendar, curriculum) with AI and return a reviewable change set against the student’s plan. Uses the student’s intake allowance. Follow with apply_changes.', { kind: z.enum(['auto', 'academic-overview', 'transcript', 'exam-schedule', 'timetable', 'academic-calendar', 'curriculum']).optional(), description: z.string().optional(), documents: z.array(z.object({ name: z.string(), type: z.string().optional(), text: z.string().optional(), images: z.array(z.string()).optional() })) },
   run((body) => api('/api/academics/documents/analyze', { method: 'POST', body })))
 server.tool('apply_changes', 'Apply accepted change objects (from analyze_documents or a calendar preview) to the active plan.', { changes: z.array(z.record(z.any())), expectedRevision: z.number().int() },
   run((body) => api('/api/academics/documents/apply', { method: 'POST', body })))

package/study-tools.mjs

@@ -0,0 +1,36 @@
+// The web workspace and MCP use the same account-scoped API and proposal receipts.
+export function registerStudyTools(server, { z, run, api, defaultCanvasUrl }) {
+  const id = z.string().min(1).max(160)
+  const code = z.string().max(40).optional()
+  const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
+  const canvasUrl = z.string().url().optional()
+  const context = z.object({ courseId: code, courseCode: code, chapterId: code, sourcePath: z.string().max(500).optional(), attachmentIds: z.array(id).max(10).optional() }).optional()
+  const tool = (name, description, schema, handler) => server.tool(name, description, schema, run(handler))
+  tool('read_course_source', 'Read 12 indexed passages from an authorised Canvas document returned by search_course. Follow nextOffset to read beyond the snippet, including later paper-list pages. Retains edition, path and page citations; never widens source access.', { assetId: id, courseCode: z.string().min(1).max(40), offset: z.number().int().min(0).max(100000).optional() }, args => api('/api/retrieve/source', { query: args }))
+  tool('canvas_course_materials', 'List indexed originals and source editions for one course. Select an exact academic year for a retake; use read_course_source for extracted text.', { courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional() }, args => api('/api/corpus/materials', { query: args }))
+  tool('canvas_assignment_detail', 'Read the full assignment brief, due/unlock/lock dates, own submission status, grade, rubric and submission comments. Use Canvas numeric course and assignment IDs from canvas_updates. Direct the student to /app/updates?tab=assignments&assignment=COURSE_ID%3AASSIGNMENT_ID; Canvas remains a secondary link.', { canvasUrl, courseId: z.string().regex(/^\d+$/), assignmentId: z.string().regex(/^\d+$/), refresh: z.boolean().optional() }, ({ refresh, ...args }) => api('/api/integrations/canvas/assignment', { query: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl, refresh: refresh ? '1' : undefined } }))
+  tool('canvas_sync_logs', 'Inspect durable progress for one sync job, optionally filtered by stage or severity. before is the next cursor returned by an earlier page. Last progress and worker checkpoints are distinct; do not claim a task is advancing from its heartbeat alone.', { job: id, before: z.string().max(160).optional(), stage: z.string().max(40).optional(), level: z.enum(['info','warning','error']).optional() }, args => api('/api/account/integrations/canvas/corpus/logs', { query: args }))
+  tool('canvas_sync_control', 'Stop or retry one owned course-edition sync, after the student requests that action. Retry resumes saved originals and unfinished stages; stop fences the running worker and pauses future material refreshes for that edition.', { jobId: id, action: z.enum(['stop','retry']) }, ({ jobId, action }) => api(`/api/integrations/canvas/corpus/jobs/${encodeURIComponent(jobId)}`, { method: 'POST', body: { action } }))
+  tool('canvas_sync_course', 'Queue a specific accessible Canvas course edition. Current-period latest editions refresh automatically; use this for a missing or historical edition or an explicit refresh. Existing material consent is required; this cannot grant consent. force:false reuses verified unchanged resources.', { canvasUrl, canvasCourseId: z.string().regex(/^\d+$/), force: z.boolean().default(false) }, args => api('/api/integrations/canvas/corpus/course', { method: 'POST', body: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl } }))
+  tool('tutor_prepare_attendance_update', 'Prepare an exact attendance change without applying it or calling a model. First read get_attendance, then use its exact session IDs and the student’s explicit report. Show the returned proposal detail and ask for confirmation before tutor_confirm_update.', { courseCode: code, from: date, to: date, eventIds: z.array(id).min(1).max(20), status: z.enum(['attended','missed','unknown']), note: z.string().max(500).optional() }, body => api('/api/tutor/updates/prepare', { method: 'POST', body: { ...body, kind: 'attendance' } }))
+  tool('tutor_prepare_context', 'Prepare personal context for future Tutor answers without adding it to memory yet or calling a model. Examples: preferred explanation style, project role, or work every Tuesday/Friday. Store exact student-provided wording; optional dates bound temporary context. Availability is advice context, not proof of absence. Show the returned wording, dates and weekdays before requesting confirmation.', { kind: z.enum(['preference','availability','context']), text: z.string().min(1).max(400), weekdays: z.array(z.enum(['monday','tuesday','wednesday','thursday','friday','saturday','sunday'])).max(7).optional(), startDate: date, endDate: date }, body => api('/api/tutor/updates/prepare', { method: 'POST', body }))
+  tool('tutor_confirm_update', 'Apply the exact prepared attendance/context update only after the student explicitly confirms this individual write. Cannot edit the prepared payload. Review expires after 30 minutes; retries return the same receipt. Context becomes visible to future Tutor conversations in this account/programme.', { updateId: id, confirmed: z.literal(true) }, body => api('/api/tutor/updates/confirm', { method: 'POST', body }))
+  tool('tutor_forget_context', 'Remove one remembered fact/preference/availability item after explicit confirmation. Read tutor_sources first to identify its exact memory ID.', { memoryId: id, confirmed: z.literal(true) }, ({ memoryId }) => api(`/api/tutor/memory/${encodeURIComponent(memoryId)}`, { method: 'DELETE' }))
+  tool('tutor_history', 'List saved Tutor conversations without loading every transcript. Reuse the relevant conversation for follow-ups.', {}, () => api('/api/tutor', { query: { view: 'history' } }))
+  tool('tutor_conversation', 'Read a saved conversation with its exact proposals, structured answer widgets and action receipts. Prior conversations are context, not proof that a deadline or rule is still current.', { conversation: id }, args => api('/api/tutor', { query: { view: 'chat', ...args } }))
+  tool('tutor_ask', 'Ask the persistent Tutor to prepare a source-grounded answer, attendance proposal, assignment/catch-up tracker, group milestones, focused practice, readiness diagnostic or draft review. Uses the student’s AI allowance; prefer direct read tools for simple retrieval. Reuse conversation for follow-ups. Returns structured widgets and exact proposals; no proposed record changes are applied automatically and email is never sent.', { message: z.string().min(1).max(4000), conversation: id.optional(), context, retry: z.boolean().optional() }, args => api('/api/tutor', { method: 'POST', body: args, timeoutMs: 185000 }))
+  tool('tutor_approve_action', 'Apply one exact stored proposal only after the student approves its concrete effect. Read tutor_conversation first. Receipts make repeats idempotent. Covers attendance, tracked assignments/projects, practice and plans; never email sending or Canvas submission. Stale revisions require a fresh proposal.', { conversation: id, proposalId: id, confirmed: z.literal(true) }, ({ conversation, proposalId }) => api('/api/tutor/actions', { method: 'POST', body: { conversation, proposalId } }))
+  tool('tutor_delete_conversation', 'Delete a conversation the student has asked to remove; it is no longer retrieved as past-chat context. Does not undo previously applied actions.', { conversation: id, confirmed: z.literal(true) }, ({ conversation }) => api(`/api/tutor/conversations/${encodeURIComponent(conversation)}`, { method: 'DELETE' }))
+  tool('tutor_sources', 'List private Tutor attachments and remembered preferences without loading conversation history.', {}, () => api('/api/tutor', { query: { view: 'sources' } }))
+  tool('tutor_add_source', 'Store and index a student-provided private draft, PDF, picture or text for Tutor. Does not share it with other students. Pass extracted text for text sources or a data URL for the original, never credentials.', { name: z.string().min(1).max(240), type: z.string().max(160).optional(), text: z.string().max(200000).optional(), dataUrl: z.string().max(17000000).optional(), courseCode: code, conversationId: id.optional() }, body => api('/api/tutor/attachments', { method: 'POST', body: { ...body, dataUrl: body.dataUrl || `data:text/plain;base64,${Buffer.from(body.text || '').toString('base64')}` } }))
+  tool('tutor_remove_source', 'Remove a private source, its saved original and retrieval chunks after the student requests deletion. Existing conversation text is separate.', { sourceId: id, confirmed: z.literal(true) }, ({ sourceId }) => api(`/api/tutor/attachments/${encodeURIComponent(sourceId)}`, { method: 'DELETE' }))
+  tool('get_study_work', 'Read persistent assignments, catch-up tasks, group milestones, blockers, diagnostics and supported capabilities. Personal completion is separate from Canvas submission/grades.', {}, () => api('/api/tutor/work'))
+  const readContext = view => args => api('/api/tutor/context', { query: { view, ...args } })
+  tool('get_attendance', 'Read recorded attendance against confirmed requirements, separated by activity and edition, with exact teaching-session IDs. Unmarked means unknown; personal excused marks do not grant an institutional exception. Use tutor_prepare_attendance_update to prepare reported attendance changes without a model call.', { courseCode: code, from: date, to: date }, readContext('attendance'))
+  tool('get_course_obligations', 'Read indexed course requirements and recent rule-changing announcements with provenance and unresolved conflicts. Explicit later amendments can supersede an older coursebook; a generic update notice does not establish a new rule.', { courseCode: code }, readContext('obligations'))
+  tool('get_study_readiness', 'Read self-ratings, actual practice, unresolved mistakes, diagnostic attempts and completed mocks for a course. Coverage gaps remain unknown; this is not a pass probability.', { courseCode: z.string().min(1).max(40) }, readContext('readiness'))
+  tool('get_weekly_review', 'Read completed, overdue and blocked personal study work plus practice activity over a date range. Personal done status does not mean submitted to Canvas.', { courseCode: code, from: date, to: date }, readContext('weekly-review'))
+  tool('canvas_search_announcements', 'Search relevant announcement text, including paper lists, links and explicit rule amendments. Returns author, date, course, text and coverage problems. Use a focused course/query instead of collecting every announcement.', { courseCode: code, query: z.string().max(500).optional(), days: z.number().int().min(1).max(365).optional(), limit: z.number().int().min(1).max(12).optional(), rulesOnly: z.boolean().optional() }, readContext('announcements'))
+  tool('get_study_diagnostic', 'Read a saved formative practice diagnostic prepared by Tutor. This is not an official grade.', { diagnosticId: id }, ({ diagnosticId }) => api(`/api/tutor/diagnostics/${encodeURIComponent(diagnosticId)}`))
+  tool('answer_study_diagnostic', 'Record the student’s answers to a saved diagnostic. Submit only answers they supplied, never answer for them and report it as their performance. Reuse requestId when retrying.', { diagnosticId: id, answers: z.record(z.number().int().min(0)), requestId: z.string().regex(/^[\w-]{8,100}$/) }, ({ diagnosticId, ...body }) => api(`/api/tutor/diagnostics/${encodeURIComponent(diagnosticId)}/answers`, { method: 'POST', body }))
+}

package/vendor/canvas-course-import.mjs

@@ -232,16 +232,26 @@ async function downloadResponseToFile(response, destinationPath, maxBytes) {
   }
 }
 
-export function createCanvasApi({ origin, accessToken, fetchImpl = fetch }) {
+export function createCanvasApi({ origin, accessToken, fetchImpl = fetch, checkpoint = null }) {
   async function request(value, { accept = 'application/json' } = {}) {
     const url = new URL(value, origin)
     if (url.origin !== origin) throw new CanvasCourseImportError('Canvas API requests must stay on the supplied Canvas origin.')
+    const cached = checkpoint ? await checkpoint.get(url.href) : null
+    if (!cached) await checkpoint?.beforeRequest?.()
     let response
     try {
+      if (cached) response = new Response(cached.body, { status: cached.status, headers: cached.headers })
+      else
       response = await fetchImpl(url, { headers: { accept, authorization: `Bearer ${accessToken}` }, signal: AbortSignal.timeout(CANVAS_IMPORT_LIMITS.timeoutMs) })
     } catch (error) {
       throw new CanvasCourseImportError(`Canvas could not be reached: ${error.message}`)
     }
+    if (checkpoint && !cached && (response.ok || [403, 404].includes(response.status))) {
+      const body = await response.text()
+      const headers = Object.fromEntries(response.headers.entries())
+      await checkpoint.set(url.href, { body, status: response.status, headers })
+      response = new Response(body, { status: response.status, headers })
+    }
     if (!response.ok) {
       if (response.status === 401) throw new CanvasCourseImportError(`Canvas returned HTTP 401 for ${url.pathname}. The importer sent the PAT correctly, but this Canvas host did not accept it. It may be expired, revoked, from another Canvas host, or Personal Access Token API access may be disabled by the institution.`)
       if (response.status === 403) throw new CanvasCourseImportError(`Canvas returned HTTP 403 for ${url.pathname}. The account or institution denied this API request. This does not by itself mean the PAT is incorrect; verify that the same Canvas account can open this course and that API access is permitted.`)
@@ -259,8 +269,11 @@ export function createCanvasApi({ origin, accessToken, fetchImpl = fetch }) {
     async getPaged(path) {
       const values = []
       let next = new URL(path, origin)
+      const visited = new Set()
       for (let page = 0; next; page++) {
-        if (page > 50) throw new CanvasCourseImportError('Canvas returned too many pagination pages.')
+        if (visited.has(next.href)) throw new CanvasCourseImportError('Canvas repeated a pagination URL.')
+        visited.add(next.href)
+        if (!checkpoint && page > 50) throw new CanvasCourseImportError('Canvas returned too many pagination pages.')
         const response = await request(next)
         let body
         try { body = await response.json() } catch { throw new CanvasCourseImportError('Canvas returned an unreadable paginated response.') }
@@ -389,7 +402,7 @@ export async function listCanvasCourseModules({ courseUrl, accessToken, fetchImp
   }
 }
 
-export async function importCanvasCourse({ courseUrl, accessToken, outputFolder, moduleIds, maxResources = CANVAS_IMPORT_LIMITS.maxResources, maxFileBytes = CANVAS_IMPORT_LIMITS.maxFileBytes, fetchImpl = fetch } = {}) {
+export async function importCanvasCourse({ courseUrl, accessToken, outputFolder, moduleIds, maxResources = CANVAS_IMPORT_LIMITS.maxResources, maxFileBytes = CANVAS_IMPORT_LIMITS.maxFileBytes, fetchImpl = fetch, onProgress = async () => {}, durable = null } = {}) {
   const canvas = parseCanvasCourseUrl(courseUrl)
   if (!text(accessToken, 20)) throw new CanvasCourseImportError('A Canvas Personal Access Token is required. Use the local hidden prompt or a local environment variable; never pass a password or OTP to this importer.')
   if (!outputFolder || !String(outputFolder).trim()) throw new CanvasCourseImportError('outputFolder is required and should be a dedicated local course folder.')
@@ -398,18 +411,20 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
   if (!Number.isInteger(maxFileBytes) || maxFileBytes < 1 || maxFileBytes > CANVAS_IMPORT_LIMITS.maxFileBytes) throw new CanvasCourseImportError(`maxFileBytes must be between 1 byte and ${Math.round(CANVAS_IMPORT_LIMITS.maxFileBytes / 1024 / 1024)} MB.`)
 
   const root = resolve(String(outputFolder))
-  await mkdir(root, { recursive: true })
+  if (!durable) await mkdir(root, { recursive: true })
   const manifestPath = join(root, '.wicker-canvas-import.json')
-  const entries = await readdir(root)
+  const entries = durable ? [] : await readdir(root)
   let previousManifest = null
   try {
-    previousManifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+    previousManifest = durable ? null : JSON.parse(await readFile(manifestPath, 'utf8'))
   } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
     if (error.code !== 'ENOENT') throw new CanvasCourseImportError('The existing Canvas import manifest could not be read. Choose a new folder or repair that manifest before importing again.')
   }
   const nonImportEntries = entries.filter((entry) => !['.DS_Store', '.wicker-canvas-import.json'].includes(entry))
   if (nonImportEntries.length && !previousManifest) throw new CanvasCourseImportError('Choose a new empty output folder, or a folder created by an earlier Wicker Study Canvas import. This prevents overwriting unrelated files.')
-  const api = createCanvasApi({ origin: canvas.origin, accessToken: String(accessToken), fetchImpl })
+  const api = createCanvasApi({ origin: canvas.origin, accessToken: String(accessToken), fetchImpl, checkpoint: durable?.checkpoint })
+  await onProgress({ stage: 'discovery', message: 'Connecting to Canvas and listing course resources.' })
   // Verify authentication independently before checking course-specific access. This
   // turns an opaque token error into a useful, non-sensitive diagnosis.
   await api.getJson('/api/v1/users/self/profile')
@@ -439,6 +454,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
   try {
     courseFiles = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/files?per_page=100`)
   } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
     if (error instanceof CanvasCourseImportError && (
       /HTTP (403|404) for \/api\/v1\/courses\/.+\/files/.test(error.message) ||
       /Canvas denied access to \/api\/v1\/courses\/.+\/files/.test(error.message)
@@ -448,6 +464,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       throw error
     }
   }
+  await onProgress({ stage: 'discovery', message: 'Module and file listings received.', completed: courseFiles.length })
   let resourceCount = 0
   const claimResource = (label) => {
     if (resourceCount >= maxResources) { skipped.push({ label, reason: `import limit (${maxResources})` }); return false }
@@ -455,6 +472,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     return true
   }
   const write = async (path, contents) => {
+    if (durable) return durable.write(path.slice(root.length + 1), contents)
     await mkdir(resolve(path, '..'), { recursive: true })
     await writeFile(path, contents)
   }
@@ -484,12 +502,16 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       const itemName = filename(detail.display_name || detail.filename || source.title || `file-${id}`)
       const extension = extname(itemName) || '.bin'
       const outputPath = pagePath(join(base, fileCategory(itemName)), position, itemName.replace(new RegExp(`${extension.replace('.', '\\.')}$`, 'i'), ''), `file-${id}`, extension)
-      const bytes = await api.downloadToFile(detail.url, outputPath, maxFileBytes)
+      await onProgress({ stage: 'download', message: 'Downloading file.', item: itemName })
+      const bytes = durable ? await durable.file(outputPath.slice(root.length + 1), { ...detail, id }) : await api.downloadToFile(detail.url, outputPath, maxFileBytes)
       const value = { id, name: itemName, relativePath: outputPath.slice(root.length + 1), bytes }
       downloadedFileIds.set(id, value)
+      await onProgress({ stage: 'download', message: 'File downloaded.', item: itemName, completed: downloadedFileIds.size })
       records.push({ kind: 'file', id, source, path: value.relativePath, bytes, mediaType: detail.content_type || null, canvasUrl: detail.url || null })
       return value
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
+      await onProgress({ stage: 'download', level: 'warning', message: 'File could not be downloaded; continuing with accessible material.', item: source.title || `Canvas file ${id}` })
       skipped.push({ label: source.title || `Canvas file ${id}`, reason: error.message })
       return null
     }
@@ -504,6 +526,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     // forever (a common pattern in Canvas navigation pages).
     importedPageSlugs.add(pageSlug)
     try {
+      await onProgress({ stage: 'download', message: 'Reading Canvas page.', item: title || pageSlug })
       const page = await api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/pages/${encodeURIComponent(pageSlug)}`)
       const pageTitle = page.title || title || 'Canvas page'
       const pageUrl = `${canvas.origin}/courses/${canvas.courseId}/pages/${encodeURIComponent(pageSlug)}`
@@ -516,6 +539,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       await indexAndFollowLinks({ title: pageTitle, pageUrl, body: page.body, outputPath, source, id: `page-${pageSlug}`, links })
       return outputPath
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       skipped.push({ label: title || 'Canvas page', reason: error.message })
       return null
     }
@@ -572,6 +596,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       await indexAndFollowLinks({ title, pageUrl: assignment.html_url || `${canvas.origin}/courses/${canvas.courseId}/assignments/${id}`, body: assignment.description, outputPath, source, id: `assignment-${id}`, links })
       return outputPath
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       skipped.push({ label: source.title || `Canvas assignment ${id}`, reason: error.message })
       return null
     }
@@ -593,6 +618,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       await indexAndFollowLinks({ title, pageUrl: discussion.html_url || `${canvas.origin}/courses/${canvas.courseId}/discussion_topics/${id}`, body: discussion.message, outputPath, source, id: `discussion-${id}`, links })
       return outputPath
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       skipped.push({ label: source.title || `Canvas discussion ${id}`, reason: error.message })
       return null
     }
@@ -625,10 +651,12 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
           records.push({ kind: 'quiz-questions', id: `quiz-${id}-questions`, source, path: questionsPath.slice(root.length + 1), quizId: id, count: questions.length })
         }
       } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
         skipped.push({ label: `${title} question bank`, reason: error.message })
       }
       return outputPath
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       skipped.push({ label: source.title || `Canvas quiz ${id}`, reason: error.message })
       return null
     }
@@ -668,6 +696,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       records.push({ kind: 'other', id: itemId, source, path: outputPath.slice(root.length + 1) })
       return outputPath
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       skipped.push({ label: source.title || item.type || 'Canvas item', reason: error.message })
       return null
     }
@@ -675,6 +704,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
 
   for (const module of selectedModules.sort((left, right) => number(left.position) - number(right.position))) {
     const moduleBase = join(root, 'modules', `${prefix(module.position)} ${safeSegment(module.name)}--module-${safeSegment(module.id)}`)
+    if (durable) module.items = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules/${encodeURIComponent(module.id)}/items?per_page=100`)
     const hierarchy = []
     for (const item of (Array.isArray(module.items) ? module.items : []).sort((left, right) => number(left.position) - number(right.position))) {
       const indent = Math.min(12, Math.max(0, number(item.indent)))
@@ -707,6 +737,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     try {
       return await api.getPaged(path)
     } catch (error) {
+      if (durable && (error?.checkpointYield || !/HTTP (403|404)\b/.test(String(error?.message)))) throw error
       // These endpoints are often deliberately restricted for students, while
       // module items remain readable. The private snapshot should still finish
       // and make the missing collection visible in its manifest.
@@ -737,6 +768,13 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     await importDiscussion({ discussionId: id, base: join(root, 'course-communications'), position: index + 1, source: { moduleId: null, moduleName: null, itemId: id, itemType: 'Course discussion', title: text(discussion.title, 300) }, initial: discussion })
   }
 
+  if (durable) {
+    const announcements = await optionalCourseCollection('Course announcements', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/discussion_topics?only_announcements=true&per_page=100`)
+    for (const [index, announcement] of announcements.entries()) {
+      await importDiscussion({ discussionId: announcement.id, base: join(root, 'course-announcements'), position: index + 1, source: { itemType: 'Announcement', title: announcement.title }, initial: announcement })
+    }
+  }
+
   // Lecturers often publish wiki pages through the Pages navigation without
   // adding them to a module. Enumerate that collection during a full archive;
   // importPage deduplicates anything already reached through modules or links.
@@ -772,6 +810,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     staleLocalResources,
     limits: { maxResources, maxFileBytes }
   }
+  if (durable) { await durable.finish(summary); return { ...summary, downloadedFiles: downloadedFileIds.size } }
   await writeFile(manifestPath, `${JSON.stringify(summary, null, 2)}\n`, 'utf8')
   await writeFile(join(root, 'README.md'), `# ${courseName}\n\nImported privately from Canvas on ${summary.importedAt.slice(0, 10)}.\n\n- Canvas course: ${canvas.courseUrl}\n- Modules included: ${selectedModules.length}${requestedModuleIds ? ' (chosen subset)' : ''}\n- Resources written: ${records.length}\n- Resources skipped: ${skipped.length}\n- Previous imported paths no longer found: ${staleLocalResources.length}\n\nThe snapshot includes the Canvas rich-text syllabus when the account can read it, plus separately uploaded course files (including syllabus/course-manual files), module material, standalone course Pages, accessible course-wide assignments, quizzes, discussions, and question banks where Canvas permits question access. Canvas pages are followed recursively when they link to another page in this same course. File links in rich-text records are downloaded when accessible; every HTTP(S) reference is compiled into a nearby \`link-index\` file and the hidden manifest. External sites are recorded, never crawled.\n\nThis folder is a source snapshot. Keep it local until the administrator confirms they are authorised to submit the materials for editorial review. The hidden \`.wicker-canvas-import.json\` file records exactly what was found. Re-run the importer into this same folder to refresh changed or newly published Canvas material. Paths no longer returned by Canvas are listed in that manifest for review; they are never deleted automatically.\n`, 'utf8')
 

package/write-confirmation.mjs

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+export const toolRequestContext = new AsyncLocalStorage()
+const writes = new Set('wicker_sign_out join_programme canvas_corpus_sync submit_answer set_mastery review_card add_to_deck create_flashcard review_flashcard resolve_mistake record_chapter_read save_academic_plan update_planning_objective set_course_visibility apply_changes save_calendar_link sync_calendar_link remove_calendar_link canvas_import_remote_course canvas_import_remote_course_set canvas_sync_control canvas_sync_course tutor_ask tutor_approve_action tutor_delete_conversation tutor_add_source tutor_remove_source tutor_forget_context tutor_confirm_update answer_study_diagnostic'.split(' '))
+export function requiresWriteConfirmation(name) {
+  return writes.has(name) || name.startsWith('admin_') && !/^(admin_status|admin_inventory_|admin_list_|admin_estimate_)/.test(name)
+}
+export function installWriteConfirmation(server, z) {
+  const register = server.tool.bind(server)
+  server.tool = (name, description, schema, handler) => {
+    const handle = handler
+    handler = (args, extra) => toolRequestContext.run({ tool: name, confirmed: args.confirmed === true }, () => handle(args, extra))
+    if (!requiresWriteConfirmation(name)) return register(name, description, schema, handler)
+    const dryRun = name === 'admin_sync_course_folder'
+    return register(name, `${description} Requires explicit student confirmation for this individual write; prior approvals do not authorise later writes.`, { ...schema, confirmed: dryRun ? z.literal(true).optional() : z.literal(true) }, (args, extra) => {
+      if (!(dryRun && args.dryRun !== false) && args.confirmed !== true) return { isError: true, content: [{ type: 'text', text: 'Show the exact change and obtain explicit confirmation before this write.' }] }
+      return handler(args, extra)
+    })
+  }
+}