@mccaskie-labs/workbench-ai 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mccaskie-labs/workbench-ai
 
+## 0.5.0
+
+### Minor Changes
+
+- Message intake: `ai.intake()` reads a social media message (a screenshot, pasted text or both) into one of the project's intake types through the Gateway's `POST /v1/intake/read`. It returns the reply drafter's `IntakeResult` (snake_case, as the Gateway sends it) typed by the project's own types: the type, its fields, what is missing or reads two ways, and `needs_human_check`, so `ai.reply` takes it unchanged. `npx workbench-ai intake generate` checks `workbench/intake/*.json` with the Gateway's own rules and writes `src/intake.generated.ts` (`--check` for Checks). With `save_input: project` it keeps the image and text in the project's own `INTAKE_STORE` bucket; Workbench keeps only the call's facts. `createFakeAi` answers from each type's examples. The `intake` manifest carries its client questions.
+
+### Patch Changes
+
+- Updated dependencies
+  - @mccaskie-labs/workbench-config@0.4.0
+
+## 0.4.1
+
+### Patch Changes
+
+- `REPLY_SCRIPT` now defines its own `__name`, so Copy and Write it again work when the app is bundled by Wrangler (esbuild's keepNames wrapped its functions in `__name(...)`, which the browser doesn't have).
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -54,6 +54,24 @@ 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.
 
+## Message intake: `ai.intake()`
+
+Reads one social media message (a screenshot, pasted text or both) into one of the project's intake types (`docs/message-intake.md`). Keep one file per type in `workbench/intake/<name>.json`, then:
+
+```sh
+npx workbench-ai intake generate          # checks the files, writes src/intake.generated.ts
+npx workbench-ai intake generate --check  # in Checks: fails when the file is stale
+```
+
+```ts
+import { intakeTypes } from "./intake.generated";
+
+const r = await ai.intake({ types: intakeTypes, text, image: { bytes, mimeType: "image/png" }, timeZone: "Asia/Manila", job: "intake.quote-request", subject: `user:${user.id}`, ref: `enquiry:${id}` });
+if (r.type === "venue-quote-request" && !r.needs_human_check) save(r.data);
+```
+
+Workbench keeps only the call's facts, never the image or the text. With `"save_input": "project"` in `workbench/intake.json`, pass `store: env.INTAKE_STORE` and the image and text are written to the project's own bucket; `r.saved` says where. The result is the reply drafter's `IntakeResult` (snake_case, as the Gateway sends it), typed by your types, so it goes straight into `ai.reply`'s `incoming.intake`.
+
 ## 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.

package/dist/ai.d.ts

@@ -1,14 +1,10 @@
-import Anthropic from "@anthropic-ai/sdk";
-import { type GatewayMeta } from "./capture.ts";
-import type { Ai, AiOptions, TextResult } from "./types.ts";
+import type { Ai, AiOptions } from "./types.ts";
 /**
  * Claude through the Workbench Gateway (docs/spec.md §3). The app holds only
  * its Gateway key; the Gateway resolves aliases, checks the budget, retries,
  * and meters every call.
  */
 export declare function createAi(opts: AiOptions): Ai;
-/** Turns a Message into a result, or throws: a refusal or a truncation is never a success (audit F18). */
-export declare function toTextResult(message: Anthropic.Message, meta: GatewayMeta): TextResult;
 /**
  * Top-level fields the model left empty (`""`, `null`, `[]`), except those it
  * may lack. Structured outputs guarantees the keys are present; this catches

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 { createIntake } from "./intake.js";
 import { draftReply } from "./replies.js";
 import { SPELLING_NAMES, VOICE_NAMES } from "./writing.js";
 const KEY_PREFIX = {
@@ -202,9 +203,10 @@ export function createAi(opts) {
         return value;
     }
     const images = createImages({ url, key: opts.key, env, fetch: baseFetch });
+    const intake = createIntake({ url, key: opts.key, env, fetch: baseFetch });
     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 };
+    return { anthropic, text, structured, stream, countTokens, budget, images, intake, reply, replyWithTemplate };
 }
 function params(req, defaultMax) {
     const body = {
@@ -242,7 +244,7 @@ function metaOf(message, cap) {
     });
 }
 /** Turns a Message into a result, or throws: a refusal or a truncation is never a success (audit F18). */
-export function toTextResult(message, meta) {
+function toTextResult(message, meta) {
     const base = { requestId: meta.request_id, model: meta.model };
     if (message.stop_reason === "refusal" || meta.refused === true) {
         const category = message.stop_details?.category ?? null;

package/dist/cli.js

@@ -11,6 +11,10 @@
 //     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 intake generate [--check] [dir]
+//     Checks workbench/intake/*.json with the Gateway's rules and writes
+//     src/intake.generated.ts (docs/message-intake.md §3). --check only
+//     compares, for the project's Checks.
 //   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]
@@ -20,11 +24,13 @@ 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";
+import { IntakeGenerateError, intakeGenerate } from "./intake-generate.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 intake generate [--check] [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]",
@@ -275,6 +281,22 @@ export async function replies(argv) {
 }
 export async function main(argv) {
     try {
+        if (argv[0] === "intake") {
+            const rest = argv.slice(1);
+            const check = rest.includes("--check");
+            const pos = rest.filter((a) => a !== "--check");
+            if (pos[0] !== "generate" || pos.length > 2 || pos.some((a) => a.startsWith("--")))
+                throw new Stop(USAGE, 2);
+            try {
+                console.log(intakeGenerate(resolve(pos[1] ?? "."), check).join("\n"));
+            }
+            catch (e) {
+                if (e instanceof IntakeGenerateError)
+                    throw new Stop(e.message, 1);
+                throw e;
+            }
+            return 0;
+        }
         if (argv[0] === "replies") {
             console.log((await replies(argv.slice(1))).join("\n"));
             return 0;

package/dist/fake.d.ts

@@ -34,6 +34,8 @@ export interface FakeCall {
     /** The Workbench voice and spelling named (X-Workbench-Voice, X-Workbench-Spelling). */
     voice: string | null;
     spelling: string | null;
+    /** The app's own reference (X-Workbench-Ref), sent by intake. */
+    ref: string | null;
     /** The parsed JSON body (Anthropic Messages request), if any. */
     body: Record<string, unknown> | null;
     stream: boolean;
@@ -75,7 +77,37 @@ export interface FakeScript {
             error?: FakeError;
         };
     };
+    /**
+     * What `intake` gets back. By default the fake reads the message as the type
+     * whose example has the same text (else the first type asked for) and answers
+     * with that example's data, so tests run on the project's own examples.
+     */
+    intake?: {
+        answer?: FakeIntakeAnswer | ((body: Record<string, unknown>) => FakeIntakeAnswer);
+        error?: FakeError;
+    };
 }
+/** What the fake `/v1/intake/read` answers: Gateway fields (snake_case) laid over the default reading. */
+export type FakeIntakeAnswer = Partial<{
+    type: string;
+    type_version: number | null;
+    confidence: number;
+    data: Record<string, unknown> | null;
+    missing: string[];
+    ambiguous: {
+        field: string;
+        reason: string;
+        options: unknown[];
+    }[];
+    assumptions: {
+        field: string;
+        note: string;
+    }[];
+    raw_text: string;
+    languages: string[];
+    needs_human_check: boolean;
+    check_reasons: string[];
+}>;
 export interface FakeError {
     status: number;
     code: string;

package/dist/fake.js

@@ -63,6 +63,52 @@ function fakeSearch(script, body, requestId) {
         request_id: requestId,
     });
 }
+function fakeIntake(script, body, requestId) {
+    const i = script.intake ?? {};
+    if (i.error)
+        return v1Error(i.error.status, requestId, i.error.code, i.error.message ?? i.error.code);
+    const types = (Array.isArray(body?.["types"]) ? body["types"] : []);
+    if (types.length === 0)
+        return v1Error(400, requestId, "invalid_request", "types must list 1 to 20 intake type definitions");
+    const only = Array.isArray(body?.["only"]) ? body["only"] : types.map((t) => t.name);
+    const text = typeof body?.["text"] === "string" ? body["text"] : "";
+    const asked = types.filter((t) => only.includes(t.name));
+    const matched = asked.find((t) => t.examples?.some((e) => e.text === text));
+    const t = matched ?? asked[0];
+    const example = t.examples?.find((e) => e.text === text) ?? t.examples?.[0];
+    const data = example?.data ?? {};
+    const missing = (t.schema?.required ?? []).filter((f) => !(f in data));
+    const base = {
+        type: t.name,
+        type_version: t.version,
+        confidence: 0.95,
+        candidates: [{ type: t.name, confidence: 0.95 }],
+        data,
+        missing,
+        ambiguous: [],
+        assumptions: [],
+        raw_text: text,
+        languages: ["en"],
+        needs_human_check: missing.length > 0,
+        check_reasons: missing.length > 0 ? ["missing_required"] : [],
+    };
+    const over = typeof i.answer === "function" ? i.answer(body ?? {}) : (i.answer ?? {});
+    const answer = { ...base, ...over };
+    const cost = 0.0089;
+    return json(200, requestId, {
+        ...answer,
+        workbench: {
+            request_id: requestId,
+            model: ALIASES.get("claude-default") ?? "claude-default",
+            alias: "claude-default",
+            cost_usd: cost,
+            attempts: 1,
+            kept: "facts_only",
+            intake_prompt_version: "fake",
+            receipt: { request_id: requestId, type: answer.type, type_version: answer.type_version, confidence: answer.confidence, needs_human_check: answer.needs_human_check, cost_usd: cost },
+        },
+    });
+}
 export function createFakeAi(script = {}) {
     const env = script.env ?? "development";
     const { fetch, calls } = fakeGateway(script);
@@ -93,6 +139,7 @@ export function fakeGateway(script = {}) {
             keep: req.headers.get("x-workbench-keep")?.toLowerCase() !== "no",
             voice: req.headers.get("x-workbench-voice"),
             spelling: req.headers.get("x-workbench-spelling"),
+            ref: req.headers.get("x-workbench-ref"),
             body,
             stream: body?.["stream"] === true,
         };
@@ -116,6 +163,8 @@ export function fakeGateway(script = {}) {
             return fakeImage(script, body, requestId);
         if (url.pathname === "/v1/images/search")
             return fakeSearch(script, body, requestId);
+        if (url.pathname === "/v1/intake/read")
+            return fakeIntake(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;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createAi, missingRequired } from "./ai.ts";
-export { createFakeAi, fakeGateway, type FakeScript, type FakeReply, type FakeCall, type FakeAi } from "./fake.ts";
+export { createFakeAi, fakeGateway, type FakeScript, type FakeReply, type FakeCall, type FakeAi, type FakeIntakeAnswer, type FakeError, type ReplyFor } from "./fake.ts";
+export { defineIntakeTypes, type AiIntake, type IntakeCheckReason, type IntakeDefinition, type IntakeImageType, type IntakeRequest, type IntakeReading, type IntakeSaved, type IntakeTyped, type IntakeSaveInput, type IntakeStore, type IntakeTypes, } from "./intake.ts";
 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";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createAi, missingRequired } from "./ai.js";
 export { createFakeAi, fakeGateway } from "./fake.js";
+export { defineIntakeTypes, } from "./intake.js";
 export { cachedSystem, cachedBlocks, provenance } from "./helpers.js";
 export { WorkbenchAiError } from "./errors.js";
 export { REQUEST_ID_HEADER } from "./capture.js";

package/dist/intake-definition.d.ts

@@ -0,0 +1,88 @@
+type Json = Record<string, unknown>;
+export declare const intakeLimits: {
+    types: number;
+    definitionBytes: number;
+    allTypesBytes: number;
+    properties: number;
+    objectArrayItems: number;
+    examples: number;
+    notThis: number;
+    glossary: number;
+};
+declare const PERSONAL_KINDS: readonly ["name", "handle", "phone", "email", "address", "photo"];
+type PersonalKind = (typeof PERSONAL_KINDS)[number];
+declare const STRING_FORMATS: readonly ["date", "date-time", "email", "phone", "uri"];
+type StringFormat = (typeof STRING_FORMATS)[number];
+/** One checked scalar property. */
+export interface ScalarProp {
+    kind: "string" | "integer" | "number" | "boolean";
+    description?: string;
+    enum?: string[];
+    maxLength?: number;
+    format?: StringFormat;
+    minimum?: number;
+    maximum?: number;
+    personal?: PersonalKind;
+}
+export interface ScalarArrayProp {
+    kind: "array";
+    items: ScalarProp;
+    maxItems?: number;
+    description?: string;
+    personal?: PersonalKind;
+}
+interface ObjectProp {
+    kind: "object";
+    properties: Record<string, ScalarProp | ScalarArrayProp>;
+    required: string[];
+    description?: string;
+    personal?: PersonalKind;
+}
+interface ObjectArrayProp {
+    kind: "object_array";
+    items: {
+        properties: Record<string, ScalarProp>;
+        required: string[];
+    };
+    maxItems: number;
+    description?: string;
+    personal?: PersonalKind;
+}
+export type Prop = ScalarProp | ScalarArrayProp | ObjectProp | ObjectArrayProp;
+interface IntakeExample {
+    received_at?: string;
+    text: string;
+    data: Json;
+}
+/** A checked intake type. `source` is the definition as sent, `bytes` its canonical JSON. */
+export interface IntakeType {
+    name: string;
+    version: number;
+    description: string;
+    not_this: string[];
+    glossary: Record<string, string>;
+    examples: IntakeExample[];
+    properties: Record<string, Prop>;
+    required: string[];
+    confidence_floor: number;
+    model: "claude-default" | "claude-fast";
+    /** The schema as sent, for the prompt (the model reads its descriptions). */
+    schema: Json;
+}
+/** A definition that breaks §3, with the type and the JSON path in its message. */
+export declare class IntakeTypeProblem extends Error {
+}
+/** Checks one definition. Throws IntakeTypeProblem with the type and the JSON path. */
+export declare function checkDefinition(def: unknown, index: number): IntakeType;
+export interface DataError {
+    /** The JSON path inside data, e.g. guest_count.min. "" for data itself. */
+    path: string;
+    /** The top-level field it belongs to, or "" for data itself. */
+    field: string;
+    message: string;
+}
+/** Checks data against a type's schema: every rule the structured-output schema can't hold (§4). Top-level required fields are not checked here: missing is worked out separately. */
+export declare function validateData(t: IntakeType, data: unknown, opts?: {
+    requireTop?: boolean;
+}): DataError[];
+export {};

package/dist/intake-definition.js

@@ -0,0 +1,420 @@
+// Intake type definitions (docs/message-intake.md §3): what a project sends in
+// `types` with every POST /v1/intake/read. A project keeps one file per type in
+// its own repo. This file checks one definition and validates data against it.
+//
+// It has no imports, and the same file is in the workbench-ai package
+// (packages/ai/src/intake-definition.ts), where `npx workbench-ai intake
+// generate` checks a project's files with it before they are ever sent. A test
+// there keeps the two byte for byte the same: change one, copy it to the other.
+//
+// The schema is a JSON Schema subset, so that every schema can be turned into a
+// structured-output schema (the Gateway's schema.ts) and checked the same way:
+//
+//   string    enum, maxLength, format (date, date-time, email, phone, uri)
+//   integer   minimum, maximum
+//   number    minimum, maximum
+//   boolean
+//   array     of a scalar, maxItems
+//   object    one level down, of scalars and arrays of scalars
+//   array     of flat objects (scalars only), maxItems up to 30
+//
+// A property that holds a personal detail is marked with "x-personal"; one whose
+// name or format looks personal and isn't marked is refused (§3, "Personal
+// details are marked").
+export const intakeLimits = {
+    types: 20,
+    definitionBytes: 16 * 1024,
+    allTypesBytes: 64 * 1024,
+    properties: 40,
+    objectArrayItems: 30,
+    examples: 5,
+    notThis: 10,
+    glossary: 50,
+};
+const PERSONAL_KINDS = ["name", "handle", "phone", "email", "address", "photo"];
+const STRING_FORMATS = ["date", "date-time", "email", "phone", "uri"];
+const DEFAULT_CONFIDENCE_FLOOR = 0.75;
+const NAME = /^[a-z0-9-]{1,48}$/;
+const PROP_NAME = /^[a-z][a-z0-9_]{0,47}$/;
+/** Words in a property name that suggest a personal detail (§3). */
+const PERSONAL_NAME = /(^|_)(name|names|phone|phones|mobile|email|emails|contact|contacts|fb|facebook|profile|avatar|handle|address)(_|$)/;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A definition that breaks §3, with the type and the JSON path in its message. */
+export class IntakeTypeProblem extends Error {
+}
+function fail(type, path, message) {
+    throw new IntakeTypeProblem(`Intake type ${type}: ${path}: ${message}`);
+}
+function onlyKeys(type, path, o, allowed) {
+    for (const k of Object.keys(o)) {
+        if (!allowed.includes(k))
+            fail(type, `${path}.${k}`, `isn't allowed here (allowed: ${allowed.join(", ")}).`);
+    }
+}
+function text(type, path, v, min, max) {
+    if (typeof v !== "string" || v.trim().length < min || v.length > max)
+        fail(type, path, `must be text of ${min} to ${max} characters.`);
+    return v;
+}
+function whole(type, path, v, min, max) {
+    if (typeof v !== "number" || !Number.isInteger(v) || v < min || v > max)
+        fail(type, path, `must be a whole number from ${min} to ${max}.`);
+    return v;
+}
+function finite(type, path, v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        fail(type, path, "must be a number.");
+    return v;
+}
+function personalOf(type, path, p) {
+    const v = p["x-personal"];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || !PERSONAL_KINDS.includes(v))
+        fail(type, `${path}.x-personal`, `must be one of ${PERSONAL_KINDS.join(", ")}.`);
+    return v;
+}
+function scalar(type, path, name, p, count) {
+    if (!isObject(p))
+        fail(type, path, "must be an object.");
+    count.n++;
+    const kind = p["type"];
+    const common = ["type", "description", "x-personal"];
+    const out = { kind: "string" };
+    if (kind === "string") {
+        onlyKeys(type, path, p, [...common, "enum", "maxLength", "format"]);
+        if (p["enum"] !== undefined) {
+            const e = p["enum"];
+            if (!Array.isArray(e) || e.length < 1 || e.length > 100 || e.some((x) => typeof x !== "string" || x.length < 1 || x.length > 100)) {
+                fail(type, `${path}.enum`, "must list 1 to 100 strings of 1 to 100 characters.");
+            }
+            if (new Set(e).size !== e.length)
+                fail(type, `${path}.enum`, "has a value twice.");
+            out.enum = e;
+        }
+        if (p["maxLength"] !== undefined)
+            out.maxLength = whole(type, `${path}.maxLength`, p["maxLength"], 1, 20_000);
+        if (p["format"] !== undefined) {
+            if (!STRING_FORMATS.includes(p["format"]))
+                fail(type, `${path}.format`, `must be one of ${STRING_FORMATS.join(", ")}.`);
+            out.format = p["format"];
+        }
+    }
+    else if (kind === "integer" || kind === "number") {
+        onlyKeys(type, path, p, [...common, "minimum", "maximum"]);
+        out.kind = kind;
+        if (p["minimum"] !== undefined)
+            out.minimum = finite(type, `${path}.minimum`, p["minimum"]);
+        if (p["maximum"] !== undefined)
+            out.maximum = finite(type, `${path}.maximum`, p["maximum"]);
+        if (out.minimum !== undefined && out.maximum !== undefined && out.minimum > out.maximum)
+            fail(type, path, "minimum is above maximum.");
+    }
+    else if (kind === "boolean") {
+        onlyKeys(type, path, p, common);
+        out.kind = "boolean";
+    }
+    else {
+        fail(type, `${path}.type`, "must be string, integer, number or boolean here.");
+    }
+    if (p["description"] !== undefined)
+        out.description = text(type, `${path}.description`, p["description"], 1, 600);
+    const personal = personalOf(type, path, p);
+    if (personal)
+        out.personal = personal;
+    else if (PERSONAL_NAME.test(name) || out.format === "phone" || out.format === "email") {
+        fail(type, path, `looks like a personal detail. Mark it with "x-personal" (${PERSONAL_KINDS.join(", ")}) if the type really needs it, or leave it out (docs/message-intake.md §3).`);
+    }
+    return out;
+}
+function scalarArray(type, path, name, p, count) {
+    onlyKeys(type, path, p, ["type", "items", "maxItems", "description", "x-personal"]);
+    count.n++;
+    const items = scalar(type, `${path}.items`, name, p["items"], { n: 0 });
+    const out = { kind: "array", items };
+    if (p["maxItems"] !== undefined)
+        out.maxItems = whole(type, `${path}.maxItems`, p["maxItems"], 1, 100);
+    if (p["description"] !== undefined)
+        out.description = text(type, `${path}.description`, p["description"], 1, 600);
+    const personal = personalOf(type, path, p) ?? items.personal;
+    if (personal)
+        out.personal = personal;
+    return out;
+}
+function requiredOf(type, path, o, props) {
+    const r = o["required"];
+    if (r === undefined)
+        return [];
+    if (!Array.isArray(r) || r.some((x) => typeof x !== "string"))
+        fail(type, `${path}.required`, "must be a list of property names.");
+    for (const x of r)
+        if (!Object.hasOwn(props, x))
+            fail(type, `${path}.required`, `names ${x}, which isn't a property.`);
+    if (new Set(r).size !== r.length)
+        fail(type, `${path}.required`, "names a property twice.");
+    return r;
+}
+function propsOf(type, path, o) {
+    const props = o["properties"];
+    if (!isObject(props) || Object.keys(props).length === 0)
+        fail(type, `${path}.properties`, "must be an object with at least one property.");
+    for (const k of Object.keys(props))
+        if (!PROP_NAME.test(k))
+            fail(type, `${path}.properties.${k}`, "a property name must be [a-z][a-z0-9_]{0,47}.");
+    return props;
+}
+function property(type, path, name, p, count, depth) {
+    if (!isObject(p))
+        fail(type, path, "must be an object.");
+    if (p["type"] === "object") {
+        if (depth === 1)
+            fail(type, path, "an object can only be one level down.");
+        onlyKeys(type, path, p, ["type", "properties", "required", "description", "x-personal"]);
+        count.n++;
+        const raw = propsOf(type, path, p);
+        const properties = {};
+        for (const [k, v] of Object.entries(raw)) {
+            const child = property(type, `${path}.properties.${k}`, k, v, count, 1);
+            if (child.kind === "object" || child.kind === "object_array")
+                fail(type, `${path}.properties.${k}`, "an object's properties must be scalars or lists of scalars.");
+            properties[k] = child;
+        }
+        const out = { kind: "object", properties, required: requiredOf(type, path, p, raw) };
+        if (p["description"] !== undefined)
+            out.description = text(type, `${path}.description`, p["description"], 1, 600);
+        const personal = personalOf(type, path, p);
+        if (personal)
+            out.personal = personal;
+        return out;
+    }
+    if (p["type"] === "array") {
+        const items = p["items"];
+        if (isObject(items) && items["type"] === "object") {
+            if (depth === 1)
+                fail(type, path, "a list of objects can only be at the top level.");
+            onlyKeys(type, path, p, ["type", "items", "maxItems", "description", "x-personal"]);
+            onlyKeys(type, `${path}.items`, items, ["type", "properties", "required"]);
+            count.n++;
+            const raw = propsOf(type, `${path}.items`, items);
+            const properties = {};
+            for (const [k, v] of Object.entries(raw)) {
+                if (isObject(v) && (v["type"] === "object" || v["type"] === "array"))
+                    fail(type, `${path}.items.properties.${k}`, "a listed object's properties must all be scalars.");
+                properties[k] = scalar(type, `${path}.items.properties.${k}`, k, v, count);
+            }
+            if (p["maxItems"] === undefined)
+                fail(type, `${path}.maxItems`, `is required on a list of objects (up to ${intakeLimits.objectArrayItems}).`);
+            const out = {
+                kind: "object_array",
+                items: { properties, required: requiredOf(type, `${path}.items`, items, raw) },
+                maxItems: whole(type, `${path}.maxItems`, p["maxItems"], 1, intakeLimits.objectArrayItems),
+            };
+            if (p["description"] !== undefined)
+                out.description = text(type, `${path}.description`, p["description"], 1, 600);
+            const personal = personalOf(type, path, p);
+            if (personal)
+                out.personal = personal;
+            return out;
+        }
+        return scalarArray(type, path, name, p, count);
+    }
+    return scalar(type, path, name, p, count);
+}
+const DEFINITION_KEYS = ["$comment", "format", "name", "version", "description", "not_this", "examples", "glossary", "schema", "confidence_floor", "model", "save_input"];
+/** Checks one definition. Throws IntakeTypeProblem with the type and the JSON path. */
+export function checkDefinition(def, index) {
+    if (!isObject(def))
+        throw new IntakeTypeProblem(`types[${index}] must be an intake type definition (an object).`);
+    const name = typeof def["name"] === "string" && NAME.test(def["name"]) ? def["name"] : null;
+    if (!name)
+        throw new IntakeTypeProblem(`types[${index}].name must be [a-z0-9-]{1,48}.`);
+    if (name === "unknown")
+        fail(name, "name", "unknown is reserved.");
+    onlyKeys(name, "$", def, DEFINITION_KEYS);
+    if (def["format"] !== 1)
+        fail(name, "format", "must be 1.");
+    const version = whole(name, "version", def["version"], 1, 1_000_000);
+    const description = text(name, "description", def["description"], 1, 600);
+    const notThis = def["not_this"] ?? [];
+    if (!Array.isArray(notThis) || notThis.length > intakeLimits.notThis)
+        fail(name, "not_this", `must be a list of up to ${intakeLimits.notThis} lines.`);
+    notThis.forEach((l, i) => text(name, `not_this[${i}]`, l, 1, 200));
+    const glossary = def["glossary"] ?? {};
+    if (!isObject(glossary) || Object.keys(glossary).length > intakeLimits.glossary)
+        fail(name, "glossary", `must be up to ${intakeLimits.glossary} "term": "meaning" pairs.`);
+    for (const [k, v] of Object.entries(glossary)) {
+        text(name, `glossary`, k, 1, 60);
+        text(name, `glossary.${k}`, v, 1, 200);
+    }
+    const schema = def["schema"];
+    if (!isObject(schema) || schema["type"] !== "object")
+        fail(name, "schema", "must be an object schema (type: object).");
+    onlyKeys(name, "schema", schema, ["type", "properties", "required", "description"]);
+    const count = { n: 0 };
+    const raw = propsOf(name, "schema", schema);
+    const properties = {};
+    for (const [k, v] of Object.entries(raw))
+        properties[k] = property(name, `schema.properties.${k}`, k, v, count, 0);
+    if (count.n > intakeLimits.properties)
+        fail(name, "schema", `has ${count.n} properties; the limit is ${intakeLimits.properties} in all.`);
+    const required = requiredOf(name, "schema", schema, raw);
+    let floor = DEFAULT_CONFIDENCE_FLOOR;
+    if (def["confidence_floor"] !== undefined) {
+        const f = def["confidence_floor"];
+        if (typeof f !== "number" || f < 0.5 || f > 0.95)
+            fail(name, "confidence_floor", "must be from 0.5 to 0.95.");
+        floor = f;
+    }
+    const model = def["model"] ?? "claude-default";
+    if (model !== "claude-default" && model !== "claude-fast")
+        fail(name, "model", "must be claude-default or claude-fast.");
+    const save = def["save_input"];
+    if (save !== undefined && save !== "none" && save !== "project")
+        fail(name, "save_input", "must be none or project.");
+    const t = {
+        name,
+        version,
+        description,
+        not_this: notThis,
+        glossary: glossary,
+        examples: [],
+        properties,
+        required,
+        confidence_floor: floor,
+        model,
+        schema,
+    };
+    const examples = def["examples"];
+    if (!Array.isArray(examples) || examples.length < 1 || examples.length > intakeLimits.examples)
+        fail(name, "examples", `must be 1 to ${intakeLimits.examples} examples.`);
+    examples.forEach((ex, i) => {
+        const path = `examples[${i}]`;
+        if (!isObject(ex))
+            fail(name, path, "must be an object.");
+        onlyKeys(name, path, ex, ["received_at", "text", "data"]);
+        const exText = text(name, `${path}.text`, ex["text"], 1, 2000);
+        if (ex["received_at"] !== undefined && (typeof ex["received_at"] !== "string" || Number.isNaN(Date.parse(ex["received_at"])))) {
+            fail(name, `${path}.received_at`, "must be an ISO date and time.");
+        }
+        if (!isObject(ex["data"]))
+            fail(name, `${path}.data`, "must be an object.");
+        const errors = validateData(t, ex["data"], { requireTop: false });
+        if (errors.length)
+            fail(name, `${path}.data${errors[0].path === "" ? "" : `.${errors[0].path}`}`, errors[0].message);
+        t.examples.push({ ...(ex["received_at"] ? { received_at: ex["received_at"] } : {}), text: exText, data: ex["data"] });
+    });
+    return t;
+}
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+function validDate(s) {
+    if (!DATE.test(s))
+        return false;
+    const d = new Date(`${s}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
+}
+const FORMAT_CHECK = {
+    date: validDate,
+    "date-time": (s) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(s) && !Number.isNaN(Date.parse(s)),
+    email: (s) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s),
+    phone: (s) => /^\+?[0-9 ()-]{6,24}$/.test(s),
+    uri: (s) => {
+        try {
+            return /^https?:$/.test(new URL(s).protocol);
+        }
+        catch {
+            return false;
+        }
+    },
+};
+function checkScalar(p, v, path, field, errors) {
+    const err = (message) => void errors.push({ path, field, message });
+    switch (p.kind) {
+        case "string":
+            if (typeof v !== "string")
+                return err("must be text.");
+            if (p.enum && !p.enum.includes(v))
+                return err(`must be one of ${p.enum.join(", ")}.`);
+            if (p.maxLength !== undefined && v.length > p.maxLength)
+                return err(`must be at most ${p.maxLength} characters.`);
+            if (p.format && !FORMAT_CHECK[p.format](v))
+                return err(`must be a valid ${p.format}.`);
+            return;
+        case "integer":
+        case "number":
+            if (typeof v !== "number" || !Number.isFinite(v))
+                return err("must be a number.");
+            if (p.kind === "integer" && !Number.isInteger(v))
+                return err("must be a whole number.");
+            if (p.minimum !== undefined && v < p.minimum)
+                return err(`must be at least ${p.minimum}.`);
+            if (p.maximum !== undefined && v > p.maximum)
+                return err(`must be at most ${p.maximum}.`);
+            return;
+        case "boolean":
+            if (typeof v !== "boolean")
+                err("must be true or false.");
+    }
+}
+function checkFlat(props, required, v, path, field, errors) {
+    if (!isObject(v)) {
+        errors.push({ path, field, message: "must be an object." });
+        return;
+    }
+    for (const k of Object.keys(v))
+        if (!Object.hasOwn(props, k))
+            errors.push({ path: `${path}.${k}`, field, message: "isn't in the schema." });
+    for (const r of required)
+        if (v[r] === undefined)
+            errors.push({ path: `${path}.${r}`, field, message: "is required." });
+    for (const [k, p] of Object.entries(props)) {
+        if (v[k] === undefined)
+            continue;
+        if (p.kind === "array")
+            checkScalarArray(p, v[k], `${path}.${k}`, field, errors);
+        else
+            checkScalar(p, v[k], `${path}.${k}`, field, errors);
+    }
+}
+function checkScalarArray(p, v, path, field, errors) {
+    if (!Array.isArray(v)) {
+        errors.push({ path, field, message: "must be a list." });
+        return;
+    }
+    if (p.maxItems !== undefined && v.length > p.maxItems)
+        errors.push({ path, field, message: `must have at most ${p.maxItems} items.` });
+    v.forEach((x, i) => checkScalar(p.items, x, `${path}[${i}]`, field, errors));
+}
+/** Checks data against a type's schema: every rule the structured-output schema can't hold (§4). Top-level required fields are not checked here: missing is worked out separately. */
+export function validateData(t, data, opts = { requireTop: true }) {
+    const errors = [];
+    if (!isObject(data))
+        return [{ path: "", field: "", message: "must be an object." }];
+    for (const k of Object.keys(data))
+        if (!Object.hasOwn(t.properties, k))
+            errors.push({ path: k, field: k, message: "isn't in the schema." });
+    if (opts.requireTop)
+        for (const r of t.required)
+            if (data[r] === undefined)
+                errors.push({ path: r, field: r, message: "is required." });
+    for (const [k, p] of Object.entries(t.properties)) {
+        const v = data[k];
+        if (v === undefined)
+            continue;
+        if (p.kind === "object")
+            checkFlat(p.properties, p.required, v, k, k, errors);
+        else if (p.kind === "object_array") {
+            if (!Array.isArray(v))
+                errors.push({ path: k, field: k, message: "must be a list." });
+            else {
+                if (v.length > p.maxItems)
+                    errors.push({ path: k, field: k, message: `must have at most ${p.maxItems} items.` });
+                v.forEach((x, i) => checkFlat(p.items.properties, p.items.required, x, `${k}[${i}]`, k, errors));
+            }
+        }
+        else if (p.kind === "array")
+            checkScalarArray(p, v, k, k, errors);
+        else
+            checkScalar(p, v, k, k, errors);
+    }
+    return errors;
+}

package/dist/intake-generate.d.ts

@@ -0,0 +1,9 @@
+export declare class IntakeGenerateError extends Error {
+}
+/** Reads and checks the project's intake files and returns the generated file's text. */
+export declare function intakeGenerated(dir: string): {
+    text: string;
+    types: string[];
+};
+/** Writes src/intake.generated.ts, or with check only compares it. Returns the lines to print. */
+export declare function intakeGenerate(dir: string, check: boolean): string[];

package/dist/intake-generate.js

@@ -0,0 +1,149 @@
+// `npx workbench-ai intake generate [--check]` (docs/message-intake.md §3):
+// checks every workbench/intake/<name>.json with the Gateway's own rules
+// (intake-definition.ts, the same file) and writes src/intake.generated.ts:
+// the definitions, the project's save_input setting from workbench/intake.json,
+// and a TypeScript type for each type's data. --check, for the project's
+// Checks, fails when the generated file is missing or out of date.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { checkDefinition, intakeLimits, IntakeTypeProblem } from "./intake-definition.js";
+const INTAKE_DIR = "workbench/intake";
+const INTAKE_SETTINGS = "workbench/intake.json";
+const INTAKE_GENERATED = "src/intake.generated.ts";
+export class IntakeGenerateError extends Error {
+}
+const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+function parseJson(path, rel) {
+    try {
+        return JSON.parse(read(path));
+    }
+    catch (e) {
+        throw new IntakeGenerateError(`${rel} isn't valid JSON: ${e.message}`);
+    }
+}
+/** workbench/intake.json: `{ "format": 1, "save_input": "none" | "project" }`. Missing means none. */
+function readSettings(dir) {
+    const path = join(dir, INTAKE_SETTINGS);
+    if (!existsSync(path))
+        return "none";
+    const s = parseJson(path, INTAKE_SETTINGS);
+    if (typeof s !== "object" || s === null || Array.isArray(s))
+        throw new IntakeGenerateError(`${INTAKE_SETTINGS} must be an object.`);
+    const o = s;
+    for (const k of Object.keys(o))
+        if (!["$comment", "format", "save_input"].includes(k))
+            throw new IntakeGenerateError(`${INTAKE_SETTINGS}: ${k} isn't a setting (format, save_input).`);
+    if (o["format"] !== 1)
+        throw new IntakeGenerateError(`${INTAKE_SETTINGS}: format must be 1.`);
+    const save = o["save_input"] ?? "none";
+    if (save !== "none" && save !== "project")
+        throw new IntakeGenerateError(`${INTAKE_SETTINGS}: save_input must be none or project.`);
+    return save;
+}
+const quote = (s) => JSON.stringify(s);
+const doc = (d, indent) => (d ? `${indent}/** ${d.replace(/\*\//g, "*\\/")} */\n` : "");
+const pascal = (name) => name.replace(/(^|-)([a-z0-9])/g, (_, __, c) => c.toUpperCase());
+function scalarType(p) {
+    if (p.kind === "string")
+        return p.enum ? p.enum.map(quote).join(" | ") : "string";
+    if (p.kind === "boolean")
+        return "boolean";
+    return "number";
+}
+function fields(props, required, indent) {
+    return Object.entries(props)
+        .map(([k, p]) => `${doc(p.description, indent)}${indent}${k}${required.includes(k) ? "" : "?"}: ${propType(p, indent)};\n`)
+        .join("");
+}
+function propType(p, indent) {
+    switch (p.kind) {
+        case "object":
+            return `{\n${fields(p.properties, p.required, `${indent}  `)}${indent}}`;
+        case "object_array":
+            return `Array<{\n${fields(p.items.properties, p.items.required, `${indent}  `)}${indent}}>`;
+        case "array": {
+            const t = scalarType(p.items);
+            return p.items.enum ? `Array<${t}>` : `${t}[]`;
+        }
+        default:
+            return scalarType(p);
+    }
+}
+/** One type's data. Every top-level field may be missing: the reader leaves out what a message doesn't give. */
+function dataInterface(t) {
+    return `${doc(t.description, "")}export interface ${pascal(t.name)}Data {\n${fields(t.properties, [], "  ")}}\n`;
+}
+/** Reads and checks the project's intake files and returns the generated file's text. */
+export function intakeGenerated(dir) {
+    const folder = join(dir, INTAKE_DIR);
+    const files = existsSync(folder) ? readdirSync(folder).filter((f) => f.endsWith(".json")).sort() : [];
+    if (files.length === 0)
+        throw new IntakeGenerateError(`No intake types: add one file per type in ${INTAKE_DIR}/ (<name>.json, docs/message-intake.md §3).`);
+    if (files.length > intakeLimits.types)
+        throw new IntakeGenerateError(`${files.length} intake types; the Gateway takes at most ${intakeLimits.types} in a call.`);
+    const saveInput = readSettings(dir);
+    const raws = [];
+    const checked = [];
+    let total = 0;
+    files.forEach((f, i) => {
+        const rel = `${INTAKE_DIR}/${f}`;
+        const raw = parseJson(join(folder, f), rel);
+        const bytes = JSON.stringify(raw).length;
+        total += bytes;
+        if (bytes > intakeLimits.definitionBytes)
+            throw new IntakeGenerateError(`${rel} is over ${intakeLimits.definitionBytes / 1024} KB.`);
+        if (total > intakeLimits.allTypesBytes)
+            throw new IntakeGenerateError(`The intake types are over ${intakeLimits.allTypesBytes / 1024} KB in all.`);
+        let t;
+        try {
+            t = checkDefinition(raw, i);
+        }
+        catch (e) {
+            if (e instanceof IntakeTypeProblem)
+                throw new IntakeGenerateError(`${rel}: ${e.message}`);
+            throw e;
+        }
+        if (`${t.name}.json` !== f)
+            throw new IntakeGenerateError(`${rel} holds the type ${t.name}: name the file ${t.name}.json.`);
+        // The comment is for the file's readers, not the reader: it isn't sent.
+        const { $comment: _, ...sent } = raw;
+        raws.push(sent);
+        checked.push(t);
+    });
+    const text = [
+        "// Generated by `npx workbench-ai intake generate` from workbench/intake/ and",
+        "// workbench/intake.json. Don't edit it: change those files and run it again.",
+        "",
+        'import { defineIntakeTypes } from "@mccaskie-labs/workbench-ai";',
+        "",
+        checked.map(dataInterface).join("\n"),
+        "/** Each intake type's data, by type name. */",
+        "export interface IntakeData {",
+        ...checked.map((t) => `  ${quote(t.name)}: ${pascal(t.name)}Data;`),
+        "}",
+        "",
+        "/** Pass as `types` to ai.intake(). */",
+        `export const intakeTypes = defineIntakeTypes<IntakeData>({`,
+        `  saveInput: ${quote(saveInput)},`,
+        `  definitions: ${JSON.stringify(raws, null, 2).replace(/\n/g, "\n  ")},`,
+        "});",
+        "",
+    ].join("\n");
+    return { text, types: checked.map((t) => t.name) };
+}
+/** Writes src/intake.generated.ts, or with check only compares it. Returns the lines to print. */
+export function intakeGenerate(dir, check) {
+    const { text, types } = intakeGenerated(dir);
+    const target = join(dir, INTAKE_GENERATED);
+    const current = existsSync(target) ? read(target) : null;
+    if (check) {
+        if (current !== text)
+            throw new IntakeGenerateError(`${INTAKE_GENERATED} is out of date with ${INTAKE_DIR}/: run npx workbench-ai intake generate and commit it.`);
+        return [`${INTAKE_GENERATED} is up to date (${types.join(", ")}).`];
+    }
+    if (current === text)
+        return [`${INTAKE_GENERATED} is already up to date (${types.join(", ")}).`];
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, text);
+    return [`Wrote ${INTAKE_GENERATED}: ${types.join(", ")}.`];
+}

package/dist/intake.d.ts

@@ -0,0 +1,102 @@
+import { type GatewayTarget } from "./http.ts";
+import type { IntakeResult } from "./replies.ts";
+export type IntakeSaveInput = "none" | "project";
+/** One intake type as written in workbench/intake/<name>.json (§3). */
+export interface IntakeDefinition {
+    readonly format: 1;
+    readonly name: string;
+    readonly version: number;
+    readonly save_input?: IntakeSaveInput;
+    readonly [key: string]: unknown;
+}
+/**
+ * The project's intake types, from src/intake.generated.ts. `M` maps each
+ * type's name to its `data`, so a result is typed by the type it found.
+ */
+export interface IntakeTypes<M extends object = Record<string, Record<string, unknown>>> {
+    readonly definitions: readonly IntakeDefinition[];
+    /** The project's setting, workbench/intake.json. A type's own `save_input` overrides it. */
+    readonly saveInput: IntakeSaveInput;
+    /** Type-level only: never set. */
+    readonly __data?: M;
+}
+/** Used by the generated file. */
+export declare function defineIntakeTypes<M extends object>(types: {
+    definitions: readonly IntakeDefinition[];
+    saveInput: IntakeSaveInput;
+}): IntakeTypes<M>;
+export type IntakeImageType = "image/png" | "image/jpeg" | "image/webp";
+/** The bucket the project keeps its input in (INTAKE_STORE, an R2 bucket). */
+export interface IntakeStore {
+    put(key: string, value: Uint8Array | string, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+    }): Promise<unknown>;
+}
+export interface IntakeRequest<M extends object> {
+    /** `intakeTypes` from src/intake.generated.ts. */
+    types: IntakeTypes<M>;
+    /** Pasted text, or a caption to go with the image. Up to 20,000 characters. */
+    text?: string;
+    /** One screenshot: PNG, JPEG or WebP, up to 5 MB. */
+    image?: {
+        bytes: Uint8Array;
+        mimeType: IntakeImageType;
+    };
+    /** Classify among these types only. Default: all of them. */
+    only?: readonly (keyof M & string)[];
+    /** When the message was sent or pasted. Relative dates are read against it. Default: now. */
+    receivedAt?: Date | string;
+    /** IANA name, e.g. Asia/Manila: pass the country pack's (`country.timeZone.id`). Default UTC. */
+    timeZone?: string;
+    /** X-Workbench-Job, e.g. intake.quote-request. */
+    job: string;
+    /** `user:<id>` of the app's own user who sent it in, never the poster. */
+    subject?: string;
+    /** The app's own id for the record (X-Workbench-Ref), e.g. enquiry:4812, so the charge can be found from it. */
+    ref?: string;
+    /** Needed when the input is kept (save_input: project): the project's INTAKE_STORE bucket. */
+    store?: IntakeStore;
+}
+export type IntakeCheckReason = "unknown_type" | "low_confidence" | "missing_required" | "ambiguous_required" | "invalid_output" | "unreadable_image";
+/** Where the input was kept in the project's own bucket. Only when save_input is project. */
+export interface IntakeSaved {
+    image?: {
+        key: string;
+        sha256: string;
+        mime: string;
+        bytes: number;
+    };
+    text: {
+        key: string;
+    };
+}
+/**
+ * Narrows the drafter's IntakeResult by the project's own types: `data` is the
+ * found type's data, typed from the generated file (docs/message-intake.md §9:
+ * one result type, which ai.reply takes unchanged).
+ */
+export type IntakeTyped<M extends object> = {
+    [K in keyof M & string]: {
+        type: K;
+        type_version: number;
+        data: M[K];
+    };
+}[keyof M & string] | {
+    type: "unknown";
+    type_version: null;
+    data: null;
+};
+/** What ai.intake returns: the Gateway's answer (§2) as is, typed by the project's types. */
+export type IntakeReading<M extends object> = IntakeResult & IntakeTyped<M> & {
+    workbench: {
+        request_id: string;
+        [key: string]: unknown;
+    };
+};
+export interface AiIntake {
+    <M extends object>(req: IntakeRequest<M>): Promise<IntakeReading<M>>;
+}
+export declare function createIntake(target: GatewayTarget): AiIntake;

package/dist/intake.js

@@ -0,0 +1,134 @@
+// ai.intake: read one social media message (a screenshot, pasted text or both)
+// into one of the project's intake types, through the Gateway's
+// POST /v1/intake/read (docs/message-intake.md).
+//
+// The project's types are files in its own repo, workbench/intake/<name>.json;
+// `npx workbench-ai intake generate` checks them and writes
+// src/intake.generated.ts, whose `intakeTypes` is passed here and sent with
+// every call. Workbench keeps only the call's facts. When the project (or the
+// type) keeps its input (`save_input: project`), this writes the image and the
+// text to the project's own bucket after the call and returns where.
+import { WorkbenchAiError } from "./errors.js";
+import { gatewayFetch } from "./http.js";
+/** Used by the generated file. */
+export function defineIntakeTypes(types) {
+    return types;
+}
+const JOB = /^[a-z0-9._-]{1,64}$/;
+const SUBJECT = /^[a-z0-9_-]+:[^\s]{1,128}$/;
+const REF = /^[A-Za-z0-9._:-]{1,64}$/;
+const IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp"];
+const MAX_IMAGE = 5 * 1024 * 1024;
+const MAX_TEXT = 20_000;
+const EXT = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" };
+const str = (v) => (typeof v === "string" ? v : "");
+function toBase64(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+async function sha256Hex(bytes) {
+    const d = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Whether a reading of this type keeps its input: the type's own setting, else the project's. */
+function keeps(types, type) {
+    const own = types.definitions.find((d) => d.name === type)?.save_input;
+    return (own ?? types.saveInput) === "project";
+}
+function check(req) {
+    const bad = (m) => new WorkbenchAiError("invalid_request", m);
+    if (!req.types || !Array.isArray(req.types.definitions) || req.types.definitions.length === 0) {
+        throw bad("types must be intakeTypes from src/intake.generated.ts (run npx workbench-ai intake generate)");
+    }
+    if (!JOB.test(req.job))
+        throw bad("job must match [a-z0-9._-]{1,64}");
+    if (req.text === undefined && req.image === undefined)
+        throw bad("intake needs text, an image, or both");
+    if (req.text !== undefined && (typeof req.text !== "string" || req.text.length > MAX_TEXT))
+        throw bad(`text must be up to ${MAX_TEXT} characters`);
+    if (req.image !== undefined) {
+        if (!IMAGE_TYPES.includes(req.image.mimeType))
+            throw bad(`image.mimeType must be one of ${IMAGE_TYPES.join(", ")}`);
+        if (!(req.image.bytes instanceof Uint8Array) || req.image.bytes.byteLength === 0 || req.image.bytes.byteLength > MAX_IMAGE)
+            throw bad("image must be 1 byte to 5 MB");
+    }
+    const names = req.types.definitions.map((d) => d.name);
+    for (const o of req.only ?? [])
+        if (!names.includes(o))
+            throw bad(`only names ${o}, which isn't one of the types`);
+    // Checked before the call, so a missing bucket never costs a paid reading.
+    const could = [...(req.only ?? names), "unknown"];
+    if (req.store === undefined && could.some((t) => keeps(req.types, t))) {
+        throw new WorkbenchAiError("invalid_config", "This project keeps its intake input (save_input: project), so ai.intake needs store: env.INTAKE_STORE");
+    }
+    const h = {};
+    if (req.subject !== undefined) {
+        if (!SUBJECT.test(req.subject))
+            throw bad("subject must be type:id");
+        h["X-Workbench-Subject"] = req.subject;
+    }
+    if (req.ref !== undefined) {
+        if (!REF.test(req.ref))
+            throw bad("ref must be [A-Za-z0-9._:-]{1,64}, e.g. enquiry:4812");
+        h["X-Workbench-Ref"] = req.ref;
+    }
+    return h;
+}
+export function createIntake(target) {
+    return async function intake(req) {
+        const headers = check(req);
+        const receivedAt = req.receivedAt instanceof Date ? req.receivedAt.toISOString() : req.receivedAt;
+        const { response, requestId } = await gatewayFetch(target, "/v1/intake/read", {
+            job: req.job,
+            headers,
+            body: {
+                types: req.types.definitions,
+                ...(req.only !== undefined ? { only: req.only } : {}),
+                ...(req.text !== undefined ? { text: req.text } : {}),
+                ...(req.image !== undefined ? { image: { mime_type: req.image.mimeType, data_base64: toBase64(req.image.bytes) } } : {}),
+                ...(receivedAt !== undefined ? { received_at: receivedAt } : {}),
+                ...(req.timeZone !== undefined ? { time_zone: req.timeZone } : {}),
+            },
+        });
+        const body = (await response.json().catch(() => null));
+        if (!body || typeof body["type"] !== "string")
+            throw new WorkbenchAiError("upstream_error", "The Gateway returned no reading", { ...(requestId ? { requestId } : {}) });
+        // The Gateway's answer as it comes (the drafter reads these names), with the request id always there.
+        const result = { ...body, workbench: { ...(body["workbench"] ?? {}), request_id: str(body["workbench"]?.["request_id"]) || requestId || "" } };
+        if (req.store && keeps(req.types, result.type)) {
+            try {
+                result.saved = await save(req.store, req, result, receivedAt);
+            }
+            catch (e) {
+                result.save_error = `Couldn't keep the input: ${e.message}`;
+            }
+        }
+        return result;
+    };
+}
+/** Writes the input to the project's own bucket: images/<sha256>.<ext> and text/<request_id>.json (§5). */
+async function save(store, req, r, receivedAt) {
+    const requestId = r.workbench.request_id;
+    const meta = { request_id: requestId, type: r.type };
+    const saved = { text: { key: `text/${requestId}.json` } };
+    if (req.image) {
+        const sha256 = await sha256Hex(req.image.bytes);
+        const key = `images/${sha256}.${EXT[req.image.mimeType]}`;
+        await store.put(key, req.image.bytes, { httpMetadata: { contentType: req.image.mimeType }, customMetadata: meta });
+        saved.image = { key, sha256, mime: req.image.mimeType, bytes: req.image.bytes.byteLength };
+    }
+    const record = {
+        request_id: requestId,
+        received_at: receivedAt ?? null,
+        type: r.type,
+        type_version: r.type_version,
+        text: req.text ?? null,
+        raw_text: r.raw_text ?? "",
+        data: r.data,
+        ...(saved.image ? { image: saved.image.key } : {}),
+    };
+    await store.put(saved.text.key, JSON.stringify(record), { httpMetadata: { contentType: "application/json" }, customMetadata: meta });
+    return saved;
+}

package/dist/replies.d.ts

@@ -97,6 +97,25 @@ export interface IntakeResult {
         receipt?: unknown;
         [key: string]: unknown;
     };
+    /** From ai.intake: up to three types with their scores. */
+    candidates?: readonly {
+        type: string;
+        confidence: number;
+    }[];
+    /** From ai.intake, when the project keeps its input: where it went in the project's own bucket. */
+    saved?: {
+        image?: {
+            key: string;
+            sha256: string;
+            mime: string;
+            bytes: number;
+        };
+        text: {
+            key: string;
+        };
+    };
+    /** From ai.intake: the input should have been kept and writing it failed. The reading itself is good. */
+    save_error?: string;
 }
 export interface ReplyRequest<G extends string = ReplyGuideName> {
     guide: G;

package/dist/reply-ui.d.ts

@@ -32,5 +32,12 @@ export interface CopyDeps {
 export declare function copyReply(text: string, deps: CopyDeps): Promise<"copied" | "selected">;
 /** Runs on the page: wires every box's Copy button. Stringified into REPLY_SCRIPT, so it uses nothing from outside. */
 export declare function mountReplyBoxes(copy: typeof copyReply): void;
-/** The box's script: put it in the page under its nonce, after the boxes. */
+/**
+ * The box's script: put it in the page under its nonce, after the boxes.
+ *
+ * It is the functions' own source, so whatever bundles the app's Worker shapes
+ * it. Wrangler's esbuild keeps function names by wrapping them in `__name(…)`,
+ * a helper that exists only in the bundle, so the script brings a stand-in of
+ * its own: without it the box's buttons do nothing.
+ */
 export declare const REPLY_SCRIPT: string;

package/dist/reply-ui.js

@@ -142,5 +142,12 @@ export function mountReplyBoxes(copy) {
         });
     }
 }
-/** The box's script: put it in the page under its nonce, after the boxes. */
-export const REPLY_SCRIPT = `(${mountReplyBoxes.toString()})(${copyReply.toString()});`;
+/**
+ * The box's script: put it in the page under its nonce, after the boxes.
+ *
+ * It is the functions' own source, so whatever bundles the app's Worker shapes
+ * it. Wrangler's esbuild keeps function names by wrapping them in `__name(…)`,
+ * a helper that exists only in the bundle, so the script brings a stand-in of
+ * its own: without it the box's buttons do nothing.
+ */
+export const REPLY_SCRIPT = `(function(){var __name=function(f){return f};(${mountReplyBoxes.toString()})(${copyReply.toString()});})();`;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type Anthropic from "@anthropic-ai/sdk";
+import type { AiIntake } from "./intake.ts";
 import type { WorkbenchEnv } from "@mccaskie-labs/workbench-config";
 import type { DraftWithTemplate, ReplyDraft, ReplyGuide, ReplyGuideName, ReplyRequest } from "./replies.ts";
 import type { OwnVoice, SpellingName, VoiceName } from "./writing.ts";
@@ -134,6 +135,8 @@ export interface Ai {
     budget(): Promise<BudgetStatus>;
     /** Image generation and image search (step 4.8). The key needs the images or search scope. */
     readonly images: AiImages;
+    /** Read a social media message into one of the project's intake types (docs/message-intake.md). The key needs the ai scope. */
+    readonly intake: AiIntake;
     /**
      * A ready-to-paste reply from facts and a reply guide (docs/capabilities/04-reply-drafter.md).
      * The model places each fact as a token; the package fills and checks them, so a price or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-ai",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Claude through the Workbench Gateway: text, structured output, streaming, budget status and reply drafts whose facts are checked by code, with no Anthropic key in the app. Refusals and truncations throw; createFakeAi for tests.",
   "license": "UNLICENSED",
   "type": "module",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^1.5.0",
-    "@mccaskie-labs/workbench-config": "^0.3.0",
+    "@mccaskie-labs/workbench-config": "^0.4.0",
     "@mccaskie-labs/workbench-country": "^0.2.1"
   },
   "peerDependencies": {
@@ -55,6 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "24.19.2",
+    "esbuild": "0.28.2",
     "vitest": "^5.1.0",
     "zod": "4.6.7"
   }