@mccaskie-labs/workbench-ai 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mccaskie-labs/workbench-ai
 
+## 0.1.5
+
+### Patch Changes
+
+- Kept calls (`docs/spec.md` §2.9): a `keep` option on `text`, `structured`, `stream`, `countTokens`, `images.generate` and `images.search`. `keep: false` sends `X-Workbench-Keep: no`, so the Gateway keeps the call's facts but not its text; a refused call is kept whatever it says. `subject` is documented as how a person's kept calls are found: an app with signed-in users sends `user:<its own user id>`. `createFakeAi` records `keep` on each call.
+
+## 0.1.4
+
+### Patch Changes
+
+- Shared voices (`docs/spec.md` §2.8). `workbench-ai`: `voice` and `spelling` options on `text`, `structured`, `stream` and `countTokens` (a Workbench voice by name, or `{ instructions }` for the app's own), `voice` on a text result, and a writing check with no AI call: `checkWriting`, `writingStops`, `writingNotes`, `writingFixNote`, `paragraphBands`. Paragraph length is a target: quiet up to 1.25 times, a note up to double, a stop only past that. `createFakeAi` records the voice and spelling of each call. `workbench-config`: the `ai` manifest lists the voices, spellings, targets and banned phrases, and three probes. `workbench-ai` now needs `workbench-config` 0.1.14.
+- Updated dependencies
+  - @mccaskie-labs/workbench-config@0.1.12
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,10 @@ await save({ text: r.text, model: r.model, requestId: r.requestId })
 | `ai.budget()` | `{ status: 'ok' \| 'warn' \| 'reached', leftUsd, monthlyUsd, spentUsd, mode, month }` for this key's project and environment, cached 60 s |
 | `ai.images.generate({ prompt, aspectRatio, job, model?, references? })` | One image: `{ bytes, mimeType, model, requestId, costUsd }`. `model` is `image-default` (the default), `image-pro` or `image-openai`; `references` work on the Google aliases only. Needs the `images` scope |
 | `ai.images.search({ q, job, num?, gl?, hl? })` | Serper image search: a list of `{ title, imageUrl, thumbnailUrl, width, height, source, pageUrl }` that also carries `requestId`, `costUsd` and `credits`. Needs the `search` scope |
+| `voice`, `spelling` on `text`, `structured`, `stream`, `countTokens` | `voice: 'conversational'` (or `casual`, `plain`, `formal`, `strict-formal`) has the Gateway add Workbench's house writing standards and that voice ahead of your system prompt; `spelling: 'en-AU'` (or `en-PH`, `en-GB`, `en-US`) adds one line. The text is the same bytes for every app, so it is cached and shared. `voice: { instructions }` is your own voice: it goes first in your own system prompt and no Workbench writing rule is added. A text result carries `voice: { name, spelling, version }` when one was named |
+| `subject`, `keep` on every call | The Gateway keeps what each call sent and got back, for audit (`docs/spec.md` §2.9). `subject: 'user:<id>'` (your own user id, never a name or email address) is how a person's calls are found and deleted. `keep: false` keeps the call's facts but not its text; a refused call is kept whatever it says |
+| `checkWriting(text, { voice?, paragraphTarget?, exempt? })` | Checks text against the house standards with no AI call. Stops: long dashes and the banned phrases. Paragraph length is a target: no issue up to 1.25 times it, a note up to double, a stop only past double. Sentence length is never an issue. `exempt` is required wording to leave out |
+| `writingStops(issues)`, `writingNotes(issues)`, `writingFixNote(issues)` | The stops, the notes, and the text to add to a prompt when asking once more after a stop |
 | `ai.anthropic` | The official `@anthropic-ai/sdk` client pointed at the Gateway, for anything else |
 | `createFakeAi(script)` | The real client against a scripted fake Gateway, for tests: replies in order, refusals, truncations and Gateway errors, every call recorded in `.calls`. No key, no network |
 | `cachedSystem(stable, ...volatile)`, `cachedBlocks(...texts)` | System blocks with a prompt-cache breakpoint |

package/dist/ai.js

@@ -5,6 +5,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 { SPELLING_NAMES, VOICE_NAMES } from "./writing.js";
 const KEY_PREFIX = {
     development: "wbk_dev_",
     staging: "wbk_stg_",
@@ -59,6 +60,24 @@ export function createAi(opts) {
                 throw new WorkbenchAiError("invalid_request", "subject must be type:id");
             h["X-Workbench-Subject"] = req.subject;
         }
+        if (req.keep === false)
+            h["X-Workbench-Keep"] = "no";
+        // Checked here too, so a wrong name fails before the network. The Gateway refuses it as well.
+        if (typeof req.voice === "string") {
+            if (!VOICE_NAMES.includes(req.voice))
+                throw new WorkbenchAiError("invalid_request", `voice must be one of ${VOICE_NAMES.join(", ")}, or { instructions } for the app's own`);
+            h["X-Workbench-Voice"] = req.voice;
+        }
+        else if (req.voice !== undefined && !isOwnVoice(req.voice)) {
+            throw new WorkbenchAiError("invalid_request", "an own voice needs its instructions");
+        }
+        if (req.spelling !== undefined) {
+            // Any case, as the Gateway takes it.
+            const spelling = SPELLING_NAMES.find((n) => n.toLowerCase() === String(req.spelling).toLowerCase());
+            if (spelling === undefined)
+                throw new WorkbenchAiError("invalid_request", `spelling must be one of ${SPELLING_NAMES.join(", ")}`);
+            h["X-Workbench-Spelling"] = spelling;
+        }
         return h;
     }
     async function create(body, req) {
@@ -160,7 +179,7 @@ export function createAi(opts) {
             const r = await client(cap.fetch).messages.countTokens({
                 model: req.model,
                 messages: [{ role: "user", content: req.prompt }],
-                ...(req.system !== undefined ? { system: req.system } : {}),
+                ...withOwnVoice(req),
             }, { headers: headers(req) });
             return { inputTokens: r.input_tokens };
         }
@@ -187,12 +206,26 @@ function params(req, defaultMax) {
         max_tokens: req.maxTokens ?? defaultMax,
         messages: [{ role: "user", content: req.prompt }],
     };
-    if (req.system !== undefined)
-        body.system = req.system;
+    Object.assign(body, withOwnVoice(req));
     if (req.effort !== undefined)
         body.output_config = { effort: req.effort };
     return body;
 }
+/**
+ * The app's system prompt. An own voice goes first in it, as the app's own block: the Gateway adds
+ * nothing for it, and its own content rules still come before everything.
+ */
+function withOwnVoice(req) {
+    if (!isOwnVoice(req.voice))
+        return req.system !== undefined ? { system: req.system } : {};
+    const own = { type: "text", text: req.voice.instructions };
+    if (req.system === undefined || req.system === "")
+        return { system: [own] };
+    return { system: [own, ...(typeof req.system === "string" ? [{ type: "text", text: req.system }] : req.system)] };
+}
+function isOwnVoice(v) {
+    return typeof v === "object" && v !== null && typeof v.instructions === "string" && v.instructions.trim() !== "";
+}
 function metaOf(message, cap) {
     const meta = message.workbench;
     if (isGatewayMeta(meta))
@@ -219,7 +252,14 @@ export function toTextResult(message, meta) {
         .filter((b) => b.type === "text")
         .map((b) => b.text)
         .join("");
-    return { text, model: meta.model, requestId: meta.request_id, usage: usageOf(message.usage), costUsd: meta.cost_usd };
+    return {
+        text,
+        model: meta.model,
+        requestId: meta.request_id,
+        usage: usageOf(message.usage),
+        costUsd: meta.cost_usd,
+        ...(meta.voice ? { voice: meta.voice } : {}),
+    };
 }
 function usageOf(u) {
     return {

package/dist/capture.d.ts

@@ -8,6 +8,12 @@ export interface GatewayMeta {
     refused?: boolean;
     alias?: string | null;
     attempts?: number;
+    /** Present when the call named a Workbench voice or spelling (docs/spec.md §2.8). */
+    voice?: {
+        name: string | null;
+        spelling: string | null;
+        version: number;
+    };
 }
 export interface Capture {
     fetch: typeof fetch;

package/dist/fake.d.ts

@@ -28,6 +28,11 @@ export interface FakeCall {
     job: string | null;
     promptVersion: string | null;
     subject: string | null;
+    /** False when the call was marked do-not-keep (X-Workbench-Keep: no, docs/spec.md §2.9). */
+    keep: boolean;
+    /** The Workbench voice and spelling named (X-Workbench-Voice, X-Workbench-Spelling). */
+    voice: string | null;
+    spelling: string | null;
     /** The parsed JSON body (Anthropic Messages request), if any. */
     body: Record<string, unknown> | null;
     stream: boolean;

package/dist/fake.js

@@ -90,6 +90,9 @@ export function fakeGateway(script = {}) {
             job: req.headers.get("x-workbench-job"),
             promptVersion: req.headers.get("x-workbench-prompt-version"),
             subject: req.headers.get("x-workbench-subject"),
+            keep: req.headers.get("x-workbench-keep")?.toLowerCase() !== "no",
+            voice: req.headers.get("x-workbench-voice"),
+            spelling: req.headers.get("x-workbench-spelling"),
             body,
             stream: body?.["stream"] === true,
         };
@@ -113,6 +116,19 @@ export function fakeGateway(script = {}) {
             return fakeImage(script, body, requestId);
         if (url.pathname === "/v1/images/search")
             return fakeSearch(script, body, requestId);
+        if (url.pathname.startsWith("/anthropic/")) {
+            // As the Gateway does: an unknown name is refused, and a spelling is read in any case.
+            const allowed = capabilities.ai.allowed;
+            if (call.voice !== null && !allowed.voices.some((v) => v.name === call.voice)) {
+                return anthropicError(400, requestId, "invalid_request", `X-Workbench-Voice must be one of ${allowed.voices.map((v) => v.name).join(", ")}.`);
+            }
+            if (call.spelling !== null) {
+                const named = allowed.spellings.find((x) => x.toLowerCase() === call.spelling.toLowerCase());
+                if (named === undefined)
+                    return anthropicError(400, requestId, "invalid_request", `X-Workbench-Spelling must be one of ${allowed.spellings.join(", ")}.`);
+                call.spelling = named;
+            }
+        }
         if (url.pathname === "/anthropic/v1/messages/count_tokens") {
             return json(200, requestId, { input_tokens: script.inputTokens ?? 12 });
         }
@@ -164,6 +180,9 @@ export function fakeGateway(script = {}) {
             cost_usd: reply.costUsd ?? 0.0001,
             refused: stopReason === "refusal",
             attempts: 1,
+            ...(call.voice !== null || call.spelling !== null
+                ? { voice: { name: call.voice, spelling: call.spelling, version: capabilities.ai.allowed.writing.voice_set_version } }
+                : {}),
         };
         if (call.stream)
             return sse(requestId, message, meta);

package/dist/images.js

@@ -17,6 +17,8 @@ function headers(req) {
             throw new WorkbenchAiError("invalid_request", "subject must be type:id");
         h["X-Workbench-Subject"] = req.subject;
     }
+    if (req.keep === false)
+        h["X-Workbench-Keep"] = "no";
     return h;
 }
 function toBase64(bytes) {

package/dist/index.d.ts

@@ -4,4 +4,5 @@ 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 type { Ai, AiImages, AiOptions, AspectRatio, GeneratedImage, ImageGenerateRequest, ImageSearchRequest, ImageSearchResult, ImageSearchResults, AiStream, BudgetStatus, ContentBlockParam, CountTokensRequest, Effort, MessageStreamEvent, Provenance, StructuredRequest, StructuredResult, SystemBlock, TextRequest, TextResult, Usage, ZodLike, } from "./types.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,3 +4,4 @@ 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 { checkWriting, paragraphBands, paragraphTarget, paragraphsOf, writingFixNote, writingNotes, writingStops, SPELLING_NAMES, VOICE_NAMES, } from "./writing.js";

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type Anthropic from "@anthropic-ai/sdk";
 import type { WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+import type { OwnVoice, SpellingName, VoiceName } from "./writing.ts";
 export type SystemBlock = Anthropic.TextBlockParam;
 export type ContentBlockParam = Anthropic.ContentBlockParam;
 export type MessageStreamEvent = Anthropic.MessageStreamEvent;
@@ -24,8 +25,26 @@ export interface TextRequest {
     maxTokens?: number;
     effort?: Effort;
     promptVersion?: string;
-    /** `type:id` of the thing the call is about. */
+    /**
+     * How the text reads (docs/spec.md §2.8). A name asks the Gateway to add Workbench's house writing
+     * standards and that voice ahead of `system`, the same bytes for every app, so they are cached and
+     * shared. `{ instructions }` is the app's own voice: it goes first in the app's own system prompt and
+     * no Workbench writing rule is added. Left out, nothing is added.
+     */
+    voice?: VoiceName | OwnVoice;
+    /** The spelling to write in. The Gateway adds one line for it. Separate from the voice. */
+    spelling?: SpellingName;
+    /**
+     * `type:id` of the thing the call is about. An app with signed-in users sends `user:<its own user id>`
+     * (never a name, email address or phone number), so a person's kept calls can be found and deleted.
+     */
     subject?: string;
+    /**
+     * False marks this call do-not-keep (`X-Workbench-Keep: no`): the Gateway keeps its facts but
+     * not its text (docs/spec.md §2.9). A refused call is kept whatever this says. Left out, the
+     * project's own setting decides.
+     */
+    keep?: boolean;
 }
 export interface StructuredRequest<T> extends TextRequest {
     /** A zod schema. Its JSON Schema is sent as `output_config.format`; the reply is validated against it. */
@@ -59,6 +78,14 @@ export interface TextResult {
     requestId: string;
     usage: Usage;
     costUsd: number;
+    /** The Workbench voice and spelling the Gateway added, and the version of that text. Absent when none was named. */
+    voice?: VoiceUsed;
+}
+/** What wrote the text: store it with the output, beside the model. */
+export interface VoiceUsed {
+    name: VoiceName | null;
+    spelling: SpellingName | null;
+    version: number;
 }
 export interface StructuredResult<T> {
     data: T;
@@ -72,6 +99,9 @@ export interface CountTokensRequest {
     job: string;
     system?: string | SystemBlock[];
     prompt: string | ContentBlockParam[];
+    /** As on a text call, so the count includes what the Gateway adds. */
+    voice?: VoiceName | OwnVoice;
+    spelling?: SpellingName;
 }
 export interface BudgetStatus {
     /** `ok` below the warning level, `warn` at or above it, `reached` at or above the cap. */
@@ -116,6 +146,12 @@ export interface ImageGenerateRequest {
     }[];
     promptVersion?: string;
     subject?: string;
+    /**
+     * False marks this call do-not-keep (`X-Workbench-Keep: no`): the Gateway keeps its facts but
+     * not its text (docs/spec.md §2.9). A refused call is kept whatever this says. Left out, the
+     * project's own setting decides.
+     */
+    keep?: boolean;
 }
 export interface GeneratedImage {
     bytes: Uint8Array;
@@ -136,6 +172,12 @@ export interface ImageSearchRequest {
     /** Language, e.g. `en`. */
     hl?: string;
     subject?: string;
+    /**
+     * False marks this call do-not-keep (`X-Workbench-Keep: no`): the Gateway keeps its facts but
+     * not its text (docs/spec.md §2.9). A refused call is kept whatever this says. Left out, the
+     * project's own setting decides.
+     */
+    keep?: boolean;
 }
 export interface ImageSearchResult {
     title: string;

package/dist/writing.d.ts

@@ -0,0 +1,104 @@
+declare const allowed: {
+    readonly aliases: readonly [{
+        readonly alias: "claude-default";
+        readonly provider: "anthropic";
+        readonly default_model: "claude-sonnet-5-5";
+    }, {
+        readonly alias: "claude-best";
+        readonly provider: "anthropic";
+        readonly default_model: "claude-opus-5-5";
+    }, {
+        readonly alias: "claude-fast";
+        readonly provider: "anthropic";
+        readonly default_model: "claude-haiku-5-5";
+    }];
+    readonly explicit_models: readonly ["claude-sonnet-5", "claude-opus-5"];
+    readonly server_tools: readonly ["web_search", "web_fetch", "code_execution"];
+    readonly required_headers: readonly ["X-Workbench-Job"];
+    readonly optional_headers: readonly ["X-Workbench-Voice", "X-Workbench-Spelling"];
+    readonly voices: readonly [{
+        readonly name: "casual";
+        readonly paragraph_target: 50;
+        readonly sentence_target: 18;
+    }, {
+        readonly name: "conversational";
+        readonly paragraph_target: 60;
+        readonly sentence_target: 22;
+    }, {
+        readonly name: "plain";
+        readonly paragraph_target: 60;
+        readonly sentence_target: 20;
+    }, {
+        readonly name: "formal";
+        readonly paragraph_target: 80;
+        readonly sentence_target: 25;
+    }, {
+        readonly name: "strict-formal";
+        readonly paragraph_target: 80;
+        readonly sentence_target: 28;
+    }];
+    readonly spellings: readonly ["en-AU", "en-PH", "en-GB", "en-US"];
+    readonly writing: {
+        readonly voice_set_version: 1;
+        readonly house_paragraph_target: 80;
+        readonly paragraph_grace: 1.25;
+        readonly paragraph_ceiling: 2;
+        readonly banned_phrases: readonly ["delve", "it's worth noting", "it is worth noting", "it's important to note", "it is important to note", "in today's fast-paced world", "navigate the complexities", "a testament to", "game-changer", "game-changing", "let's dive in", "dive into", "rest assured", "in conclusion", "at the end of the day", "the world of", "unlock the", "embark on", "tapestry"];
+    };
+};
+export type VoiceName = (typeof allowed.voices)[number]["name"];
+export type SpellingName = (typeof allowed.spellings)[number];
+/** The Workbench voices an app can name. */
+export declare const VOICE_NAMES: readonly VoiceName[];
+/** The spellings an app can name. */
+export declare const SPELLING_NAMES: readonly SpellingName[];
+/** An app's own voice: its instructions go in the app's own system prompt, and no Workbench writing rule is added. */
+export interface OwnVoice {
+    instructions: string;
+}
+export interface WritingIssue {
+    /** `stop`: the text breaks a hard limit, so fix or retry it. `note`: worth showing, never a reason to retry. */
+    severity: "stop" | "note";
+    rule: "long-dash" | "banned-phrase" | "paragraph-length";
+    issue: string;
+    /** A short quote from the text, where one helps. */
+    location?: string;
+    suggestion?: string;
+}
+export interface CheckWritingOptions {
+    /** The voice the text was written in. Sets the paragraph target; left out, the house target applies. */
+    voice?: VoiceName;
+    /** Overrides the paragraph target, in words. */
+    paragraphTarget?: number;
+    /** Required wording (a disclaimer, a quotation) that must be copied exactly, so it is left out of the check. */
+    exempt?: string[];
+}
+/** The word counts for a paragraph target: the target, where a note starts (above `grace`) and where a stop starts (above `ceiling`). */
+export declare function paragraphBands(target: number): {
+    target: number;
+    grace: number;
+    ceiling: number;
+};
+/** The paragraph target for a voice, in words. Never above the house target. */
+export declare function paragraphTarget(voice?: VoiceName): number;
+/** The issues that are stops. */
+export declare const writingStops: (issues: readonly WritingIssue[]) => WritingIssue[];
+/** The notes only. */
+export declare const writingNotes: (issues: readonly WritingIssue[]) => WritingIssue[];
+/**
+ * A Markdown text's paragraphs and list items, without headings, tables and code. As in Markdown, a
+ * blank line ends a paragraph and a single line break doesn't.
+ */
+export declare function paragraphsOf(text: string): string[];
+/**
+ * Checks text written for a reader against the Workbench house standards and
+ * a voice's paragraph target. Makes no AI call. An app that brought its own
+ * voice has its own rules, so this check isn't for its text.
+ */
+export declare function checkWriting(text: string, opts?: CheckWritingOptions): WritingIssue[];
+/**
+ * Text to add to a prompt that is asked once more because its answer broke the house standards.
+ * Only the stops are listed: a note is never a reason to ask again. Empty when there is no stop.
+ */
+export declare function writingFixNote(issues: readonly WritingIssue[]): string;
+export {};

package/dist/writing.js

@@ -0,0 +1,209 @@
+// The writing check, with no AI (docs/spec.md §2.8): does a text keep the
+// Workbench house standards and its voice's targets? Brought over from
+// Imprint's checkWritingStyle. The names and figures come from the manifest
+// (capabilities/ai.json), which the Gateway's own text is tested against, so
+// what the model was told and what is checked here can't drift apart.
+//
+// Two things are hard limits: long dashes and the banned phrases. Paragraph
+// length is a target (Robert, 11 November 2026, as in Imprint): up to target x
+// grace passes with no note, up to target x ceiling passes with a note, and
+// only past the ceiling is it a stop. A long sentence is never an issue.
+import { capabilities } from "@mccaskie-labs/workbench-config";
+const allowed = capabilities.ai.allowed;
+const writing = allowed.writing;
+/** The Workbench voices an app can name. */
+export const VOICE_NAMES = allowed.voices.map((v) => v.name);
+/** The spellings an app can name. */
+export const SPELLING_NAMES = [...allowed.spellings];
+/** The word counts for a paragraph target: the target, where a note starts (above `grace`) and where a stop starts (above `ceiling`). */
+export function paragraphBands(target) {
+    return { target, grace: Math.round(target * writing.paragraph_grace), ceiling: Math.round(target * writing.paragraph_ceiling) };
+}
+/** The paragraph target for a voice, in words. Never above the house target. */
+export function paragraphTarget(voice) {
+    const v = allowed.voices.find((x) => x.name === voice);
+    return Math.min(v?.paragraph_target ?? writing.house_paragraph_target, writing.house_paragraph_target);
+}
+/** The issues that are stops. */
+export const writingStops = (issues) => issues.filter((i) => i.severity === "stop");
+/** The notes only. */
+export const writingNotes = (issues) => issues.filter((i) => i.severity === "note");
+const LONG_DASH_RE = /—|\s–\s|\s-\s/g;
+/** A spaced hyphen between two numbers is arithmetic, not punctuation. */
+const BETWEEN_NUMBERS_RE = /\d\s-\s\d/;
+const MOST = 6;
+function quoteAround(text, index) {
+    const start = Math.max(0, index - 40);
+    const end = Math.min(text.length, index + 40);
+    return (start > 0 ? "…" : "") + text.slice(start, end).replace(/\s+/g, " ").trim() + (end < text.length ? "…" : "");
+}
+function firstWords(text, n = 12) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ");
+    return words.slice(0, n).join(" ") + (words.length > n ? "…" : "");
+}
+function wordCount(text) {
+    const t = text.replace(/[*_`#>[\]()]/g, " ").trim();
+    return t ? t.split(/\s+/).length : 0;
+}
+/**
+ * A Markdown text's paragraphs and list items, without headings, tables and code. As in Markdown, a
+ * blank line ends a paragraph and a single line break doesn't.
+ */
+export function paragraphsOf(text) {
+    const out = [];
+    let inCode = false;
+    let current = [];
+    const flush = () => {
+        if (current.length)
+            out.push(current.join(" ").trim());
+        current = [];
+    };
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("```")) {
+            flush();
+            inCode = !inCode;
+            continue;
+        }
+        if (inCode)
+            continue;
+        if (!line || /^#{1,6}\s/.test(line) || line.startsWith("|") || /^(-{3,}|\*{3,})$/.test(line)) {
+            flush();
+            continue;
+        }
+        if (/^([-*+]|\d+[.)])\s+/.test(line)) {
+            flush();
+            current.push(line.replace(/^([-*+]|\d+[.)])\s+/, ""));
+            continue;
+        }
+        current.push(line.replace(/^>\s?/, ""));
+    }
+    flush();
+    return out.filter(Boolean);
+}
+function paragraphIssues(paragraphs, target) {
+    const { grace, ceiling } = paragraphBands(target);
+    const counted = paragraphs.map((p) => ({ p, words: wordCount(p) }));
+    const stops = counted.filter((x) => x.words > ceiling);
+    const notes = counted.filter((x) => x.words > grace && x.words <= ceiling);
+    const out = [];
+    for (const x of stops.slice(0, MOST)) {
+        out.push({
+            severity: "stop",
+            rule: "paragraph-length",
+            issue: `A paragraph has ${x.words} words; the limit is ${ceiling} (aim for ${target}).`,
+            location: `"${firstWords(x.p)}"`,
+            suggestion: "Cut filler and repetition first. If it is still long, split it into two paragraphs with one idea each.",
+        });
+    }
+    if (stops.length > MOST) {
+        out.push({
+            severity: "stop",
+            rule: "paragraph-length",
+            issue: `${stops.length - MOST} more paragraphs are over the ${ceiling}-word limit (aim for ${target}).`,
+            suggestion: "Shorten every paragraph over the limit.",
+        });
+    }
+    for (const x of notes.slice(0, MOST)) {
+        out.push({
+            severity: "note",
+            rule: "paragraph-length",
+            issue: `Long paragraph: ${x.words} words, and the target is ${target}. Consider splitting it.`,
+            location: `"${firstWords(x.p)}"`,
+            suggestion: "Two paragraphs with one idea each read more easily.",
+        });
+    }
+    if (notes.length > MOST) {
+        out.push({ severity: "note", rule: "paragraph-length", issue: `${notes.length - MOST} more long paragraphs are over the ${target}-word target. Consider splitting them.` });
+    }
+    return out;
+}
+/**
+ * The prose of a Markdown text, for the dash and phrase checks: fenced code, inline code and table
+ * rows are taken out (the standards don't apply to code or data), quote marks and list markers are
+ * dropped from the start of each line, and a typographic apostrophe reads as a plain one.
+ */
+function proseOf(text) {
+    const out = [];
+    let inCode = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("```")) {
+            inCode = !inCode;
+            out.push("");
+            continue;
+        }
+        if (inCode || line.startsWith("|")) {
+            out.push("");
+            continue;
+        }
+        out.push(line
+            .replace(/^(>\s?)+/, "")
+            .replace(/^(([-*+]|\d+[.)])\s+)+/, "")
+            .replace(/`[^`]*`/g, " ")
+            .replace(/[’‘]/g, "'"));
+    }
+    return out.join("\n");
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Checks text written for a reader against the Workbench house standards and
+ * a voice's paragraph target. Makes no AI call. An app that brought its own
+ * voice has its own rules, so this check isn't for its text.
+ */
+export function checkWriting(text, opts = {}) {
+    const body = (opts.exempt ?? []).reduce((acc, e) => (e ? acc.split(e).join(" ") : acc), text);
+    const prose = proseOf(body);
+    const issues = [];
+    const quotes = [];
+    let dashes = 0;
+    for (const m of prose.matchAll(LONG_DASH_RE)) {
+        if (m[0] !== "—") {
+            // A dash that starts its line is a list marker, and one between two numbers is a minus sign.
+            const dashAt = m.index + m[0].search(/[–-]/);
+            const lineStart = prose.lastIndexOf("\n", dashAt - 1) + 1;
+            if (prose.slice(lineStart, dashAt).trim() === "")
+                continue;
+            if (BETWEEN_NUMBERS_RE.test(prose.slice(Math.max(0, m.index - 1), m.index + m[0].length + 1)))
+                continue;
+        }
+        dashes++;
+        if (quotes.length < 3)
+            quotes.push(quoteAround(prose, m.index));
+    }
+    if (dashes > 0) {
+        issues.push({
+            severity: "stop",
+            rule: "long-dash",
+            issue: `The text uses ${dashes} long or spaced dash${dashes === 1 ? "" : "es"} (— or " - ") as punctuation, which the house standards ban.`,
+            location: quotes.map((q) => `"${q}"`).join(" / "),
+            suggestion: "Rewrite each one with a full stop, comma, colon or brackets. Remove every one.",
+        });
+    }
+    const target = opts.paragraphTarget !== undefined && opts.paragraphTarget >= 1 ? opts.paragraphTarget : paragraphTarget(opts.voice);
+    issues.push(...paragraphIssues(paragraphsOf(body), target));
+    for (const phrase of writing.banned_phrases) {
+        const m = new RegExp(`(^|[^\\p{L}])${escapeRe(phrase)}(?=$|[^\\p{L}])`, "iu").exec(prose);
+        if (m) {
+            issues.push({
+                severity: "stop",
+                rule: "banned-phrase",
+                issue: `Uses the banned phrase "${phrase}".`,
+                location: `"${quoteAround(prose, m.index + m[1].length)}"`,
+                suggestion: "Rewrite the sentence without it, or cut the sentence if it adds nothing.",
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Text to add to a prompt that is asked once more because its answer broke the house standards.
+ * Only the stops are listed: a note is never a reason to ask again. Empty when there is no stop.
+ */
+export function writingFixNote(issues) {
+    const stops = writingStops(issues);
+    if (stops.length === 0)
+        return "";
+    const lines = stops.map((i) => `- ${i.issue}${i.location ? ` (at: ${i.location})` : ""}${i.suggestion ? ` Fix: ${i.suggestion}` : ""}`);
+    return `\n\nIMPORTANT: a previous answer to this request broke the house writing standards:\n${lines.join("\n")}\nWrite the whole answer again with every one of these fixed. Change nothing else.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-ai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^1.5.0",
-    "@mccaskie-labs/workbench-config": "^0.1.2"
+    "@mccaskie-labs/workbench-config": "^0.1.14"
   },
   "peerDependencies": {
     "zod": "^4.1.0"