@mccaskie-labs/workbench-ai 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mccaskie-labs/workbench-ai
 
+## 0.3.0
+
+### Minor Changes
+
+- Client questions for AI, pictures and picture search (feature or content): a routing question, then who may use a visitor feature and its monthly cap, or drafts of content made once. `npx workbench-ai drafts text|image|search` and `pick` make and keep that content through the Gateway with the development key. A drafts skill with no development key now offers the client's own wording or picture as well as the standard version.
+
+### Patch Changes
+
+- Updated dependencies
+  - @mccaskie-labs/workbench-config@0.2.4
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -40,3 +40,16 @@ Every result carries the **resolved** model id (never the alias), the Gateway's
 The package doesn't retry: the Gateway already does (3 attempts on transient failures). Error codes: `refused`, `truncated`, `invalid_output`, `unexpected_stop`, and the Gateway's `unauthorised`, `forbidden_scope`, `invalid_request`, `model_not_allowed`, `budget_exceeded`, `rate_limited`, `not_found`, `not_available`, `upstream_error`, `upstream_timeout`, `internal_error`, plus `network` and `invalid_config`.
 
 Runs on Node 24 and the Cloudflare Workers runtime. `zod` 4 is a peer dependency.
+
+## Content made once: `npx workbench-ai`
+
+For wording or a picture made once for a site, rather than a feature visitors use (docs/capabilities-manifest.md §9.8). Run in the project's folder; it uses the development key (`WORKBENCH_GATEWAY_KEY` starting `wbk_dev_`) in `.dev.vars` and the Gateway address from `.dev.vars` or `wrangler.jsonc`.
+
+```
+npx workbench-ai drafts text <name> --about "<what it is for>" [--count 3] [--spelling en-AU]
+npx workbench-ai drafts image <name> --about "<what it shows>" [--aspect 3:2] [--count 3]
+npx workbench-ai drafts search <name> --about "<what to search for>" [--count 4]
+npx workbench-ai pick <name> <round>-<draft> [--licence "<the owner's words>"] [--replace]
+```
+
+`drafts` writes the drafts and a preview page to `workbench/<ai|images|image-search>/drafts/<name>/` (keep it out of git), prints what the round cost, and stops after three rounds. `pick` keeps one in `workbench/<tool>/<name>.json`, and for a picture writes `public/images/<name>.<ext>`. A found picture needs `--licence`. Exit codes: 2 for a bad command, 3 for no development key or Gateway address, 4 after the last round.

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { type ContentAi } from "./content.ts";
+/** Rounds of drafts per piece (the offers' drafts.max_rounds), counted in the drafts folder's rounds.json. */
+export declare const MAX_ROUNDS = 3;
+interface Args {
+    positional: string[];
+    flags: Record<string, string | true>;
+}
+/** Simple KEY=value lines; quotes around a value are dropped. Values are never printed. */
+export declare function readDevVars(text: string): Record<string, string>;
+export declare function drafts(dir: string, args: Args, ai?: ContentAi): Promise<string[]>;
+type Fetch = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export declare function pick(dir: string, args: Args, fetcher?: Fetch): Promise<string[]>;
+export declare function main(argv: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Content made once for a site (docs/capabilities-manifest.md §9.8), run in a
+// project's folder:
+//
+//   workbench-ai drafts text|image|search <name> --about "<what it is for>" [--count 3] [--aspect 3:2] [--spelling en-AU] [dir]
+//     Drafts through the Workbench Gateway with the project's development key
+//     from .dev.vars. Writes each draft and a preview page to
+//     workbench/<tool>/drafts/<name>/ (not committed) and prints what the
+//     round cost.
+//   workbench-ai pick <name> <round>-<draft> [--licence "<the owner's words>"] [--replace] [dir]
+//     Keeps that draft: workbench/<tool>/<name>.json, and for a picture the
+//     file in public/images/. A found picture needs --licence: what the owner
+//     said gives the site the right to use it.
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ASPECT_RATIOS, CONTENT_KINDS, draftContent } from "./content.js";
+/** Rounds of drafts per piece (the offers' drafts.max_rounds), counted in the drafts folder's rounds.json. */
+export const MAX_ROUNDS = 3;
+const USAGE = [
+    'usage: workbench-ai drafts text|image|search <name> --about "<what it is for>" [--count 3] [--aspect 3:2] [--spelling en-AU] [dir]',
+    '       workbench-ai pick <name> <round>-<draft> [--licence "<the owner\'s words>"] [--replace] [dir]',
+].join("\n");
+const NAME = /^[a-z][a-z0-9_]{0,39}$/;
+/** The largest found picture `pick` downloads. */
+const MAX_DOWNLOAD = 10 * 1024 * 1024;
+const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const dollars = (n) => `US$${n.toFixed(2)}`;
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const extFor = (mime) => (mime === "image/jpeg" ? "jpg" : mime === "image/webp" ? "webp" : "png");
+class Stop extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+function parse(argv) {
+    const out = { positional: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith("--"))
+            out.positional.push(a);
+        else if (a === "--replace")
+            out.flags.replace = true;
+        else if (!["--about", "--count", "--aspect", "--spelling", "--licence"].includes(a))
+            throw new Stop(`${a} isn't an option\n${USAGE}`, 2);
+        else {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Stop(`${a} needs a value\n${USAGE}`, 2);
+            out.flags[a.slice(2)] = v;
+        }
+    }
+    return out;
+}
+/** Simple KEY=value lines; quotes around a value are dropped. Values are never printed. */
+export function readDevVars(text) {
+    const vars = {};
+    for (const line of text.split("\n")) {
+        const m = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+        if (m)
+            vars[m[1]] = m[2].replace(/^(["'])(.*)\1$/, "$2");
+    }
+    return vars;
+}
+/** The development key and the Gateway's address: .dev.vars first, then wrangler.jsonc's vars for the address. */
+function gatewayFor(dir) {
+    const vars = existsSync(join(dir, ".dev.vars")) ? readDevVars(read(join(dir, ".dev.vars"))) : {};
+    const key = vars.WORKBENCH_GATEWAY_KEY;
+    if (!key || !key.startsWith("wbk_dev_")) {
+        throw new Stop("No development key: .dev.vars has no WORKBENCH_GATEWAY_KEY starting wbk_dev_. Drafts need one, so ask the owner for the wording or picture instead. Never ask for a key in chat: the owner adds it to .dev.vars.", 3);
+    }
+    let url = vars.WORKBENCH_GATEWAY_URL;
+    if (!url && existsSync(join(dir, "wrangler.jsonc")))
+        url = /"WORKBENCH_GATEWAY_URL"\s*:\s*"([^"]+)"/.exec(read(join(dir, "wrangler.jsonc")))?.[1];
+    if (!url || !/^https:\/\//.test(url))
+        throw new Stop("No Gateway address: set WORKBENCH_GATEWAY_URL in wrangler.jsonc's vars or .dev.vars.", 3);
+    return { key, url };
+}
+/** Where a piece's drafts are, whichever kind it is: a name is used by one kind only. */
+function findDrafts(dir, name) {
+    for (const kind of Object.keys(CONTENT_KINDS)) {
+        const folder = join(dir, CONTENT_KINDS[kind].folder, "drafts", name);
+        if (existsSync(join(folder, "rounds.json")))
+            return { kind, folder };
+    }
+    return undefined;
+}
+const readRounds = (folder) => (existsSync(join(folder, "rounds.json")) ? JSON.parse(read(join(folder, "rounds.json"))) : { rounds: [] });
+export async function drafts(dir, args, ai) {
+    const [, kind, name] = args.positional;
+    const about = args.flags.about;
+    if (!kind || !(kind in CONTENT_KINDS) || !name || !NAME.test(name) || typeof about !== "string" || about.trim() === "")
+        throw new Stop(USAGE, 2);
+    const k = kind;
+    const count = Number(args.flags.count ?? (k === "search" ? 4 : 3));
+    if (!Number.isInteger(count) || count < 2 || count > 4)
+        throw new Stop("--count must be 2, 3 or 4", 2);
+    const aspect = args.flags.aspect;
+    if (aspect !== undefined && (k !== "image" || !ASPECT_RATIOS.includes(aspect)))
+        throw new Stop(`--aspect is for pictures, and must be one of ${ASPECT_RATIOS.join(" ")}`, 2);
+    const spelling = args.flags.spelling;
+    if (spelling !== undefined && !["en-AU", "en-PH", "en-GB", "en-US"].includes(spelling))
+        throw new Stop("--spelling must be en-AU, en-PH, en-GB or en-US", 2);
+    if (!existsSync(join(dir, "package.json")))
+        throw new Stop(`${dir} has no package.json: run this in the project's folder`, 2);
+    const other = findDrafts(dir, name);
+    if (other && other.kind !== k)
+        throw new Stop(`${name} already has ${other.kind} drafts: give this piece another name.`, 2);
+    const folder = join(dir, CONTENT_KINDS[k].folder, "drafts", name);
+    const history = readRounds(folder);
+    const round = history.rounds.length + 1;
+    if (round > MAX_ROUNDS)
+        throw new Stop(`${name} has had ${MAX_ROUNDS} rounds of drafts. Ask the owner to pick one of them, or to give the wording or picture themselves.`, 4);
+    const client = ai ?? (await gatewayAi(dir));
+    const r = await draftContent(client, { kind: k, name, about, count, ...(aspect ? { aspect: aspect } : {}), ...(spelling ? { spelling: spelling } : {}), seen: history.rounds.flatMap((x) => x.ideas) });
+    mkdirSync(folder, { recursive: true });
+    // The round is recorded before anything else can fail, so a paid round is always counted.
+    history.rounds.push({ round, kind: k, about, cost_usd: r.costUsd, calls: r.calls.map((c) => ({ request_id: c.requestId, model: c.model, cost_usd: c.costUsd })), ideas: r.drafts.map((d) => d.idea) });
+    writeFileSync(join(folder, "rounds.json"), json(history));
+    const rel = `${CONTENT_KINDS[k].folder}/drafts/${name}`;
+    const lines = [`Round ${round} of ${MAX_ROUNDS} for ${name}: ${r.drafts.length} draft${r.drafts.length === 1 ? "" : "s"}. This round cost ${dollars(r.costUsd)}.`];
+    const cards = [];
+    for (const [i, d] of r.drafts.entries()) {
+        const id = `${round}-${i + 1}`;
+        const saved = { idea: d.idea };
+        let shown = "";
+        if (d.text !== undefined) {
+            saved.text = d.text;
+            shown = d.text.split(/\n{2,}/).map((p) => `<p>${esc(p)}</p>`).join("");
+        }
+        else if (d.image) {
+            const file = `${id}.${extFor(d.image.mimeType)}`;
+            writeFileSync(join(folder, file), d.image.bytes);
+            Object.assign(saved, { prompt: d.prompt, file, mime_type: d.image.mimeType, model: d.image.model, request_id: d.image.requestId });
+            shown = `<img src="${file}" alt="">`;
+        }
+        else if (d.found) {
+            saved.found = d.found;
+            shown = `<img src="${esc(d.found.thumbnailUrl)}" alt=""><p><a href="${esc(d.found.pageUrl)}">${esc(d.found.site)}</a>: check its licence before using it.</p>`;
+        }
+        writeFileSync(join(folder, `${id}.json`), json(saved));
+        cards.push(`<section><h2>${id}</h2><p><strong>${esc(d.idea)}</strong></p>${shown}</section>`);
+        lines.push(`  ${id}: ${d.idea}`);
+    }
+    const page = `<!doctype html><meta charset="utf-8"><title>${esc(name)}: round ${round}</title><style>body{font:16px/1.5 system-ui,sans-serif;max-width:60rem;margin:2rem auto;padding:0 1rem}section{border-top:1px solid #ccc;padding:1rem 0}img{max-width:100%;height:auto}</style><h1>${esc(name)}: round ${round}</h1>${cards.join("")}`;
+    writeFileSync(join(folder, `round-${round}.html`), page);
+    lines.push(`Preview: ${rel}/round-${round}.html`);
+    for (const why of r.failed)
+        lines.push(`  (${why})`);
+    if (r.drafts.length === 0)
+        throw new Stop(`${lines.join("\n")}\nNo drafts this round. Run it again with other words, or ask the owner for the wording or picture.`, 1);
+    lines.push(`Show the owner the preview, then keep their choice with: npx workbench-ai pick ${name} <round>-<draft>${k === "search" ? ' --licence "<what the owner said gives the site the right to use it>"' : ""}`);
+    return lines;
+}
+async function gatewayAi(dir) {
+    const { key, url } = gatewayFor(dir);
+    const { createAi } = await import("./ai.js");
+    return createAi({ key, env: "development", url });
+}
+export async function pick(dir, args, fetcher = fetch) {
+    const [, name, which] = args.positional;
+    if (!name || !NAME.test(name) || !which || !/^\d+-\d+$/.test(which))
+        throw new Stop(USAGE, 2);
+    const found = findDrafts(dir, name);
+    if (!found)
+        throw new Stop(`There are no drafts for ${name}.`, 2);
+    const { kind, folder } = found;
+    const src = join(folder, `${which}.json`);
+    if (!existsSync(src))
+        throw new Stop(`There is no draft ${which} for ${name}.`, 2);
+    const [round, draft] = which.split("-").map(Number);
+    const meta = readRounds(folder).rounds.find((r) => r.round === round);
+    if (!meta)
+        throw new Stop(`${name}'s rounds.json has no round ${round}.`, 2);
+    const target = join(dir, CONTENT_KINDS[kind].folder, `${name}.json`);
+    if (existsSync(target) && args.flags.replace !== true)
+        throw new Stop(`${CONTENT_KINDS[kind].folder}/${name}.json is already saved. Pass --replace once the owner has agreed to replace it.`, 2);
+    const licence = args.flags.licence;
+    if (kind === "search" && (typeof licence !== "string" || licence.trim().length < 3)) {
+        throw new Stop("A found picture needs --licence: ask the owner what gives the site the right to use it (their own photo, a free licence and its name, permission from the owner), in their words.", 2);
+    }
+    const d = JSON.parse(read(src));
+    const picked = { round, draft, cost_usd: meta.cost_usd, calls: meta.calls };
+    const saved = { format: 1, route: "content", kind, name, about: meta.about, idea: d.idea };
+    const lines = [];
+    if (kind === "text") {
+        saved.text = d.text;
+    }
+    else {
+        const images = join(dir, "public/images");
+        mkdirSync(images, { recursive: true });
+        let file;
+        if (kind === "image") {
+            file = `public/images/${name}.${extFor(d.mime_type)}`;
+            writeFileSync(join(dir, file), readFileSync(join(folder, d.file)));
+            Object.assign(saved, { prompt: d.prompt, model: d.model, request_id: d.request_id });
+        }
+        else {
+            const f = d.found;
+            if (!f.imageUrl.startsWith("https://"))
+                throw new Stop(`${which}'s picture isn't on https, so it isn't downloaded.`, 1);
+            const res = await fetcher(f.imageUrl);
+            const type = (res.headers.get("content-type") ?? "").split(";")[0].trim();
+            if (!res.ok || !["image/png", "image/jpeg", "image/webp"].includes(type))
+                throw new Stop(`${which}'s picture couldn't be downloaded (HTTP ${res.status}, ${type || "no type"}). Pick another.`, 1);
+            const bytes = new Uint8Array(await res.arrayBuffer());
+            if (bytes.byteLength > MAX_DOWNLOAD)
+                throw new Stop(`${which}'s picture is over 10 MB. Pick another.`, 1);
+            file = `public/images/${name}.${extFor(type)}`;
+            writeFileSync(join(dir, file), bytes);
+            Object.assign(saved, { source: { title: f.title, site: f.site, page_url: f.pageUrl, image_url: f.imageUrl, width: f.width, height: f.height }, licence: licence.trim() });
+        }
+        saved.file = file;
+        lines.push(`Saved ${file}.`);
+    }
+    saved.picked = picked;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, json(saved));
+    lines.unshift(`Saved ${CONTENT_KINDS[kind].folder}/${name}.json from draft ${which}.`);
+    if (kind === "text")
+        lines.push("Put the wording into the strings catalogue (see the workbench-strings skill), keyed for where it is shown.");
+    return lines;
+}
+export async function main(argv) {
+    try {
+        const args = parse(argv);
+        const command = args.positional[0];
+        const rest = args.positional.slice(3);
+        const dir = resolve(rest[0] ?? ".");
+        const lines = command === "drafts" ? await drafts(dir, args) : command === "pick" ? await pick(dir, args) : null;
+        if (!lines)
+            throw new Stop(USAGE, 2);
+        console.log(lines.join("\n"));
+        return 0;
+    }
+    catch (e) {
+        console.error(e.message);
+        return e instanceof Stop ? e.exitCode : 1;
+    }
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
+    process.exitCode = await main(process.argv.slice(2));

package/dist/content.d.ts

@@ -0,0 +1,128 @@
+import type { AspectRatio } from "./types.ts";
+/** The part of the Ai client the drafts need. */
+export interface ContentAi {
+    structured<T>(req: {
+        model: string;
+        job: string;
+        system: string;
+        prompt: string;
+        schema: {
+            safeParse(v: unknown): {
+                success: true;
+                data: T;
+            } | {
+                success: false;
+                error: {
+                    message: string;
+                };
+            };
+        };
+        spelling?: "en-AU" | "en-PH" | "en-GB" | "en-US";
+        maxTokens?: number;
+        promptVersion?: string;
+    }): Promise<{
+        data: T;
+        model: string;
+        requestId: string;
+        costUsd: number;
+    }>;
+    images: {
+        generate(req: {
+            prompt: string;
+            aspectRatio: AspectRatio;
+            job: string;
+            model?: string;
+            promptVersion?: string;
+        }): Promise<{
+            bytes: Uint8Array;
+            mimeType: string;
+            model: string;
+            requestId: string;
+            costUsd: number;
+        }>;
+        search(req: {
+            q: string;
+            job: string;
+            num?: number;
+        }): Promise<{
+            title: string;
+            imageUrl: string;
+            thumbnailUrl: string;
+            width: number;
+            height: number;
+            source: string;
+            pageUrl: string;
+        }[] & {
+            requestId: string;
+            costUsd: number;
+        }>;
+    };
+}
+/** The three kinds, each the content route of one tool, with the folder its answers go in. */
+export declare const CONTENT_KINDS: {
+    readonly text: {
+        readonly tool: "ai";
+        readonly folder: "workbench/ai";
+        readonly job: "ai.drafts";
+    };
+    readonly image: {
+        readonly tool: "images";
+        readonly folder: "workbench/images";
+        readonly job: "images.drafts";
+    };
+    readonly search: {
+        readonly tool: "image-search";
+        readonly folder: "workbench/image-search";
+        readonly job: "image-search.drafts";
+    };
+};
+export type ContentKind = keyof typeof CONTENT_KINDS;
+export declare const ASPECT_RATIOS: readonly AspectRatio[];
+export interface ContentRequest {
+    kind: ContentKind;
+    /** The piece's name: about_us, home_hero. */
+    name: string;
+    /** What it is for, in the owner's words. */
+    about: string;
+    count: number;
+    aspect?: AspectRatio;
+    spelling?: "en-AU" | "en-PH" | "en-GB" | "en-US";
+    /** Ideas from earlier rounds, so a new round tries something else. */
+    seen?: string[];
+}
+/** One draft: its idea, and the wording, the picture or the search result. */
+interface ContentDraft {
+    idea: string;
+    text?: string;
+    prompt?: string;
+    image?: {
+        bytes: Uint8Array;
+        mimeType: string;
+        model: string;
+        requestId: string;
+    };
+    found?: {
+        title: string;
+        imageUrl: string;
+        thumbnailUrl: string;
+        width: number;
+        height: number;
+        site: string;
+        pageUrl: string;
+    };
+}
+export interface ContentRound {
+    drafts: ContentDraft[];
+    /** Each paid call in the round. */
+    calls: {
+        requestId: string;
+        model: string;
+        costUsd: number;
+    }[];
+    costUsd: number;
+    /** Drafts that failed, with the reason (a picture the provider didn't make). */
+    failed: string[];
+}
+/** One round of drafts. Every paid call is in `calls`, even when a draft fails. */
+export declare function draftContent(ai: ContentAi, req: ContentRequest): Promise<ContentRound>;
+export {};

package/dist/content.js

@@ -0,0 +1,80 @@
+// Content made once for a site (docs/capabilities-manifest.md §9.8): wording,
+// a picture made by AI, or a picture found on the web. `npx workbench-ai
+// drafts` offers a few to pick from, through the Workbench Gateway with the
+// project's development key, and `pick` keeps the one the owner chose. This
+// module holds the calls and their prompts; it takes the AI client as a
+// parameter so tests can script it.
+import { z } from "zod";
+/** The three kinds, each the content route of one tool, with the folder its answers go in. */
+export const CONTENT_KINDS = {
+    text: { tool: "ai", folder: "workbench/ai", job: "ai.drafts" },
+    image: { tool: "images", folder: "workbench/images", job: "images.drafts" },
+    search: { tool: "image-search", folder: "workbench/image-search", job: "image-search.drafts" },
+};
+export const ASPECT_RATIOS = ["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"];
+const TEXT_MODEL = "claude-default";
+const IMAGE_MODEL = "image-default";
+const PROMPT_VERSION = "content-drafts-1";
+const TEXT_SYSTEM = `You write wording for a small business's website: a page's main text, a short blurb, a product or service description. Write it for the people who will read it on the site, in plain words, short sentences and short paragraphs.
+
+Never invent facts about the business: no prices, dates, numbers, awards, names, places or promises the owner didn't give you. Where the wording needs a fact you don't have, write it in square brackets for the owner to fill in, like [year founded].
+
+Make each draft clearly different from the others in what it says first, its length and its tone, not just in wording. Start each with one plain sentence (idea) that tells the owner what is different about it.`;
+const IMAGE_SYSTEM = `You write prompts for an AI image model, for pictures on a small business's website. Each prompt describes one picture in concrete visual terms: the subject, the setting, the light, the style and the framing. No text, letters, logos or brand names in the picture, and no real, identifiable people.
+
+Make each prompt clearly different from the others in subject, style or composition, not just in wording. Start each with one plain sentence (idea) that tells the owner what the picture shows and how it differs.`;
+const textReply = z.object({ drafts: z.array(z.object({ idea: z.string(), text: z.string() })) });
+const promptReply = z.object({ drafts: z.array(z.object({ idea: z.string(), prompt: z.string() })) });
+function prompt(req, what) {
+    return [
+        `Name: ${req.name.replace(/_/g, " ")}.`,
+        `What the owner said it is for: ${req.about}`,
+        ...(req.aspect ? [`Shape: ${req.aspect} (width:height).`] : []),
+        `Make ${req.count} ${what}.`,
+        ...(req.seen?.length ? [`The owner has already seen these and wants something different:\n${req.seen.map((s) => `- ${s}`).join("\n")}`] : []),
+    ].join("\n");
+}
+/** One round of drafts. Every paid call is in `calls`, even when a draft fails. */
+export async function draftContent(ai, req) {
+    const job = CONTENT_KINDS[req.kind].job;
+    const out = { drafts: [], calls: [], costUsd: 0, failed: [] };
+    const paid = (c) => {
+        out.calls.push({ requestId: c.requestId, model: c.model, costUsd: c.costUsd });
+        out.costUsd += c.costUsd;
+    };
+    const spelling = req.spelling ? { spelling: req.spelling } : {};
+    if (req.kind === "text") {
+        const r = await ai.structured({ model: TEXT_MODEL, job, system: TEXT_SYSTEM, prompt: prompt(req, "drafts"), schema: textReply, maxTokens: 8000, promptVersion: PROMPT_VERSION, ...spelling });
+        paid(r);
+        for (const d of r.data.drafts.slice(0, req.count))
+            if (d.text.trim())
+                out.drafts.push({ idea: d.idea, text: d.text.trim() });
+        return out;
+    }
+    if (req.kind === "image") {
+        const aspectRatio = req.aspect ?? "3:2";
+        const r = await ai.structured({ model: TEXT_MODEL, job, system: IMAGE_SYSTEM, prompt: prompt(req, "picture prompts"), schema: promptReply, maxTokens: 4000, promptVersion: PROMPT_VERSION, ...spelling });
+        paid(r);
+        for (const [i, d] of r.data.drafts.slice(0, req.count).entries()) {
+            try {
+                const img = await ai.images.generate({ prompt: d.prompt, aspectRatio, job, model: IMAGE_MODEL, promptVersion: PROMPT_VERSION });
+                paid(img);
+                out.drafts.push({ idea: d.idea, prompt: d.prompt, image: { bytes: img.bytes, mimeType: img.mimeType, model: img.model, requestId: img.requestId } });
+            }
+            catch (e) {
+                out.failed.push(`picture ${i + 1}: ${e.message}`);
+            }
+        }
+        return out;
+    }
+    // A search: the owner's words are the query, and the first results wide enough for a web page are offered.
+    const results = await ai.images.search({ q: req.about, job, num: 10 });
+    paid({ requestId: results.requestId, model: "serper", costUsd: results.costUsd });
+    for (const f of results.filter((x) => x.imageUrl.startsWith("https://") && x.width >= 600).slice(0, req.count)) {
+        out.drafts.push({
+            idea: `${f.title} (${f.source}, ${f.width}×${f.height})`,
+            found: { title: f.title, imageUrl: f.imageUrl, thumbnailUrl: f.thumbnailUrl, width: f.width, height: f.height, site: f.source, pageUrl: f.pageUrl },
+        });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-ai",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Claude through the Workbench Gateway: text, structured output, streaming and budget status, with no Anthropic key in the app. Refusals and truncations throw; createFakeAi for tests.",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,6 +20,9 @@
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "workbench-ai": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md",
@@ -36,7 +39,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^1.5.0",
-    "@mccaskie-labs/workbench-config": "^0.2.0"
+    "@mccaskie-labs/workbench-config": "^0.2.4"
   },
   "peerDependencies": {
     "zod": "^4.1.0"