@mccaskie-labs/workbench-config 0.3.2 → 0.4.0

package/CHANGELOG.md

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

package/capabilities/intake.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "intake",
+  "title": "Message intake through the Gateway",
+  "summary": "Reads one social media message (a Messenger chat, a group post or a comment), as a screenshot, pasted text or both, into one of the project's own intake types: the type, its fields, what is missing or reads two ways, and whether a person should check it. The types are files in the project's repo, sent with every call. Workbench keeps only the call's facts, never the image or the text; the project can keep them in its own bucket.",
+  "status": "built",
+  "delivery": {
+    "choice": "optional",
+    "intro": "Turns a pasted message or a screenshot of a chat into a filled-in form, so enquiries don't have to be typed up by hand."
+  },
+  "surfaces": {
+    "gateway": [
+      "POST /v1/intake/read"
+    ],
+    "package": [
+      "Ai.intake",
+      "defineIntakeTypes",
+      "IntakeTypes",
+      "IntakeResult"
+    ]
+  },
+  "config": [
+    {
+      "name": "WORKBENCH_GATEWAY_KEY",
+      "required": true,
+      "secret": true,
+      "environments": [
+        "staging",
+        "production"
+      ],
+      "description": "Project key with the ai scope, delivered as a Worker secret by gw_key_issue"
+    }
+  ],
+  "limits": [
+    { "id": "intake.types-per-call", "value": 20, "unit": "types", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.properties-per-type", "value": 40, "unit": "properties", "per": "type", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.definition-size", "value": 16384, "unit": "bytes", "per": "type", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.types-size", "value": 65536, "unit": "bytes", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.text-length", "value": 20000, "unit": "characters", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.image-size", "value": 5242880, "unit": "bytes", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "intake.images-per-call", "value": 1, "unit": "images", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" }
+  ],
+  "errors": [
+    { "code": "invalid_request", "http": 400, "retryable": false, "meaning": "No text or image, an image too large or of another kind, or a type definition that breaks the rules (the message names the type and the JSON path)" },
+    { "code": "budget_exceeded", "http": 402, "retryable": false, "meaning": "The project's budget, its intake cap or the global ceiling is reached" },
+    { "code": "content_refused", "http": 422, "retryable": false, "meaning": "The content rules, or Claude itself, refused the message or the reading" },
+    { "code": "content_check_unavailable", "http": 503, "retryable": true, "meaning": "The content checker is down, so nothing was read" },
+    { "code": "upstream_error", "http": 502, "retryable": true, "meaning": "Anthropic failed after the Gateway's retries" },
+    { "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "Anthropic didn't answer in time" }
+  ],
+  "rules": [
+    {
+      "id": "intake.types-from-files",
+      "kind": "must",
+      "text": "Keep each intake type as a file, workbench/intake/<name>.json, and pass intakeTypes from src/intake.generated.ts. Run npx workbench-ai intake generate after changing one, and keep npx workbench-ai intake generate --check in the project's Checks. Never write definitions inline.",
+      "enforced_by": "types",
+      "probe": "intake.read.text"
+    },
+    {
+      "id": "intake.human-check",
+      "kind": "must",
+      "text": "Act on needsHumanCheck: show the reading to a person (or keep it marked to check) before it becomes a booking, a quote or a reply. It is the Gateway's rule, not the model's score.",
+      "enforced_by": "review",
+      "probe": "intake.read.unknown"
+    },
+    {
+      "id": "intake.personal-marked",
+      "kind": "must",
+      "text": "Mark every field that holds a personal detail with x-personal (name, handle, phone, email, address, photo). An unmarked field whose name or format looks personal is refused, and personal details the type doesn't ask for are blanked in rawText.",
+      "enforced_by": "gateway",
+      "probe": "intake.read.personal-blanked"
+    },
+    {
+      "id": "intake.no-content-kept",
+      "kind": "must_not",
+      "text": "Expect Workbench to keep the image or the text: it keeps only the call's facts. To keep them, set save_input to project in workbench/intake.json and pass store: env.INTAKE_STORE.",
+      "enforced_by": "gateway",
+      "probe": "intake.read.text"
+    },
+    {
+      "id": "intake.subject-is-app-user",
+      "kind": "must_not",
+      "text": "Send the poster's name or number as subject or ref. subject is user:<id> of the app's own user; ref is the app's own record id, such as enquiry:4812.",
+      "enforced_by": "review",
+      "probe": "intake.read.text"
+    },
+    {
+      "id": "intake.bad-type-refused",
+      "kind": "must_not",
+      "text": "Send a type that breaks the format: the Gateway refuses it with invalid_request before any spend.",
+      "enforced_by": "gateway",
+      "probe": "intake.read.bad-type-refused"
+    }
+  ],
+  "examples": [
+    {
+      "id": "intake.example.read",
+      "title": "Read a pasted message or a screenshot",
+      "lang": "ts",
+      "probe": "intake.read.text",
+      "code": "import { intakeTypes } from './intake.generated'\n\nconst r = await ai.intake({ types: intakeTypes, text, image, timeZone: country.timeZone.id, job: 'intake.quote-request', subject: `user:${user.id}`, ref: `enquiry:${enquiry.id}`, store: env.INTAKE_STORE })\nif (r.type === 'venue-quote-request') {\n  await saveEnquiry({ ...r.data, toCheck: r.needsHumanCheck, missing: r.missing })\n}"
+    }
+  ],
+  "probes": [
+    { "id": "intake.read.text", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0.01, "note": "One of HmPo's sample messages as text: the type, the data and no human check" },
+    { "id": "intake.read.unknown", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.01, "note": "A thank-you review comes back unknown, with needs_human_check and unknown_type" },
+    { "id": "intake.read.personal-blanked", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.01, "note": "A message with a phone number the type doesn't ask for: rawText shows [phone]" },
+    { "id": "intake.read.bad-type-refused", "half": "runtime", "expect": "refused_as_expected", "refusal": "invalid_request", "cost_hint_usd": 0, "note": "A type with an unmarked contact_phone field is refused before any spend" }
+  ],
+  "offer": {
+    "pattern": "settings",
+    "when": "The client gets enquiries, orders or posts as messages (Messenger, a Facebook group, comments) and wants them read into a form or a list instead of typed up by hand.",
+    "say": "I'll set this up with Workbench message intake: you paste a message or a screenshot and it fills in the details, and flags the ones a person should check. Workbench never keeps the message. Here are the details I'd pull out; tell me what to change.",
+    "answers_file": "workbench/intake/<name>.json",
+    "per": "kind of message",
+    "generator": "npx workbench-ai intake generate",
+    "answers_format": "One type per file, docs/message-intake.md §3: `{ \"format\": 1, \"name\", \"version\": 1, \"description\" (the client's words, made plain), \"not_this\", \"examples\" (1 to 5 real-looking messages with the data each should give), \"glossary\" (the trade's own shorthand), \"schema\" (the fields from intake.fields; required lists what the app can't do without), \"confidence_floor\", \"model\", \"save_input\" }`. The project's own setting is workbench/intake.json, `{ \"format\": 1, \"save_input\": \"none\" | \"project\" }`. Then run the generator and commit src/intake.generated.ts.",
+    "questions": [
+      {
+        "id": "intake.kind",
+        "sets": ["name", "description"],
+        "ask": "What kind of message do you want read?",
+        "style": "table",
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 200,
+          "description": "In the client's words, such as \"quote requests on Messenger\" or \"orders in comments under our posts\"."
+        },
+        "must_ask": true,
+        "note": "Only the client knows. Name the type after it in lower case with hyphens (venue-quote-request). Ask for two or three real messages (names blanked) to use as examples."
+      },
+      {
+        "id": "intake.fields",
+        "sets": ["schema", "examples"],
+        "ask": "Here are the details I'd pull out of each message. Keep them, change some, or add or remove?",
+        "style": "table",
+        "other": {
+          "kind": "list",
+          "min": 1,
+          "max": 40,
+          "description": "Each detail: its name, what it is, whether the app can't do without it, and the choices if it is one of a list."
+        },
+        "must_ask": true,
+        "note": "Propose from intake.kind, as a table of field, meaning, kind (text, number, date, one of a list), and needed. For an enquiry: the date, how many people, what for, budget, extras. Mark as needed only what the app can't act without; the rest are optional."
+      },
+      {
+        "id": "intake.personal",
+        "sets": "schema.x-personal",
+        "ask": "Should it keep the person's name or contact details?",
+        "style": "cards",
+        "answers": [
+          { "label": "No, leave them out", "value": "none", "means": "Names, numbers and handles are blanked in what it reads, and never kept." },
+          { "label": "Their display name only", "value": "name", "means": "The name shown on the message, so the owner knows who asked." },
+          { "label": "Name and how to reach them", "value": "contact", "means": "The name and a phone number or email when the message gives one." }
+        ],
+        "must_ask": true,
+        "note": "Each kept detail becomes a field marked x-personal with its kind (name, phone, email). Say that what the app keeps is under its own privacy notice."
+      },
+      {
+        "id": "intake.save",
+        "sets": "save_input",
+        "ask": "Should your app keep a copy of each message (the screenshot and its text)?",
+        "style": "cards",
+        "answers": [
+          { "label": "No, read it and let it go", "value": "none", "means": "Only the filled-in details are kept, by your app." },
+          { "label": "Yes, in your own storage", "value": "project", "means": "Your app keeps the screenshot and text in its own private bucket. Workbench never keeps it." }
+        ],
+        "must_ask": true,
+        "note": "project sets save_input in workbench/intake.json and needs the INTAKE_STORE bucket bound to the app (a private R2 bucket <id>-intake per environment, in the projects account). Pass store: env.INTAKE_STORE on every call. Say who will be able to see the copies and for how long."
+      },
+      {
+        "id": "intake.check",
+        "sets": "app.when_unsure",
+        "ask": "When it isn't sure, what should the app do?",
+        "style": "cards",
+        "answers": [
+          { "label": "Ask you to check first", "value": "ask", "means": "The details wait for you to confirm before they are saved." },
+          { "label": "Save it, marked to check", "value": "mark", "means": "It is saved straight away with a \"to check\" mark." },
+          { "label": "Skip it", "value": "skip", "means": "Unsure readings aren't saved; you read the message yourself." }
+        ],
+        "note": "This is the app's own behaviour when needsHumanCheck is true; nothing in the type file changes."
+      },
+      {
+        "id": "intake.model",
+        "sets": "model",
+        "ask": "How careful should the reading be?",
+        "style": "cards",
+        "answers": [
+          { "label": "Careful", "value": "claude-default", "means": "About US$0.01 a message." },
+          { "label": "Quick and cheap", "value": "claude-fast", "means": "Cheaper, and misses more in long or messy chats." }
+        ],
+        "note": "Recommend careful. Leave model out of the file for claude-default."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "confidence_floor",
+        "why": "0.75 suits a start; it is tuned from real results, not asked."
+      },
+      {
+        "sets": "glossary",
+        "why": "Claude adds the trade's own shorthand from the client's example messages (DU for day use); the Gateway's built-in Filipino and Taglish glossary covers everyday words."
+      },
+      {
+        "sets": "budget",
+        "why": "Intake has its own monthly cap in the Gateway, set with Control's gw_budget_set (tool intake); offer it only when the client asks about cost."
+      }
+    ]
+  }
+}

package/capabilities/schema.json

@@ -36,7 +36,8 @@
         "ui",
         "forms",
         "sign-in",
-        "availability"
+        "availability",
+        "intake"
       ]
     },
     "title": {
@@ -432,7 +433,8 @@
           "ui",
           "forms",
           "sign-in",
-          "availability"
+          "availability",
+          "intake"
         ]
       }
     },

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "4a52a6ba9520";
+export declare const MANIFEST_VERSION: "7ad8cef4de58";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -2895,6 +2895,297 @@ export declare const capabilities: {
             readonly intro: "Pictures made by AI from a description.";
         };
     };
+    readonly intake: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "intake";
+        readonly title: "Message intake through the Gateway";
+        readonly summary: "Reads one social media message (a Messenger chat, a group post or a comment), as a screenshot, pasted text or both, into one of the project's own intake types: the type, its fields, what is missing or reads two ways, and whether a person should check it. The types are files in the project's repo, sent with every call. Workbench keeps only the call's facts, never the image or the text; the project can keep them in its own bucket.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly gateway: readonly ["POST /v1/intake/read"];
+            readonly package: readonly ["Ai.intake", "defineIntakeTypes", "IntakeTypes", "IntakeResult"];
+        };
+        readonly config: readonly [{
+            readonly name: "WORKBENCH_GATEWAY_KEY";
+            readonly required: true;
+            readonly secret: true;
+            readonly environments: readonly ["staging", "production"];
+            readonly description: "Project key with the ai scope, delivered as a Worker secret by gw_key_issue";
+        }];
+        readonly limits: readonly [{
+            readonly id: "intake.types-per-call";
+            readonly value: 20;
+            readonly unit: "types";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.properties-per-type";
+            readonly value: 40;
+            readonly unit: "properties";
+            readonly per: "type";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.definition-size";
+            readonly value: 16384;
+            readonly unit: "bytes";
+            readonly per: "type";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.types-size";
+            readonly value: 65536;
+            readonly unit: "bytes";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.text-length";
+            readonly value: 20000;
+            readonly unit: "characters";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.image-size";
+            readonly value: 5242880;
+            readonly unit: "bytes";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "intake.images-per-call";
+            readonly value: 1;
+            readonly unit: "images";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }];
+        readonly errors: readonly [{
+            readonly code: "invalid_request";
+            readonly http: 400;
+            readonly retryable: false;
+            readonly meaning: "No text or image, an image too large or of another kind, or a type definition that breaks the rules (the message names the type and the JSON path)";
+        }, {
+            readonly code: "budget_exceeded";
+            readonly http: 402;
+            readonly retryable: false;
+            readonly meaning: "The project's budget, its intake cap or the global ceiling is reached";
+        }, {
+            readonly code: "content_refused";
+            readonly http: 422;
+            readonly retryable: false;
+            readonly meaning: "The content rules, or Claude itself, refused the message or the reading";
+        }, {
+            readonly code: "content_check_unavailable";
+            readonly http: 503;
+            readonly retryable: true;
+            readonly meaning: "The content checker is down, so nothing was read";
+        }, {
+            readonly code: "upstream_error";
+            readonly http: 502;
+            readonly retryable: true;
+            readonly meaning: "Anthropic failed after the Gateway's retries";
+        }, {
+            readonly code: "upstream_timeout";
+            readonly http: 504;
+            readonly retryable: true;
+            readonly meaning: "Anthropic didn't answer in time";
+        }];
+        readonly rules: readonly [{
+            readonly id: "intake.types-from-files";
+            readonly kind: "must";
+            readonly text: "Keep each intake type as a file, workbench/intake/<name>.json, and pass intakeTypes from src/intake.generated.ts. Run npx workbench-ai intake generate after changing one, and keep npx workbench-ai intake generate --check in the project's Checks. Never write definitions inline.";
+            readonly enforced_by: "types";
+            readonly probe: "intake.read.text";
+        }, {
+            readonly id: "intake.human-check";
+            readonly kind: "must";
+            readonly text: "Act on needsHumanCheck: show the reading to a person (or keep it marked to check) before it becomes a booking, a quote or a reply. It is the Gateway's rule, not the model's score.";
+            readonly enforced_by: "review";
+            readonly probe: "intake.read.unknown";
+        }, {
+            readonly id: "intake.personal-marked";
+            readonly kind: "must";
+            readonly text: "Mark every field that holds a personal detail with x-personal (name, handle, phone, email, address, photo). An unmarked field whose name or format looks personal is refused, and personal details the type doesn't ask for are blanked in rawText.";
+            readonly enforced_by: "gateway";
+            readonly probe: "intake.read.personal-blanked";
+        }, {
+            readonly id: "intake.no-content-kept";
+            readonly kind: "must_not";
+            readonly text: "Expect Workbench to keep the image or the text: it keeps only the call's facts. To keep them, set save_input to project in workbench/intake.json and pass store: env.INTAKE_STORE.";
+            readonly enforced_by: "gateway";
+            readonly probe: "intake.read.text";
+        }, {
+            readonly id: "intake.subject-is-app-user";
+            readonly kind: "must_not";
+            readonly text: "Send the poster's name or number as subject or ref. subject is user:<id> of the app's own user; ref is the app's own record id, such as enquiry:4812.";
+            readonly enforced_by: "review";
+            readonly probe: "intake.read.text";
+        }, {
+            readonly id: "intake.bad-type-refused";
+            readonly kind: "must_not";
+            readonly text: "Send a type that breaks the format: the Gateway refuses it with invalid_request before any spend.";
+            readonly enforced_by: "gateway";
+            readonly probe: "intake.read.bad-type-refused";
+        }];
+        readonly examples: readonly [{
+            readonly id: "intake.example.read";
+            readonly title: "Read a pasted message or a screenshot";
+            readonly lang: "ts";
+            readonly code: "import { intakeTypes } from './intake.generated'\n\nconst r = await ai.intake({ types: intakeTypes, text, image, timeZone: country.timeZone.id, job: 'intake.quote-request', subject: `user:${user.id}`, ref: `enquiry:${enquiry.id}`, store: env.INTAKE_STORE })\nif (r.type === 'venue-quote-request') {\n  await saveEnquiry({ ...r.data, toCheck: r.needsHumanCheck, missing: r.missing })\n}";
+            readonly probe: "intake.read.text";
+        }];
+        readonly probes: readonly [{
+            readonly id: "intake.read.text";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0.01;
+            readonly note: "One of HmPo's sample messages as text: the type, the data and no human check";
+        }, {
+            readonly id: "intake.read.unknown";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.01;
+            readonly note: "A thank-you review comes back unknown, with needs_human_check and unknown_type";
+        }, {
+            readonly id: "intake.read.personal-blanked";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.01;
+            readonly note: "A message with a phone number the type doesn't ask for: rawText shows [phone]";
+        }, {
+            readonly id: "intake.read.bad-type-refused";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "invalid_request";
+            readonly cost_hint_usd: 0;
+            readonly note: "A type with an unmarked contact_phone field is refused before any spend";
+        }];
+        readonly offer: {
+            readonly pattern: "settings";
+            readonly when: "The client gets enquiries, orders or posts as messages (Messenger, a Facebook group, comments) and wants them read into a form or a list instead of typed up by hand.";
+            readonly say: "I'll set this up with Workbench message intake: you paste a message or a screenshot and it fills in the details, and flags the ones a person should check. Workbench never keeps the message. Here are the details I'd pull out; tell me what to change.";
+            readonly answers_file: "workbench/intake/<name>.json";
+            readonly per: "kind of message";
+            readonly generator: "npx workbench-ai intake generate";
+            readonly answers_format: "One type per file, docs/message-intake.md §3: `{ \"format\": 1, \"name\", \"version\": 1, \"description\" (the client's words, made plain), \"not_this\", \"examples\" (1 to 5 real-looking messages with the data each should give), \"glossary\" (the trade's own shorthand), \"schema\" (the fields from intake.fields; required lists what the app can't do without), \"confidence_floor\", \"model\", \"save_input\" }`. The project's own setting is workbench/intake.json, `{ \"format\": 1, \"save_input\": \"none\" | \"project\" }`. Then run the generator and commit src/intake.generated.ts.";
+            readonly questions: readonly [{
+                readonly id: "intake.kind";
+                readonly sets: readonly ["name", "description"];
+                readonly ask: "What kind of message do you want read?";
+                readonly style: "table";
+                readonly other: {
+                    readonly kind: "text";
+                    readonly min: 3;
+                    readonly max: 200;
+                    readonly description: "In the client's words, such as \"quote requests on Messenger\" or \"orders in comments under our posts\".";
+                };
+                readonly must_ask: true;
+                readonly note: "Only the client knows. Name the type after it in lower case with hyphens (venue-quote-request). Ask for two or three real messages (names blanked) to use as examples.";
+            }, {
+                readonly id: "intake.fields";
+                readonly sets: readonly ["schema", "examples"];
+                readonly ask: "Here are the details I'd pull out of each message. Keep them, change some, or add or remove?";
+                readonly style: "table";
+                readonly other: {
+                    readonly kind: "list";
+                    readonly min: 1;
+                    readonly max: 40;
+                    readonly description: "Each detail: its name, what it is, whether the app can't do without it, and the choices if it is one of a list.";
+                };
+                readonly must_ask: true;
+                readonly note: "Propose from intake.kind, as a table of field, meaning, kind (text, number, date, one of a list), and needed. For an enquiry: the date, how many people, what for, budget, extras. Mark as needed only what the app can't act without; the rest are optional.";
+            }, {
+                readonly id: "intake.personal";
+                readonly sets: "schema.x-personal";
+                readonly ask: "Should it keep the person's name or contact details?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "No, leave them out";
+                    readonly value: "none";
+                    readonly means: "Names, numbers and handles are blanked in what it reads, and never kept.";
+                }, {
+                    readonly label: "Their display name only";
+                    readonly value: "name";
+                    readonly means: "The name shown on the message, so the owner knows who asked.";
+                }, {
+                    readonly label: "Name and how to reach them";
+                    readonly value: "contact";
+                    readonly means: "The name and a phone number or email when the message gives one.";
+                }];
+                readonly must_ask: true;
+                readonly note: "Each kept detail becomes a field marked x-personal with its kind (name, phone, email). Say that what the app keeps is under its own privacy notice.";
+            }, {
+                readonly id: "intake.save";
+                readonly sets: "save_input";
+                readonly ask: "Should your app keep a copy of each message (the screenshot and its text)?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "No, read it and let it go";
+                    readonly value: "none";
+                    readonly means: "Only the filled-in details are kept, by your app.";
+                }, {
+                    readonly label: "Yes, in your own storage";
+                    readonly value: "project";
+                    readonly means: "Your app keeps the screenshot and text in its own private bucket. Workbench never keeps it.";
+                }];
+                readonly must_ask: true;
+                readonly note: "project sets save_input in workbench/intake.json and needs the INTAKE_STORE bucket bound to the app (a private R2 bucket <id>-intake per environment, in the projects account). Pass store: env.INTAKE_STORE on every call. Say who will be able to see the copies and for how long.";
+            }, {
+                readonly id: "intake.check";
+                readonly sets: "app.when_unsure";
+                readonly ask: "When it isn't sure, what should the app do?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "Ask you to check first";
+                    readonly value: "ask";
+                    readonly means: "The details wait for you to confirm before they are saved.";
+                }, {
+                    readonly label: "Save it, marked to check";
+                    readonly value: "mark";
+                    readonly means: "It is saved straight away with a \"to check\" mark.";
+                }, {
+                    readonly label: "Skip it";
+                    readonly value: "skip";
+                    readonly means: "Unsure readings aren't saved; you read the message yourself.";
+                }];
+                readonly note: "This is the app's own behaviour when needsHumanCheck is true; nothing in the type file changes.";
+            }, {
+                readonly id: "intake.model";
+                readonly sets: "model";
+                readonly ask: "How careful should the reading be?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "Careful";
+                    readonly value: "claude-default";
+                    readonly means: "About US$0.01 a message.";
+                }, {
+                    readonly label: "Quick and cheap";
+                    readonly value: "claude-fast";
+                    readonly means: "Cheaper, and misses more in long or messy chats.";
+                }];
+                readonly note: "Recommend careful. Leave model out of the file for claude-default.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "confidence_floor";
+                readonly why: "0.75 suits a start; it is tuned from real results, not asked.";
+            }, {
+                readonly sets: "glossary";
+                readonly why: "Claude adds the trade's own shorthand from the client's example messages (DU for day use); the Gateway's built-in Filipino and Taglish glossary covers everyday words.";
+            }, {
+                readonly sets: "budget";
+                readonly why: "Intake has its own monthly cap in the Gateway, set with Control's gw_budget_set (tool intake); offer it only when the client asks about cost.";
+            }];
+        };
+        readonly delivery: {
+            readonly choice: "optional";
+            readonly intro: "Turns a pasted message or a screenshot of a chat into a filled-in form, so enquiries don't have to be typed up by hand.";
+        };
+    };
     readonly pdf: {
         readonly $schema: "./schema.json";
         readonly format: 1;

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 = "4a52a6ba9520";
+export const MANIFEST_VERSION = "7ad8cef4de58";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -3799,6 +3799,369 @@ export const capabilities = {
             "intro": "Pictures made by AI from a description."
         }
     },
+    "intake": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "intake",
+        "title": "Message intake through the Gateway",
+        "summary": "Reads one social media message (a Messenger chat, a group post or a comment), as a screenshot, pasted text or both, into one of the project's own intake types: the type, its fields, what is missing or reads two ways, and whether a person should check it. The types are files in the project's repo, sent with every call. Workbench keeps only the call's facts, never the image or the text; the project can keep them in its own bucket.",
+        "status": "built",
+        "surfaces": {
+            "gateway": [
+                "POST /v1/intake/read"
+            ],
+            "package": [
+                "Ai.intake",
+                "defineIntakeTypes",
+                "IntakeTypes",
+                "IntakeResult"
+            ]
+        },
+        "config": [
+            {
+                "name": "WORKBENCH_GATEWAY_KEY",
+                "required": true,
+                "secret": true,
+                "environments": [
+                    "staging",
+                    "production"
+                ],
+                "description": "Project key with the ai scope, delivered as a Worker secret by gw_key_issue"
+            }
+        ],
+        "limits": [
+            {
+                "id": "intake.types-per-call",
+                "value": 20,
+                "unit": "types",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.properties-per-type",
+                "value": 40,
+                "unit": "properties",
+                "per": "type",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.definition-size",
+                "value": 16384,
+                "unit": "bytes",
+                "per": "type",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.types-size",
+                "value": 65536,
+                "unit": "bytes",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.text-length",
+                "value": 20000,
+                "unit": "characters",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.image-size",
+                "value": 5242880,
+                "unit": "bytes",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "intake.images-per-call",
+                "value": 1,
+                "unit": "images",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            }
+        ],
+        "errors": [
+            {
+                "code": "invalid_request",
+                "http": 400,
+                "retryable": false,
+                "meaning": "No text or image, an image too large or of another kind, or a type definition that breaks the rules (the message names the type and the JSON path)"
+            },
+            {
+                "code": "budget_exceeded",
+                "http": 402,
+                "retryable": false,
+                "meaning": "The project's budget, its intake cap or the global ceiling is reached"
+            },
+            {
+                "code": "content_refused",
+                "http": 422,
+                "retryable": false,
+                "meaning": "The content rules, or Claude itself, refused the message or the reading"
+            },
+            {
+                "code": "content_check_unavailable",
+                "http": 503,
+                "retryable": true,
+                "meaning": "The content checker is down, so nothing was read"
+            },
+            {
+                "code": "upstream_error",
+                "http": 502,
+                "retryable": true,
+                "meaning": "Anthropic failed after the Gateway's retries"
+            },
+            {
+                "code": "upstream_timeout",
+                "http": 504,
+                "retryable": true,
+                "meaning": "Anthropic didn't answer in time"
+            }
+        ],
+        "rules": [
+            {
+                "id": "intake.types-from-files",
+                "kind": "must",
+                "text": "Keep each intake type as a file, workbench/intake/<name>.json, and pass intakeTypes from src/intake.generated.ts. Run npx workbench-ai intake generate after changing one, and keep npx workbench-ai intake generate --check in the project's Checks. Never write definitions inline.",
+                "enforced_by": "types",
+                "probe": "intake.read.text"
+            },
+            {
+                "id": "intake.human-check",
+                "kind": "must",
+                "text": "Act on needsHumanCheck: show the reading to a person (or keep it marked to check) before it becomes a booking, a quote or a reply. It is the Gateway's rule, not the model's score.",
+                "enforced_by": "review",
+                "probe": "intake.read.unknown"
+            },
+            {
+                "id": "intake.personal-marked",
+                "kind": "must",
+                "text": "Mark every field that holds a personal detail with x-personal (name, handle, phone, email, address, photo). An unmarked field whose name or format looks personal is refused, and personal details the type doesn't ask for are blanked in rawText.",
+                "enforced_by": "gateway",
+                "probe": "intake.read.personal-blanked"
+            },
+            {
+                "id": "intake.no-content-kept",
+                "kind": "must_not",
+                "text": "Expect Workbench to keep the image or the text: it keeps only the call's facts. To keep them, set save_input to project in workbench/intake.json and pass store: env.INTAKE_STORE.",
+                "enforced_by": "gateway",
+                "probe": "intake.read.text"
+            },
+            {
+                "id": "intake.subject-is-app-user",
+                "kind": "must_not",
+                "text": "Send the poster's name or number as subject or ref. subject is user:<id> of the app's own user; ref is the app's own record id, such as enquiry:4812.",
+                "enforced_by": "review",
+                "probe": "intake.read.text"
+            },
+            {
+                "id": "intake.bad-type-refused",
+                "kind": "must_not",
+                "text": "Send a type that breaks the format: the Gateway refuses it with invalid_request before any spend.",
+                "enforced_by": "gateway",
+                "probe": "intake.read.bad-type-refused"
+            }
+        ],
+        "examples": [
+            {
+                "id": "intake.example.read",
+                "title": "Read a pasted message or a screenshot",
+                "lang": "ts",
+                "code": "import { intakeTypes } from './intake.generated'\n\nconst r = await ai.intake({ types: intakeTypes, text, image, timeZone: country.timeZone.id, job: 'intake.quote-request', subject: `user:${user.id}`, ref: `enquiry:${enquiry.id}`, store: env.INTAKE_STORE })\nif (r.type === 'venue-quote-request') {\n  await saveEnquiry({ ...r.data, toCheck: r.needsHumanCheck, missing: r.missing })\n}",
+                "probe": "intake.read.text"
+            }
+        ],
+        "probes": [
+            {
+                "id": "intake.read.text",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0.01,
+                "note": "One of HmPo's sample messages as text: the type, the data and no human check"
+            },
+            {
+                "id": "intake.read.unknown",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.01,
+                "note": "A thank-you review comes back unknown, with needs_human_check and unknown_type"
+            },
+            {
+                "id": "intake.read.personal-blanked",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.01,
+                "note": "A message with a phone number the type doesn't ask for: rawText shows [phone]"
+            },
+            {
+                "id": "intake.read.bad-type-refused",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "invalid_request",
+                "cost_hint_usd": 0,
+                "note": "A type with an unmarked contact_phone field is refused before any spend"
+            }
+        ],
+        "offer": {
+            "pattern": "settings",
+            "when": "The client gets enquiries, orders or posts as messages (Messenger, a Facebook group, comments) and wants them read into a form or a list instead of typed up by hand.",
+            "say": "I'll set this up with Workbench message intake: you paste a message or a screenshot and it fills in the details, and flags the ones a person should check. Workbench never keeps the message. Here are the details I'd pull out; tell me what to change.",
+            "answers_file": "workbench/intake/<name>.json",
+            "per": "kind of message",
+            "generator": "npx workbench-ai intake generate",
+            "answers_format": "One type per file, docs/message-intake.md §3: `{ \"format\": 1, \"name\", \"version\": 1, \"description\" (the client's words, made plain), \"not_this\", \"examples\" (1 to 5 real-looking messages with the data each should give), \"glossary\" (the trade's own shorthand), \"schema\" (the fields from intake.fields; required lists what the app can't do without), \"confidence_floor\", \"model\", \"save_input\" }`. The project's own setting is workbench/intake.json, `{ \"format\": 1, \"save_input\": \"none\" | \"project\" }`. Then run the generator and commit src/intake.generated.ts.",
+            "questions": [
+                {
+                    "id": "intake.kind",
+                    "sets": [
+                        "name",
+                        "description"
+                    ],
+                    "ask": "What kind of message do you want read?",
+                    "style": "table",
+                    "other": {
+                        "kind": "text",
+                        "min": 3,
+                        "max": 200,
+                        "description": "In the client's words, such as \"quote requests on Messenger\" or \"orders in comments under our posts\"."
+                    },
+                    "must_ask": true,
+                    "note": "Only the client knows. Name the type after it in lower case with hyphens (venue-quote-request). Ask for two or three real messages (names blanked) to use as examples."
+                },
+                {
+                    "id": "intake.fields",
+                    "sets": [
+                        "schema",
+                        "examples"
+                    ],
+                    "ask": "Here are the details I'd pull out of each message. Keep them, change some, or add or remove?",
+                    "style": "table",
+                    "other": {
+                        "kind": "list",
+                        "min": 1,
+                        "max": 40,
+                        "description": "Each detail: its name, what it is, whether the app can't do without it, and the choices if it is one of a list."
+                    },
+                    "must_ask": true,
+                    "note": "Propose from intake.kind, as a table of field, meaning, kind (text, number, date, one of a list), and needed. For an enquiry: the date, how many people, what for, budget, extras. Mark as needed only what the app can't act without; the rest are optional."
+                },
+                {
+                    "id": "intake.personal",
+                    "sets": "schema.x-personal",
+                    "ask": "Should it keep the person's name or contact details?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "No, leave them out",
+                            "value": "none",
+                            "means": "Names, numbers and handles are blanked in what it reads, and never kept."
+                        },
+                        {
+                            "label": "Their display name only",
+                            "value": "name",
+                            "means": "The name shown on the message, so the owner knows who asked."
+                        },
+                        {
+                            "label": "Name and how to reach them",
+                            "value": "contact",
+                            "means": "The name and a phone number or email when the message gives one."
+                        }
+                    ],
+                    "must_ask": true,
+                    "note": "Each kept detail becomes a field marked x-personal with its kind (name, phone, email). Say that what the app keeps is under its own privacy notice."
+                },
+                {
+                    "id": "intake.save",
+                    "sets": "save_input",
+                    "ask": "Should your app keep a copy of each message (the screenshot and its text)?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "No, read it and let it go",
+                            "value": "none",
+                            "means": "Only the filled-in details are kept, by your app."
+                        },
+                        {
+                            "label": "Yes, in your own storage",
+                            "value": "project",
+                            "means": "Your app keeps the screenshot and text in its own private bucket. Workbench never keeps it."
+                        }
+                    ],
+                    "must_ask": true,
+                    "note": "project sets save_input in workbench/intake.json and needs the INTAKE_STORE bucket bound to the app (a private R2 bucket <id>-intake per environment, in the projects account). Pass store: env.INTAKE_STORE on every call. Say who will be able to see the copies and for how long."
+                },
+                {
+                    "id": "intake.check",
+                    "sets": "app.when_unsure",
+                    "ask": "When it isn't sure, what should the app do?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "Ask you to check first",
+                            "value": "ask",
+                            "means": "The details wait for you to confirm before they are saved."
+                        },
+                        {
+                            "label": "Save it, marked to check",
+                            "value": "mark",
+                            "means": "It is saved straight away with a \"to check\" mark."
+                        },
+                        {
+                            "label": "Skip it",
+                            "value": "skip",
+                            "means": "Unsure readings aren't saved; you read the message yourself."
+                        }
+                    ],
+                    "note": "This is the app's own behaviour when needsHumanCheck is true; nothing in the type file changes."
+                },
+                {
+                    "id": "intake.model",
+                    "sets": "model",
+                    "ask": "How careful should the reading be?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "Careful",
+                            "value": "claude-default",
+                            "means": "About US$0.01 a message."
+                        },
+                        {
+                            "label": "Quick and cheap",
+                            "value": "claude-fast",
+                            "means": "Cheaper, and misses more in long or messy chats."
+                        }
+                    ],
+                    "note": "Recommend careful. Leave model out of the file for claude-default."
+                }
+            ],
+            "not_asked": [
+                {
+                    "sets": "confidence_floor",
+                    "why": "0.75 suits a start; it is tuned from real results, not asked."
+                },
+                {
+                    "sets": "glossary",
+                    "why": "Claude adds the trade's own shorthand from the client's example messages (DU for day use); the Gateway's built-in Filipino and Taglish glossary covers everyday words."
+                },
+                {
+                    "sets": "budget",
+                    "why": "Intake has its own monthly cap in the Gateway, set with Control's gw_budget_set (tool intake); offer it only when the client asks about cost."
+                }
+            ]
+        },
+        "delivery": {
+            "choice": "optional",
+            "intro": "Turns a pasted message or a screenshot of a chat into a filled-in form, so enquiries don't have to be typed up by hand."
+        }
+    },
     "pdf": {
         "$schema": "./schema.json",
         "format": 1,

package/dist/capability-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings", "ui", "forms", "sign-in", "availability"];
+export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings", "ui", "forms", "sign-in", "availability", "intake"];
 export type Component = (typeof COMPONENTS)[number];
 export declare const allowedSchemas: {
     gateway: z.ZodObject<{
@@ -177,6 +177,7 @@ export declare const capabilitySchema: z.ZodObject<{
         github: "github";
         "image-search": "image-search";
         images: "images";
+        intake: "intake";
         kv: "kv";
         pdf: "pdf";
         r2: "r2";
@@ -309,6 +310,7 @@ export declare const capabilitySchema: z.ZodObject<{
         github: "github";
         "image-search": "image-search";
         images: "images";
+        intake: "intake";
         kv: "kv";
         pdf: "pdf";
         r2: "r2";

package/dist/capability-schema.js

@@ -27,6 +27,7 @@ export const COMPONENTS = [
     "forms",
     "sign-in",
     "availability",
+    "intake",
 ];
 const id = z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, "lower case, digits, dots and hyphens");
 const code = z.string().regex(/^[a-z][a-z0-9_]*$/, "a snake_case error code");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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",