@lingochunk/mcp 0.3.1 → 0.8.0

package/dist/tools.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { ApiError } from "./client.js";
+import { GUIDES, GUIDE_TOPICS } from "./generated/guides.js";
 /** card.v1 kinds (POST /cards with format=card.v1). Mirrors the server's
  *  CardKindV1 / CARD_V1_BLUR_KINDS in lingochunk_shared.models.public_v1. */
 const CARD_V1_KINDS = new Set([
@@ -121,10 +122,12 @@ function sanitise(value) {
 function params(obj) {
     return obj;
 }
-const EXPORT_POLL_INTERVAL_MS = 2_000;
-const EXPORT_POLL_BUDGET_MS = 60_000;
+// Shared cadence for the async-job pollers (deck export and language apply):
+// both start a job then poll its status to completion.
+const POLL_INTERVAL_MS = 2_000;
+const POLL_BUDGET_MS = 60_000;
 // Fallback wait when a 429 carries no Retry-After.
-const EXPORT_RETRY_FALLBACK_MS = 5_000;
+const POLL_RETRY_FALLBACK_MS = 5_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -145,7 +148,7 @@ async function triggerExport(client, deckId, deadline) {
                 return false;
             const wait = err.retryAfter && err.retryAfter > 0
                 ? err.retryAfter * 1000
-                : EXPORT_RETRY_FALLBACK_MS;
+                : POLL_RETRY_FALLBACK_MS;
             await sleep(Math.min(wait, remaining));
         }
     }
@@ -156,7 +159,7 @@ async function triggerExport(client, deckId, deadline) {
  *  (not an abort). A 400 (e.g. a deck with no linked submission) or 403 bubbles
  *  up as an ApiError for errorResult. */
 async function exportAndPoll(client, deckId) {
-    const deadline = Date.now() + EXPORT_POLL_BUDGET_MS;
+    const deadline = Date.now() + POLL_BUDGET_MS;
     if (!(await triggerExport(client, deckId, deadline))) {
         return jsonResult({
             status: "pending",
@@ -190,10 +193,87 @@ async function exportAndPoll(client, deckId) {
                     "re-trigger if a later call reports 'failed' or 'none'.",
             });
         }
-        await sleep(EXPORT_POLL_INTERVAL_MS);
+        await sleep(POLL_INTERVAL_MS);
     }
 }
-export function registerTools(server, client, config) {
+/** POST the draft commit, absorbing a 429 with a Retry-After backoff (capped by
+ *  the remaining budget) rather than aborting. Returns the apply job id, or null
+ *  when the budget runs out mid-backoff. A 400/403/404/409 bubbles up. */
+async function commitDraft(client, submissionId, language, deadline) {
+    for (;;) {
+        try {
+            const { job_id } = await client.commitTranslationDraft(submissionId, language);
+            return job_id;
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.status !== 429)
+                throw err;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return null;
+            const wait = err.retryAfter && err.retryAfter > 0
+                ? err.retryAfter * 1000
+                : POLL_RETRY_FALLBACK_MS;
+            await sleep(Math.min(wait, remaining));
+        }
+    }
+}
+/** Commit a language draft, then poll the apply job for up to ~60s. On success
+ *  resolve the new sibling's submission id via list_languages. A 409 (the draft
+ *  is missing sentence positions) or 403 bubbles up as an ApiError. */
+async function commitAndPoll(client, submissionId, language) {
+    const deadline = Date.now() + POLL_BUDGET_MS;
+    const jobId = await commitDraft(client, submissionId, language, deadline);
+    if (jobId === null) {
+        return jsonResult({
+            status: "processing",
+            language,
+            message: "Rate limited before the commit could start; call commit_language " +
+                "again shortly (a duplicate commit converges safely).",
+        });
+    }
+    for (;;) {
+        const job = await client.getJob(jobId);
+        if (job.status === "completed") {
+            let siblingId;
+            try {
+                const langs = await client.listSubmissionLanguages(submissionId);
+                siblingId = langs.languages.find((l) => l.language === language)?.submission_id;
+            }
+            catch {
+                // The apply succeeded; failing to resolve the sibling id is non-fatal.
+            }
+            return jsonResult({
+                status: "completed",
+                language,
+                submission_id: siblingId,
+                job_id: jobId,
+            });
+        }
+        if (job.status === "failed") {
+            return jsonResult({
+                status: "failed",
+                language,
+                job_id: jobId,
+                error: job.error ?? null,
+                message: "The apply job failed. Check the draft with list_languages, then " +
+                    "call commit_language again to retry.",
+            });
+        }
+        if (Date.now() >= deadline) {
+            return jsonResult({
+                status: "processing",
+                language,
+                job_id: jobId,
+                message: "Still applying. Call list_languages shortly to see the new " +
+                    "sibling's status; do not re-commit unless it never appears.",
+            });
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+export function registerTools(server, client, config, mode = "local") {
+    const local = mode === "local";
     server.registerTool("get_vocabulary", {
         title: "Get vocabulary",
         description: "List the user's vocabulary, aggregated per word with FSRS maturity " +
@@ -257,8 +337,8 @@ export function registerTools(server, client, config) {
         title: "List library",
         description: "List the user's ready-to-study episodes (their own submissions plus " +
             "collections they follow), newest first. Cursor-paginated. Use the " +
-            "returned submission ids with get_transcript / get_audio_url / " +
-            "get_audio_clip.",
+            "returned submission ids with get_transcript / get_audio_url" +
+            (local ? " / get_audio_clip." : "."),
         inputSchema: {
             limit: z.number().int().min(1).max(200).optional(),
             cursor: z
@@ -272,8 +352,11 @@ export function registerTools(server, client, config) {
         description: "Fetch a submission's transcript: timestamped sentences with " +
             "translations. Sliceable by sentence-position range (from_sentence/" +
             "to_sentence) or time range in seconds (from_time/to_time) so you can " +
-            "pull an excerpt instead of a whole episode. transcript_state tells you " +
-            "if it is ready, still processing, or unavailable.",
+            "pull an excerpt instead of a whole episode. Each sentence also carries " +
+            "a stable 'sentence_id' and its 'display' string, which the annotation " +
+            "tools use to anchor creator notes (offsets are Unicode code points into " +
+            "'display'). transcript_state tells you if it is ready, still " +
+            "processing, or unavailable.",
         inputSchema: {
             submission_id: z.string().min(1).describe("The submission id."),
             from_sentence: z.number().int().min(1).optional(),
@@ -285,8 +368,11 @@ export function registerTools(server, client, config) {
     server.registerTool("get_audio_url", {
         title: "Get audio URL",
         description: "Get a short-lived presigned URL to a submission's full native audio " +
-            "(supports HTTP Range). Use for streaming; for a durable snippet to " +
-            "embed in a lesson, use get_audio_clip instead.",
+            "(supports HTTP Range). " +
+            (local
+                ? "Use for streaming; for a durable snippet to embed in a lesson, " +
+                    "use get_audio_clip instead."
+                : "Use it for streaming or to give the user a link they can play."),
         inputSchema: {
             submission_id: z.string().min(1).describe("The submission id."),
         },
@@ -324,39 +410,85 @@ export function registerTools(server, client, config) {
         }
         return runJson(() => client.searchExamples(params(args)));
     });
-    server.registerTool("get_audio_clip", {
-        title: "Get audio clip",
-        description: "Cut a native-audio snippet [start, end] (seconds, max 60s) from a " +
-            "submission and SAVE IT to a local file, returning the file path. Use " +
-            "these small clips to embed audio in a self-contained HTML lesson (e.g. " +
-            "as a data URI). Rate limited.",
+    server.registerTool("whats_possible", {
+        title: "What you can do with LingoChunk",
+        description: "The quick tour of this connection: the menu of what the user can " +
+            "ask for (talk through an episode, vocabulary checks, lessons, " +
+            "courses, flashcards + Anki export, creator notes, extra languages, " +
+            "publishing to an audience), one example prompt per area. CALL THIS " +
+            "when the user asks what they can do with LingoChunk, what is " +
+            "possible, how to get started, or for help in general - then answer " +
+            "SHORT (a line per area) and offer to go deeper on the area they " +
+            "pick (the full craft guides live behind get_authoring_guide). " +
+            "Read-only; needs no scope.",
+        inputSchema: {},
+    }, () => Promise.resolve({
+        content: [{ type: "text", text: GUIDES.overview.body }],
+    }));
+    server.registerTool("get_authoring_guide", {
+        title: "Get an authoring guide",
+        description: "Fetch the craft guide for a LingoChunk authoring task, so your output " +
+            "matches the app's own quality instead of rendering flat. CALL THIS " +
+            "FIRST - before you compose - the first time in a conversation you " +
+            "build any of: a lesson (topic 'lesson', before save_lesson), a " +
+            "multi-lesson course ('course', before create_course), flashcards " +
+            "('cards', before add_card), creator notes ('annotations', before " +
+            "create_annotation), a translation / added language ('add-language', " +
+            "before add_language or the draft flow), or a guided discussion " +
+            "('discuss'). Topic 'overview' is the what-can-I-do tour (same " +
+            "content as whats_possible). Returns the guide markdown: anchoring " +
+            "rules, the block/kind menu, and worked recipes. Read-only; needs " +
+            "no scope.",
         inputSchema: {
-            submission_id: z.string().min(1).describe("The submission id."),
-            start: z.number().min(0).describe("Clip start in seconds."),
-            end: z.number().gt(0).describe("Clip end in seconds (start < end)."),
+            topic: z
+                .enum(GUIDE_TOPICS)
+                .describe("Which authoring task: 'lesson' (lesson.v1 documents), 'course' " +
+                "(a multi-lesson series), 'cards' (card.v1 flashcards), " +
+                "'annotations' (creator notes), 'add-language' (translations / " +
+                "leveled same-language decks), 'discuss' (guided episode " +
+                "discussion) or 'overview' (the what-can-I-do tour)."),
         },
-    }, async ({ submission_id, start, end }) => runResult(async () => {
-        // The API enforces these too; checking here gives a precise message and
-        // avoids a wasted request.
-        if (!(start < end)) {
-            throw new Error("get_audio_clip needs start < end.");
-        }
-        if (end - start > 60) {
-            throw new Error("get_audio_clip cannot exceed 60 seconds (end - start).");
-        }
-        const clip = await client.getAudioClip(submission_id, start, end);
-        // 0o700: the clip dir holds the user's own study audio, so keep it
-        // readable only by them (mode applies to dirs this call creates).
-        await fs.mkdir(config.clipDir, { recursive: true, mode: 0o700 });
-        const filename = `clip-${sanitise(submission_id)}-${start}-${end}${extensionFor(clip.contentType)}`;
-        const filePath = path.join(config.clipDir, filename);
-        await fs.writeFile(filePath, clip.data);
-        return jsonResult({
-            path: filePath,
-            media_type: clip.contentType,
-            size_bytes: clip.data.byteLength,
-        });
+    }, ({ topic }) => Promise.resolve({
+        content: [{ type: "text", text: GUIDES[topic].body }],
     }));
+    // Remote mode never registers this tool: it saves to the *server's* disk,
+    // which the remote caller cannot read, and unmetered writes on a shared
+    // host would be an abuse vector besides.
+    if (local) {
+        server.registerTool("get_audio_clip", {
+            title: "Get audio clip",
+            description: "Cut a native-audio snippet [start, end] (seconds, max 60s) from a " +
+                "submission and SAVE IT to a local file, returning the file path. Use " +
+                "these small clips to embed audio in a self-contained HTML lesson (e.g. " +
+                "as a data URI). Rate limited.",
+            inputSchema: {
+                submission_id: z.string().min(1).describe("The submission id."),
+                start: z.number().min(0).describe("Clip start in seconds."),
+                end: z.number().gt(0).describe("Clip end in seconds (start < end)."),
+            },
+        }, async ({ submission_id, start, end }) => runResult(async () => {
+            // The API enforces these too; checking here gives a precise message and
+            // avoids a wasted request.
+            if (!(start < end)) {
+                throw new Error("get_audio_clip needs start < end.");
+            }
+            if (end - start > 60) {
+                throw new Error("get_audio_clip cannot exceed 60 seconds (end - start).");
+            }
+            const clip = await client.getAudioClip(submission_id, start, end);
+            // 0o700: the clip dir holds the user's own study audio, so keep it
+            // readable only by them (mode applies to dirs this call creates).
+            await fs.mkdir(config.clipDir, { recursive: true, mode: 0o700 });
+            const filename = `clip-${sanitise(submission_id)}-${start}-${end}${extensionFor(clip.contentType)}`;
+            const filePath = path.join(config.clipDir, filename);
+            await fs.writeFile(filePath, clip.data);
+            return jsonResult({
+                path: filePath,
+                media_type: clip.contentType,
+                size_bytes: clip.data.byteLength,
+            });
+        }));
+    }
     // --- Write tools (phase 3) ----------------------------------------------
     server.registerTool("list_decks", {
         title: "List decks",
@@ -385,8 +517,9 @@ export function registerTools(server, client, config) {
             "Responses carry a problems[] list of degradations (e.g. " +
             "focus_span_no_timings) - fix and resend to clear them; resending the " +
             "same headword updates the card in place (created=false), preserving " +
-            "review history. Read the lingochunk-cards skill for per-kind guidance " +
-            "and quality rules before batch-creating cards. LEGACY kinds still " +
+            "review history. Before composing cards, call get_authoring_guide with " +
+            "topic='cards' (once per conversation) for per-kind guidance and " +
+            "quality rules. LEGACY kinds still " +
             "work: kind=vocab adds a word ALREADY in the user's vocabulary by " +
             "lemma (409 code=ambiguous_lemma: pass submission_id or pos); " +
             "kind=custom is a flat front/back card (409 code=duplicate_card is " +
@@ -591,9 +724,11 @@ export function registerTools(server, client, config) {
     server.registerTool("save_lesson", {
         title: "Save a lesson",
         description: "Save a lesson to the user's private LingoChunk library (up to 100 " +
-            "lessons, private by default). PREFERRED: pass `document`, a " +
-            "structured lesson.v1 JSON document (see the lingochunk-lesson " +
-            "skill) - the app renders it natively in a Lessons tab on the source " +
+            "lessons, private by default). Before composing a lesson, call " +
+            "get_authoring_guide with topic='lesson' (once per conversation) for " +
+            "the scaffold, anchoring rules and recipes. PREFERRED: pass `document`, " +
+            "a structured lesson.v1 JSON document - the app renders it natively in " +
+            "a Lessons tab on the source " +
             "episode, with real audio playback, live vocabulary state, links " +
             "into the Words/Listen tabs and a built-in Ask AI tutor; the " +
             "response's app_url is where it opens, and unknown_lemmas lists any " +
@@ -603,8 +738,14 @@ export function registerTools(server, client, config) {
             "sentence references (400 with a stable code). LEGACY: pass `html` " +
             "(a complete self-contained HTML file, 10 MB max, title + language " +
             "required) to store an opaque artefact opened via a short-lived " +
-            "view URL. Exactly one of document/html. Requires the lessons:write " +
-            "scope.",
+            "view URL. Exactly one of document/html. To catch every problem in one " +
+            "pass, call validate_lesson FIRST and fix what it reports, then " +
+            "save_lesson. File a lesson into a course (from create_course) with " +
+            "course_id + optional sequence. Creators: visibility:'public' " +
+            "publishes the lesson to everyone who can view the source episode " +
+            "(e.g. followers of a collection it belongs to); it requires owning " +
+            "the episode and works for documents only. Requires the " +
+            "lessons:write scope.",
         inputSchema: {
             title: z
                 .string()
@@ -633,8 +774,87 @@ export function registerTools(server, client, config) {
                 .array(z.string())
                 .optional()
                 .describe("Optional provenance: the episode ids the lesson was built from."),
+            course_id: z
+                .string()
+                .max(36)
+                .optional()
+                .describe("File this lesson under a course you own (from create_course)."),
+            sequence: z
+                .number()
+                .int()
+                .optional()
+                .describe("Ordering position within the course (ties break by created_at). " +
+                "Requires course_id."),
+            visibility: z
+                .enum(["private", "public"])
+                .optional()
+                .describe("'private' (default, owner only) or 'public' (publish: visible " +
+                "to everyone who can view the source episode, e.g. via a " +
+                "public collection). Documents only, and only on an episode " +
+                "you own (403 publish_not_submission_owner otherwise)."),
+        },
+    }, async (args) => {
+        // Mirror the server's request-shape rule client-side: sequence only means
+        // something inside a course, so a bare sequence is a 422 on the server.
+        if (args.sequence !== undefined && args.course_id === undefined) {
+            return errorResult(new Error("save_lesson 'sequence' requires 'course_id'."));
+        }
+        return runJson(() => client.createLesson(args));
+    });
+    server.registerTool("validate_lesson", {
+        title: "Validate a lesson document",
+        description: "Dry-run validate a lesson.v1 `document` WITHOUT saving it, and get " +
+            "EVERY problem back at once instead of one save -> 400 -> fix cycle at " +
+            "a time. Call it before save_lesson (repeatedly, as you fix) and only " +
+            "save once it returns valid:true. Returns {valid, errors, " +
+            "unknown_lemmas}: each error carries a stable `code` and a `loc` " +
+            "(dotted path into the document) for schema faults, or `positions` / " +
+            "`audio_windows` for reference faults (the same codes save_lesson " +
+            "raises: unknown_positions, position_outside_slice, " +
+            "audio_outside_episode, audio_outside_slice, dialogue_mismatch, " +
+            "order_mismatch). `unknown_lemmas` is advisory - glossary lemmas the " +
+            "episode does not know; they do NOT make the document invalid. Stores " +
+            "nothing and spends no lesson-cap budget. Requires the lessons:write " +
+            "scope.",
+        inputSchema: {
+            document: z
+                .record(z.unknown())
+                .describe("A lesson.v1 document (same shape as save_lesson's document)."),
         },
-    }, async (args) => runJson(() => client.createLesson(args)));
+    }, async ({ document }) => runJson(() => client.validateLesson({ document })));
+    server.registerTool("list_lessons", {
+        title: "List lessons",
+        description: "List the user's saved lessons, newest first: id, title, language, " +
+            "format (lesson.v1 or html), source submission, created_at, and its " +
+            "course_id / sequence / course_title when the lesson is filed under a " +
+            "course (so you can group without a second call). Cursor-paginated. " +
+            "Use it to find a lesson id for get_lesson / delete_lesson, or to see " +
+            "what already exists before saving another. Requires the lessons:write " +
+            "scope.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z
+                .string()
+                .optional()
+                .describe("Opaque cursor from a previous page's next_cursor."),
+        },
+    }, async (args) => runJson(() => client.listLessons(params(args))));
+    server.registerTool("get_lesson", {
+        title: "Get a lesson document",
+        description: "Read back a saved lesson.v1 document by id (ids from list_lessons " +
+            "or save_lesson's response). This closes the revision loop: lessons " +
+            "are immutable, so to revise one, get_lesson -> edit the document -> " +
+            "save_lesson (a NEW id) -> delete_lesson the superseded one. 404 for " +
+            "legacy HTML lessons - they have no document. Requires the " +
+            "lessons:write scope.",
+        inputSchema: {
+            lesson_id: z
+                .string()
+                .min(1)
+                .max(36)
+                .describe("The lesson to read (id from list_lessons/save_lesson)."),
+        },
+    }, async ({ lesson_id }) => runJson(() => client.getLessonDocument(lesson_id)));
     server.registerTool("delete_lesson", {
         title: "Delete a lesson",
         description: "Permanently delete ONE of the user's saved lessons (the stored " +
@@ -657,5 +877,364 @@ export function registerTools(server, client, config) {
         await client.deleteLesson(lesson_id);
         return { deleted: true, lesson_id };
     }));
+    server.registerTool("create_course", {
+        title: "Create a course",
+        description: "Create a course: a named, ordered series to file lessons under " +
+            "(e.g. 'lesson 3 of 8'). Returns {id, title, description, " +
+            "lesson_count, created_at}; pass the id as save_lesson's course_id " +
+            "(with an optional sequence) to place lessons in it. Courses are " +
+            "authored via the API only (no in-app course editor). Requires the " +
+            "lessons:write scope.",
+        inputSchema: {
+            title: z
+                .string()
+                .min(1)
+                .max(255)
+                .describe("Course title (1-255 characters)."),
+            description: z
+                .string()
+                .max(2000)
+                .optional()
+                .describe("Optional longer description of the course."),
+        },
+    }, async (args) => runJson(() => client.createCourse(args)));
+    server.registerTool("list_courses", {
+        title: "List courses",
+        description: "List the user's courses, newest first, each with its lesson_count. " +
+            "Use it to find a course_id for save_lesson (or delete_course), or to " +
+            "see what series already exist before creating another. Requires the " +
+            "lessons:write scope.",
+    }, async () => runJson(() => client.listCourses()));
+    server.registerTool("delete_course", {
+        title: "Delete a course",
+        description: "Delete ONE of the user's courses by id. This un-groups its lessons " +
+            "(their course_id is set NULL) but NEVER deletes them - authored " +
+            "lessons always survive. Destructive only to the grouping, and " +
+            "idempotent. 404 means the id does not exist or is not the user's. " +
+            "Requires the lessons:write scope.",
+        annotations: { destructiveHint: true, idempotentHint: true },
+        inputSchema: {
+            course_id: z
+                .string()
+                .min(1)
+                .max(36)
+                .describe("The course to delete (id from create_course/list_courses)."),
+        },
+    }, async ({ course_id }) => runJson(async () => {
+        await client.deleteCourse(course_id);
+        return { deleted: true, course_id };
+    }));
+    // --- Language / translation tools (phase 4) -----------------------------
+    server.registerTool("list_languages", {
+        title: "List submission languages",
+        description: "List a submission's target languages and how to add more. Returns " +
+            "'languages' (the fan-out group so far, each with its own " +
+            "submission_id, status and is_primary flag), 'available_targets' " +
+            "(ordinary languages you can hand to add_language for the server-side " +
+            "Groq fan-out), 'simplify_targets' (leveled same-language codes like " +
+            "'de-a2' = German audio glossed in simpler A2 German, which ONLY the " +
+            "draft flow accepts) and 'drafts' (in-progress agent translations with " +
+            "sentences_drafted / sentence_count). Use it to choose a target and to " +
+            "poll a target's status after add_language or commit_language. " +
+            "Requires the content:read scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+        },
+    }, async ({ submission_id }) => runJson(() => client.listSubmissionLanguages(submission_id)));
+    server.registerTool("add_language", {
+        title: "Add languages (server-side fan-out)",
+        description: "Fan a submission out into extra ORDINARY target languages " +
+            "server-side (Groq translation; spends none of your tokens). Pass " +
+            "1-10 language codes from list_languages' available_targets; returns a " +
+            "job per accepted language and a 'skipped' list (e.g. the source " +
+            "language, an existing sibling, or a leveled code with reason " +
+            "'agent_only_target'). Poll list_languages until each new sibling's " +
+            "status is 'ready'. Leveled same-language codes (en-a2, de-b1, ...) " +
+            "are NOT accepted here: translate and commit them yourself via " +
+            "get_translation_source + put_language_translations + commit_language. " +
+            "Requires the translations:write scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            languages: z
+                .array(z
+                .string()
+                .min(1)
+                .transform((v) => v.trim().toLowerCase()))
+                .min(1)
+                .max(10)
+                .describe("1-10 ordinary target codes from available_targets " +
+                "(normalised to lowercase)."),
+        },
+    }, async ({ submission_id, languages }) => runJson(() => client.addLanguages(submission_id, languages)));
+    server.registerTool("get_translation_source", {
+        title: "Get translation source",
+        description: "Page through the primary submission's sentences to translate " +
+            "yourself. Each sentence gives the source 'text', a " +
+            "'pivot_translation' (the whole sentence in the pivot language) and " +
+            "'tokens' (surface, lemma, pos and a 'pivot_meaning' that FIXES each " +
+            "word's sense in context). THE CONTRACT you must honour when you " +
+            "translate: produce exactly one meaning per token, in the same order, " +
+            "same length as 'tokens'; render the sense the 'pivot_meaning' fixes " +
+            "(do not re-interpret the word); PUNCT and INTJ tokens map to \"\"; " +
+            "proper nouns stay as the name; never copy the pivot or source word " +
+            "verbatim as its meaning. Before drafting, call get_authoring_guide " +
+            "with topic='add-language' (once per conversation) for the full " +
+            "per-level rules (ordinary target vs leveled same-language). " +
+            "Page with 'from_position' (0-based) until 'next_from_position' is " +
+            "null. Only the READY primary of a group is a valid source. Requires " +
+            "the content:read scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            from_position: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("0-based sentence position to start from (default 0)."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Sentences per page (max 100)."),
+        },
+    }, async ({ submission_id, ...rest }) => runJson(() => client.getTranslationSource(submission_id, params(rest))));
+    server.registerTool("put_language_translations", {
+        title: "Put draft translations",
+        description: "Upload a batch of your draft sentences for one target or leveled " +
+            "language (1-100 per call; page with get_translation_source and PUT " +
+            "25-50 at a time). Each sentence carries its 0-based 'position', a " +
+            "whole-sentence 'translation' (or null to leave the sentence back " +
+            "blank - hide-on-fail for leveled decks) and 'meanings' (one per " +
+            "source token, SAME ORDER and EXACT length as that sentence's " +
+            "tokens). The server validates each sentence against the real " +
+            "transcript and returns a 'rejected' list (meanings_length_mismatch " +
+            "with expected/got, unknown position, oversize strings) while " +
+            "ACCEPTING the rest - fix the rejected ones and PUT them again. " +
+            "'sentences_drafted' / 'sentence_count' track completeness. Set " +
+            "'generator' to the model producing the translations, for provenance. " +
+            "Keep a local tally of covered positions: commit_language needs every " +
+            "one. Requires the translations:write scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            language: z
+                .string()
+                .min(1)
+                .transform((v) => v.trim().toLowerCase())
+                .describe("The target or leveled code being drafted (normalised to " +
+                "lowercase)."),
+            generator: z
+                .string()
+                .max(100)
+                .optional()
+                .describe("Model producing the translations, recorded for provenance."),
+            sentences: z
+                .array(z.object({
+                position: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .describe("0-based sentence position from get_translation_source."),
+                translation: z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe("Whole-sentence text, or null for no sentence back."),
+                meanings: z
+                    .array(z.string())
+                    .describe("One meaning per source token, same order and exact length " +
+                    "as the sentence's tokens."),
+            }))
+                .min(1)
+                .max(100)
+                .describe("1-100 draft sentences."),
+        },
+    }, async ({ submission_id, language, generator, sentences }) => runJson(() => client.putTranslations(submission_id, language, {
+        generator,
+        sentences: sentences.map((s) => ({
+            position: s.position,
+            translation: s.translation ?? null,
+            meanings: s.meanings,
+        })),
+    })));
+    server.registerTool("commit_language", {
+        title: "Commit a language draft",
+        description: "Validate a complete draft for one language and apply it, minting a " +
+            "new sibling submission (its own deck). The draft must cover EVERY " +
+            "sentence position of the primary: a 409 lists the missing count and " +
+            "first missing positions - PUT those with put_language_translations, " +
+            "then commit again. This starts the apply job and polls it for up to " +
+            "~60s: it returns {status:'completed', submission_id} with the new " +
+            "sibling's id when ready, {status:'processing'} (call list_languages " +
+            "shortly to check) if it is still applying, or {status:'failed'} to " +
+            "retry. A duplicate commit while a job is in flight converges safely. " +
+            "Requires the translations:write scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            language: z
+                .string()
+                .min(1)
+                .transform((v) => v.trim().toLowerCase())
+                .describe("The target or leveled code to commit (normalised to lowercase)."),
+        },
+    }, async ({ submission_id, language }) => runResult(() => commitAndPoll(client, submission_id, language)));
+    server.registerTool("discard_language_draft", {
+        title: "Discard a language draft",
+        description: "Permanently delete the in-progress draft sentences for one language " +
+            "on a submission (NOT any committed sibling deck - those are " +
+            "untouched). Destructive: only discard a draft the user has asked to " +
+            "abandon or restart. Returns {deleted_sentences}. Requires the " +
+            "translations:write scope.",
+        annotations: { destructiveHint: true, idempotentHint: true },
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            language: z
+                .string()
+                .min(1)
+                .transform((v) => v.trim().toLowerCase())
+                .describe("The target or leveled code whose draft to delete (normalised to " +
+                "lowercase)."),
+        },
+    }, async ({ submission_id, language }) => runJson(() => client.deleteTranslationDraft(submission_id, language)));
+    // --- Creator annotation tools (phase 5) ---------------------------------
+    server.registerTool("list_annotations", {
+        title: "List creator annotations",
+        description: "List the creator annotations already on one of your own episodes. " +
+            "Each is a markdown note anchored to a transcript sentence span (or a " +
+            "whole sentence). Returns 'annotations' (ordered by sentence then " +
+            "char_start; each with its id, sentence_id, char_start/char_end, the " +
+            "server's 'selected_text' snapshot, the 'note' and a 'stale' flag), " +
+            "plus 'count' and 'max_annotations' (the per-episode cap). BUDGET " +
+            "against count vs max_annotations, and read this FIRST so you do not " +
+            "re-annotate an expression that already has a note. 'stale: true' means " +
+            "the sentence was edited after the note was made, so the app hides its " +
+            "tint until it is re-anchored - replace or delete a stale note rather " +
+            "than leaving it. Requires the content:read scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+        },
+    }, async ({ submission_id }) => runJson(() => client.listAnnotations(submission_id)));
+    server.registerTool("create_annotation", {
+        title: "Create a creator annotation",
+        description: "Add ONE creator annotation to your own episode: a markdown note " +
+            "tinted onto a transcript sentence span (owners see the tint + note " +
+            "sheet; followers get a forward-only note card). Anchor it with " +
+            "'sentence_id' (from get_transcript, stable across edits) plus " +
+            "'char_start'/'char_end' - UNICODE CODE-POINT offsets into that " +
+            "sentence's 'display' string (Python string semantics: count code " +
+            "points, so an astral character like an emoji is 1, NOT the 2 that " +
+            "JavaScript's string.length / indexOf would report). Offsets are " +
+            "BOTH-OR-NEITHER: give both for a span, or omit both for a " +
+            "whole-sentence note; char_start must be < char_end. The server " +
+            "snapshots and returns 'selected_text' = display[char_start:char_end] - " +
+            "VERIFY it equals the span you intended; if it does not, your offsets " +
+            "were off (usually a UTF-16 vs code-point miscount), so delete_annotation " +
+            "and create it again with corrected offsets. 'note' is markdown (1-5000 " +
+            "chars), rendered natively in a bottom sheet - keep it to ~4 short " +
+            "lines. Leave start_time/end_time unset - the server derives the " +
+            "span's audio times from the transcript, so the note sheet's Play and " +
+            "the card clip work without them. The episode has a cap (see " +
+            "list_annotations' max_annotations). " +
+            "Before annotating, call get_authoring_guide with topic='annotations' " +
+            "(once per conversation) for what is worth a note and the note format. " +
+            "Requires the annotations:write scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            sentence_id: z
+                .number()
+                .int()
+                .describe("The sentence's stable id from get_transcript (NOT its position)."),
+            char_start: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Code-point offset into the sentence's 'display' where the span " +
+                "starts (omit together with char_end for a whole-sentence note)."),
+            char_end: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Code-point offset where the span ends (exclusive); must be > " +
+                "char_start."),
+            note: z
+                .string()
+                .min(1)
+                .max(5000)
+                .describe("The markdown note (1-5000 chars; keep it to ~4 short lines)."),
+            start_time: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Optional audio-span start (s); usually left unset."),
+            end_time: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Optional audio-span end (s); usually left unset."),
+        },
+    }, async ({ submission_id, sentence_id, char_start, char_end, note, start_time, end_time, }) => {
+        // Mirror the server's both-or-neither + ordering rules so the message is
+        // precise and no request is wasted.
+        if ((char_start === undefined) !== (char_end === undefined)) {
+            return errorResult(new Error("create_annotation needs char_start and char_end TOGETHER (a span), " +
+                "or NEITHER (a whole-sentence note)."));
+        }
+        if (char_start !== undefined &&
+            char_end !== undefined &&
+            !(char_start < char_end)) {
+            return errorResult(new Error("create_annotation needs char_start < char_end."));
+        }
+        return runJson(() => client.createAnnotation(submission_id, {
+            sentence_id,
+            char_start,
+            char_end,
+            note,
+            start_time,
+            end_time,
+        }));
+    });
+    server.registerTool("update_annotation", {
+        title: "Update a creator annotation",
+        description: "Replace the markdown note on one existing annotation; its anchor and " +
+            "span stay put. Use it to fix or reword a note without moving it; to " +
+            "re-anchor a span you must delete_annotation and create it again. " +
+            "Returns the updated annotation (staleness recomputed). 404 means the " +
+            "annotation does not exist or is not on this episode. Requires the " +
+            "annotations:write scope.",
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            annotation_id: z
+                .number()
+                .int()
+                .describe("The annotation to update (id from list_annotations)."),
+            note: z
+                .string()
+                .min(1)
+                .max(5000)
+                .describe("The replacement markdown note (1-5000 chars)."),
+        },
+    }, async ({ submission_id, annotation_id, note }) => runJson(() => client.updateAnnotation(submission_id, annotation_id, note)));
+    server.registerTool("delete_annotation", {
+        title: "Delete a creator annotation",
+        description: "Permanently delete ONE creator annotation from your episode (the tint " +
+            "and its note disappear; any follower note card stops being generated). " +
+            "Destructive and not undoable: delete only an annotation the user asked " +
+            "to remove, a stale one you are replacing, or one whose 'selected_text' " +
+            "did not match the span you intended (then create it again with " +
+            "corrected offsets). Returns {deleted, annotation_id}. 404 means the id " +
+            "does not exist or is not on this episode. Requires the " +
+            "annotations:write scope.",
+        annotations: { destructiveHint: true, idempotentHint: true },
+        inputSchema: {
+            submission_id: z.string().min(1).describe("The submission id."),
+            annotation_id: z
+                .number()
+                .int()
+                .describe("The annotation to delete (id from list_annotations)."),
+        },
+    }, async ({ submission_id, annotation_id }) => runJson(() => client.deleteAnnotation(submission_id, annotation_id)));
 }
 //# sourceMappingURL=tools.js.map