@mccaskie-labs/workbench-config 0.0.0-stage → 0.1.1

package/dist/capabilities.gen.js

@@ -0,0 +1,554 @@
+// 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 = "8c09d0a71651";
+export const capabilities = {
+    "ai": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "ai",
+        "title": "Claude through the Gateway",
+        "summary": "Text, structured output and streaming from Claude, metered against the project's budget. Apps never hold an Anthropic key.",
+        "status": "planned",
+        "surfaces": {
+            "gateway": [
+                "POST /anthropic/v1/messages",
+                "POST /anthropic/v1/messages/count_tokens"
+            ],
+            "package": [
+                "createAi",
+                "Ai.text",
+                "Ai.structured",
+                "Ai.stream",
+                "Ai.budget",
+                "createFakeAi"
+            ]
+        },
+        "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"
+            },
+            {
+                "name": "WORKBENCH_ENV",
+                "required": true,
+                "secret": false,
+                "environments": [
+                    "development",
+                    "staging",
+                    "production"
+                ],
+                "description": "Drives key checks; never NODE_ENV"
+            }
+        ],
+        "allowed": {
+            "aliases": [
+                {
+                    "alias": "claude-default",
+                    "provider": "anthropic",
+                    "default_model": "claude-sonnet-5-5"
+                },
+                {
+                    "alias": "claude-best",
+                    "provider": "anthropic",
+                    "default_model": "claude-opus-5-5"
+                },
+                {
+                    "alias": "claude-fast",
+                    "provider": "anthropic",
+                    "default_model": "claude-haiku-5-5"
+                }
+            ],
+            "explicit_models": [
+                "claude-sonnet-5",
+                "claude-opus-5"
+            ],
+            "server_tools": [
+                "web_search",
+                "web_fetch",
+                "code_execution"
+            ],
+            "required_headers": [
+                "X-Workbench-Job"
+            ]
+        },
+        "limits": [
+            {
+                "id": "ai.retry-attempts",
+                "value": 3,
+                "unit": "attempts",
+                "per": "request",
+                "enforced_by": "gateway"
+            }
+        ],
+        "errors": [
+            {
+                "code": "model_not_allowed",
+                "http": 400,
+                "retryable": false,
+                "meaning": "Not an alias or an allowlisted model id"
+            },
+            {
+                "code": "budget_exceeded",
+                "http": 402,
+                "retryable": false,
+                "meaning": "Enforced monthly budget reached"
+            }
+        ],
+        "rules": [
+            {
+                "id": "ai.no-partial-success",
+                "kind": "must_not",
+                "text": "Treat a refusal or a max_tokens truncation as a successful result.",
+                "enforced_by": "types",
+                "probe": "ai.text.truncation-throws"
+            },
+            {
+                "id": "ai.store-resolved-model",
+                "kind": "must",
+                "text": "Store the resolved model and request id with any output kept.",
+                "enforced_by": "review",
+                "probe": "ai.text.claude-default"
+            },
+            {
+                "id": "ai.aliases-only",
+                "kind": "must",
+                "text": "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.",
+                "enforced_by": "gateway",
+                "probe": "ai.model-not-allowed"
+            }
+        ],
+        "examples": [
+            {
+                "id": "ai.example.text",
+                "title": "One-shot text",
+                "lang": "ts",
+                "code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })",
+                "probe": "ai.text.claude-default"
+            }
+        ],
+        "probes": [
+            {
+                "id": "ai.text.claude-default",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0.002
+            },
+            {
+                "id": "ai.text.claude-best",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.004
+            },
+            {
+                "id": "ai.text.claude-fast",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.001
+            },
+            {
+                "id": "ai.stream",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.002
+            },
+            {
+                "id": "ai.structured",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.003
+            },
+            {
+                "id": "ai.text.truncation-throws",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.001
+            },
+            {
+                "id": "ai.model-not-allowed",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "model_not_allowed",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "ai.count-tokens",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0
+            }
+        ]
+    },
+    "config": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "config",
+        "title": "App configuration with workbench-config",
+        "summary": "Reads WORKBENCH_ENV and the app's own variables and secrets. A missing or invalid variable fails at startup, by name, and no value is ever printed.",
+        "status": "built",
+        "surfaces": {
+            "package": [
+                "workbenchEnv",
+                "defineConfig",
+                "sharedSecret",
+                "workerSecret",
+                "redact",
+                "redactAll",
+                "WorkbenchConfigError",
+                "capabilitySchema",
+                "capabilities",
+                "MANIFEST_VERSION",
+                "compareDevVars"
+            ]
+        },
+        "config": [
+            {
+                "name": "WORKBENCH_ENV",
+                "required": true,
+                "secret": false,
+                "environments": [
+                    "development",
+                    "staging",
+                    "production"
+                ],
+                "description": "development, staging or production. Drives key checks and the email transport; never NODE_ENV (audit F9)"
+            }
+        ],
+        "allowed": {
+            "environments": [
+                "development",
+                "staging",
+                "production"
+            ]
+        },
+        "rules": [
+            {
+                "id": "config.fail-by-name",
+                "kind": "must",
+                "text": "Fail at startup when a required variable is missing or invalid, naming every bad variable in one error.",
+                "enforced_by": "types",
+                "probe": "config.missing-variable-named"
+            },
+            {
+                "id": "config.never-print-values",
+                "kind": "must_not",
+                "text": "Print, log or include in an error the value of any variable, valid or not.",
+                "enforced_by": "types",
+                "probe": "config.value-never-printed"
+            },
+            {
+                "id": "config.no-node-env",
+                "kind": "must_not",
+                "text": "Decide the environment from NODE_ENV or a default. WORKBENCH_ENV is required and has no fallback.",
+                "enforced_by": "types",
+                "probe": "config.env-required"
+            },
+            {
+                "id": "config.dev-vars-example",
+                "kind": "must",
+                "text": "Keep .dev.vars.example listing every variable .dev.vars has, with no values; check with npx workbench-config check.",
+                "enforced_by": "review",
+                "probe": "config.dev-vars-check"
+            }
+        ],
+        "examples": [
+            {
+                "id": "config.example.define",
+                "title": "Declare and read the app's variables",
+                "lang": "ts",
+                "code": "import { z } from 'zod'\nimport { defineConfig, workbenchEnv } from '@mccaskie-labs/workbench-config'\n\nconst config = defineConfig({\n  WORKBENCH_GATEWAY_KEY: z.string().startsWith('wbk_'),\n  SITE_NAME: z.string().default('wb-probe'),\n})\n\nexport default {\n  async fetch(request: Request, env: Env) {\n    const stage = workbenchEnv(env)\n    const { WORKBENCH_GATEWAY_KEY, SITE_NAME } = config.parse(env)\n    return new Response(`${SITE_NAME} on ${stage}`)\n  },\n}",
+                "probe": "config.missing-variable-named"
+            }
+        ],
+        "probes": [
+            {
+                "id": "config.missing-variable-named",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "config.value-never-printed",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "config.env-required",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "config.dev-vars-check",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "Manual: run npx workbench-config check in the project"
+            }
+        ]
+    },
+    "gateway": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "gateway",
+        "title": "Workbench Gateway: keys, headers, budgets and errors",
+        "summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
+        "status": "planned",
+        "surfaces": {
+            "gateway": [
+                "GET /v1/health",
+                "GET /v1/usage",
+                "GET /v1/capabilities"
+            ],
+            "package": [
+                "DEFAULT_GATEWAY_URL"
+            ]
+        },
+        "config": [
+            {
+                "name": "WORKBENCH_GATEWAY_KEY",
+                "required": true,
+                "secret": true,
+                "environments": [
+                    "staging",
+                    "production"
+                ],
+                "description": "The project's Gateway key for this environment, delivered as a Worker secret by gw_key_issue. Never in code, .dev.vars.example or logs"
+            },
+            {
+                "name": "WORKBENCH_GATEWAY_URL",
+                "required": false,
+                "secret": false,
+                "default": "https://gateway.mccaskielabs.dev",
+                "environments": [
+                    "development",
+                    "staging",
+                    "production"
+                ],
+                "description": "Gateway base URL. Leave unset outside tests"
+            }
+        ],
+        "allowed": {
+            "scopes": [
+                "ai",
+                "images",
+                "search",
+                "email"
+            ],
+            "key_environments": [
+                {
+                    "environment": "development",
+                    "prefix": "wbk_dev_"
+                },
+                {
+                    "environment": "staging",
+                    "prefix": "wbk_stg_"
+                },
+                {
+                    "environment": "production",
+                    "prefix": "wbk_prd_"
+                }
+            ],
+            "request_headers": [
+                {
+                    "name": "Authorization",
+                    "required": true,
+                    "description": "Bearer <key>. On /anthropic/* the key goes in x-api-key instead, so the official SDK works unchanged"
+                },
+                {
+                    "name": "X-Workbench-Job",
+                    "required": true,
+                    "pattern": "^[a-z0-9._-]{1,64}$",
+                    "description": "What the call is for, e.g. article.write. Recorded with usage"
+                },
+                {
+                    "name": "X-Workbench-Prompt-Version",
+                    "required": false,
+                    "description": "The app's prompt version, recorded with usage (audit F17)"
+                },
+                {
+                    "name": "X-Workbench-Subject",
+                    "required": false,
+                    "pattern": "^[a-z0-9_-]+:[^\\s]{1,128}$",
+                    "description": "type:id of the thing the call is about"
+                },
+                {
+                    "name": "Idempotency-Key",
+                    "required": false,
+                    "description": "Email only: a repeat within 24 hours returns the stored result"
+                }
+            ],
+            "response_headers": [
+                "X-Workbench-Request-Id",
+                "Server-Timing"
+            ],
+            "server_timing_metrics": [
+                "gw",
+                "vendor_fb",
+                "vendor",
+                "total"
+            ]
+        },
+        "limits": [
+            {
+                "id": "gateway.key-cache",
+                "value": 60,
+                "unit": "seconds",
+                "per": "isolate",
+                "enforced_by": "gateway"
+            },
+            {
+                "id": "gateway.budget-cache",
+                "value": 60,
+                "unit": "seconds",
+                "per": "isolate",
+                "enforced_by": "gateway"
+            },
+            {
+                "id": "gateway.job-format",
+                "value": "[a-z0-9._-]{1,64}",
+                "unit": "pattern",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            }
+        ],
+        "errors": [
+            {
+                "code": "unauthorised",
+                "http": 401,
+                "retryable": false,
+                "meaning": "No key, a malformed or unknown key, a revoked key, or a key from the wrong environment"
+            },
+            {
+                "code": "forbidden_scope",
+                "http": 403,
+                "retryable": false,
+                "meaning": "The key doesn't carry the scope this endpoint needs"
+            },
+            {
+                "code": "invalid_request",
+                "http": 400,
+                "retryable": false,
+                "meaning": "The body or a required header is missing or malformed"
+            },
+            {
+                "code": "budget_exceeded",
+                "http": 402,
+                "retryable": false,
+                "meaning": "The environment's enforced monthly budget, or the global ceiling, is reached"
+            },
+            {
+                "code": "rate_limited",
+                "http": 429,
+                "retryable": true,
+                "meaning": "Per-key rate limit; it stops runaway loops, budgets limit spend"
+            },
+            {
+                "code": "not_available",
+                "http": 501,
+                "retryable": false,
+                "meaning": "Not built yet, e.g. bulk email"
+            },
+            {
+                "code": "upstream_error",
+                "http": 502,
+                "retryable": true,
+                "meaning": "The vendor failed after the Gateway's retries"
+            },
+            {
+                "code": "upstream_timeout",
+                "http": 504,
+                "retryable": true,
+                "meaning": "The vendor didn't answer in time"
+            }
+        ],
+        "rules": [
+            {
+                "id": "gateway.no-vendor-keys",
+                "kind": "must_not",
+                "text": "Hold a vendor key (Anthropic, Google, OpenAI, Serper, email) in an app. The Gateway key is the only Workbench credential an app has.",
+                "enforced_by": "review",
+                "probe": "gateway.no-vendor-keys.scan"
+            },
+            {
+                "id": "gateway.key-per-environment",
+                "kind": "must",
+                "text": "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.",
+                "enforced_by": "gateway",
+                "probe": "gateway.wrong-environment"
+            },
+            {
+                "id": "gateway.request-id-kept",
+                "kind": "must",
+                "text": "Keep X-Workbench-Request-Id with any output stored or any error logged, so it can be matched to a usage row.",
+                "enforced_by": "review",
+                "probe": "gateway.health"
+            }
+        ],
+        "probes": [
+            {
+                "id": "gateway.health",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "gateway.bad-key",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "unauthorised",
+                "smoke": true,
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "gateway.wrong-scope",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "forbidden_scope",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "gateway.wrong-environment",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "unauthorised",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "gateway.revoked-key",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "unauthorised",
+                "cost_hint_usd": 0,
+                "note": "Stops within 60 seconds of revocation"
+            },
+            {
+                "id": "gateway.budget-enforced",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "budget_exceeded",
+                "cost_hint_usd": 0.01,
+                "note": "Uses the development key's US$0.01 enforce budget (docs/phase-4-plan.md §3 Q10)"
+            },
+            {
+                "id": "gateway.no-vendor-keys.scan",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets"
+            }
+        ]
+    }
+};