@athanlab/mcp 0.0.0-stage → 0.1.0

package/dist/tools.js

@@ -0,0 +1,617 @@
+import { z } from 'zod';
+import { formatError, toAthanLabError, AthanLabError } from './api/errors.js';
+import { JOB_STATUSES, NUMBER_MODES, OUTPUT_FORMATS } from './api/types.js';
+import { ensureDir, sanitizeFilename, uniquePath, writeResponseToFile } from './files.js';
+import { redact } from './log.js';
+import { CONFIRM_CHARACTERS_THRESHOLD, CONFIRM_LINES_THRESHOLD, runScript } from './script.js';
+import { runSpeak, DEFAULT_SPEAK_TIMEOUT_SECONDS } from './speak.js';
+import { checkJobId, downloadJobAudio, getJob, jobOutcomeError, listJobs, quoteSpeech, stamp, summarizeJob, } from './speech.js';
+const MAX_PREVIEW_BYTES = 25 * 1024 * 1024;
+// ── Shared schemas ───────────────────────────────
+const voiceId = z.string().min(1).max(128)
+    .describe('A voice id from athanlab_list_voices. Leave it out to use the API default voice.');
+const jobId = z.string().regex(/^[0-9a-f]{32}$/, 'a job id is 32 lowercase hex characters')
+    .describe('The job id (32 lowercase hex characters) from athanlab_speak, athanlab_list_jobs or a timeout result.');
+const speechText = z.string().min(1).max(5000)
+    .describe('Burmese text to speak, 1–5,000 characters (UTF-16 units: an emoji counts 2). Write Burmese script, end sentences with ။ ! or ?. See the athanlab-writing-guide.');
+const numberMode = z.enum(NUMBER_MODES)
+    .describe('How digits are read: smart (default: Burmese digits as words, Latin digits as written), place (all digits as Burmese place words), digits (Burmese, one digit at a time — phone numbers), english (English number words), english_digits (English, one digit at a time).');
+const outputFormat = z.enum(OUTPUT_FORMATS);
+const filename = z.string().min(1).max(200)
+    .describe('Optional file name (no folders: only the last path segment is used, the extension is forced to the format). Written inside the server\'s output directory; never overwrites — an existing name gets a suffix.');
+const segmentOut = z.object({
+    index: z.number(),
+    start_seconds: z.number(),
+    end_seconds: z.number(),
+    characters: z.number(),
+});
+const timingOut = {
+    speech_start_seconds: z.number().nullable().describe('Where speech starts in the file (seconds); null until the API reports timing.'),
+    speech_end_seconds: z.number().nullable().describe('Where speech ends in the file (seconds); null until the API reports timing.'),
+    segments: z.array(segmentOut).nullable().describe('Timed spans of the audio; null until the API reports timing.'),
+};
+// Values the API owns (statuses, formats, sources) are plain strings in the
+// output schemas: the API may add values within v1, and a client validating
+// structuredContent must not reject a job because of one.
+const jobSummaryShape = {
+    job_id: z.string(),
+    status: z.string().describe('processing, succeeded, failed or cancelled.'),
+    progress: z.number().nullable(),
+    created_at: z.string(),
+    completed_at: z.string().nullable(),
+    voice_id: z.string().nullable(),
+    output_format: z.string(),
+    number_mode: z.string(),
+    characters: z.number(),
+    characters_charged: z.number(),
+    characters_refunded: z.number(),
+    audio: z.object({ format: z.string(), duration_seconds: z.number(), expires_at: z.string() }).nullable(),
+    ...timingOut,
+    error: z.object({ code: z.string(), message: z.string(), retryable: z.boolean() }).nullable(),
+    metadata: z.record(z.string(), z.string()),
+};
+const jobSummaryOut = z.object(jobSummaryShape);
+function speedShape(features) {
+    if (!features.speed)
+        return {};
+    const { min, max } = features.speed;
+    return {
+        speed: z.number().min(min).max(max).optional()
+            .describe(`Speaking pace, ${min}–${max} in steps of 0.01 (1 = normal). Pitch is preserved; the price does not change.`),
+    };
+}
+function replacementsShape(features) {
+    if (!features.replacements)
+        return {};
+    const limits = features.replacements;
+    return {
+        replacements: z.array(z.object({
+            from: z.string().min(1).max(limits.fromMaxLength).describe('Literal text as written in `text` (no regex).'),
+            to: z.string().max(limits.toMaxLength).describe('What to say instead (Burmese script). "" deletes the match.'),
+            case_sensitive: z.boolean().optional().describe('Default true; false folds ASCII A–Z only.'),
+        })).max(limits.maxRules).optional()
+            .describe(`Pronunciation rules applied only to what is spoken, e.g. [{"from": "AthanLab", "to": "အသံလက်ဘ်"}]. Up to ${limits.maxRules}. Billing stays on the length of text.`),
+    };
+}
+function scrub(value, secrets) {
+    return JSON.parse(redact(JSON.stringify(value), secrets));
+}
+/**
+ * notifications/progress for a client that sent a progressToken.
+ *
+ * MCP requires progress to increase with every notification, but a job can
+ * sit at the same progress for minutes (a single-piece job reports 0 until it
+ * finishes; a cold start takes over a minute) — and a client that keeps its
+ * request alive on progress must still hear from us on every poll. So a
+ * report that does not move progress goes out anyway as a heartbeat whose
+ * value creeps up by a shrinking step (n + k/(k+1)): always increasing, never
+ * reaching the next whole value. Callers report whole numbers.
+ */
+export function progressReporter(extra) {
+    const token = extra?._meta?.progressToken;
+    if (token === undefined || !extra)
+        return undefined;
+    let last = Number.NEGATIVE_INFINITY;
+    let base = 0;
+    let beats = 0;
+    return (progress, total, message) => {
+        let value;
+        if (progress > last) {
+            value = progress;
+            base = progress;
+            beats = 0;
+        }
+        else {
+            beats++;
+            value = base + beats / (beats + 1);
+            if (!(value > last))
+                return;
+        }
+        last = value;
+        void extra.sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken: token, progress: value, ...(total !== undefined ? { total } : {}), ...(message ? { message } : {}) },
+        }).catch(() => { });
+    };
+}
+function makeRunner(deps) {
+    return async function run(tool, fn) {
+        try {
+            const { text, structured, isError } = await fn();
+            return {
+                content: [{ type: 'text', text: redact(text, deps.secrets) }],
+                structuredContent: scrub(structured, deps.secrets),
+                ...(isError ? { isError: true } : {}),
+            };
+        }
+        catch (err) {
+            const e = toAthanLabError(err);
+            deps.ctx.logger.warn('tool call failed', { tool, code: e.code, status: e.status, request_id: e.requestId });
+            // No structuredContent on errors: clients validate any structuredContent
+            // against the tool's outputSchema, error or not. The second block is the
+            // same error as JSON, for agents that branch on fields.
+            return {
+                isError: true,
+                content: [
+                    { type: 'text', text: redact(formatError(e), deps.secrets) },
+                    { type: 'text', text: redact(JSON.stringify({ error: e.toJSON() }), deps.secrets) },
+                ],
+            };
+        }
+    };
+}
+function speakInput(args, features, fallbackFormat) {
+    return {
+        text: args.text,
+        voice_id: args.voice_id,
+        output_format: args.output_format ?? fallbackFormat,
+        number_mode: args.number_mode,
+        ...(features.speed && args.speed !== undefined ? { speed: args.speed } : {}),
+        ...(features.replacements && args.replacements ? { replacements: args.replacements } : {}),
+        metadata: { client: 'athanlab-mcp' },
+    };
+}
+function normalizeSpeak(result) {
+    if (result.status === 'succeeded') {
+        return {
+            status: 'succeeded',
+            path: result.path,
+            job_id: result.job_id,
+            output_format: result.output_format,
+            duration_seconds: result.duration_seconds,
+            speech_start_seconds: result.speech_start_seconds,
+            speech_end_seconds: result.speech_end_seconds,
+            segments: result.segments,
+            characters_charged: result.characters_charged,
+            voice_id: result.voice_id,
+            bytes: result.bytes,
+            replayed: result.replayed,
+            progress: 1,
+            message: null,
+        };
+    }
+    return {
+        status: 'processing',
+        path: null,
+        job_id: result.job_id,
+        output_format: result.output_format,
+        duration_seconds: null,
+        speech_start_seconds: null,
+        speech_end_seconds: null,
+        segments: null,
+        characters_charged: result.characters_charged,
+        voice_id: null,
+        bytes: null,
+        replayed: null,
+        progress: result.progress,
+        message: result.message,
+    };
+}
+function jobLine(s) {
+    const audio = s.audio ? `, ${s.audio.duration_seconds.toFixed(1)} s ${s.audio.format}` : '';
+    const error = s.error ? `, ${s.error.code}` : '';
+    return `${s.job_id}  ${s.status}${s.status === 'processing' && s.progress !== null ? ` ${Math.round(s.progress * 100)}%` : ''}  ${s.characters} chars${audio}${error}  (${s.created_at})`;
+}
+// ── Registration ─────────────────────────────────
+export function registerTools(server, deps) {
+    const { ctx } = deps;
+    const { features, config } = ctx;
+    const run = makeRunner(deps);
+    const outputDirNote = `Files are written to ${config.outputDir}.`;
+    server.registerTool('athanlab_list_voices', {
+        title: 'List AthanLab voices',
+        description: 'Lists the voices this API key can speak with: AthanLab\'s official Burmese voices (source "athanlab") and the voices in the account\'s own library (source "user"), plus default_voice_id — the voice used when a speech call names none. Call this first to pick a voice_id for athanlab_speak / athanlab_speak_script. Free; read-only.',
+        inputSchema: {},
+        outputSchema: {
+            voices: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                category: z.string(),
+                source: z.string().describe('athanlab (official) or user (your library).'),
+                is_default: z.boolean(),
+            })),
+            default_voice_id: z.string().nullable(),
+        },
+        annotations: { title: 'List voices', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async () => run('athanlab_list_voices', async () => {
+        const { data } = await ctx.client.json('/voices');
+        const voices = data.data.map(v => ({ id: v.id, name: v.name, category: v.category, source: v.source, is_default: v.is_default }));
+        const text = voices.length
+            ? `${voices.length} voice(s):\n${voices.map(v => `- ${v.id} — ${v.name} (${v.category}, ${v.source})${v.is_default ? ' [default]' : ''}`).join('\n')}${data.default_voice_id ? '' : '\nThe API default voice is unavailable right now: pass voice_id explicitly.'}`
+            : 'No voices are available to this key.';
+        return { text, structured: { voices, default_voice_id: data.default_voice_id } };
+    }));
+    server.registerTool('athanlab_preview_voice', {
+        title: 'Preview an AthanLab voice',
+        description: `Returns a signed URL of a short sample of one voice (valid about an hour; no API key needed to play it), so the user can hear a voice before choosing it. With save: true the sample is also downloaded into the output directory. Free. ${outputDirNote}`,
+        inputSchema: {
+            voice_id: z.string().min(1).max(128).describe('A voice id from athanlab_list_voices.'),
+            save: z.boolean().default(false).describe('Also download the sample into the output directory.'),
+        },
+        outputSchema: {
+            voice_id: z.string(),
+            name: z.string(),
+            url: z.string(),
+            expires_in: z.number(),
+            path: z.string().nullable(),
+            bytes: z.number().nullable(),
+        },
+        annotations: { title: 'Preview voice', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => run('athanlab_preview_voice', async () => {
+        const { data } = await ctx.client.json(`/voices/${encodeURIComponent(args.voice_id)}/preview`);
+        let savedPath = null;
+        let bytes = null;
+        if (args.save) {
+            const url = new URL(data.url);
+            if (url.protocol !== 'https:' && !(url.protocol === 'http:' && /^(localhost|127\.0\.0\.1)$/.test(url.hostname))) {
+                throw AthanLabError.client('invalid_response', 'The sample URL is not https; not downloading it.');
+            }
+            // A signed storage URL: fetched WITHOUT the API key, which only ever goes to the API.
+            const fetchImpl = ctx.fetchImpl ?? fetch;
+            const res = await fetchImpl(url.toString(), { signal: AbortSignal.timeout(120_000) });
+            if (!res.ok) {
+                throw new AthanLabError({ code: 'download_failed', message: `The sample download answered HTTP ${res.status}.`, source: 'network', retryable: res.status >= 500 });
+            }
+            const type = res.headers.get('content-type') ?? '';
+            const fromPath = url.pathname.toLowerCase().match(/\.(wav|mp3)$/)?.[1];
+            const ext = /mpeg|mp3/.test(type) ? 'mp3' : /wav/.test(type) ? 'wav' : fromPath ?? 'wav';
+            await ensureDir(config.outputDir);
+            const name = sanitizeFilename(`voice-preview-${args.voice_id}`, ext, 'voice-preview');
+            savedPath = await uniquePath(config.outputDir, name, stamp(ctx.clock.now()));
+            bytes = await writeResponseToFile(res, savedPath, MAX_PREVIEW_BYTES);
+        }
+        const text = `Sample of ${data.name} (${data.id}): ${data.url}\nThe link expires in ${Math.round(data.expires_in / 60)} minutes.${savedPath ? `\nSaved to ${savedPath}` : ''}`;
+        return { text, structured: { voice_id: data.id, name: data.name, url: data.url, expires_in: data.expires_in, path: savedPath, bytes } };
+    }));
+    server.registerTool('athanlab_quote', {
+        title: 'Quote speech (free dry run)',
+        description: 'Validates a text exactly as athanlab_speak would and returns what it would cost — without creating a job or charging anything. Returns characters (the exact charge: UTF-16 length), dispatches (how many pieces the text is split into), spendable (the account\'s balance now) and sufficient. Use it before long texts, or to check that a text will be accepted (it surfaces unspeakable_text, text_too_long and voice_not_found errors for free).',
+        inputSchema: {
+            text: speechText,
+            voice_id: voiceId.optional(),
+            number_mode: numberMode.optional(),
+            ...speedShape(features),
+            ...replacementsShape(features),
+        },
+        outputSchema: {
+            characters: z.number(),
+            dispatches: z.number(),
+            spendable: z.number(),
+            sufficient: z.boolean(),
+            max_chars_per_call: z.number().nullable(),
+            within_max_chars_per_call: z.boolean(),
+            replacements: z.unknown().optional(),
+        },
+        annotations: { title: 'Quote', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => run('athanlab_quote', async () => {
+        ctx.client.assertKey();
+        const input = speakInput(args, features, 'mp3');
+        const quote = await quoteSpeech(ctx, { ...input, metadata: undefined });
+        const cap = config.maxCharsPerCall;
+        const within = cap === null || quote.characters <= cap;
+        const structured = {
+            characters: quote.characters,
+            dispatches: quote.dispatches,
+            spendable: quote.spendable,
+            sufficient: quote.sufficient,
+            max_chars_per_call: cap,
+            within_max_chars_per_call: within,
+        };
+        if (quote.replacements !== undefined)
+            structured.replacements = quote.replacements;
+        const text = `Would cost ${quote.characters} characters (${quote.dispatches} piece${quote.dispatches === 1 ? '' : 's'}). The account can spend ${quote.spendable}: ${quote.sufficient ? 'enough' : 'NOT enough'}.${within ? '' : ` Above this server's ATHANLAB_MAX_CHARS_PER_CALL (${cap}): athanlab_speak would refuse it.`} Nothing was charged.`;
+        return { text, structured };
+    }));
+    server.registerTool('athanlab_speak', {
+        title: 'Speak Burmese text',
+        description: `Turns one Burmese text (up to 5,000 characters) into an audio file and returns its path. COSTS the text's length in characters from the account balance (failed jobs are refunded). Creates an asynchronous job, waits for it (usually seconds to a few minutes) and downloads the audio. If it does not finish within timeout_seconds the job keeps running: the result has status "processing" and the job_id — then use athanlab_get_job / athanlab_download_audio and do NOT call athanlab_speak again for the same text (that would pay twice). For dialogue or many lines, use athanlab_speak_script. Read the athanlab-writing-guide first. ${outputDirNote}`,
+        inputSchema: {
+            text: speechText,
+            voice_id: voiceId.optional(),
+            output_format: outputFormat.default('wav').describe('wav (default; exact, for editing) or mp3 (smaller).'),
+            number_mode: numberMode.optional(),
+            ...speedShape(features),
+            ...replacementsShape(features),
+            filename: filename.optional(),
+            timeout_seconds: z.number().int().min(30).max(3600).default(DEFAULT_SPEAK_TIMEOUT_SECONDS)
+                .describe('How long to wait for the job before returning its job_id instead (default 900).'),
+            idempotency_key: z.string().regex(/^[\x20-\x7E]{1,255}$/).optional()
+                .describe('Only to retry a call that failed with an unknown outcome (network error): pass the idempotency_key from that error so the same text is never charged twice. Leave it out otherwise.'),
+        },
+        outputSchema: {
+            status: z.enum(['succeeded', 'processing']),
+            path: z.string().nullable().describe('Absolute path of the audio file; null while processing.'),
+            job_id: z.string(),
+            output_format: outputFormat,
+            duration_seconds: z.number().nullable(),
+            ...timingOut,
+            characters_charged: z.number().nullable(),
+            voice_id: z.string().nullable(),
+            bytes: z.number().nullable(),
+            replayed: z.boolean().nullable(),
+            progress: z.number().nullable(),
+            message: z.string().nullable(),
+        },
+        annotations: { title: 'Speak (costs characters)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args, extra) => run('athanlab_speak', async () => {
+        const progress = progressReporter(extra);
+        const started = ctx.clock.now();
+        // One notification per poll (a heartbeat when progress did not move), with the time waited so far.
+        const onProgress = progress
+            ? (job) => {
+                const percent = Math.round((job.progress ?? 0) * 100);
+                const seconds = Math.round((ctx.clock.now() - started) / 1000);
+                progress(percent, 100, `Job ${job.id}: ${job.status}${job.status === 'processing' && percent > 0 ? ` ${percent}%` : ''}, ${seconds} s`);
+            }
+            : undefined;
+        const result = await runSpeak(ctx, speakInput(args, features, 'wav'), {
+            filename: args.filename,
+            timeoutSeconds: args.timeout_seconds,
+            idempotencyKey: args.idempotency_key,
+            signal: extra?.signal,
+            ...(onProgress ? { onProgress } : {}),
+        });
+        const structured = normalizeSpeak(result);
+        const text = result.status === 'succeeded'
+            ? `Saved ${result.path} (${result.duration_seconds.toFixed(2)} s ${result.output_format}, ${result.characters_charged} characters charged${result.replayed ? ', replayed — not charged again' : ''}). Job ${result.job_id}.`
+            : result.message;
+        return { text, structured };
+    }));
+    server.registerTool('athanlab_speak_script', {
+        title: 'Speak a multi-line script',
+        description: `Generates a dialogue or script line by line: one audio file per line (named from the line's id or speaker and its position) plus manifest.json with every line on one timeline — consecutive lines of the same speaker are separated by gaps.sentence seconds, a speaker change by gaps.turn — and optionally combined.wav (combine: true, WAV only). Each line's voice is its voice_id, else voices[speaker], else the default voice. COSTS the characters of every new line. It quotes all lines first (free); above ${CONFIRM_CHARACTERS_THRESHOLD.toLocaleString('en-US')} characters or ${CONFIRM_LINES_THRESHOLD} lines it returns the quote WITHOUT creating anything unless confirm is true — show the quote to the user, then call again with confirm: true. RESUMABLE: re-running the same call (same lines and out_subdir) skips finished lines and follows running jobs without paying again; changing one line's text regenerates only that line; a line whose earlier audio is gone (deleted after 30 days) is quoted and charged again like a new line. Run ONE call per out_subdir at a time: a second call on the same folder while one is running returns script_running and does nothing. Stops creating jobs on plan_required, insufficient_characters or key_budget_exceeded and reports which lines are done. ${outputDirNote}`,
+        inputSchema: {
+            lines: z.array(z.object({
+                id: z.string().min(1).max(64).optional().describe('Your label for the line (used in its file name).'),
+                speaker: z.string().min(1).max(100).optional().describe('Who speaks it; maps to a voice through `voices`.'),
+                text: z.string().min(1).max(5000).describe('One sentence-sized line of Burmese text.'),
+                voice_id: voiceId.optional(),
+            })).min(1).max(200).describe('The lines, in order (1–200).'),
+            voices: z.record(z.string(), z.string().min(1).max(128)).optional()
+                .describe('speaker → voice_id, e.g. {"narrator": "athanlab-default-female-v1"}.'),
+            gaps: z.object({
+                sentence: z.number().min(0).max(10).default(0.4).describe('Seconds between consecutive lines of the same speaker (default 0.4).'),
+                turn: z.number().min(0).max(10).default(0.55).describe('Seconds at a speaker change (default 0.55).'),
+            }).optional(),
+            output_format: outputFormat.default('wav').describe('wav (default) or mp3. combine needs wav.'),
+            number_mode: numberMode.optional(),
+            combine: z.boolean().default(false).describe('Also write combined.wav: every line joined on the timeline with silent gaps (WAV only).'),
+            confirm: z.boolean().default(false).describe(`Required above ${CONFIRM_CHARACTERS_THRESHOLD.toLocaleString('en-US')} characters or ${CONFIRM_LINES_THRESHOLD} lines; otherwise only the quote is returned.`),
+            out_subdir: z.string().min(1).max(100).optional()
+                .describe('Folder (inside the output directory) for this script. Reuse it to resume or to regenerate changed lines; defaults to a name derived from the script.'),
+            timeout_seconds: z.number().int().min(60).max(3600).default(900)
+                .describe('Stop waiting after this long (default 900); running jobs continue and a re-run picks them up.'),
+        },
+        outputSchema: {
+            status: z.enum(['completed', 'partial', 'stopped', 'timed_out', 'confirmation_required']),
+            directory: z.string(),
+            manifest_path: z.string().nullable(),
+            combined_path: z.string().nullable(),
+            quote: z.object({
+                characters: z.number(),
+                lines: z.number(),
+                dispatches: z.number(),
+                spendable: z.number().nullable(),
+                sufficient: z.boolean().nullable(),
+                lines_skipped: z.number(),
+                lines_resumed: z.number(),
+            }).nullable(),
+            lines_total: z.number(),
+            lines_succeeded: z.number(),
+            lines_skipped: z.number(),
+            lines_failed: z.number(),
+            lines_pending: z.number(),
+            characters_charged: z.number(),
+            total_duration_seconds: z.number().nullable(),
+            timeline_complete: z.boolean(),
+            stopped: z.record(z.string(), z.unknown()).nullable(),
+            combine_error: z.record(z.string(), z.unknown()).nullable(),
+            used_batch: z.boolean(),
+            message: z.string(),
+            lines: z.array(z.object({
+                index: z.number(),
+                id: z.string().nullable(),
+                speaker: z.string().nullable(),
+                status: z.string(),
+                file: z.string().nullable(),
+                job_id: z.string().nullable(),
+                duration_seconds: z.number().nullable(),
+                start_seconds: z.number().nullable(),
+                end_seconds: z.number().nullable(),
+                error: z.object({ code: z.string(), message: z.string() }).nullable(),
+            })),
+        },
+        annotations: { title: 'Speak script (costs characters)', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args, extra) => run('athanlab_speak_script', async () => {
+        const progress = progressReporter(extra);
+        const input = {
+            lines: args.lines,
+            voices: args.voices,
+            gaps: args.gaps,
+            output_format: args.output_format,
+            number_mode: args.number_mode,
+            combine: args.combine,
+            confirm: args.confirm,
+            out_subdir: args.out_subdir,
+            timeout_seconds: args.timeout_seconds,
+        };
+        const result = await runScript(ctx, input, {
+            signal: extra?.signal,
+            ...(progress ? { onProgress: (done, total, message) => progress(done, total, message) } : {}),
+        });
+        return { text: result.message, structured: result };
+    }));
+    server.registerTool('athanlab_get_job', {
+        title: 'Get a speech job',
+        description: 'Returns one speech job: status (processing, succeeded, failed, cancelled), progress, characters charged and refunded, audio duration and expiry, and the failure reason. Use it to check on a job returned by a timed-out athanlab_speak. Free; read-only.',
+        inputSchema: { job_id: jobId },
+        outputSchema: jobSummaryShape,
+        annotations: { title: 'Get job', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => run('athanlab_get_job', async () => {
+        ctx.client.assertKey();
+        const summary = summarizeJob(await getJob(ctx, args.job_id));
+        const next = summary.status === 'succeeded' && summary.audio
+            ? ' Save it with athanlab_download_audio.'
+            : summary.status === 'processing' ? ' Check again in a few seconds.' : '';
+        return { text: `${jobLine(summary)}.${next}`, structured: summary };
+    }));
+    server.registerTool('athanlab_list_jobs', {
+        title: 'List speech jobs',
+        description: 'Lists the account\'s speech jobs, newest first (all keys of the account share one history). Filter by status; page with cursor (the previous page\'s next_cursor). Use status "processing" to find jobs still running. Free; read-only.',
+        inputSchema: {
+            status: z.enum(JOB_STATUSES).optional().describe('Only jobs in this status.'),
+            limit: z.number().int().min(1).max(100).optional().describe('Jobs per page, 1–100 (default 20).'),
+            cursor: z.string().min(1).max(512).optional().describe('next_cursor from the previous page, unchanged.'),
+        },
+        outputSchema: {
+            jobs: z.array(jobSummaryOut),
+            has_more: z.boolean(),
+            next_cursor: z.string().nullable(),
+        },
+        annotations: { title: 'List jobs', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => run('athanlab_list_jobs', async () => {
+        ctx.client.assertKey();
+        const list = await listJobs(ctx, { status: args.status, limit: args.limit, cursor: args.cursor });
+        const jobs = list.data.map(summarizeJob);
+        const text = jobs.length
+            ? `${jobs.length} job(s)${list.has_more ? ' (more: pass next_cursor)' : ''}:\n${jobs.map(jobLine).join('\n')}`
+            : 'No jobs.';
+        return { text, structured: { jobs, has_more: list.has_more, next_cursor: list.next_cursor } };
+    }));
+    server.registerTool('athanlab_cancel_job', {
+        title: 'Cancel a speech job',
+        description: 'Stops a job that is still processing. The part already generated stays charged; the rest is refunded (characters_refunded). Cancelling an already cancelled job returns it again; a finished job cannot be cancelled (job_finished). Works even when the key is read-only.',
+        inputSchema: { job_id: jobId },
+        outputSchema: jobSummaryShape,
+        annotations: { title: 'Cancel job', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => run('athanlab_cancel_job', async () => {
+        checkJobId(args.job_id);
+        const res = await ctx.client.json(`/speech/${args.job_id}/cancel`, { method: 'POST' });
+        const summary = summarizeJob(res.data);
+        return {
+            text: `Job ${summary.job_id} ${summary.status}: ${summary.characters_refunded} of ${summary.characters_charged} characters refunded.`,
+            structured: summary,
+        };
+    }));
+    server.registerTool('athanlab_download_audio', {
+        title: 'Download a job\'s audio',
+        description: `Saves the audio of a succeeded job to a file and returns its path — for jobs from a timed-out athanlab_speak, from athanlab_list_jobs, or to get the other format (a job made as wav can be downloaded as mp3 and vice versa). Free (the job was paid when created). Audio is kept 30 days after the job was created. ${outputDirNote}`,
+        inputSchema: {
+            job_id: jobId,
+            format: outputFormat.optional().describe('wav or mp3; defaults to the job\'s own format.'),
+            filename: filename.optional(),
+        },
+        outputSchema: {
+            path: z.string(),
+            job_id: z.string(),
+            format: z.string(),
+            bytes: z.number(),
+            duration_seconds: z.number().nullable(),
+            ...timingOut,
+        },
+        annotations: { title: 'Download audio', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args, extra) => run('athanlab_download_audio', async () => {
+        ctx.client.assertKey();
+        const job = await getJob(ctx, args.job_id);
+        if (job.status === 'processing') {
+            throw new AthanLabError({
+                code: 'job_not_finished',
+                message: `Job ${job.id} is still processing (${Math.round((job.progress ?? 0) * 100)}%).`,
+                source: 'client',
+                retryable: true,
+                jobId: job.id,
+            });
+        }
+        if (job.status !== 'succeeded')
+            throw jobOutcomeError(job);
+        if (!job.audio) {
+            throw new AthanLabError({ code: 'audio_expired', message: `The audio of job ${job.id} is no longer available (kept 30 days).`, source: 'client', jobId: job.id });
+        }
+        const format = args.format ?? job.input.output_format;
+        await ensureDir(config.outputDir);
+        const name = sanitizeFilename(args.filename, format, `athanlab-${job.id}`);
+        const target = await uniquePath(config.outputDir, name, stamp(ctx.clock.now()));
+        let bytes;
+        try {
+            bytes = await downloadJobAudio(ctx, job.id, format, target, extra?.signal);
+        }
+        catch (err) {
+            const e = toAthanLabError(err);
+            e.jobId = job.id;
+            throw e;
+        }
+        const summary = summarizeJob(job);
+        return {
+            text: `Saved ${target} (${format}, ${bytes} bytes${job.audio ? `, ${job.audio.duration_seconds.toFixed(2)} s` : ''}).`,
+            structured: {
+                path: target,
+                job_id: job.id,
+                format,
+                bytes,
+                duration_seconds: job.audio?.duration_seconds ?? null,
+                speech_start_seconds: summary.speech_start_seconds,
+                speech_end_seconds: summary.speech_end_seconds,
+                segments: summary.segments,
+            },
+        };
+    }));
+    server.registerTool('athanlab_usage', {
+        title: 'AthanLab balance and limits',
+        description: 'Returns the account\'s character balance and API limits: plan, whether this key may create jobs (entitled — false means read-only: Max plan or founder access needed), the monthly allowance and when it resets, Athan Tokens, spendable (monthly remaining + tokens), jobs running now against max_concurrent_jobs, and this key\'s monthly budget. Free; read-only.',
+        inputSchema: {},
+        outputSchema: {
+            plan: z.string(),
+            entitled: z.boolean(),
+            upgrade_url: z.string().nullable(),
+            monthly: z.object({ limit: z.number(), used: z.number(), remaining: z.number(), resets_at: z.string().nullable() }),
+            tokens: z.object({ balance: z.number() }),
+            spendable: z.number(),
+            active_jobs: z.number(),
+            max_concurrent_jobs: z.number(),
+            job_slots_available: z.number(),
+            key: z.object({
+                id: z.string(),
+                monthly_char_budget: z.number().nullable(),
+                used_this_month: z.number().nullable(),
+                remaining: z.number().nullable(),
+                resets_at: z.string().nullable(),
+            }),
+        },
+        annotations: { title: 'Usage', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async () => run('athanlab_usage', async () => {
+        const { data } = await ctx.client.json('/usage');
+        const slots = Math.max(0, data.max_concurrent_jobs - data.active_jobs);
+        const budget = data.key.monthly_char_budget !== null
+            ? ` This key's budget: ${data.key.remaining} of ${data.key.monthly_char_budget} left this month.`
+            : '';
+        const text = `Plan ${data.plan}${data.entitled ? '' : ' — READ-ONLY: creating jobs needs Max (or founder access)'}. Spendable: ${data.spendable} characters (monthly ${data.monthly.remaining} of ${data.monthly.limit}${data.monthly.resets_at ? `, resets ${data.monthly.resets_at}` : ''}; tokens ${data.tokens.balance}). Jobs running: ${data.active_jobs}/${data.max_concurrent_jobs}.${budget}`;
+        return {
+            text,
+            structured: {
+                // Field by field: the output schema is strict, and the API may add fields.
+                plan: data.plan,
+                entitled: data.entitled,
+                upgrade_url: data.upgrade_url ?? null,
+                monthly: {
+                    limit: data.monthly.limit,
+                    used: data.monthly.used,
+                    remaining: data.monthly.remaining,
+                    resets_at: data.monthly.resets_at ?? null,
+                },
+                tokens: { balance: data.tokens.balance },
+                spendable: data.spendable,
+                active_jobs: data.active_jobs,
+                max_concurrent_jobs: data.max_concurrent_jobs,
+                job_slots_available: slots,
+                key: {
+                    id: data.key.id,
+                    monthly_char_budget: data.key.monthly_char_budget ?? null,
+                    used_this_month: data.key.used_this_month ?? null,
+                    remaining: data.key.remaining ?? null,
+                    resets_at: data.key.resets_at ?? null,
+                },
+            },
+        };
+    }));
+}
+//# sourceMappingURL=tools.js.map