@mccaskie-labs/workbench-config 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.14
+
+### 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.
+
 ## 0.1.13
 
 ### Patch Changes

package/capabilities/ai.json

@@ -7,7 +7,7 @@
   "status": "built",
   "surfaces": {
     "gateway": ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"],
-    "package": ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.countTokens", "Ai.budget", "createFakeAi"]
+    "package": ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.countTokens", "Ai.budget", "createFakeAi", "checkWriting", "writingStops", "writingNotes", "writingFixNote"]
   },
   "config": [
     {
@@ -33,7 +33,43 @@
     ],
     "explicit_models": ["claude-sonnet-5", "claude-opus-5"],
     "server_tools": ["web_search", "web_fetch", "code_execution"],
-    "required_headers": ["X-Workbench-Job"]
+    "required_headers": ["X-Workbench-Job"],
+    "optional_headers": ["X-Workbench-Voice", "X-Workbench-Spelling"],
+    "voices": [
+      { "name": "casual", "paragraph_target": 50, "sentence_target": 18 },
+      { "name": "conversational", "paragraph_target": 60, "sentence_target": 22 },
+      { "name": "plain", "paragraph_target": 60, "sentence_target": 20 },
+      { "name": "formal", "paragraph_target": 80, "sentence_target": 25 },
+      { "name": "strict-formal", "paragraph_target": 80, "sentence_target": 28 }
+    ],
+    "spellings": ["en-AU", "en-PH", "en-GB", "en-US"],
+    "writing": {
+      "voice_set_version": 1,
+      "house_paragraph_target": 80,
+      "paragraph_grace": 1.25,
+      "paragraph_ceiling": 2,
+      "banned_phrases": [
+        "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"
+      ]
+    }
   },
   "limits": [
     { "id": "ai.retry-attempts", "value": 3, "unit": "attempts", "per": "request", "enforced_by": "gateway" }
@@ -45,7 +81,8 @@
   "rules": [
     { "id": "ai.no-partial-success", "kind": "must_not", "text": "Treat a refusal or a max_tokens truncation as a successful result.", "enforced_by": "types", "probe": "ai.text.truncation-throws" },
     { "id": "ai.store-resolved-model", "kind": "must", "text": "Store the resolved model and request id with any output kept.", "enforced_by": "review", "probe": "ai.text.claude-default" },
-    { "id": "ai.aliases-only", "kind": "must", "text": "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.", "enforced_by": "gateway", "probe": "ai.model-not-allowed" }
+    { "id": "ai.aliases-only", "kind": "must", "text": "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.", "enforced_by": "gateway", "probe": "ai.model-not-allowed" },
+    { "id": "ai.voice-by-name", "kind": "must", "text": "Name a Workbench voice and spelling with the voice and spelling options, so the Gateway adds the text, or bring the app's own voice. Never paste Workbench's voice text into a prompt.", "enforced_by": "gateway", "probe": "ai.voice" }
   ],
   "examples": [
     {
@@ -54,6 +91,13 @@
       "lang": "ts",
       "probe": "ai.text.claude-default",
       "code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })"
+    },
+    {
+      "id": "ai.example.voice",
+      "title": "Text in a Workbench voice, then checked without AI",
+      "lang": "ts",
+      "probe": "ai.voice",
+      "code": "const r = await ai.text({ model: 'claude-default', job: 'article.write', voice: 'conversational', spelling: 'en-AU', prompt })\nconst issues = checkWriting(r.text, { voice: 'conversational' })\nif (writingStops(issues).length > 0) await retryWith(prompt + writingFixNote(issues))"
     }
   ],
   "probes": [
@@ -65,6 +109,9 @@
     { "id": "ai.text.truncation-throws", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.001 },
     { "id": "ai.model-not-allowed", "half": "runtime", "expect": "refused_as_expected", "refusal": "model_not_allowed", "cost_hint_usd": 0 },
     { "id": "ai.count-tokens", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
-    { "id": "ai.budget", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 }
+    { "id": "ai.budget", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "ai.voice", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.004 },
+    { "id": "ai.voice.unknown", "half": "runtime", "expect": "refused_as_expected", "refusal": "invalid_request", "cost_hint_usd": 0 },
+    { "id": "ai.voice.cache-read", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.008 }
   ]
 }

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "f3d5b55e579d";
+export declare const MANIFEST_VERSION: "d0f2550e1f81";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -9,7 +9,7 @@ export declare const capabilities: {
         readonly status: "built";
         readonly surfaces: {
             readonly gateway: readonly ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"];
-            readonly package: readonly ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.countTokens", "Ai.budget", "createFakeAi"];
+            readonly package: readonly ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.countTokens", "Ai.budget", "createFakeAi", "checkWriting", "writingStops", "writingNotes", "writingFixNote"];
         };
         readonly config: readonly [{
             readonly name: "WORKBENCH_GATEWAY_KEY";
@@ -41,6 +41,36 @@ export declare const capabilities: {
             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"];
+            };
         };
         readonly limits: readonly [{
             readonly id: "ai.retry-attempts";
@@ -78,6 +108,12 @@ export declare const capabilities: {
             readonly text: "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.";
             readonly enforced_by: "gateway";
             readonly probe: "ai.model-not-allowed";
+        }, {
+            readonly id: "ai.voice-by-name";
+            readonly kind: "must";
+            readonly text: "Name a Workbench voice and spelling with the voice and spelling options, so the Gateway adds the text, or bring the app's own voice. Never paste Workbench's voice text into a prompt.";
+            readonly enforced_by: "gateway";
+            readonly probe: "ai.voice";
         }];
         readonly examples: readonly [{
             readonly id: "ai.example.text";
@@ -85,6 +121,12 @@ export declare const capabilities: {
             readonly lang: "ts";
             readonly code: "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })";
             readonly probe: "ai.text.claude-default";
+        }, {
+            readonly id: "ai.example.voice";
+            readonly title: "Text in a Workbench voice, then checked without AI";
+            readonly lang: "ts";
+            readonly code: "const r = await ai.text({ model: 'claude-default', job: 'article.write', voice: 'conversational', spelling: 'en-AU', prompt })\nconst issues = checkWriting(r.text, { voice: 'conversational' })\nif (writingStops(issues).length > 0) await retryWith(prompt + writingFixNote(issues))";
+            readonly probe: "ai.voice";
         }];
         readonly probes: readonly [{
             readonly id: "ai.text.claude-default";
@@ -135,6 +177,22 @@ export declare const capabilities: {
             readonly expect: "pass";
             readonly smoke: true;
             readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "ai.voice";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.004;
+        }, {
+            readonly id: "ai.voice.unknown";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "invalid_request";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "ai.voice.cache-read";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.008;
         }];
     };
     readonly analytics: {

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "f3d5b55e579d";
+export const MANIFEST_VERSION = "d0f2550e1f81";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -21,7 +21,11 @@ export const capabilities = {
                 "Ai.stream",
                 "Ai.countTokens",
                 "Ai.budget",
-                "createFakeAi"
+                "createFakeAi",
+                "checkWriting",
+                "writingStops",
+                "writingNotes",
+                "writingFixNote"
             ]
         },
         "config": [
@@ -76,7 +80,71 @@ export const capabilities = {
             ],
             "required_headers": [
                 "X-Workbench-Job"
-            ]
+            ],
+            "optional_headers": [
+                "X-Workbench-Voice",
+                "X-Workbench-Spelling"
+            ],
+            "voices": [
+                {
+                    "name": "casual",
+                    "paragraph_target": 50,
+                    "sentence_target": 18
+                },
+                {
+                    "name": "conversational",
+                    "paragraph_target": 60,
+                    "sentence_target": 22
+                },
+                {
+                    "name": "plain",
+                    "paragraph_target": 60,
+                    "sentence_target": 20
+                },
+                {
+                    "name": "formal",
+                    "paragraph_target": 80,
+                    "sentence_target": 25
+                },
+                {
+                    "name": "strict-formal",
+                    "paragraph_target": 80,
+                    "sentence_target": 28
+                }
+            ],
+            "spellings": [
+                "en-AU",
+                "en-PH",
+                "en-GB",
+                "en-US"
+            ],
+            "writing": {
+                "voice_set_version": 1,
+                "house_paragraph_target": 80,
+                "paragraph_grace": 1.25,
+                "paragraph_ceiling": 2,
+                "banned_phrases": [
+                    "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"
+                ]
+            }
         },
         "limits": [
             {
@@ -122,6 +190,13 @@ export const capabilities = {
                 "text": "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.",
                 "enforced_by": "gateway",
                 "probe": "ai.model-not-allowed"
+            },
+            {
+                "id": "ai.voice-by-name",
+                "kind": "must",
+                "text": "Name a Workbench voice and spelling with the voice and spelling options, so the Gateway adds the text, or bring the app's own voice. Never paste Workbench's voice text into a prompt.",
+                "enforced_by": "gateway",
+                "probe": "ai.voice"
             }
         ],
         "examples": [
@@ -131,6 +206,13 @@ export const capabilities = {
                 "lang": "ts",
                 "code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })",
                 "probe": "ai.text.claude-default"
+            },
+            {
+                "id": "ai.example.voice",
+                "title": "Text in a Workbench voice, then checked without AI",
+                "lang": "ts",
+                "code": "const r = await ai.text({ model: 'claude-default', job: 'article.write', voice: 'conversational', spelling: 'en-AU', prompt })\nconst issues = checkWriting(r.text, { voice: 'conversational' })\nif (writingStops(issues).length > 0) await retryWith(prompt + writingFixNote(issues))",
+                "probe": "ai.voice"
             }
         ],
         "probes": [
@@ -191,6 +273,25 @@ export const capabilities = {
                 "expect": "pass",
                 "smoke": true,
                 "cost_hint_usd": 0
+            },
+            {
+                "id": "ai.voice",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.004
+            },
+            {
+                "id": "ai.voice.unknown",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "invalid_request",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "ai.voice.cache-read",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.008
             }
         ]
     },

package/dist/capability-schema.d.ts

@@ -39,6 +39,20 @@ export declare const allowedSchemas: {
         explicit_models: z.ZodArray<z.ZodString>;
         server_tools: z.ZodArray<z.ZodString>;
         required_headers: z.ZodArray<z.ZodString>;
+        optional_headers: z.ZodArray<z.ZodString>;
+        voices: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            paragraph_target: z.ZodNumber;
+            sentence_target: z.ZodNumber;
+        }, z.core.$strict>>;
+        spellings: z.ZodArray<z.ZodString>;
+        writing: z.ZodObject<{
+            voice_set_version: z.ZodNumber;
+            house_paragraph_target: z.ZodNumber;
+            paragraph_grace: z.ZodNumber;
+            paragraph_ceiling: z.ZodNumber;
+            banned_phrases: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
     }, z.core.$strict>;
     images: z.ZodObject<{
         aliases: z.ZodArray<z.ZodObject<{

package/dist/capability-schema.js

@@ -99,6 +99,20 @@ export const allowedSchemas = {
         explicit_models: z.array(z.string().min(1)),
         server_tools: z.array(z.string().min(1)),
         required_headers: z.array(z.string().min(1)),
+        // Voices and spelling (docs/spec.md §2.8). The Gateway holds the text; these are the names and the
+        // figures the package's writing check needs, kept here so the two can't drift apart.
+        optional_headers: z.array(z.string().min(1)),
+        voices: z
+            .array(z.strictObject({ name: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/), paragraph_target: z.number().int().positive(), sentence_target: z.number().int().positive() }))
+            .min(1),
+        spellings: z.array(z.string().regex(/^[a-z]{2,3}-[A-Z]{2}$/)).min(1),
+        writing: z.strictObject({
+            voice_set_version: z.number().int().positive(),
+            house_paragraph_target: z.number().int().positive(),
+            paragraph_grace: z.number().min(1),
+            paragraph_ceiling: z.number().min(1),
+            banned_phrases: z.array(z.string().min(1)).min(1),
+        }),
     }),
     images: z.strictObject({
         aliases: z.array(aliasEntry.extend({ provider: z.enum(["google", "openai"]) })).min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",