@oharness/engine 0.7.1 → 0.9.0

package/dist/runtime-plugins/builtin/studio.d.ts

@@ -1,33 +1,104 @@
+import type { MediaAccess } from "../../mcp/builtin.ts";
+import type { AuthManager } from "../../auth/manager.ts";
 import type { McpToolDefinition } from "../../mcp/protocol.ts";
 import type { Tool, ToolContext } from "../../tools/types.ts";
 import type { RuntimePlugin } from "../types.ts";
 export interface StudioPluginOptions {
-    /** The gateway credential, from the same sources completions resolve. */
-    secret(): Promise<string | undefined>;
+    /** Who calls are made as, and where they go. Asked before every call. */
+    access(): Promise<MediaAccess | undefined>;
 }
+/**
+ * The credential media calls go out on: the OHarness account, and nothing else.
+ *
+ * Media is billed only through our gateway, which charges the account (or the
+ * team it bills to) in OHarness credits the way it charges chat. A vendor key
+ * the user happens to hold for chat is deliberately not used here: two ways to
+ * pay for the same image would be two balances to explain, and a generation
+ * the user expected on their plan would land on a different bill.
+ *
+ * The team rides in the path because the server offers nowhere else: all a
+ * caller sets is a base URL and a key.
+ */
+export declare function mediaAccess(auth: AuthManager): Promise<MediaAccess | undefined>;
 export declare function createStudioPlugin(options: StudioPluginOptions): RuntimePlugin;
+/** What the model is told when media exists but the user is not signed in. */
+export declare const SIGN_IN_PROMPT: string;
+/** One upstream tool: what it is called here, and what it produces. */
+export interface FacadeEntry {
+    upstream: string;
+    name: string;
+    /**
+     * What generated files are named after; empty for a tool that only reads,
+     * which is also what makes it skip confirmation and download nothing.
+     */
+    kind: string;
+    note: string;
+}
 /**
- * What each upstream tool is called here, and what it produces.
+ * The tools this file knows by name, and what to say about each.
  *
- * The rename is the whole of the mapping. Parameters are not restated: the
- * schema comes from the server, so a model can send anything that server
+ * The rename and the note are the whole of it. Parameters are not restated:
+ * the schema comes from the server, so a model can send anything that server
  * accepts and a parameter added upstream works the day it ships. Writing them
  * out here would be a second, staler copy of somebody else's list — and the
  * failure mode is silent, since a parameter this file has not heard of would
  * simply never reach the gateway.
+ *
+ * A tool missing from here is still offered; see `facadeEntry`.
  */
-export declare const FACADE: Array<{
-    upstream: string;
-    name: string;
-    kind: string;
-    note: string;
-}>;
+export declare const FACADE: FacadeEntry[];
+/**
+ * The name a tool is offered under: the known one, or one derived from the
+ * upstream name with the vendor taken off — `ottoport_remove_background`
+ * becomes `RemoveBackground`.
+ */
+export declare function facadeName(upstream: string): string;
+/**
+ * How to present a tool, whether or not this file has heard of it.
+ *
+ * An unknown tool is assumed to spend money unless its name says it only
+ * looks something up. Guessing the other way would let a new paid tool skip
+ * confirmation, and the cost of that guess is a charge the user never agreed
+ * to; guessing this way costs one extra click on a lookup.
+ */
+export declare function facadeEntry(upstream: string): FacadeEntry;
+/**
+ * A server-written description, in this harness's words.
+ *
+ * The vendor's name is not part of the product, and the server's text is full
+ * of it — "through an OttoPort image model", "call ottoport_list_models".
+ * Left alone, the second is worse than cosmetic: it names a tool the model
+ * does not have, under the name it is offered as here. So tool references
+ * become the names they are offered under, the vendor's name is dropped, and
+ * a sentence about something withheld or refused is dropped with it.
+ */
+export declare function rebrand(text: string): string;
+/**
+ * The server's input schema, as this harness offers it: descriptions in its
+ * words at every depth, and without the parameters the gateway refuses.
+ */
+export declare function facadeSchema(inputSchema: unknown): {
+    properties?: Record<string, unknown>;
+    [k: string]: unknown;
+};
 /**
  * One upstream tool, wearing this harness's name and manners.
  *
- * `inputSchema` is the server's own, with `path` added. Nothing validates it
- * here: the server validates its own inputs, and a second opinion derived from
- * its JSON Schema would only be a less accurate one — the same reasoning the
- * MCP tool adapter states.
+ * `inputSchema` is the server's own, rebranded, with `path` added. Nothing
+ * validates it here: the server validates its own inputs, and a second
+ * opinion derived from its JSON Schema would only be a less accurate one —
+ * the same reasoning the MCP tool adapter states.
+ */
+export declare function facadeTool(entry: FacadeEntry, def: McpToolDefinition, call: (tool: string, args: Record<string, unknown>, ctx: ToolContext) => Promise<string>): Tool;
+/**
+ * Where one output goes: into a folder, or under a name.
+ *
+ * A model asked for "a kitten picture" passes `media/kitten.png` as often as
+ * `media/` — and treating every path as a folder saved that one as
+ * `media/kitten.png/image-….jpg`, a folder named like an image with the image
+ * inside it. A path whose last part has an extension is a file name. The
+ * extension kept is the one the bytes have, because renaming a JPEG to .png
+ * makes a file that some viewers refuse; the name asked for is kept. A second
+ * output of the same call is numbered beside the first.
  */
-export declare function facadeTool(entry: (typeof FACADE)[number], def: McpToolDefinition, call: (tool: string, args: Record<string, unknown>, ctx: ToolContext) => Promise<string>): Tool;
+export declare function destination(into: string | undefined, kind: string, index: number, extension: string): string;

package/dist/runtime-plugins/builtin/studio.js

@@ -1,11 +1,14 @@
 import path from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { McpClient } from "../../mcp/client.js";
-import { ottoportMediaServer } from "../../mcp/builtin.js";
+import { WITHHELD_TOOLS, bundledOttoport, ottoportCacheRoot, ottoportMediaServer, serverEntry } from "../../mcp/builtin.js";
+import { updateOttoport } from "../../mcp/ottoport-updates.js";
+import { officialBaseUrl, officialTeam } from "../../auth/providers/official.js";
 import { normalizeObjectSchema } from "../../util/schema.js";
 import { toolError, toolText } from "../../tools/types.js";
 /**
- * Image, video, speech and music, as four ordinary tools.
+ * Image, video, speech and music — and whatever else the media server adds —
+ * as ordinary tools.
  *
  * The generation itself belongs to a vendor and always will: the models change
  * weekly, each takes different parameters, and keeping a copy of that here
@@ -32,13 +35,45 @@ import { toolError, toolText } from "../../tools/types.js";
  */
 /** Where generated files land when the caller does not say. */
 const DEFAULT_DIR = "media";
+/**
+ * How long an account token must still have when a call starts.
+ *
+ * The server holds the key it was started with for as long as it runs, and a
+ * video is a job it polls for up to ten minutes. A token that lapsed halfway
+ * through would lose a generation that has already been paid for, so the
+ * token is renewed early rather than at the last minute.
+ */
+const ACCOUNT_TOKEN_VALID_MS = 15 * 60_000;
+/**
+ * The credential media calls go out on: the OHarness account, and nothing else.
+ *
+ * Media is billed only through our gateway, which charges the account (or the
+ * team it bills to) in OHarness credits the way it charges chat. A vendor key
+ * the user happens to hold for chat is deliberately not used here: two ways to
+ * pay for the same image would be two balances to explain, and a generation
+ * the user expected on their plan would land on a different bill.
+ *
+ * The team rides in the path because the server offers nowhere else: all a
+ * caller sets is a base URL and a key.
+ */
+export async function mediaAccess(auth) {
+    // An exported key wins over a session, the same order `officialAuth` loads in.
+    const session = process.env["OHARNESS_API_KEY"]
+        ? undefined
+        : await auth.accessToken("official", ACCOUNT_TOKEN_VALID_MS).catch(() => undefined);
+    const key = session ?? (await auth.secret("official").catch(() => undefined));
+    if (!key)
+        return undefined;
+    const team = officialTeam();
+    return { key, baseUrl: `${officialBaseUrl()}${team ? `/teams/${team}` : ""}` };
+}
 export function createStudioPlugin(options) {
     return {
         id: "studio",
         version: "1.0.0",
         apiVersion: 1,
         // The id names it in config and code; this is what the panel shows.
-        title: "AI Creative Media Plugin",
+        title: "OH Creative Media Generator",
         description: "Image, video, speech and music generation",
         parseConfig(raw) {
             if (raw !== undefined && (typeof raw !== "object" || raw === null)) {
@@ -47,76 +82,229 @@ export function createStudioPlugin(options) {
             return {};
         },
         async setup(ctx) {
-            /**
-             * No credential, no tools — and no subprocess either.
-             *
-             * Registering them anyway would put five tool definitions in the system
-             * prompt of every request for every user who will never generate an
-             * image, and each one would fail on the first call.
-             */
-            if (!(await options.secret()))
-                return;
-            const config = ottoportMediaServer();
-            if (!config) {
+            // Resolved once, so every server this session starts is the same
+            // version: a newer one downloaded mid-session waits for the next.
+            const entry = serverEntry();
+            if (!entry) {
                 ctx.logger.warn("studio tools unavailable: the gateway client is not installed");
                 return;
             }
-            const client = new McpClient("studio", config, ctx.logger, undefined, async () => options.secret());
-            ctx.onDispose(async () => {
-                await client.close().catch(() => { });
-            });
             /**
-             * Connected during setup, because the tools are built from what the
-             * server says it takes.
+             * No credential, no tools — and no subprocess either, until there is
+             * one.
+             *
+             * Registering them anyway would put every media tool's definition in
+             * the system prompt of every request for every user who will never
+             * generate an image, and each one would fail on the first call.
              *
-             * The alternative — connecting on the first call — would mean writing
-             * the parameters out here, and a copy of someone else's parameter list
-             * goes stale silently: a field added upstream would never reach the
-             * gateway, and nothing would report it. One subprocess for an account
-             * that actually has a media gateway is the cheaper mistake.
+             * But signing in is something people do after the app is open — on a
+             * first launch it is the usual order — and a plugin that decided once,
+             * at startup, left them with no media until a restart they had no
+             * reason to think of. So while signed out it offers a short paragraph
+             * instead, and that paragraph is read at the start of every turn: the
+             * turn that finds the user signed in starts the server and registers
+             * the tools, and since a turn reads its prompt before its tool list,
+             * that same turn can already use them.
              */
-            let advertised;
+            let started;
+            const start = () => (started ??= enable(ctx, entry).then((ok) => {
+                // A gateway that could not be reached is tried again next turn.
+                if (!ok)
+                    started = undefined;
+                return ok;
+            }));
+            if (await options.access()) {
+                await start();
+                return;
+            }
+            ctx.logger.info("studio tools waiting: not signed in to OHarness");
+            // Without it a model asked for an image says it cannot make images,
+            // which is untrue and sends the user nowhere. This way it says what to
+            // do about it — and stops saying it the moment it no longer applies.
+            ctx.prompts.register(async () => {
+                if (started && (await started))
+                    return undefined;
+                if (!(await options.access()))
+                    return SIGN_IN_PROMPT;
+                await start();
+                return undefined;
+            });
+        },
+    };
+    /**
+     * Start the media server and register what it offers. False when it could
+     * not be started, which is never fatal: a gateway that cannot be reached is
+     * a session without media tools, not a session that will not start.
+     */
+    async function enable(ctx, entry) {
+        checkForUpdate(ctx.logger, ctx.signal);
+        const open = async (access) => {
+            const client = new McpClient("studio", ottoportMediaServer(access, entry), ctx.logger);
             try {
                 await client.connect();
-                advertised = await client.listTools();
             }
             catch (err) {
-                // Never fatal. A gateway that cannot be reached is a session without
-                // media tools, not a session that will not start.
-                ctx.logger.warn("studio tools unavailable", { error: String(err) });
                 await client.close().catch(() => { });
-                return;
+                throw err;
             }
-            const call = async (tool, args, tctx) => {
-                const result = await client.callTool(tool, args, tctx.signal);
-                const text = result.content
-                    .map((block) => (block.type === "text" ? block.text : ""))
-                    .join("")
-                    .trim();
-                if (result.isError)
-                    throw new Error(text || "the gateway refused the request");
-                return text;
-            };
-            for (const entry of FACADE) {
-                const def = advertised.find((candidate) => candidate.name === entry.upstream);
-                // A tool this gateway does not serve is simply not offered; registering
-                // one from a hardcoded list would put a button here that cannot work.
-                if (!def)
-                    continue;
-                ctx.tools.register(facadeTool(entry, def, call));
+            return client;
+        };
+        /**
+         * The server for the credential as it stands now.
+         *
+         * An account token is renewed while the session runs, and the server
+         * holds whatever key it was started with — so a new token means a new
+         * server. The old one is closed only once nothing is using it: closing
+         * it under a video that is still rendering would throw away a
+         * generation that has already been charged.
+         */
+        let live;
+        const retire = (connection) => {
+            connection.retired = true;
+            if (connection.users === 0) {
+                void connection.client.then((client) => client.close()).catch(() => { });
             }
-        },
-    };
+        };
+        const acquire = async () => {
+            const access = await options.access();
+            if (!access)
+                throw new Error("not signed in — sign in to OHarness to generate media");
+            const signature = `${access.baseUrl}\n${access.key}`;
+            if (live?.signature !== signature) {
+                if (live)
+                    retire(live);
+                const fresh = { signature, client: open(access), users: 0, retired: false };
+                // A server that would not start is not kept: the next call tries again.
+                fresh.client.catch(() => {
+                    if (live === fresh)
+                        live = undefined;
+                });
+                live = fresh;
+            }
+            live.users += 1;
+            return live;
+        };
+        const release = (connection) => {
+            connection.users -= 1;
+            if (connection.retired)
+                retire(connection);
+        };
+        ctx.onDispose(async () => {
+            if (live)
+                retire(live);
+        });
+        /**
+         * Connected during setup, because the tools are built from what the
+         * server says it takes.
+         *
+         * The alternative — connecting on the first call — would mean writing
+         * the parameters out here, and a copy of someone else's parameter list
+         * goes stale silently: a field added upstream would never reach the
+         * gateway, and nothing would report it. One subprocess for an account
+         * that actually has a media gateway is the cheaper mistake.
+         */
+        let advertised;
+        const connection = await acquire().catch(() => undefined);
+        try {
+            if (!connection)
+                throw new Error("could not start the media server");
+            advertised = await (await connection.client).listTools();
+        }
+        catch (err) {
+            // Never fatal. A gateway that cannot be reached is a session without
+            // media tools, not a session that will not start.
+            ctx.logger.warn("studio tools unavailable", { error: String(err) });
+            if (live)
+                retire(live);
+            live = undefined;
+            return false;
+        }
+        finally {
+            if (connection)
+                release(connection);
+        }
+        const call = async (tool, args, tctx) => {
+            const connection = await acquire();
+            let result;
+            try {
+                result = await (await connection.client).callTool(tool, args, tctx.signal);
+            }
+            finally {
+                release(connection);
+            }
+            const text = result.content
+                .map((block) => (block.type === "text" ? block.text : ""))
+                .join("")
+                .trim();
+            if (result.isError)
+                throw new Error(text || "the gateway refused the request");
+            return text;
+        };
+        /**
+         * Whatever the server advertises, less what is withheld.
+         *
+         * Not a list of the tools this file knows: the server gains tools on
+         * its vendor's schedule, and each should reach the model the day it
+         * ships rather than the day a release here catches up. A tool this
+         * gateway does not serve is equally never offered — a button that
+         * cannot work is worse than none.
+         */
+        const taken = new Set();
+        for (const def of advertised) {
+            if (WITHHELD_TOOLS.includes(def.name))
+                continue;
+            const entry = facadeEntry(def.name);
+            // Two upstream names that fold to one here would otherwise have the
+            // second silently replace the first.
+            if (taken.has(entry.name)) {
+                ctx.logger.warn("studio tool skipped: name already taken", { tool: def.name, name: entry.name });
+                continue;
+            }
+            taken.add(entry.name);
+            ctx.tools.register(facadeTool(entry, def, call));
+        }
+        ctx.logger.info("studio tools registered", { tools: taken.size });
+        return true;
+    }
 }
+/** What the model is told when media exists but the user is not signed in. */
+export const SIGN_IN_PROMPT = "Image, video, speech and music generation is available in OHarness, but only with an OHarness " +
+    "account: it is billed to the account's credits, and this user is not signed in. If they ask for " +
+    "media, say so and ask them to sign in — from the account menu in the app, or with " +
+    "`oharness auth login official` in a terminal. The tools appear as soon as they have.";
 /**
- * What each upstream tool is called here, and what it produces.
+ * Look for a newer media server, without anyone waiting on it.
  *
- * The rename is the whole of the mapping. Parameters are not restated: the
- * schema comes from the server, so a model can send anything that server
+ * Unawaited and unthrowing by construction: a slow or absent registry is a
+ * session that keeps the server it has, never one that starts late.
+ */
+function checkForUpdate(logger, signal) {
+    const bundled = bundledOttoport();
+    if (!bundled)
+        return;
+    void updateOttoport({ root: ottoportCacheRoot(), current: bundled.version, signal })
+        .then((result) => {
+        if (result.status === "installed") {
+            logger.info("media server updated; the new version is used from the next session", { version: result.version });
+        }
+        else if (result.status === "failed") {
+            // Debug, not a warning: offline is an ordinary way to be.
+            logger.debug("media server update check failed", { error: result.error });
+        }
+    })
+        .catch(() => { });
+}
+/**
+ * The tools this file knows by name, and what to say about each.
+ *
+ * The rename and the note are the whole of it. Parameters are not restated:
+ * the schema comes from the server, so a model can send anything that server
  * accepts and a parameter added upstream works the day it ships. Writing them
  * out here would be a second, staler copy of somebody else's list — and the
  * failure mode is silent, since a parameter this file has not heard of would
  * simply never reach the gateway.
+ *
+ * A tool missing from here is still offered; see `facadeEntry`.
  */
 export const FACADE = [
     {
@@ -157,25 +345,130 @@ export const FACADE = [
             "full-length track costs several dollars — ask for the length the user actually needs.",
     },
 ];
+const VENDOR_PREFIX = /^ottoport_/;
+/** Said of every tool this file does not know that may spend money. */
+const UNKNOWN_SPEND_NOTE = "Saves what it produces into the workspace and returns the paths. Billed to the user's OHarness " +
+    "credits — do not repeat a call unless the user asked for another.";
+/**
+ * The name a tool is offered under: the known one, or one derived from the
+ * upstream name with the vendor taken off — `ottoport_remove_background`
+ * becomes `RemoveBackground`.
+ */
+export function facadeName(upstream) {
+    const known = FACADE.find((entry) => entry.upstream === upstream);
+    if (known)
+        return known.name;
+    return upstream
+        .replace(VENDOR_PREFIX, "")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+}
+/**
+ * How to present a tool, whether or not this file has heard of it.
+ *
+ * An unknown tool is assumed to spend money unless its name says it only
+ * looks something up. Guessing the other way would let a new paid tool skip
+ * confirmation, and the cost of that guess is a charge the user never agreed
+ * to; guessing this way costs one extra click on a lookup.
+ */
+export function facadeEntry(upstream) {
+    const known = FACADE.find((entry) => entry.upstream === upstream);
+    if (known)
+        return known;
+    const bare = upstream.replace(VENDOR_PREFIX, "");
+    const name = facadeName(upstream);
+    if (/^(list|get|describe|search)_/.test(bare))
+        return { upstream, name, kind: "", note: "" };
+    // Named for what it makes, as a file prefix: `generate_3d` → `3d-…`.
+    const kind = bare
+        .replace(/^generate_/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return { upstream, name, kind: kind || "media", note: UNKNOWN_SPEND_NOTE };
+}
+/** Parameters the account gateway refuses: it delivers results itself. */
+const REFUSED_PARAMETERS = ["webhook_url", "webhook_secret"];
+/**
+ * A server-written description, in this harness's words.
+ *
+ * The vendor's name is not part of the product, and the server's text is full
+ * of it — "through an OttoPort image model", "call ottoport_list_models".
+ * Left alone, the second is worse than cosmetic: it names a tool the model
+ * does not have, under the name it is offered as here. So tool references
+ * become the names they are offered under, the vendor's name is dropped, and
+ * a sentence about something withheld or refused is dropped with it.
+ */
+export function rebrand(text) {
+    const sentences = text.split(/(?<=[.!?])\s+/).flatMap((sentence) => {
+        if (WITHHELD_TOOLS.some((tool) => sentence.includes(tool)))
+            return [];
+        if (!REFUSED_PARAMETERS.some((param) => sentence.includes(param)))
+            return [sentence];
+        // "…returns a video URL, unless `webhook_url` is given." keeps its first
+        // half; a sentence that is only about the webhook goes altogether.
+        const trimmed = sentence.replace(/,[^,]*webhook_(?:url|secret)[^,.!?]*(?=[.!?]?$)/, "");
+        return trimmed === sentence ? [] : [trimmed];
+    });
+    return sentences
+        .join(" ")
+        .replace(/\bottoport_[a-z0-9_]+/g, (tool) => facadeName(tool))
+        .replace(/\b(an?)\s+OttoPort(?:'s)?\s+(\w)/gi, (_m, article, next) => {
+        const vowel = /[aeiou]/i.test(next);
+        const upper = article[0] === "A";
+        return `${vowel ? (upper ? "An" : "an") : upper ? "A" : "a"} ${next}`;
+    })
+        .replace(/\bOttoPort(?:'s)?\s+(\w)/gi, (_m, next, offset, whole) => 
+    // At the start of a sentence the next word now starts it.
+    /(^|[.!?]\s*)$/.test(whole.slice(0, offset)) ? next.toUpperCase() : next)
+        .replace(/\bOttoPort\b/gi, "the gateway");
+}
+/**
+ * The server's input schema, as this harness offers it: descriptions in its
+ * words at every depth, and without the parameters the gateway refuses.
+ */
+export function facadeSchema(inputSchema) {
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (!node || typeof node !== "object")
+            return node;
+        return Object.fromEntries(Object.entries(node).map(([key, value]) => [
+            key,
+            key === "description" && typeof value === "string" ? rebrand(value) : walk(value),
+        ]));
+    };
+    const schema = walk(normalizeObjectSchema((inputSchema ?? {})));
+    if (schema.properties) {
+        schema.properties = Object.fromEntries(Object.entries(schema.properties).filter(([key]) => !REFUSED_PARAMETERS.includes(key)));
+    }
+    if (Array.isArray(schema.required)) {
+        schema.required = schema.required.filter((key) => !REFUSED_PARAMETERS.includes(key));
+    }
+    return schema;
+}
 /** The one parameter that is ours: the gateway has no idea where files go. */
 const PATH_PROPERTY = {
     type: "string",
-    description: `Where to save the result. Relative to the project; default ${DEFAULT_DIR}/.`,
+    description: `Where to save the result, relative to the project: a folder, or a file name (the file gets the ` +
+        `format the model actually returned, so kitten.png may be saved as kitten.jpg). Default ${DEFAULT_DIR}/.`,
 };
 /**
  * One upstream tool, wearing this harness's name and manners.
  *
- * `inputSchema` is the server's own, with `path` added. Nothing validates it
- * here: the server validates its own inputs, and a second opinion derived from
- * its JSON Schema would only be a less accurate one — the same reasoning the
- * MCP tool adapter states.
+ * `inputSchema` is the server's own, rebranded, with `path` added. Nothing
+ * validates it here: the server validates its own inputs, and a second
+ * opinion derived from its JSON Schema would only be a less accurate one —
+ * the same reasoning the MCP tool adapter states.
  */
 export function facadeTool(entry, def, call) {
     const generates = entry.kind !== "";
-    const schema = normalizeObjectSchema(def.inputSchema ?? {});
+    const schema = facadeSchema(def.inputSchema);
     return {
         name: entry.name,
-        description: `${def.description ?? entry.name} ${entry.note}`,
+        description: [rebrand(def.description ?? entry.name), entry.note].filter(Boolean).join(" "),
         inputSchema: {
             ...schema,
             ...(generates
@@ -301,8 +594,7 @@ async function download(url, ctx, into, kind, index) {
 }
 /** One file into the workspace, named for what made it. */
 async function write(bytes, ctx, into, kind, index, extension) {
-    const name = `${kind}-${Date.now()}${index ? `-${index + 1}` : ""}${extension}`;
-    const target = path.join(into ?? DEFAULT_DIR, name);
+    const target = destination(into, kind, index, extension);
     // Through the workspace policy, so a model-supplied `path` cannot write
     // outside the roots this session is allowed to touch.
     const absolute = ctx.host.resolvePath?.(target, "write") ?? path.resolve(ctx.cwd, target);
@@ -310,6 +602,26 @@ async function write(bytes, ctx, into, kind, index, extension) {
     await writeFile(absolute, bytes);
     return path.relative(ctx.cwd, absolute) || absolute;
 }
+/**
+ * Where one output goes: into a folder, or under a name.
+ *
+ * A model asked for "a kitten picture" passes `media/kitten.png` as often as
+ * `media/` — and treating every path as a folder saved that one as
+ * `media/kitten.png/image-….jpg`, a folder named like an image with the image
+ * inside it. A path whose last part has an extension is a file name. The
+ * extension kept is the one the bytes have, because renaming a JPEG to .png
+ * makes a file that some viewers refuse; the name asked for is kept. A second
+ * output of the same call is numbered beside the first.
+ */
+export function destination(into, kind, index, extension) {
+    const numbered = index ? `-${index + 1}` : "";
+    const asked = into ? path.extname(into) : "";
+    if (into && asked && !into.endsWith("/") && !into.endsWith(path.sep)) {
+        const stem = into.slice(0, -asked.length);
+        return `${stem}${numbered}${extension || asked}`;
+    }
+    return path.join(into ?? DEFAULT_DIR, `${kind}-${Date.now()}${numbered}${extension}`);
+}
 /**
  * An extension for a media type, when it says something useful.
  *