corent-mcp 0.6.0 → 0.8.0

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * Shared Corent MCP server definition — the 10 tools, used by both the
+ * Shared Corent MCP server definition — the tools and prompts, used by both the
  * stdio entrypoint (index.ts, for local `npx` use) and the hosted HTTP
  * entrypoint (http.ts). Keeping the tools in one place means the two
  * transports can never drift apart.
@@ -16,8 +16,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { MEDIA_WIDGET_HTML } from "./widget-html.js";
+import { registerPrompts } from "./prompts.js";
 export const DEFAULT_API_URL = "https://api.corent.tech";
-export const SERVER_VERSION = "0.6.0";
+export const SERVER_VERSION = "0.8.0";
+// Transport resilience, matching the two SDKs: a 429 or 5xx is retried with
+// backoff, but ONLY on calls that carry an Idempotency-Key (or are GETs), so a
+// retry can never buy a second generation.
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 500;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // --- MCP Apps (SEP-1865): the media tools render an inline widget in hosts
 // that support it (claude.ai web/desktop, others). Hosts without the extension
 // ignore the _meta and fall back to plain text results, so this is additive.
@@ -29,6 +36,19 @@ const WIDGET_TOOL_META = {
     ui: { resourceUri: WIDGET_URI },
     "ui/resourceUri": WIDGET_URI,
 };
+/**
+ * Per-tool _meta. ChatGPT's Apps SDK reads two plain status strings from a
+ * tool's _meta and shows them while the call runs and once it lands
+ * ("openai/toolInvocation/invoking" / "invoked"); every other host ignores
+ * unknown _meta keys. Media tools also carry the MCP Apps widget pointer.
+ */
+function toolMeta(invoking, invoked, widget = false) {
+    return {
+        "openai/toolInvocation/invoking": invoking,
+        "openai/toolInvocation/invoked": invoked,
+        ...(widget ? WIDGET_TOOL_META : {}),
+    };
+}
 // Generated media lives on Supabase storage; the logo and any brand assets on
 // corent.tech. Everything else stays blocked by the host's CSP.
 const WIDGET_CSP = {
@@ -80,6 +100,16 @@ function errorCode(err) {
 export function createCorentServer(config = {}) {
     const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
     const apiKey = config.apiKey;
+    /**
+     * A fresh Idempotency-Key for one money-spending call. The MCP used to send
+     * none at all, so any retry -- the agent's, the host's, or a user clicking
+     * again -- bought a second generation at full price (parity audit
+     * 2026-08-30). The API keys replays off (account, key), so the same key
+     * returns the ORIGINAL job instead of generating twice.
+     */
+    function idempotencyKey() {
+        return globalThis.crypto?.randomUUID?.() ?? `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
     async function corent(path, init) {
         // Key is enforced here (at call time) rather than at startup, so the server
         // can advertise its tools to catalogs/agents without a key configured.
@@ -88,19 +118,40 @@ export function createCorentServer(config = {}) {
                 message: "No Corent credentials. On claude.ai or other remote MCP clients, reconnect the Corent connector and approve access (OAuth). For local/stdio use, set CORENT_API_KEY in your MCP client config. Keys: https://corent.tech/dashboard/api-keys",
             });
         }
-        const res = await fetch(`${apiUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-                ...init?.headers,
-            },
-        });
-        const body = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            throw new CorentApiError(res.status, body.detail ?? body);
+        const headers = {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            ...(init?.headers ?? {}),
+        };
+        // Retrying is only safe when the call cannot be charged twice: a GET, or a
+        // POST carrying an Idempotency-Key (the API replays the original job for a
+        // repeated key). A POST without one is sent exactly once, forever.
+        const method = (init?.method ?? "GET").toUpperCase();
+        const replaySafe = method === "GET" || Boolean(headers["Idempotency-Key"]);
+        const maxAttempts = replaySafe ? MAX_RETRIES : 1;
+        let lastErr;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0)
+                await sleep(RETRY_BASE_MS * 2 ** (attempt - 1));
+            let res;
+            try {
+                res = await fetch(`${apiUrl}${path}`, { ...init, headers });
+            }
+            catch (err) {
+                // Transport failure: on a replay-safe call the same key returns the
+                // original job, so retrying cannot double-charge.
+                lastErr = err;
+                continue;
+            }
+            const body = await res.json().catch(() => ({}));
+            if (res.ok)
+                return body;
+            const retriable = res.status === 429 || (res.status >= 500 && res.status !== 501);
+            lastErr = new CorentApiError(res.status, body.detail ?? body);
+            if (!retriable)
+                throw lastErr;
         }
-        return body;
+        throw lastErr;
     }
     /** Success: typed structuredContent plus a text fallback for older clients. */
     function ok(data) {
@@ -159,7 +210,13 @@ export function createCorentServer(config = {}) {
     // yet) -- must be nullable, not just optional, or the SDK's output validator
     // throws on the normal poll-loop response.
     const mediaMeta = z
-        .object({ model: z.string().nullable().optional(), cost_cents: z.number().nullable().optional() })
+        .object({
+        model: z.string().nullable().optional(),
+        cost_cents: z.number().nullable().optional(),
+        seed: z.number().nullable().optional(),
+        unsupported_options: z.array(z.string()).nullable().optional(),
+        has_audio: z.boolean().nullable().optional(),
+    })
         .passthrough();
     const imageOutput = {
         id: z.string().optional(),
@@ -167,50 +224,128 @@ export function createCorentServer(config = {}) {
         images: z.array(z.object({ url: z.string() }).passthrough()).optional(),
         meta: mediaMeta.optional(),
     };
+    // meta carries two honesty fields worth surfacing to an agent: the seed
+    // that was actually used (so a render can be repeated) and the settings the
+    // chosen model could NOT honour (so an ignored knob never reads as applied).
     const jobOutput = {
         id: z.string().optional(),
         status: z.string().optional(),
         images: z.array(z.object({ url: z.string() }).passthrough()).optional(),
         videos: z.array(z.object({ url: z.string() }).passthrough()).optional(),
+        // Speech jobs answer with `audio` (routers/jobs.py). It was missing from
+        // this schema, so a polled speech job validated as a result with no
+        // deliverable in it (parity audit 2026-08-30).
+        audio: z.array(z.object({ url: z.string() }).passthrough()).optional(),
+        progress_percent: z.number().nullable().optional(),
         meta: mediaMeta.optional(),
         error: z.string().optional(),
     };
+    const batchOutput = {
+        batch_id: z.string().optional(),
+        status: z.string().optional(),
+        jobs: z.array(z.object({ id: z.string().optional() }).passthrough()).optional(),
+        counts: z.object({}).passthrough().optional(),
+        error: z.string().optional(),
+    };
+    // Shared with generate_image and the image batch items, so the two can never
+    // drift apart on which shapes and styles are reachable.
+    const IMAGE_ASPECTS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"];
+    const IMAGE_STYLES = ["photorealistic", "artistic", "anime", "logo", "text_focused", "cinematic"];
+    const TIERS = ["air", "lite", "premium", "pro", "max_pro"];
     server.registerTool("generate_image", {
         title: "Generate image",
-        _meta: WIDGET_TOOL_META,
-        description: "Generate an image from a text prompt. Returns a permanent public URL. Synchronous: typically completes in 2-20 seconds. Costs a few cents, billed to the Corent account. Failed generations are never billed.",
+        _meta: toolMeta("Generating image", "Image ready", true),
+        description: "Generate an image from a text prompt. Returns a permanent public URL. Synchronous, usually 2-20 seconds. Costs a few cents (premium ~7c); failed generations are never billed. Takes reference_image_urls to keep a face, character or product consistent (tier premium or up).",
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
-                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .enum(TIERS)
                 .optional()
                 .describe("Quality tier: air=cheapest (best value, not the quickest), lite=everyday, premium=production, pro=advanced, max_pro=maximum fidelity (flagship models). Omit for a sensible default."),
             model: z
                 .string()
                 .optional()
-                .describe("Direct model access: pin an exact model by name (list_models shows the menu). Bypasses Corent's routing -- never substituted, flat cost-plus price. Mutually exclusive with tier; prefer tier unless the user named a specific model."),
+                .describe('Direct model access: pin an exact model by name, e.g. "corent-flux-schnell" (list_models shows the menu; every name there is spelled corent-*). Bypasses Corent\'s routing -- never substituted, flat cost-plus price. Mutually exclusive with tier; prefer tier unless the user named a specific model.'),
             style: z
-                .enum(["photorealistic", "artistic", "anime", "logo", "text_focused"])
+                .enum(IMAGE_STYLES)
                 .optional()
                 .describe("Optional content style hint"),
-            aspect_ratio: z.enum(["1:1", "16:9", "9:16", "4:3", "3:4"]).default("1:1"),
+            aspect_ratio: z.enum(IMAGE_ASPECTS).default("1:1"),
+            n: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe("How many versions to render, 1 to 10. Each is a REAL render at the normal price, so n=4 " +
+                "costs four images; confirm with the user before spending on more than a couple. They come " +
+                "back together and meta.cost_cents is the total."),
+            seed: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Reproducibility. The same seed with the same prompt and model gives the same image, so use " +
+                "it to re-render a picture the user liked and change one thing. The seed that was used " +
+                "comes back in meta.seed even when you did not pass one."),
+            negative_prompt: z.string().optional().describe('What must NOT appear, e.g. "text, watermark".'),
+            source_image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("Image-to-image: start from this picture rather than from scratch. Pair with `strength`. " +
+                "Different from reference_image_urls, which pins an identity across scenes."),
+            strength: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("How far to travel from source_image_url. 0 keeps it, 1 ignores it."),
+            output_format: z.enum(["png", "jpeg", "webp"]).optional().describe("Delivered file type."),
+            transparent: z
+                .boolean()
+                .optional()
+                .describe("Transparent background, for logos and product cutouts. Forces png."),
+            width: z.number().int().min(256).max(4096).optional().describe("Explicit pixel width; pass with height."),
+            height: z.number().int().min(256).max(4096).optional().describe("Explicit pixel height; pass with width."),
+            enhance_prompt: z
+                .boolean()
+                .optional()
+                .describe("Corent rewrites the prompt before dispatch to get a better render. Pass false when the user " +
+                "has carefully worded their own prompt and wants it sent verbatim."),
+            reference_image_urls: z
+                .array(z.string().url())
+                .min(1)
+                .max(4)
+                .optional()
+                .describe("1 to 4 public https image URLs that keep a CHARACTER, FACE, or PRODUCT consistent across " +
+                "generations. The prompt is applied as an EDIT of these references, so use it whenever the " +
+                "user wants the same person/object again in a new scene, a product placed somewhere, or a " +
+                "series that has to match. Served only by edit-capable models, which sit at premium and up: " +
+                "pass tier premium/pro/max_pro (or omit tier), never air or lite. Omit entirely for plain " +
+                "text-to-image."),
         },
         outputSchema: imageOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, tier, model, style, aspect_ratio }) => corent("/v1/images/generate", {
+    }, wrap(async (args) => corent("/v1/images/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, model, style, aspect_ratio }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
     server.registerTool("generate_video", {
         title: "Generate video",
-        _meta: WIDGET_TOOL_META,
-        description: "Start generating a video from a text prompt (optionally animating a source image). Asynchronous: returns a job id immediately; poll get_job until status is 'completed'. Video costs more than images (tens of cents to a few dollars depending on tier). Failed generations are never billed.",
+        _meta: toolMeta("Starting video", "Video job started", true),
+        description: "Start a video from a text prompt, or animate a source image. Asynchronous: returns a job id at once; poll get_job until status is completed. Costs tens of cents to a few dollars per clip (premium ~52c, pro ~84c). Failed generations are never billed.",
         inputSchema: {
             prompt: z.string().describe("What to generate, in plain language"),
             tier: z
-                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .enum(TIERS)
                 .optional()
                 .describe("Quality tier: air=cheapest (best value, not the quickest), lite=everyday, premium=production, pro=advanced, max_pro=maximum fidelity (flagship models). Omit for a sensible default."),
+            style: z
+                .enum(IMAGE_STYLES)
+                .optional()
+                .describe("Optional content style hint, same vocabulary as generate_image"),
             aspect_ratio: z
                 .enum(["16:9", "9:16", "1:1"])
                 .optional()
@@ -221,20 +356,46 @@ export function createCorentServer(config = {}) {
                 .optional()
                 .describe("Pixel resolution (default 720p). Tier-capped: pro allows up to 1080p, max_pro up to 4k; above the tier's cap it is clamped down, never rejected. Higher resolutions cost more (1080p ~2.5x, 4k ~5.5x). GET /v1/tiers lists each tier's menu with prices."),
             image_url: z.string().url().optional().describe("If set, animates this image instead of pure text-to-video"),
+            audio: z
+                .boolean()
+                .optional()
+                .describe("Ask for native SOUND. Some models render audio and some are silent. true routes only to " +
+                "models that actually deliver sound, so a silent model can never quietly serve the request; " +
+                "false prefers a silent one; omit to let Corent choose. list_tiers reports supports_audio " +
+                "per tier. Use true whenever the user asks for a clip with sound, music, or speech."),
+            end_image_url: z
+                .string()
+                .url()
+                .optional()
+                .describe("The frame the clip should END on. Together with image_url this is the go-from-A-to-B / morph " +
+                "effect; alone it is a target to move toward."),
+            camera: z
+                .enum([
+                "static", "pan_left", "pan_right", "zoom_in", "zoom_out",
+                "orbit_left", "orbit_right", "tilt_up", "tilt_down",
+            ])
+                .optional()
+                .describe("Camera move."),
+            negative_prompt: z.string().optional().describe("What must NOT appear in the clip."),
+            seed: z.number().int().min(0).optional().describe("Reproducibility, same contract as generate_image."),
+            fps: z.number().int().min(8).max(60).optional().describe("Frames per second, where the model offers a choice."),
+            enhance_prompt: z.boolean().optional().describe("false sends the prompt exactly as written."),
             model: z
                 .string()
                 .optional()
-                .describe("Direct model access: pin an exact model by name (list_models shows the menu). Bypasses routing -- never substituted; duration and resolution snap to THAT model's own menu rather than a tier cap. Mutually exclusive with tier."),
+                .describe('Direct model access: pin an exact model by name, e.g. "corent-seedance-2.0" (list_models shows the menu; every name there is spelled corent-*). Bypasses routing -- never substituted; duration and resolution snap to THAT model\'s own menu rather than a tier cap. Mutually exclusive with tier.'),
         },
         outputSchema: jobOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, tier, model, aspect_ratio, duration_s, resolution, image_url }) => corent("/v1/videos/generate", {
+    }, wrap(async (args) => corent("/v1/videos/generate", {
         method: "POST",
-        body: JSON.stringify({ prompt, tier, model, aspect_ratio, duration_s, resolution, image_url }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
     server.registerTool("generate_speech", {
         title: "Generate speech (voice)",
-        description: "Generate spoken audio (text to speech) from text. Synchronous: returns the finished audio URL and the exact charge. Billed in started blocks of 1,000 input characters, so even a one-sentence request bills the full first block (roughly 25-30 cents); longer scripts amortize better. Failed generations are never billed.",
+        _meta: toolMeta("Generating speech", "Speech ready"),
+        description: "Text to speech. Synchronous: returns the finished audio URL and the exact charge. Billed in started blocks of 1,000 characters (roughly 25-30c for the first block), so a short line costs the same as a paragraph. Call list_voices first to pick a voice_id. Failed generations are never billed.",
         inputSchema: {
             text: z.string().min(1).max(5000).describe("The text to speak, max 5000 characters"),
             voice_id: z
@@ -245,7 +406,18 @@ export function createCorentServer(config = {}) {
             model: z
                 .string()
                 .optional()
-                .describe("Direct model access: pin an exact speech model by name (list_models shows the menu)."),
+                .describe('Direct model access: pin an exact speech model by name, e.g. "corent-eleven-multilingual-v2" (list_models shows the menu with kind="speech"; every name there is spelled corent-*).'),
+            stability: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("0 to 1. Low is more expressive and varies more take to take; high is steadier."),
+            similarity: z.number().min(0).max(1).optional().describe("0 to 1. How closely to hold the voice's character."),
+            style: z.number().min(0).max(1).optional().describe("0 to 1. Extra expressiveness."),
+            speed: z.number().min(0.5).max(2).optional().describe("Playback speed; 1.0 is natural pace."),
+            language: z.string().optional().describe('ISO code for the multilingual models, e.g. "en" or "pt-BR".'),
+            output_format: z.string().optional().describe('Audio format, e.g. "mp3" or "wav".'),
         },
         outputSchema: {
             id: z.string().optional(),
@@ -255,24 +427,42 @@ export function createCorentServer(config = {}) {
             error: z.string().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ text, voice_id, model }) => corent("/v1/audio/speech", {
+    }, wrap(async (args) => corent("/v1/audio/speech", {
         method: "POST",
-        body: JSON.stringify({ text, voice_id, model }),
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
     })));
     server.registerTool("generate_text", {
         title: "Generate text (language model)",
-        description: "Run a prompt through a frontier language model on the user's Corent account. Synchronous: returns the finished text, the token usage and the exact charge. Billed per token (a short answer is a fraction of a cent). Use this when the user wants a SPECIFIC model's answer, a second opinion from another lab, or work billed to their Corent balance -- not for your own reasoning, which costs them nothing. Failed generations are never billed.",
+        _meta: toolMeta("Asking the model", "Answer ready"),
+        description: "Run a prompt or conversation through a frontier language model on the user's Corent account. Synchronous: returns the text, token usage and exact charge (fractions of a cent). Use it when the user wants a specific model's answer or work billed to Corent, not for your own reasoning. Supports tool calling and JSON mode.",
         inputSchema: {
-            prompt: z.string().min(1).describe("What to ask, in plain language"),
+            prompt: z.string().min(1).optional().describe("What to ask, in plain language. Use this for a single question; use `messages` instead to continue a conversation."),
             system: z.string().optional().describe("Optional system instruction that frames the request"),
+            messages: z
+                .array(z
+                .object({
+                role: z.enum(["system", "user", "assistant", "tool"]),
+                content: z.unknown().optional(),
+                name: z.string().optional(),
+                tool_call_id: z.string().optional(),
+                tool_calls: z.array(z.object({}).passthrough()).optional(),
+            })
+                .passthrough())
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Full OpenAI-shaped conversation, for multi-turn work: prior assistant turns, and the tool " +
+                "results you are feeding back after a tool call. Takes precedence over prompt/system. " +
+                "Without this the model sees only one question and has no memory of the exchange."),
             tier: z
-                .enum(["air", "lite", "premium", "pro", "max_pro"])
+                .enum(TIERS)
                 .optional()
                 .describe("Quality tier: air=cheapest, lite=everyday, premium=production, pro=advanced, max_pro=frontier flagships. Omit for a sensible default."),
             model: z
                 .string()
                 .optional()
-                .describe("Direct model access: pin an exact text model by name (list_models shows the menu, kind='text'). Bypasses routing -- never substituted, flat cost-plus price. Mutually exclusive with tier."),
+                .describe('Direct model access: pin an exact text model by name, e.g. "corent-claude-opus-5" (list_models shows the menu with kind="text"; every name there is spelled corent-*). Bypasses routing -- never substituted, flat cost-plus price. Mutually exclusive with tier.'),
             max_tokens: z
                 .number()
                 .int()
@@ -281,9 +471,25 @@ export function createCorentServer(config = {}) {
                 .optional()
                 .describe("Cap on the reply length in tokens (default 1024). The balance gate reserves against this, so keep it realistic."),
             temperature: z.number().min(0).max(2).optional().describe("Sampling temperature; omit for the model's default"),
+            tools: z
+                .array(z.object({}).passthrough())
+                .optional()
+                .describe("OpenAI-shaped function definitions the model may call. When the model answers with tool " +
+                "calls, they come back in `tool_calls` and the reply text is empty: run them, then call " +
+                "again with `messages` carrying the assistant turn and your tool results."),
+            tool_choice: z
+                .unknown()
+                .optional()
+                .describe('How the model may use tools: "auto", "none", "required", or {type:"function",function:{name}}.'),
+            response_format: z
+                .object({})
+                .passthrough()
+                .optional()
+                .describe('Structured output, e.g. {"type":"json_object"} for JSON mode, or a json_schema block.'),
         },
         outputSchema: {
             text: z.string().optional(),
+            tool_calls: z.array(z.object({}).passthrough()).nullable().optional(),
             model: z.string().optional(),
             finish_reason: z.string().optional(),
             usage: z
@@ -298,13 +504,21 @@ export function createCorentServer(config = {}) {
             error: z.string().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, wrap(async ({ prompt, system, tier, model, max_tokens, temperature }) => {
-        const messages = system
-            ? [{ role: "system", content: system }, { role: "user", content: prompt }]
-            : [{ role: "user", content: prompt }];
+    }, wrap(async ({ prompt, system, messages: history, tier, model, max_tokens, temperature, tools, tool_choice, response_format }) => {
+        if (!history && !prompt) {
+            throw new CorentApiError(422, { message: "Pass either `prompt` (single question) or `messages` (conversation)." });
+        }
+        // An explicit conversation wins: it carries the turns and tool results a
+        // single prompt cannot express.
+        const messages = history ??
+            (system
+                ? [{ role: "system", content: system }, { role: "user", content: prompt }]
+                : [{ role: "user", content: prompt }]);
         // The API's `model` field is required and carries both modes: a pinned
-        // catalog name, or "corent/text-<tier>" for the brain-routed lane. lite
-        // matches the router's own default for an unrecognised tier.
+        // model name ("corent-claude-opus-5"), or "corent/text-<tier>" for the
+        // brain-routed lane -- note the slash, a separate namespace from the
+        // dash-prefixed model names. lite matches the router's own default for an
+        // unrecognised tier.
         const r = await corent("/v1/chat/completions", {
             method: "POST",
             body: JSON.stringify({
@@ -312,11 +526,18 @@ export function createCorentServer(config = {}) {
                 messages,
                 max_tokens,
                 temperature,
+                tools,
+                tool_choice,
+                response_format,
             }),
         });
         const choice = (r.choices ?? [{}])[0] ?? {};
         return {
             text: choice.message?.content ?? "",
+            // When the model answers with tool calls the content is empty and THIS
+            // is the answer. Returning only `text` made a tool-calling reply look
+            // like an empty response (parity audit 2026-08-30).
+            tool_calls: choice.message?.tool_calls ?? null,
             model: r.model,
             finish_reason: choice.finish_reason,
             usage: r.usage,
@@ -326,7 +547,8 @@ export function createCorentServer(config = {}) {
     }));
     server.registerTool("list_models", {
         title: "List available models",
-        description: "The direct-access menu: every model that can be pinned by name on generate_image / generate_video / generate_speech / generate_text, with its kind (image, video, speech, text), quality score and live status. Carries NO price -- do not promise the user a per-model rate from this; billing is flat cost-plus and the exact charge is returned on each generation. Read-only and free. Use this only when the user wants a SPECIFIC model -- otherwise omit `model` and let Corent route to the best one for the prompt.",
+        _meta: toolMeta("Listing models", "Models listed"),
+        description: "The direct-access menu: every model that can be pinned by name (spelled corent-*) on the generate tools, with kind, quality score and live status. Carries no price; billing is flat cost-plus and each generation returns its exact charge. Read-only and free. Only needed when the user names a specific model.",
         inputSchema: {},
         outputSchema: {
             models: z
@@ -339,24 +561,145 @@ export function createCorentServer(config = {}) {
         },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, wrap(async () => corent("/v1/models")));
+    server.registerTool("list_voices", {
+        title: "List voices",
+        _meta: toolMeta("Listing voices", "Voices listed"),
+        description: "The voices generate_speech accepts as voice_id, with display name, preview clip and descriptors (gender, age, accent, use case). Read-only and free. Call it before generate_speech whenever the user wants a particular narrator; a voice_id cannot be guessed.",
+        inputSchema: {},
+        outputSchema: {
+            voices: z
+                .array(z.object({ voice_id: z.string() }).passthrough())
+                .optional(),
+            count: z.number().optional(),
+            default_voice_id: z.string().nullable().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async () => corent("/v1/voices")));
+    server.registerTool("cancel_job", {
+        title: "Cancel a running job",
+        _meta: toolMeta("Cancelling job", "Job cancelled"),
+        description: "Stop a job that has not finished and release the money held for it. Charges nothing. Use it as soon as the user says they did not mean to start something, especially a video. A job that already finished stays completed and billed for what was delivered.",
+        inputSchema: { job_id: z.string().describe("The job id to cancel") },
+        outputSchema: {
+            id: z.string().optional(),
+            status: z.string().optional(),
+            cancelled: z.boolean().optional(),
+            detail: z.string().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ job_id }) => corent(`/v1/jobs/${job_id}/cancel`, { method: "POST" })));
+    server.registerTool("list_tiers", {
+        title: "List quality tiers and prices",
+        _meta: toolMeta("Listing tiers", "Tiers listed"),
+        description: "The live tier menu for image and video: each tier's price estimate, shapes, video durations, per-resolution pricing, and whether it accepts reference images (image) or a source image (video). Read-only and free. Check it before quoting a price. Tier-level only; never names a model.",
+        inputSchema: {},
+        outputSchema: {
+            tiers: z
+                .array(z
+                .object({
+                name: z.string().optional(),
+                estimated_cost_cents: z.number().nullable().optional(),
+                capabilities: z.object({}).passthrough().optional(),
+            })
+                .passthrough())
+                .optional(),
+            pricing_note: z.string().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async () => corent("/v1/tiers")));
+    // --- Batch tools: one call, up to 50 renders. The single-item tools are the
+    // right default; these exist for the "make me 30 variations" ask, where 30
+    // separate tool calls would be slower and far more expensive in context. ---
+    const imageBatchItem = z
+        .object({
+        prompt: z.string(),
+        tier: z.enum(TIERS).optional(),
+        style: z.enum(IMAGE_STYLES).optional(),
+        aspect_ratio: z.enum(IMAGE_ASPECTS).optional(),
+    })
+        .describe("One image in the batch. Batch items are tier-routed: to pin an exact model, use generate_image.");
+    server.registerTool("generate_image_batch", {
+        title: "Generate many images (batch)",
+        _meta: toolMeta("Submitting image batch", "Image batch submitted"),
+        description: "Submit up to 50 image generations in one call. Asynchronous: returns a batch_id and a job id per item; poll get_batch, then get_job per image. Every item bills at the normal rate, so check get_balance first. Items are tier-routed; pin a model with generate_image instead. No reference images here.",
+        inputSchema: {
+            items: z.array(imageBatchItem).min(1).max(50).describe("1 to 50 image requests"),
+        },
+        outputSchema: batchOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ items }) => corent("/v1/images/generate/batch", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify({ items }),
+    })));
+    server.registerTool("generate_video_batch", {
+        title: "Generate many videos (batch)",
+        _meta: toolMeta("Submitting video batch", "Video batch submitted"),
+        description: "Submit up to 50 video generations in one call. Asynchronous: returns a batch_id and a job id per item; poll get_batch, then get_job per clip. Video is the expensive lane: a 10-item batch can cost several dollars, so confirm with the user and check get_balance first. Items are tier-routed.",
+        inputSchema: {
+            items: z
+                .array(z.object({
+                prompt: z.string(),
+                tier: z.enum(TIERS).optional(),
+                style: z.enum(IMAGE_STYLES).optional(),
+                aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional(),
+                duration_s: z.number().int().min(1).max(30).optional(),
+                resolution: z.enum(["720p", "1080p", "4k"]).optional(),
+            }))
+                .min(1)
+                .max(50)
+                .describe("1 to 50 video requests"),
+        },
+        outputSchema: batchOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async ({ items }) => corent("/v1/videos/generate/batch", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify({ items }),
+    })));
+    server.registerTool("get_batch", {
+        title: "Check batch progress",
+        _meta: toolMeta("Checking batch", "Batch checked"),
+        description: "Progress of a batch from generate_image_batch or generate_video_batch: completed, failed and pending counts plus each item's job id. Read-only and free. Fetch a finished item's media with get_job.",
+        inputSchema: { batch_id: z.string().describe("The batch_id returned by a batch tool") },
+        outputSchema: {
+            batch_id: z.string().optional(),
+            total: z.number().optional(),
+            completed: z.number().optional(),
+            failed: z.number().optional(),
+            pending: z.number().optional(),
+            jobs: z.array(z.object({ id: z.string(), status: z.string() }).passthrough()).optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ batch_id }) => corent(`/v1/batches/${batch_id}`)));
     server.registerTool("get_job", {
         title: "Check job status",
-        _meta: WIDGET_TOOL_META,
-        description: "Check the status of a generation job (mainly videos). When completed, the response includes the permanent media URL and the cost. Read-only and free.",
+        _meta: toolMeta("Checking job", "Job checked", true),
+        description: "Check a generation job (mainly video). When completed, the response carries the permanent media URL and the cost. Read-only and free.",
         inputSchema: { job_id: z.string().describe("The job id returned by generate_video or generate_image") },
         outputSchema: jobOutput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, wrap(async ({ job_id }) => corent(`/v1/jobs/${job_id}`)));
     server.registerTool("get_balance", {
         title: "Check account balance",
-        description: "Get the Corent account's remaining balance in cents. Useful before starting expensive video generations. Read-only and free.",
+        _meta: toolMeta("Checking balance", "Balance checked"),
+        description: "The account balance in cents. balance_cents is the total, held_cents is reserved by running generations, available_cents is what a new request can actually spend; check that one before an expensive video. Read-only and free.",
         inputSchema: {},
-        outputSchema: { balance_cents: z.number().optional() },
+        outputSchema: {
+            balance_cents: z.number().optional(),
+            held_cents: z.number().optional(),
+            available_cents: z.number().optional(),
+        },
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, wrap(async () => corent("/v1/account/balance")));
     server.registerTool("get_status", {
         title: "Check service status",
-        description: "Get live operational status of Corent's generation tiers (operational/degraded). Read-only and free; useful to pick a healthy tier.",
+        _meta: toolMeta("Checking status", "Status checked"),
+        description: "Live operational status of Corent's generation tiers (operational or degraded). Read-only and free; useful to pick a healthy tier.",
         inputSchema: {},
         // /v1/status returns tiers as an ARRAY of {name, status} — declaring it
         // as a record made every call fail output validation (audit 2026-07-20).
@@ -371,7 +714,8 @@ export function createCorentServer(config = {}) {
     // prompt. The agent never picks a model or tier. ---
     server.registerTool("plan", {
         title: "Plan (cost preview, no generation)",
-        description: "Preview how Corent would handle a plain-language request WITHOUT generating anything (costs a fraction of a cent). Corent decides whether it's an image or video, which tier, aspect ratio, and duration, and returns the plan plus an estimated cost. Use this to decide or confirm cost before spending. The planner covers image and video; for spoken audio call generate_speech directly. If the request is something Corent can't generate (text documents, 3D, editing, real-world actions), can_fulfill is false with a reason.",
+        _meta: toolMeta("Planning", "Plan ready"),
+        description: "Preview how Corent would handle a plain-language request without generating anything (a fraction of a cent). Returns image vs video, tier, aspect ratio, duration and an estimated cost. Covers image and video only; for speech call generate_speech. Impossible asks come back with can_fulfill false and a reason.",
         inputSchema: {
             intent: z
                 .string()
@@ -385,8 +729,8 @@ export function createCorentServer(config = {}) {
     }, wrap(async ({ intent }) => corent("/v1/intent", { method: "POST", body: JSON.stringify({ intent }) })));
     server.registerTool("create", {
         title: "Create (plan + generate, budget-capped)",
-        _meta: WIDGET_TOOL_META,
-        description: "Describe what you want in plain language and Corent plans AND generates it — choosing image vs video, tier, aspect ratio, and duration for you (the 'zero decisions' path). You MUST pass max_cost_cents as a spend ceiling; if the estimated cost exceeds it, nothing is generated and you're told the estimate so you can raise the ceiling. Image results come back with a URL; video results come back as a job id to poll with get_job. Failed generations are never billed.",
+        _meta: toolMeta("Creating", "Created", true),
+        description: "Describe what you want in plain language; Corent plans and generates it, choosing image vs video, tier, shape and duration. max_cost_cents is a required spend ceiling: above it nothing is generated and you are told the estimate. Images return a URL; videos return a job id for get_job. Failed generations are never billed.",
         inputSchema: {
             intent: z.string().describe("What you want, in natural language"),
             max_cost_cents: z
@@ -416,5 +760,151 @@ export function createCorentServer(config = {}) {
         }
         return res;
     }));
+    // --- Image tools (v0.8.0): edit what already exists instead of generating
+    // anew. All three are synchronous, flat-priced, and replay-safe under an
+    // Idempotency-Key exactly like generate_image. ---
+    server.registerTool("upscale_image", {
+        title: "Upscale image",
+        _meta: toolMeta("Upscaling image", "Upscaled image ready", true),
+        description: "Make an existing image bigger and sharper from its public https URL. Synchronous, returns a new permanent URL. Flat price, no tier; failed runs are never billed. Optional prompt guides the added detail; omit it to enlarge faithfully. Upload a local file with upload_image first.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to enlarge and sharpen"),
+            prompt: z.string().max(2000).optional().describe("Optional guidance for the added detail; omit to enlarge faithfully"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/upscale", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    server.registerTool("remove_background", {
+        title: "Remove background",
+        _meta: toolMeta("Removing background", "Cutout ready", true),
+        description: "Cut the subject out of an image and return a PNG with a real transparent background, for logos, product shots and compositing. Synchronous, flat price, no tier; failed runs are never billed. Takes a public https URL; upload a local file with upload_image first.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to cut out"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/remove-background", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    server.registerTool("inpaint_image", {
+        title: "Inpaint image (masked edit)",
+        _meta: toolMeta("Inpainting image", "Edited image ready", true),
+        description: "Regenerate ONLY the white region of a mask and leave every pixel outside it byte-for-byte unchanged, so a product or logo stays exactly your file. Takes image_url, a same-size black-and-white mask_url (white = redo, black = keep) and a prompt for the masked area. Synchronous; failed runs are never billed.",
+        inputSchema: {
+            image_url: z.string().url().describe("Public https URL of the image to edit"),
+            mask_url: z
+                .string()
+                .url()
+                .describe("Public https URL of a black-and-white mask the same size as the image: WHITE is regenerated, BLACK is preserved byte for byte"),
+            prompt: z.string().min(1).max(2000).describe("What to generate inside the white (masked) region"),
+            tier: z.enum(TIERS).optional().describe("Quality tier for the regenerated region; omit for the default"),
+        },
+        outputSchema: imageOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, wrap(async (args) => corent("/v1/images/edit", {
+        method: "POST",
+        headers: { "Idempotency-Key": idempotencyKey() },
+        body: JSON.stringify(args),
+    })));
+    // --- Memory: what the account already made, so an assistant can find "the
+    // beach one from yesterday" and reuse the URL instead of paying again. ---
+    const MEDIA_TYPES = ["image", "video", "speech", "text"];
+    const PROMPT_PREVIEW_CHARS = 120;
+    server.registerTool("list_media", {
+        title: "List recent media",
+        _meta: toolMeta("Searching your media", "Media listed"),
+        description: "Find media the account already made, so a result can be reused instead of paid for again. Reads the last 100 jobs, filtered by type and a prompt keyword (e.g. 'beach'), newest first. Returns id, type, status, date, tier, cost and URL per job. Read-only and free.",
+        inputSchema: {
+            type: z.enum(MEDIA_TYPES).optional().describe("Only this lane: image, video, speech or text"),
+            limit: z.number().int().min(1).max(100).default(20).describe("How many rows to return, 1-100 (default 20)"),
+            query: z.string().optional().describe("Case-insensitive substring to match against each job's prompt"),
+        },
+        outputSchema: {
+            items: z
+                .array(z
+                .object({
+                id: z.string(),
+                type: z.string().nullable().optional(),
+                status: z.string().nullable().optional(),
+                created_at: z.string().nullable().optional(),
+                tier: z.string().nullable().optional(),
+                cost_cents: z.number().nullable().optional(),
+                prompt: z.string().nullable().optional(),
+                url: z.string().nullable().optional(),
+            })
+                .passthrough())
+                .optional(),
+            count: z.number().optional(),
+            scanned: z.number().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ type, limit, query }) => {
+        const usage = await corent("/v1/account/usage");
+        const recent = Array.isArray(usage?.recent_jobs) ? usage.recent_jobs : [];
+        const needle = query?.trim().toLowerCase();
+        const items = recent
+            .filter((j) => !type || j.type === type)
+            .filter((j) => !needle || String(j.prompt ?? "").toLowerCase().includes(needle))
+            .slice(0, limit ?? 20)
+            .map((j) => {
+            const prompt = typeof j.prompt === "string" ? j.prompt : null;
+            return {
+                id: String(j.id),
+                type: j.type ?? null,
+                status: j.status ?? null,
+                created_at: j.created_at ?? null,
+                tier: j.model ?? null,
+                cost_cents: j.charge_cents ?? null,
+                prompt: prompt && prompt.length > PROMPT_PREVIEW_CHARS ? `${prompt.slice(0, PROMPT_PREVIEW_CHARS - 1)}…` : prompt,
+                url: j.output_url ?? null,
+            };
+        });
+        return { items, count: items.length, scanned: recent.length };
+    }));
+    // --- Upload: turn a local file into a URL the other tools accept. ---
+    const UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
+    server.registerTool("upload_image", {
+        title: "Upload image",
+        _meta: toolMeta("Uploading image", "Upload complete"),
+        description: "Upload a local image (base64) to Corent and get back a public https URL. Use that URL as image_url, mask_url, source_image_url or a reference in the other tools. Max 25 MB. Free; the file is stored on the account.",
+        inputSchema: {
+            data_base64: z.string().min(1).describe("The file bytes, base64 encoded (no data: prefix)"),
+            content_type: z
+                .string()
+                .regex(/^image\/[a-z0-9.+-]+$/i)
+                .describe('MIME type, e.g. "image/png" or "image/jpeg"'),
+            filename: z.string().max(255).optional().describe("Optional file name, e.g. product.png"),
+        },
+        outputSchema: {
+            url: z.string().optional(),
+            id: z.string().optional(),
+            content_type: z.string().optional(),
+            bytes: z.number().optional(),
+            error: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async ({ data_base64, content_type, filename }) => {
+        // Strip an accidental data: URL prefix so a copy-pasted value still works.
+        const raw = data_base64.replace(/^data:[^;]+;base64,/, "").trim();
+        // Decoded size, computed without decoding: 3 bytes per 4 characters,
+        // minus padding. Refusing here saves shipping 30 MB to the API for a 413.
+        const padding = raw.endsWith("==") ? 2 : raw.endsWith("=") ? 1 : 0;
+        const bytes = Math.floor((raw.length * 3) / 4) - padding;
+        if (bytes > UPLOAD_MAX_BYTES) {
+            throw new CorentApiError(413, { message: `File is ${bytes} bytes; the upload limit is 25 MB.` });
+        }
+        return corent("/v1/uploads", {
+            method: "POST",
+            body: JSON.stringify({ data_base64: raw, content_type, filename }),
+        });
+    }));
+    registerPrompts(server);
     return server;
 }