@mccaskie-labs/workbench-ai 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mccaskie-labs/workbench-ai
 
+## 0.2.0
+
+### Minor Changes
+
+- Breaking: there is no built-in Gateway address any more (hard rule 13, `docs/install-plan.md`). `DEFAULT_GATEWAY_URL` is removed from workbench-config, `createAi` needs `url`, and `createMailer`'s gateway transport needs `gateway.url`. Pass the app's `WORKBENCH_GATEWAY_URL`, which Control writes into `wrangler.jsonc` when it creates a project. A missing address fails at start-up with `invalid_config` and the message "WORKBENCH_GATEWAY_URL is missing". The gateway manifest marks `WORKBENCH_GATEWAY_URL` required with no default.
+
+### Patch Changes
+
+- Updated dependencies
+  - @mccaskie-labs/workbench-config@0.2.0
+
+## 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

package/README.md

@@ -10,14 +10,14 @@ npm install @mccaskie-labs/workbench-ai @mccaskie-labs/workbench-config zod
 import { createAi } from '@mccaskie-labs/workbench-ai'
 import { workbenchEnv } from '@mccaskie-labs/workbench-config'
 
-const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })
+const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env), url: env.WORKBENCH_GATEWAY_URL })
 const r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })
 await save({ text: r.text, model: r.model, requestId: r.requestId })
 ```
 
 | Export | What it does |
 | --- | --- |
-| `createAi({ key, env, url?, fetch? })` | The client. Throws `invalid_config` at once if the key isn't for `env` (`wbk_dev_`, `wbk_stg_`, `wbk_prd_`) |
+| `createAi({ key, env, url, fetch? })` | The client. `url` is this install's Gateway address (`WORKBENCH_GATEWAY_URL`); there is no built-in one. Throws `invalid_config` at once if it is missing or the key isn't for `env` (`wbk_dev_`, `wbk_stg_`, `wbk_prd_`) |
 | `ai.text(req)` | One reply as text. Throws `refused` on a refusal and `truncated` on `max_tokens`; never returns partial text |
 | `ai.structured({ ...req, schema, mayLack? })` | JSON matching a zod schema, through structured outputs (`output_config.format`, not forced tool use). Asks once more for required fields left empty, except those in `mayLack`; throws `invalid_output` if they're still empty |
 | `ai.stream(req)` | Async iterable of Anthropic stream events, then `finalMessage()`, which throws like `text` |
@@ -26,6 +26,7 @@ await save({ text: r.text, model: r.model, requestId: r.requestId })
 | `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 |

package/dist/ai.js

@@ -1,6 +1,5 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
-import { DEFAULT_GATEWAY_URL } from "@mccaskie-labs/workbench-config";
 import { createCapture, isGatewayMeta, REQUEST_ID_HEADER } from "./capture.js";
 import { errorFromGateway, WorkbenchAiError } from "./errors.js";
 import { gatewayFetch } from "./http.js";
@@ -34,7 +33,11 @@ export function createAi(opts) {
     if (!opts.key.startsWith(prefix)) {
         throw new WorkbenchAiError("invalid_config", `WORKBENCH_GATEWAY_KEY is not a ${env} key (expected the ${prefix} prefix)`);
     }
-    const url = (opts.url ?? DEFAULT_GATEWAY_URL).replace(/\/+$/, "");
+    // No built-in address: each Workbench install has its own Gateway (hard rule 13).
+    if (typeof opts.url !== "string" || opts.url === "") {
+        throw new WorkbenchAiError("invalid_config", "WORKBENCH_GATEWAY_URL is missing");
+    }
+    const url = opts.url.replace(/\/+$/, "");
     const baseFetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
     const client = (f) => new Anthropic({
         apiKey: opts.key,
@@ -60,6 +63,8 @@ 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))

package/dist/fake.d.ts

@@ -28,6 +28,8 @@ 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;

package/dist/fake.js

@@ -90,6 +90,7 @@ 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,

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/types.d.ts

@@ -10,8 +10,8 @@ export interface AiOptions {
     key: string;
     /** From `workbenchEnv(env)`. Must match the key's environment. */
     env: WorkbenchEnv;
-    /** Gateway base URL; defaults to `DEFAULT_GATEWAY_URL`. Leave unset outside tests. */
-    url?: string;
+    /** This install's Gateway address (`WORKBENCH_GATEWAY_URL`). There is no built-in one. */
+    url: string;
     fetch?: typeof fetch;
 }
 export interface TextRequest {
@@ -34,8 +34,17 @@ export interface TextRequest {
     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. */
+    /**
+     * `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. */
@@ -137,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;
@@ -157,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/package.json

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