@mccaskie-labs/workbench-ai 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-ai
 
+## 0.4.0
+
+### Minor Changes
+
+- The reply drafter (docs/capabilities/04-reply-drafter.md). `ai.reply({ guide, facts, incoming, language, link, note, previous })` drafts a ready-to-paste reply from facts worked out by code and a reply guide (`workbench/replies/<name>.json`, typed by `npx workbench-ai replies generate` into `src/replies.generated.ts`, passed to `createAi` as `replyGuides`). The model places every fact as a token; the package fills the tokens with workbench-country (₱8,500, Saturday, December 12) and checks the finished text, so a price, date, number or address the model typed itself fails the draft, which is written once more and otherwise comes back with `needs_human_check` and its reasons. It asks only for intake's missing or ambiguous fields in the guide's `ask_order`, never one the facts hold, at most `max_questions`; replies in English, Tagalog or Taglish, matching the message by default; checks `never` lines about payment details, discounts and confirming bookings; and puts the link in exactly once. `'@mccaskie-labs/workbench-ai/reply-ui'` draws the box (`renderReplyBox`, `REPLY_SCRIPT`: Copy with a select-all fallback, Write it again), with `wb-reply-*` classes and `REPLY_STYLES` from `./styles`. `npx workbench-ai replies drafts` and `replies pick` make and keep sample replies for a guide.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -53,3 +53,38 @@ npx workbench-ai pick <name> <round>-<draft> [--licence "<the owner's words>"] [
 ```
 
 `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.
+
+## Reply drafts: `ai.reply`
+
+A ready-to-paste reply to a customer's message, from facts your code worked out and a reply guide (docs/capabilities/04-reply-drafter.md). The rule: **facts come from data, words from the AI.** The model places every fact as a token (`{{packages.0.price}}`); the package fills it with workbench-country (₱8,500, Saturday, December 12) and then checks the finished text. A price, date, number or address the model typed itself fails the draft: it is written once more, and if it still fails it comes back with `needs_human_check: true` and the reasons. Nothing is ever sent: a person copies it.
+
+```ts
+import { createAi } from '@mccaskie-labs/workbench-ai'
+import { renderReplyBox, REPLY_SCRIPT } from '@mccaskie-labs/workbench-ai/reply-ui'
+import { REPLY_GUIDES } from './replies.generated'
+
+const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env), url: env.WORKBENCH_GATEWAY_URL, replyGuides: REPLY_GUIDES })
+const draft = await ai.reply({
+  guide: 'venue-quote',
+  facts: { venue_name: 'Villa Sol', date: '2026-12-12', available: 'yes', packages: [{ name: 'Day Use Package', price: '8500.00', max_guests: 20 }] },
+  incoming: { text, intake: read },   // intake's missing and ambiguous fields decide what is asked
+  language: 'match',                  // or 'en', 'tl', 'taglish': the account's own setting
+  link: { url: quoteLink },           // put in exactly once, at {{link}}
+})
+page.body = renderReplyBox(draft, { againAction: `/enquiries/${id}/reply` }) // then REPLY_SCRIPT under the page's nonce
+```
+
+| Export | What it does |
+| --- | --- |
+| `ai.reply(req)` | `{ text, language, asked, answered, needs_human_check, check_reasons, link?, workbench }`. Job `reply.<guide>`, so its spending has its own line. `check_reasons`: `unknown_fact`, `missing_fact`, `too_long`, `ambiguous_incoming`, `language_unsure`, `never_rule`, `contradicts_fact` |
+| `req.note`, `req.previous` | Write it again: the person's note ("make it shorter") and the draft it replaces |
+| `req.fallbackLanguage` | With `match`, the language used when the message's can't be told (flagged `language_unsure`). Default `en` |
+| `checkGuide(json)` | Checks a guide's JSON, naming every problem |
+| `npx workbench-ai replies generate [--check]` | Every `workbench/replies/<name>.json` into `src/replies.generated.ts`: `REPLY_GUIDES` and each guide's facts as a type, so `ai.reply` checks the guide name and facts. `--check` fails when it is out of date |
+| `npx workbench-ai replies drafts <name> [--languages en,taglish] [--facts <file>]` | Two to four sample replies from sample facts, with the development key, written to `workbench/replies/drafts/<name>/` with the round's cost. Three rounds at most |
+| `npx workbench-ai replies pick <name> <round>-<draft>` | Makes that sample the guide's first example |
+| `renderReplyBox(draftOrError, { againAction?, hidden?, language?, words? })` (`/reply-ui`) | The draft in a text box, Copy reply and Write it again. Given the error `ai.reply` threw, a content refusal shows "We can't draft a reply to this one", anything else "Try again". English, Tagalog and Taglish words; a project's `ui.wbreply.*` strings win |
+| `REPLY_SCRIPT` (`/reply-ui`) | Copy with the Clipboard API, and when the browser refuses it, selects the text so the person can copy it |
+| `REPLY_STYLES` (`/styles`) | The `wb-reply-*` classes and `--wb-reply-*` variables, written into the project's `workbench.css` by `npx workbench-ui styles` |
+
+A guide's facts are a small JSON Schema: strings (`format: "date"` for a calendar day), numbers (`x-money: "PHP"` for an amount, given as a number or a decimal string), whole numbers, enums, and lists of these or of flat objects. Booleans and enums like `available` steer the reply but aren't written as tokens. Until the voices' language setting and the Filipino pack are built, the language instruction travels in the drafter's own prompt.

package/dist/ai.js

@@ -4,6 +4,7 @@ import { createCapture, isGatewayMeta, REQUEST_ID_HEADER } from "./capture.js";
 import { errorFromGateway, WorkbenchAiError } from "./errors.js";
 import { gatewayFetch } from "./http.js";
 import { createImages } from "./images.js";
+import { draftReply } from "./replies.js";
 import { SPELLING_NAMES, VOICE_NAMES } from "./writing.js";
 const KEY_PREFIX = {
     development: "wbk_dev_",
@@ -201,7 +202,9 @@ export function createAi(opts) {
         return value;
     }
     const images = createImages({ url, key: opts.key, env, fetch: baseFetch });
-    return { anthropic, text, structured, stream, countTokens, budget, images };
+    const replyWithTemplate = (req) => draftReply(structured, opts.replyGuides, req);
+    const reply = async (req) => (await replyWithTemplate(req)).draft;
+    return { anthropic, text, structured, stream, countTokens, budget, images, reply, replyWithTemplate };
 }
 function params(req, defaultMax) {
     const body = {

package/dist/cli.d.ts

@@ -18,5 +18,7 @@ type Fetch = (url: string) => Promise<{
     arrayBuffer(): Promise<ArrayBuffer>;
 }>;
 export declare function pick(dir: string, args: Args, fetcher?: Fetch): Promise<string[]>;
+/** `replies generate|drafts|pick`. */
+export declare function replies(argv: string[]): Promise<string[]>;
 export declare function main(argv: string[]): Promise<number>;
 export {};

package/dist/cli.js

@@ -11,15 +11,23 @@
 //     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.
+//   workbench-ai replies generate [--check] [dir]
+//   workbench-ai replies drafts <name> [--languages en,taglish] [--facts <file>] [dir]
+//   workbench-ai replies pick <name> <round>-<draft> [dir]
+//     Reply guides (docs/capabilities/04-reply-drafter.md): see replies-gen.ts.
 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";
+import { generate, pickSample, readGuides, sampleDrafts } from "./replies-gen.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]',
+    "       workbench-ai replies generate [--check] [dir]",
+    "       workbench-ai replies drafts <name> [--languages en,taglish] [--facts <file>] [dir]",
+    "       workbench-ai replies pick <name> <round>-<draft> [dir]",
 ].join("\n");
 const NAME = /^[a-z][a-z0-9_]{0,39}$/;
 /** The largest found picture `pick` downloads. */
@@ -224,8 +232,53 @@ export async function pick(dir, args, fetcher = fetch) {
         lines.push("Put the wording into the strings catalogue (see the workbench-strings skill), keyed for where it is shown.");
     return lines;
 }
+/** `replies generate|drafts|pick`. */
+export async function replies(argv) {
+    const [sub, ...rest] = argv;
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--check")
+            flags.check = true;
+        else if (a === "--languages" || a === "--facts") {
+            const v = rest[++i];
+            if (v === undefined)
+                throw new Stop(`${a} needs a value\n${USAGE}`, 2);
+            flags[a.slice(2)] = v;
+        }
+        else if (a.startsWith("--"))
+            throw new Stop(`${a} isn't an option\n${USAGE}`, 2);
+        else
+            positional.push(a);
+    }
+    try {
+        if (sub === "generate")
+            return generate(resolve(positional[0] ?? "."), flags.check === true);
+        if (sub === "drafts" && positional[0]) {
+            const dir = resolve(positional[1] ?? ".");
+            const { key, url } = gatewayFor(dir);
+            const { createAi } = await import("./ai.js");
+            const guides = Object.fromEntries(readGuides(dir).map((g) => [g.name, g]));
+            const ai = createAi({ key, env: "development", url, replyGuides: guides });
+            return await sampleDrafts(dir, positional[0], { ...(typeof flags.languages === "string" ? { languages: flags.languages } : {}), ...(typeof flags.facts === "string" ? { facts: flags.facts } : {}) }, ai);
+        }
+        if (sub === "pick" && positional[0] && positional[1])
+            return pickSample(resolve(positional[2] ?? "."), positional[0], positional[1]);
+    }
+    catch (e) {
+        if (e instanceof Stop)
+            throw e;
+        throw new Stop(e.message, 1);
+    }
+    throw new Stop(USAGE, 2);
+}
 export async function main(argv) {
     try {
+        if (argv[0] === "replies") {
+            console.log((await replies(argv.slice(1))).join("\n"));
+            return 0;
+        }
         const args = parse(argv);
         const command = args.positional[0];
         const rest = args.positional.slice(3);

package/dist/fake.d.ts

@@ -1,4 +1,5 @@
 import { type WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+import type { ReplyGuide } from "./replies.ts";
 import type { Ai } from "./types.ts";
 export interface FakeReply {
     /** Reply text. For `structured`, give `json` instead. */
@@ -51,6 +52,8 @@ export interface FakeScript {
         mode?: "enforce" | "shadow";
     } | null;
     env?: WorkbenchEnv;
+    /** The reply guides `reply` drafts with (the project's REPLY_GUIDES). */
+    replyGuides?: Readonly<Record<string, ReplyGuide>>;
     /** What `images.generate` and `images.search` get back. */
     images?: {
         /** Bytes and model for every image; by default a 1x1 PNG and the alias's target from the manifest. */

package/dist/fake.js

@@ -66,7 +66,7 @@ function fakeSearch(script, body, requestId) {
 export function createFakeAi(script = {}) {
     const env = script.env ?? "development";
     const { fetch, calls } = fakeGateway(script);
-    const ai = createAi({ key: FAKE_KEY[env], env, url: "https://gateway.fake", fetch });
+    const ai = createAi({ key: FAKE_KEY[env], env, url: "https://gateway.fake", fetch, ...(script.replyGuides ? { replyGuides: script.replyGuides } : {}) });
     return Object.assign(ai, { calls });
 }
 /** The fake Gateway on its own, as a `fetch`, for tests that build their own client. */

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { cachedSystem, cachedBlocks, provenance } from "./helpers.ts";
 export { WorkbenchAiError, type AiErrorCode, type AiErrorDetails } from "./errors.ts";
 export { REQUEST_ID_HEADER, type GatewayMeta } from "./capture.ts";
 export { ASPECT_RATIOS } from "./images.ts";
+export { checkDraft, checkGuide, guessLanguage, languageFor, questionsFor, tokensFor, GAP, LANGUAGE_LINES, REPLY_LANGUAGES, REPLY_PROMPT_VERSION, type DraftWithTemplate, type FactSchema, type GuideFacts, type IntakeResult, type ReplyCheckReason, type ReplyDraft, type ReplyExample, type ReplyGuide, type ReplyGuideFacts, type ReplyGuideName, type ReplyLanguage, type ReplyRequest, } from "./replies.ts";
 export { checkWriting, paragraphBands, paragraphTarget, paragraphsOf, writingFixNote, writingNotes, writingStops, SPELLING_NAMES, VOICE_NAMES, type CheckWritingOptions, type OwnVoice, type SpellingName, type VoiceName, type WritingIssue, } from "./writing.ts";
 export type { Ai, AiImages, AiOptions, AspectRatio, GeneratedImage, ImageGenerateRequest, ImageSearchRequest, ImageSearchResult, ImageSearchResults, AiStream, BudgetStatus, ContentBlockParam, CountTokensRequest, Effort, MessageStreamEvent, Provenance, StructuredRequest, StructuredResult, SystemBlock, TextRequest, TextResult, Usage, VoiceUsed, ZodLike, } from "./types.ts";

package/dist/index.js

@@ -4,4 +4,5 @@ export { cachedSystem, cachedBlocks, provenance } from "./helpers.js";
 export { WorkbenchAiError } from "./errors.js";
 export { REQUEST_ID_HEADER } from "./capture.js";
 export { ASPECT_RATIOS } from "./images.js";
+export { checkDraft, checkGuide, guessLanguage, languageFor, questionsFor, tokensFor, GAP, LANGUAGE_LINES, REPLY_LANGUAGES, REPLY_PROMPT_VERSION, } from "./replies.js";
 export { checkWriting, paragraphBands, paragraphTarget, paragraphsOf, writingFixNote, writingNotes, writingStops, SPELLING_NAMES, VOICE_NAMES, } from "./writing.js";

package/dist/replies-gen.d.ts

@@ -0,0 +1,20 @@
+import { type ReplyGuide } from "./replies.ts";
+import type { Ai } from "./types.ts";
+/** The project's guides, checked, by name. Throws naming every bad file. */
+export declare function readGuides(dir: string): ReplyGuide[];
+/** The generated module's text. */
+export declare function repliesModule(guides: readonly ReplyGuide[]): string;
+export interface RepliesPlan {
+    files: Record<string, string>;
+    problems: string[];
+}
+/** What `replies generate` writes, and what --check fails on. */
+export declare function planReplies(dir: string): RepliesPlan;
+export declare function generate(dir: string, check: boolean): string[];
+/** Sample replies for the owner to pick from. */
+export declare function sampleDrafts(dir: string, name: string, o: {
+    languages?: string;
+    facts?: string;
+}, ai: Pick<Ai, "replyWithTemplate">): Promise<string[]>;
+/** Makes a sample the guide's first example. */
+export declare function pickSample(dir: string, name: string, which: string): string[];

package/dist/replies-gen.js

@@ -0,0 +1,188 @@
+// `workbench-ai replies generate|drafts|pick` (docs/capabilities/04-reply-drafter.md):
+//
+//   generate [--check] [dir]   Every guide in <dir>/workbench/replies/*.json into
+//                              src/replies.generated.ts: REPLY_GUIDES for createAi and
+//                              the facts' types for ai.reply. --check writes nothing and
+//                              fails when the file is out of date or a guide is wrong.
+//   drafts <name> [--languages en,taglish] [--facts <file>] [dir]
+//                              Two to four sample replies from sample facts (the guide's
+//                              first example's, or --facts), through the Gateway with the
+//                              development key. Written to workbench/replies/drafts/<name>/.
+//   pick <name> <round>-<draft> [dir]
+//                              Makes that sample the guide's first example.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkGuide, REPLY_LANGUAGES } from "./replies.js";
+const REPLIES_MODULE = "src/replies.generated.ts";
+const REPLIES_FOLDER = "workbench/replies";
+/** Rounds of sample replies per guide. */
+const REPLY_MAX_ROUNDS = 3;
+const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+/** The project's guides, checked, by name. Throws naming every bad file. */
+export function readGuides(dir) {
+    const folder = join(dir, REPLIES_FOLDER);
+    if (!existsSync(folder))
+        return [];
+    const problems = [];
+    const guides = [];
+    for (const file of readdirSync(folder).filter((f) => f.endsWith(".json")).sort()) {
+        const where = `${REPLIES_FOLDER}/${file}`;
+        try {
+            const g = checkGuide(JSON.parse(read(join(folder, file))), where);
+            if (`${g.name}.json` !== file)
+                throw new Error(`${where}: the file is named after its guide (${g.name}.json)`);
+            guides.push(g);
+        }
+        catch (e) {
+            problems.push(e.message);
+        }
+    }
+    if (problems.length)
+        throw new Error(problems.join("\n"));
+    return guides;
+}
+const pascal = (name) => name.replace(/(^|[-_])([a-z0-9])/g, (_m, _s, c) => c.toUpperCase());
+function tsType(s, indent) {
+    switch (s.type) {
+        case "string":
+            return s.enum ? s.enum.map((e) => JSON.stringify(e)).join(" | ") : "string";
+        case "number":
+        case "integer":
+            return s["x-money"] ? "number | string" : "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return `readonly (${s.items ? tsType(s.items, indent) : "unknown"})[]`;
+        case "object": {
+            const req = new Set(s.required ?? []);
+            const fields = Object.entries(s.properties ?? {}).map(([k, p]) => `${indent}  ${k}${req.has(k) ? "" : "?"}: ${tsType(p, `${indent}  `)};`);
+            return `{\n${fields.join("\n")}\n${indent}}`;
+        }
+    }
+}
+/** The generated module's text. */
+export function repliesModule(guides) {
+    const out = [
+        "// Generated by `npx workbench-ai replies generate` from workbench/replies/*.json.",
+        "// Don't edit it: change the guide and run the command again.",
+        "",
+        'import type { ReplyGuide } from "@mccaskie-labs/workbench-ai";',
+        "",
+    ];
+    for (const g of guides) {
+        out.push(`/** The facts of the reply guide "${g.name}", version ${g.version}. */`);
+        out.push(`export interface ${pascal(g.name)}Facts ${tsType(g.facts, "")}`, "");
+    }
+    out.push('declare module "@mccaskie-labs/workbench-ai" {', "  interface ReplyGuideFacts {");
+    for (const g of guides)
+        out.push(`    ${JSON.stringify(g.name)}: ${pascal(g.name)}Facts;`);
+    out.push("  }", "}", "");
+    out.push("/** Pass to createAi as `replyGuides`. */");
+    out.push(`export const REPLY_GUIDES: Readonly<Record<${guides.length ? guides.map((g) => JSON.stringify(g.name)).join(" | ") : "string"}, ReplyGuide>> = ${JSON.stringify(Object.fromEntries(guides.map((g) => [g.name, withoutSchema(g)])), null, 2)};`, "");
+    return out.join("\n");
+}
+function withoutSchema(g) {
+    const { $schema: _drop, ...rest } = g;
+    return rest;
+}
+/** What `replies generate` writes, and what --check fails on. */
+export function planReplies(dir) {
+    const plan = { files: {}, problems: [] };
+    if (!existsSync(join(dir, "package.json"))) {
+        plan.problems.push(`${dir} is not a project (no package.json)`);
+        return plan;
+    }
+    let guides;
+    try {
+        guides = readGuides(dir);
+    }
+    catch (e) {
+        plan.problems.push(e.message);
+        return plan;
+    }
+    const path = join(dir, REPLIES_MODULE);
+    if (guides.length === 0 && !existsSync(path))
+        return plan;
+    const text = repliesModule(guides);
+    if (!existsSync(path) || read(path) !== text) {
+        plan.files[REPLIES_MODULE] = text;
+        plan.problems.push(`${REPLIES_MODULE} is out of date with ${REPLIES_FOLDER}/: run npx workbench-ai replies generate`);
+    }
+    return plan;
+}
+export function generate(dir, check) {
+    const plan = planReplies(dir);
+    const bad = plan.problems.filter((p) => !p.startsWith(REPLIES_MODULE));
+    if (bad.length)
+        throw new Error(bad.join("\n"));
+    if (check) {
+        if (plan.problems.length)
+            throw new Error(plan.problems.join("\n"));
+        return ["Reply guides are up to date."];
+    }
+    for (const [file, text] of Object.entries(plan.files)) {
+        mkdirSync(join(dir, file, ".."), { recursive: true });
+        writeFileSync(join(dir, file), text);
+    }
+    return Object.keys(plan.files).length ? [`Wrote ${REPLIES_MODULE}.`] : ["Nothing to change."];
+}
+/** Sample replies for the owner to pick from. */
+export async function sampleDrafts(dir, name, o, ai) {
+    const guide = readGuides(dir).find((g) => g.name === name);
+    if (!guide)
+        throw new Error(`There is no guide ${REPLIES_FOLDER}/${name}.json`);
+    const facts = o.facts ? JSON.parse(read(join(dir, o.facts))) : guide.examples?.find((e) => e.facts)?.facts;
+    if (!facts)
+        throw new Error("No sample facts: give --facts <file.json>, or put facts on the guide's first example");
+    const languages = (o.languages ?? "en,taglish").split(",").map((l) => l.trim());
+    if (languages.some((l) => !REPLY_LANGUAGES.includes(l)))
+        throw new Error(`--languages is a list of ${REPLY_LANGUAGES.join(", ")}`);
+    // Two to four drafts: one per language, and a second wording when only one is asked for.
+    const plan = languages.slice(0, 4).map((language) => ({ language }));
+    if (plan.length === 1)
+        plan.push({ language: plan[0].language, note: "Write a different version: other words, same facts." });
+    const folder = join(dir, REPLIES_FOLDER, "drafts", name);
+    const roundsFile = join(folder, "rounds.json");
+    const rounds = existsSync(roundsFile) ? JSON.parse(read(roundsFile)) : { rounds: [] };
+    const round = rounds.rounds.length + 1;
+    if (round > REPLY_MAX_ROUNDS)
+        throw new Error(`${name} has had ${REPLY_MAX_ROUNDS} rounds of samples. Ask the owner to pick one, or to write an example themselves.`);
+    const done = { round, cost_usd: 0, drafts: [] };
+    for (const p of plan) {
+        const r = await ai.replyWithTemplate({ guide: name, facts, language: p.language, ...(p.note ? { note: p.note } : {}) });
+        done.drafts.push({ language: p.language, template: r.template, text: r.draft.text, request_id: r.draft.workbench.request_id, model: r.draft.workbench.model, cost_usd: r.draft.workbench.cost_usd });
+        done.cost_usd += r.draft.workbench.cost_usd;
+    }
+    done.cost_usd = Math.round(done.cost_usd * 1e6) / 1e6;
+    mkdirSync(folder, { recursive: true });
+    rounds.rounds.push(done);
+    writeFileSync(roundsFile, json(rounds));
+    const cards = done.drafts.map((d, i) => `<section><h2>${round}-${i + 1} (${d.language})</h2><p>${esc(d.text)}</p></section>`).join("");
+    writeFileSync(join(folder, `round-${round}.html`), `<!doctype html><meta charset="utf-8"><title>${esc(name)}: round ${round}</title><style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}section{border-top:1px solid #ccc;padding:1rem 0}</style><h1>${esc(name)}: round ${round}</h1>${cards}`);
+    return [
+        `Round ${round} of ${REPLY_MAX_ROUNDS} for ${name}: ${done.drafts.length} samples. This round cost US$${done.cost_usd.toFixed(2)}.`,
+        ...done.drafts.map((d, i) => `  ${round}-${i + 1} (${d.language}): ${d.text}`),
+        `Preview: ${REPLIES_FOLDER}/drafts/${name}/round-${round}.html`,
+        `Keep the owner's choice with: npx workbench-ai replies pick ${name} <round>-<draft>`,
+    ];
+}
+/** Makes a sample the guide's first example. */
+export function pickSample(dir, name, which) {
+    if (!/^\d+-\d+$/.test(which))
+        throw new Error("Pick a sample as <round>-<draft>, such as 1-2");
+    const [round, n] = which.split("-").map(Number);
+    const roundsFile = join(dir, REPLIES_FOLDER, "drafts", name, "rounds.json");
+    if (!existsSync(roundsFile))
+        throw new Error(`There are no samples for ${name}`);
+    const d = JSON.parse(read(roundsFile)).rounds.find((r) => r.round === round)?.drafts[n - 1];
+    if (!d)
+        throw new Error(`There is no sample ${which} for ${name}`);
+    const file = join(dir, REPLIES_FOLDER, `${name}.json`);
+    const guide = JSON.parse(read(file));
+    const facts = guide.examples?.length ? guide.examples[0].facts : undefined;
+    guide.examples = [{ language: d.language, ...(facts ? { facts } : {}), text: d.template }, ...(guide.examples ?? [])].slice(0, 4);
+    writeFileSync(file, json(guide));
+    return [`${REPLIES_FOLDER}/${name}.json now starts with sample ${which} as its example. Run npx workbench-ai replies generate.`];
+}

package/dist/replies.d.ts

@@ -0,0 +1,211 @@
+import type { StructuredRequest, StructuredResult } from "./types.ts";
+import { type SpellingName, type VoiceName } from "./writing.ts";
+/** The version of the drafter's own instructions, sent as the prompt version with the guide's. */
+export declare const REPLY_PROMPT_VERSION = "2026-11-13";
+export type ReplyLanguage = "en" | "tl" | "taglish";
+export declare const REPLY_LANGUAGES: readonly ReplyLanguage[];
+/**
+ * Why a draft needs a person to check it before it is copied. The first five
+ * are the spec's; `never_rule` (a guide's `never` line matched) and
+ * `contradicts_fact` (the text says something a fact rules out, such as
+ * "available" when `available` is `no`) were added in the build.
+ */
+export type ReplyCheckReason = "unknown_fact" | "missing_fact" | "too_long" | "ambiguous_incoming" | "language_unsure" | "never_rule" | "contradicts_fact";
+/** One field of a guide's facts: a small JSON Schema. */
+export interface FactSchema {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: readonly string[];
+    /** `date`: a calendar day, YYYY-MM-DD, written by the country pack. */
+    format?: "date";
+    /** A money amount in this currency (ISO 4217, e.g. PHP), written by the country pack. A number, or a decimal string such as workbench-availability's "8500.00". */
+    "x-money"?: string;
+    /** A personal detail (a name), as intake marks them. */
+    "x-personal"?: string;
+    items?: FactSchema;
+    maxItems?: number;
+    properties?: Readonly<Record<string, FactSchema>>;
+    required?: readonly string[];
+}
+export interface ReplyExample {
+    language: ReplyLanguage;
+    facts?: Readonly<Record<string, unknown>>;
+    /** The reply with its tokens, as the model should write it. */
+    text: string;
+}
+/** A reply guide: `workbench/replies/<name>.json` in the project. */
+export interface ReplyGuide {
+    format: 1;
+    name: string;
+    version: number;
+    /** A Workbench voice. Default `conversational`. */
+    voice?: VoiceName;
+    /** Default from the country: en-PH for PH. */
+    spelling?: SpellingName;
+    /** The country pack that writes amounts and dates (PH, AU, GB, US). Default: the spelling's country. */
+    country?: string;
+    /** A Workbench alias. Default `claude-default`. */
+    model?: string;
+    /** Default 90. Up to 1.25 times passes quietly; past 2 times the draft fails `too_long`. */
+    max_words?: number;
+    /** Default 2. */
+    max_questions?: number;
+    facts: FactSchema & {
+        type: "object";
+        properties: Readonly<Record<string, FactSchema>>;
+    };
+    /** The fields a reply may ask for, most important first. Only these are ever asked. */
+    ask_order?: readonly string[];
+    /** Plain sentences the owner edits: how to answer. */
+    guide: readonly string[];
+    examples?: readonly ReplyExample[];
+    /** What a reply must never do. Each goes into the prompt; the ones code can see are also checked. */
+    never?: readonly string[];
+}
+/**
+ * Each guide's facts, by guide name. Empty here; a project's generated
+ * `src/replies.generated.ts` adds its guides to it, so `ai.reply` checks the
+ * guide name and the facts' types.
+ */
+export interface ReplyGuideFacts {
+}
+export type ReplyGuideName = [keyof ReplyGuideFacts] extends [never] ? string : Extract<keyof ReplyGuideFacts, string>;
+export type GuideFacts<G extends string> = G extends keyof ReplyGuideFacts ? ReplyGuideFacts[G] : Readonly<Record<string, unknown>>;
+/** What intake returned for the message (docs/message-intake.md §2), the parts the drafter reads. */
+export interface IntakeResult {
+    type: string;
+    type_version?: number;
+    confidence?: number;
+    data: Readonly<Record<string, unknown>> | null;
+    missing: readonly string[];
+    ambiguous: readonly {
+        field: string;
+        reason?: string;
+        options?: readonly unknown[];
+    }[];
+    assumptions?: readonly {
+        field: string;
+        note: string;
+    }[];
+    raw_text?: string;
+    /** ISO 639-1 codes seen in the message. */
+    languages?: readonly string[];
+    needs_human_check: boolean;
+    check_reasons: readonly string[];
+    workbench?: {
+        request_id: string;
+        receipt?: unknown;
+        [key: string]: unknown;
+    };
+}
+export interface ReplyRequest<G extends string = ReplyGuideName> {
+    guide: G;
+    facts: GuideFacts<G>;
+    /** The message being answered. Intake's `missing` and `ambiguous` decide what is asked. */
+    incoming?: {
+        text: string;
+        intake?: IntakeResult;
+    };
+    /** Default `match`: the language the message is in. */
+    language?: ReplyLanguage | "match";
+    /** With `match`, the language used when the message's language can't be told. Default `en`. */
+    fallbackLanguage?: ReplyLanguage;
+    /** "Make it shorter", "don't mention the pool": as Imprint's Write it again. */
+    note?: string;
+    /** The draft being replaced. */
+    previous?: string;
+    /**
+     * The link to put at `{{link}}`, exactly once. Until short links (capability 3)
+     * are built, the app passes the finished address. `false` or left out: no link.
+     */
+    link?: {
+        url: string;
+    } | false;
+    subject?: {
+        type: string;
+        id: string;
+    };
+    /** The app's account (plans, capability 6). Not sent yet. */
+    account?: string;
+    /** As on every call: false marks it do-not-keep. */
+    keep?: boolean;
+}
+export interface ReplyDraft {
+    /** Ready to paste. */
+    text: string;
+    language: ReplyLanguage;
+    /** The fields it asked for. */
+    asked: string[];
+    /** The facts it used. */
+    answered: string[];
+    needs_human_check: boolean;
+    check_reasons: ReplyCheckReason[];
+    /** The link put in, when there was one. */
+    link?: {
+        url: string;
+    };
+    workbench: {
+        request_id: string;
+        cost_usd: number;
+        model: string;
+        alias: string;
+    };
+}
+/** A draft and the token text it was filled from (what `replies pick` keeps as an example). */
+export interface DraftWithTemplate {
+    draft: ReplyDraft;
+    template: string;
+}
+/** Checks a guide's JSON and returns it typed, or throws an Error naming every problem. */
+export declare function checkGuide(value: unknown, where?: string): ReplyGuide;
+interface Token {
+    /** The token's name, as written between the braces: `packages.0.price`. */
+    name: string;
+    /** The top-level fact it comes from: `packages`. */
+    fact: string;
+    /** The finished words: ₱8,500. */
+    value: string;
+    /** Other ways the same fact may be written and still pass the check (8,500 for ₱8,500). */
+    also: string[];
+}
+/** Every token the facts give, with its finished words. Booleans and empty facts give none. */
+export declare function tokensFor(guide: ReplyGuide, facts: Readonly<Record<string, unknown>>): Map<string, Token>;
+/** The fields the draft asks for: intake's missing and ambiguous fields in the guide's ask_order, none the facts hold, at most max_questions. */
+export declare function questionsFor(guide: ReplyGuide, facts: Readonly<Record<string, unknown>>, intake: IntakeResult | undefined): string[];
+/** A rough reading of a short message's language, for `match` when intake gave none, and for the tests' checker. */
+export declare function guessLanguage(text: string): ReplyLanguage | undefined;
+/** The reply's language and whether it had to fall back. */
+export declare function languageFor(req: Pick<ReplyRequest, "language" | "fallbackLanguage" | "incoming">): {
+    language: ReplyLanguage;
+    unsure: boolean;
+};
+/**
+ * How each language is written. Until the voices' language setting and the
+ * Filipino pack are built (docs/spec.md §2.8), these lines go in the guide's
+ * prompt; they move there when they are.
+ */
+export declare const LANGUAGE_LINES: Readonly<Record<ReplyLanguage, string>>;
+interface Problem {
+    reason: ReplyCheckReason | "writing";
+    detail: string;
+}
+interface CheckedDraft {
+    text: string;
+    problems: Problem[];
+    answered: string[];
+}
+/** Where a fact couldn't be filled: plain for the person checking to see and fill in. */
+export declare const GAP = "___";
+/** Fills the tokens and checks the finished text. Plain code: no AI. */
+export declare function checkDraft(raw: string, ctx: {
+    guide: ReplyGuide;
+    facts: Readonly<Record<string, unknown>>;
+    tokens: Map<string, Token>;
+    link?: {
+        url: string;
+    } | false;
+}): CheckedDraft;
+type StructuredFn = <T>(req: StructuredRequest<T>) => Promise<StructuredResult<T>>;
+/** The drafter: one call, and one more when the check fails. Returns the draft and the token text it was filled from. */
+export declare function draftReply(structured: StructuredFn, guides: Readonly<Record<string, ReplyGuide>> | undefined, req: ReplyRequest<string>): Promise<DraftWithTemplate>;
+export {};