@plumbus/core 0.8.0-beta.1 → 0.8.0-beta.10

package/instructions/ai.md

@@ -31,6 +31,20 @@ Prompts should NOT hardcode `provider` or model `name` unless you have a deliber
 
 ## `ctx.ai` Operations
 
+## Provider admission and trace propagation
+
+Hosts can export `aiProviderConcurrency`, `resolveAIProviderHeaders`, and `onAIProviderSpan`
+from `app/server.ts`. The concurrency ceiling is shared by every identity-bound AI service and
+defaults to a scope of provider + tenant + `costContext.serviceArea`; saturation throws the
+structured `ai-provider-concurrency-exhausted` refusal immediately rather than waiting. Override
+`resolveScope` only when the host has another non-private package/workload key.
+
+`resolveAIProviderHeaders` is called for every real provider attempt, including validation retries
+and streams. Use it for W3C `traceparent`/`tracestate`; credential and content-type headers are
+reserved and refused. `onAIProviderSpan` receives the completed client span and is best effort:
+exporter failures never change the model-call result. Flow workers receive the persisted flow
+correlation id in the same hook, so a host can preserve one trace across request → flow → provider.
+
 ### Generate
 
 Invoke a named prompt with typed input, get validated output:
@@ -56,6 +70,11 @@ const invoice = await ctx.ai.extract({
 
 ### Classify
 
+**Start with [the classification recipe](ai-classification.md)** for provider/model
+selection, TypeSafe/Jev, Laya, and OpenAI Decisions registration, defaults, thresholds,
+and cost hooks (core **0.7.4+** / **0.8.0-beta.6+**). Use `classify()` for matching labels and `decide()`
+for richer typed questions. Keep calls inside capabilities/flows.
+
 Classify text into provided categories:
 
 ```ts
@@ -74,6 +93,8 @@ const docs = await ctx.ai.retrieve({ query: "refund policy for enterprise custom
 // docs: Array<{ content: string, source: string, score: number, metadata?: Record<string, unknown> }>
 ```
 
+`retrieve` passes its `signal` (inside flow steps `ctx.signal` by default) through the RAG pipeline to the adapter's `embed()` as `EmbeddingRequest.signal`: an abort ends the in-flight embedding request and skips the vector search. RAG `ingest`/`retrieve` take `signal` too. A custom `AIProviderAdapter.embed()` must pass `request.signal` to its transport.
+
 Ingest documents with `plumbus rag ingest <path>` (see `cli.md`).
 
 ### Generate With Usage
@@ -89,6 +110,12 @@ const { data, usage, model, provider, cost } = await ctx.ai.generateWithUsage({
 
 `generateWithUsage` is **overloaded**: called without `tools` (as above) it returns the flat `AIFinalGenerateResult` — `.data` is always present, plus a `finishReason`. Called **with** `tools` it returns the discriminated `AIToolEnabledGenerateResult` (see [Tool calling](#tool-calling-provider-native)).
 
+On OpenAI reasoning models `usage.reasoningTokens` is the reasoning share of `outputTokens` (Chat Completions and the Responses API alike, summed over validation retries); it is already priced inside `outputTokens`, so never add it to a cost yourself.
+
+With `enableStrictStructuredOutputs`, the OpenAI adapter sends an output whose root is not an object (`classify()`, a `z.array`/union/enum `extract()` schema or prompt `output`) inside a `{"value": …}` envelope and unwraps the answer itself, merges an `allOf` of several `.regex()`s into one schema, and names a `.default()` in the description (strict mode has no `default`); Zod still validates the original. For every provider the schema converter merges intersections of objects (`a.and(b)`, `a.and(b.optional())`, `a.and(b.nullable())`) into one object, sends `z.string().cidr()` as IPv4-or-IPv6 patterns, a tuple as an array of its item schemas (order in the description), and an optional output root as the value itself. Nothing to do in app code.
+
+`usage.cacheWriteTokens` counts prompt tokens written to the provider cache (Anthropic, and OpenAI's `cache_write_tokens` on Chat Completions and the Responses API); like `cachedInputTokens` it is part of `inputTokens`. Cost charges them 1.25× input on Claude and OpenAI GPT-5.6+, and the input rate on earlier OpenAI models.
+
 `generateWithUsage` also accepts per-call `provider`, `model`, and provider-neutral `reasoning` overrides:
 
 ```ts
@@ -101,11 +128,27 @@ await ctx.ai.generateWithUsage({
 });
 ```
 
-Omit `reasoning` to inherit prompt/config; use `null` to restore the provider/model default for one call, clearing both inherited `reasoning` and inherited legacy `reasoningEffort`. Explicit modes are `{ mode:'disabled' }`, `{ mode:'effort', effort:'minimal'|'low'|'medium'|'high'|'xhigh'|'max' }`, and `{ mode:'budget', maxTokens }`. Built-in core adapters translate the intent: OpenAI uses Chat Completions normally and switches caller-tool requests that need active/default GPT-5.6 reasoning to the Responses API; Anthropic uses `thinking` + `output_config.effort`. Responses tool continuations are stateless (`store:false`) and preserve encrypted reasoning items through server-owned `providerState`. Custom providers translate the contract in their own `AIProviderAdapter`. Unsupported modes fail with `AIInvalidRequestError` before provider I/O when the adapter can identify the incompatibility. Deprecated `reasoningEffort` remains the unchanged OpenAI-only `'low' | 'medium' | 'high'` shorthand.
+A per-call `timeoutMs` (on `generate`, `generateWithUsage`, `streamGenerate`, `extract`, `classify`, `retrieve` and `runToolLoop`; `timeout` on `EmbeddingRequest`, `timeoutMs` on RAG `ingest`/`retrieve`) overrides the prompt's `model.timeoutMs` and the provider's `requestTimeout` for that call; see `prompts.md`. A request its timeout ends throws a non-retryable `ProviderAPIError` carrying `timeoutMs`; detect it with `isProviderTimeoutError(error)` from `@plumbus/core` (`isProviderAPIError` for any provider HTTP failure) instead of checking the error's shape, and raise the timeout rather than retrying.
+
+Omit `reasoning` to inherit prompt/config; use `null` to restore the provider/model default for one call, clearing both inherited `reasoning` and inherited legacy `reasoningEffort`. Explicit modes are `{ mode:'disabled' }`, `{ mode:'effort', effort:'minimal'|'low'|'medium'|'high'|'xhigh'|'max' }`, and `{ mode:'budget', maxTokens }`. Built-in core adapters translate the intent: OpenAI uses Chat Completions normally and switches caller-tool requests, and the `structuredOutputTransport:'tool'` function, that need active/default GPT-5.6 or GPT-6 reasoning to the Responses API; Anthropic uses `thinking` + `output_config.effort`. GPT-6 Chat Completions use `max_completion_tokens`; GPT-6 requests omit sampling temperature unless reasoning is explicitly disabled. Responses tool continuations are stateless (`store:false`) and preserve encrypted reasoning items through server-owned `providerState`. Custom providers translate the contract in their own `AIProviderAdapter`. Unsupported modes fail with `AIInvalidRequestError` before provider I/O when the adapter can identify the incompatibility. No GPT-6 model accepts effort `minimal`, and `gpt-6-astra` / `gpt-6.1-sol` have no off switch (`{ mode:'disabled' }` fails; use `low`). Claude Fable 5.1/5, Mythos 5.1/5/Preview, Opus 5.5/5/4.8/4.7, Sonnet 5.5/5, and Haiku 5.5 reject any `temperature` other than 1, so Plumbus omits both its `0.7` default and any explicitly configured temperature for them. On those models disabled is sent as `thinking: { type: 'between_tools' }` on `claude-sonnet-5-5` and fails on Opus 5.5, Fable, and Mythos (thinking cannot be turned off; lower the effort), and budgets fail on all but `claude-mythos-preview`. Deprecated `reasoningEffort` remains the unchanged OpenAI-only `'low' | 'medium' | 'high'` shorthand.
+
+### Prompt caching (Anthropic / Bedrock)
+
+Included in this beta family (stable core **0.7.9+**). Pass `cache: true` (system + tools) or `{ system?, tools?, messages? }` on `generate` / `generateWithUsage` / `streamGenerate` / `runToolLoop`. To make it the default for every call, set `AI_PROMPT_CACHE=true` (or sections such as `system,messages`); a per-call `cache` overrides it. Anthropic gets `cache_control`; Bedrock Claude gets Converse `cachePoint` (`@plumbus/ai-bedrock` from this beta family, or stable 0.2.2+), except Claude 3 Haiku / Sonnet / Opus and Claude 3.5 Sonnet `20240620`, which reject it, and Claude 3.5 Sonnet v2 (Preview-only on Bedrock). OpenAI and non-Claude Bedrock models ignore the option. Shorter prompts may not meet provider minima — the call still succeeds.
+
+`cache: true` marks only the system prompt and tools. In a single-turn call, a prompt's `description` and its input go into the user message, so keep long, stable instructions in `system`. In multi-turn mode (`messages` set), the description and `Input: {...}` are merged into the system prompt, so an input that changes between turns writes a new cache entry every turn.
+
+```ts
+await ctx.ai.generateWithUsage({
+  prompt: 'classifyTicket',
+  input: { ticketText },
+  cache: true,
+});
+```
 
 ### Tool calling (provider-native)
 
-Pass `tools` to `generate` / `generateWithUsage` to let the model call functions natively. Both built-in adapters implement caller tools on the wire (OpenAI `tools`/`tool_calls`; Anthropic `tool_use`/`tool_result` + `input_schema`). Build each `AITool.parameters` from `zodToProviderJsonSchema(schema).schema`:
+Pass `tools` to `generate` / `generateWithUsage` to let the model call functions natively. Both built-in adapters implement caller tools on the wire (OpenAI `tools`/`tool_calls`; Anthropic `tool_use`/`tool_result` + `input_schema`). OpenAI caller tools are non-strict on both transports (the Responses API gets an explicit `strict: false`, since it would otherwise make every property required and the model would invent values for optional arguments), so optional arguments stay optional; still validate `call.arguments` with the tool's Zod input schema. Build each `AITool.parameters` from `zodToProviderJsonSchema(schema).schema`:
 
 ```ts
 import type { AITool } from "@plumbus/core";
@@ -155,7 +198,7 @@ const { final, messages, rounds } = await runToolLoop(ctx.ai, {
 // final is a flat AIFinalGenerateResult; final.data is the answer.
 ```
 
-`runToolLoop` defaults to `maxRounds: 8` (hard cap 20). On round exhaustion it makes ONE final request that **omits both `tools` and `toolChoice`** (never `toolChoice: 'none'`), so it always resolves to a non-tool answer. Invalid-argument tool calls are **never** executed — they surface to the model as a bounded `tool_arguments_invalid` observation. Observations are byte-bounded and wrapped in an `untrusted_tool_result` envelope.
+`runToolLoop` defaults to `maxRounds: 8` (hard cap 20). On round exhaustion it makes ONE final request that **omits both `tools` and `toolChoice`** (never `toolChoice: 'none'`), so it always resolves to a non-tool answer. Invalid-argument tool calls are **never** executed — they surface to the model as a bounded `tool_arguments_invalid` observation. Observations are byte-bounded and wrapped in an `untrusted_tool_result` envelope. Pass `cache: true` to reuse the cached system prompt and tools across rounds (core 0.7.9+); it is forwarded to every request.
 
 An external `AIProviderAdapter` that omits the optional `capabilities` field is treated as declaring every capability `false` (no tool support).
 
@@ -251,9 +294,11 @@ AI_ANTHROPIC_BASE_URL=https://custom-anthropic.com  # optional
 AI_ANTHROPIC_MODEL=claude-sonnet-4-20250514
 ```
 
+Each provider slot (`AI_` single-provider, `AI_OPENAI_`, `AI_ANTHROPIC_`, `AI_BEDROCK_`) also reads `REQUEST_TIMEOUT` (a whole number of ms from 1 to 2147483647), `MAX_TOKENS` (a whole number of tokens, 0 or more) and `DAILY_COST_LIMIT` (US dollars, 0 or more, e.g. `10.5`); Bedrock also `AI_BEDROCK_PRICING_TTL_MS` (whole ms, 0 or more). Write plain numbers, never units: `15m`, `4k`, `$50` or `abc` make `loadConfig()` throw naming the variable (e.g. `Invalid AI_OPENAI_REQUEST_TIMEOUT="15m": expected a whole number of milliseconds from 1 to 2147483647`), so the process does not start; a blank value is unset.
+
 ### Amazon Bedrock
 
-Requires `@plumbus/core` **≥ 0.6.16** (provider slot, env discovery, adapter `cost`, wiring v13).
+Requires `@plumbus/core` **≥ 0.7.0** (prompt caching needs core **≥ 0.7.9** and `@plumbus/ai-bedrock` **≥ 0.2.2**).
 
 ```bash
 pnpm add @plumbus/ai-bedrock
@@ -288,14 +333,22 @@ Set a global fallback model that all prompts use unless overridden:
 AI_DEFAULT_MODEL=gpt-4o
 ```
 
+### Default Prompt Caching
+
+Turn on Anthropic / Bedrock prompt caching for every call (see [Prompt caching](#prompt-caching-anthropic--bedrock)):
+
+```bash
+AI_PROMPT_CACHE=true            # system + tools; or e.g. system,tools,messages
+```
+
 ### Per-Prompt Overrides
 
-Override model, provider, temperature, or maxTokens for any specific prompt via env vars:
+Override model, provider, temperature, maxTokens, or the request timeout for any specific prompt via env vars:
 
 ```bash
 # Format: PROMPT_{NAME}_{FIELD}
 # Name = prompt name with dots → underscores, UPPERCASED
-# Fields: PROVIDER, MODEL, TEMPERATURE, MAX_TOKENS
+# Fields: PROVIDER, MODEL, TEMPERATURE, MAX_TOKENS, TIMEOUT_MS
 
 # Route "writer.write_chapter" to Anthropic:
 PROMPT_WRITER_WRITE_CHAPTER_PROVIDER=anthropic
@@ -305,16 +358,19 @@ PROMPT_WRITER_WRITE_CHAPTER_MODEL=claude-sonnet-4-20250514
 PROMPT_INTERVIEW_EXTRACT_METADATA_MODEL=gpt-4o-mini
 ```
 
+The HTTP server and the worker pool (flows, jobs, event handlers) both apply these. Numeric fields are checked when the config loads — `TIMEOUT_MS` a whole number of ms from 1 to 2147483647, `MAX_TOKENS` a whole number ≥ 1, `TEMPERATURE` 0–2 — and anything else (`abc`, `0`, `15m`) makes `loadConfig()` throw naming the variable, so the process does not start; a blank value is no override.
+
 ### Model Resolution Chain
 
-When a prompt is invoked, the model is resolved in this order:
+When a prompt is invoked, each field (`provider`, `model`, `temperature`, `maxTokens`, `reasoning`, `timeoutMs`) is resolved on its own, first set wins:
 
-1. **Dynamic overrides** (`resolveAiOverrides` hook) — highest priority
-2. **Per-prompt env override** (`PROMPT_{NAME}_MODEL`)
-3. **Prompt definition** (`model.name` in `definePrompt`) — if set
-4. **Default model** (`AI_DEFAULT_MODEL`) — global fallback
+1. **Per-call value** (`provider`, `model`, `reasoning`, `timeoutMs` on `generate` / `generateWithUsage` / `streamGenerate`)
+2. **Dynamic overrides** (`resolveAiOverrides` hook's `promptOverrides`)
+3. **Per-prompt env override** (`PROMPT_{NAME}_*`)
+4. **Prompt definition** (`model` in `definePrompt`) — if set
+5. **Defaults** — the hook's `defaultModel` / `defaultProvider`, else `AI_DEFAULT_MODEL` / `AI_DEFAULT_PROVIDER`
 
-Provider resolution follows the same chain: dynamic override → per-prompt env → prompt definition → `AI_DEFAULT_PROVIDER`.
+A layer decides only the fields it sets: a hook override `{ model: 'gpt-4.1-mini' }` keeps the prompt's `PROMPT_{NAME}_MAX_TOKENS` and `PROMPT_{NAME}_TIMEOUT_MS`. When an override changes `provider`, set `model` with it, or the model of a lower layer goes to the new provider. `reasoning` and the deprecated `reasoningEffort` count as one field: the highest layer that sets either decides both.
 
 ## Dynamic AI Config (DB Overrides)
 
@@ -330,14 +386,14 @@ export const resolveAiOverrides: NonNullable<ServerConfig['resolveAiOverrides']>
   return {
     defaultModel: 'gpt-4o',        // override global default
     defaultProvider: 'openai',      // override global provider
-    promptOverrides: {              // per-prompt overrides (key = lowercase, dots → underscores)
-      interview_ask_next_question: { model: 'gpt-4o', temperature: 0.7 },
+    promptOverrides: {              // per-prompt overrides, keyed by prompt name
+      'interview.ask_next_question': { model: 'gpt-4o', temperature: 0.7 },
     },
   };
 };
 ```
 
-The framework calls this hook before each `generate()`, `generateWithUsage()`, and `streamGenerate()` call. Dynamic overrides merge with and take priority over env-based config.
+The framework calls this hook before each `generate()`, `generateWithUsage()`, and `streamGenerate()` call, on the HTTP server and the worker pool alike. Its answer replaces the previous one (an override it stops returning no longer applies) and sits above the env config field by field, as in the chain above; unset fields keep the env and prompt values. Key `promptOverrides` by the prompt's name (`interview.ask_next_question`) or its env-style key (`interview_ask_next_question`, lower case, dots → underscores); when both are present, the entry under the name wins.
 
 **Important**: The resolver should implement caching (e.g. 60-second TTL) to avoid querying the database on every AI call. API credentials (API keys) always come from environment variables — only model selection, temperature, and maxTokens should be stored in the database.
 
@@ -368,3 +424,26 @@ See `docs/ai/ai-integration.md` and `docs/upgrading-contract-alignment.md` §12.
 - With security configured, generate/stream/extract/classify apply the field-classification policy. Extract/classify use the `text` field; arbitrary free-text PII is not automatically detected. Explainability stores redacted input.
 - Unknown prior spend rejects further requests when a dollar cap is configured. Local/unpriced providers still work without dollar caps; explicit free prices stay supported. Never supply fake zero costs to bypass budgets.
 - Read [the security release checklist](./upgrading-security-release.md) before upgrading custom cost hooks or AI wrappers.
+
+
+## Typed decisions (core 0.7.4+ / 0.8.0-beta.6+)
+
+For choices, scores, and probabilities, use `ctx.ai.decide()` inside capabilities
+and flows. Define reusable contracts with `defineDecision` from
+`@plumbus/ai-decision`; CLI startup discovers `app/decisions/`. The shared contract
+package is provided by core; install only the TypeSafe, Laya, or OpenAI Decisions
+provider required by the app. Export `decisions = { providers, defaultProvider }` from
+`app/server.ts` for both API and workers, using `createTypeSafeDecisionAdapter`,
+`createLayaDecisionAdapter`, or `createOpenAIDecisionAdapter` at that server-owned
+boundary. Do not register these adapters as text-completion providers or call them
+directly for app business logic.
+
+Core records `operation: 'decide'` with actual model, usage, cost, tenant/actor,
+optional `decisionName`, and the caller's `costContext`. Existing
+`onAICostRecorded(record, costContext, db)` hooks persist these rows; include the
+new operation in any app-owned ledger enum/schema. Failed responses and cancelled
+calls also produce rows. Unknown USD cost is null, never a free zero. Security
+scans state and structured questions; budgets are checked before provider work.
+Use `mockAI({ decide: result })` and test through `runCapability`/`simulateFlow`.
+
+Guide: https://github.com/plumbus-framework/plumbus/blob/main/docs/ai/decision-providers.md

package/instructions/cli.md

@@ -183,7 +183,7 @@ plumbus start --port $PLUMBUS_START_PORT
 plumbus start --port 8080 --host 127.0.0.1
 ```
 
-Behind a load balancer set `TRUST_PROXY=true` (or a specific IP/CIDR) so Fastify trusts `X-Forwarded-*` headers. `app/server.ts` extension hooks (`onRoutesRegistered`, `resolveAiOverrides`, `onCapabilityError`, `onProcessError`, `onAICostRecorded`, `onFlowError`, `enableStrictStructuredOutputs`, `credentials`) are loaded automatically.
+Behind a load balancer set `TRUST_PROXY=true` (or a specific IP/CIDR) so Fastify trusts `X-Forwarded-*` headers. `app/server.ts` extension hooks (`onRoutesRegistered`, `resolveAiOverrides`, `onCapabilityError`, `onProcessError`, `onAICostRecorded`, `onFlowError`, `enableStrictStructuredOutputs`, `credentials`, `authenticationRuntime`) are loaded automatically.
 
 ## Background work
 
@@ -228,6 +228,24 @@ If `@plumbus/mcp` is not installed, `plumbus mcp serve` prints `Run: pnpm add @p
 
 Read `node_modules/@plumbus/core/instructions/mcp.md` and `node_modules/@plumbus/mcp/instructions/README.md` for MCP.
 
+## Payments
+
+For apps with the optional `@plumbus/payments` add-on. The commands load the `payments` export of `app/payments/index.ts`; core does not depend on the add-on.
+
+```bash
+# Check the payments config; --live also checks keys, webhook destinations, and the billing catalog at the provider
+plumbus payments doctor --live --webhook-url https://api.example.com/payments/webhooks/stripe
+
+# Create the provider's webhook destinations (prints each signing secret once; re-run after upgrading the add-on)
+plumbus payments webhooks setup --url https://api.example.com/payments/webhooks/stripe
+
+# Create or update the billing catalog (plans, prices, features, meters) from `billing` in the config
+plumbus payments catalog sync
+plumbus payments catalog check          # read-only; exits 1 when the provider differs (CI)
+```
+
+Read `node_modules/@plumbus/payments/instructions/README.md` for payments.
+
 ## App Commands
 
 Run custom command scripts defined in your project's `app/commands/` directory. Use this for setup scripts, data migration tasks, and other one-off operations that need framework infrastructure (DB, config, password hashing).

package/instructions/entities.md

@@ -35,7 +35,9 @@ export const User = defineEntity({
 |-------------|-----------|-------|
 | `field.id()` | UUID string | Primary key |
 | `field.string(opts)` | Text | General text |
-| `field.number(opts)` | Numeric | Integer or decimal |
+| `field.number(opts)` | 32-bit integer | Counts and small integers |
+| `field.bigint(opts)` | 64-bit integer | Money in minor units (cents) and totals; JS number, safe integers only (core 0.7.7+) |
+| `field.decimal(opts)` | Floating point | Measurements; never money |
 | `field.boolean(opts)` | Boolean | |
 | `field.timestamp(opts)` | Datetime | ISO timestamps |
 | `field.json(opts)` | JSONB | Arbitrary structured data |

package/instructions/flows.md

@@ -114,6 +114,12 @@ retry: {
 
 Steps that fail with transient errors are retried. Permanent failures stop the flow and move it to the dead-letter queue.
 
+Operators can stop an open execution through the framework service. `ctx.flows.cancel(id)`
+aborts the active step and runs every declared compensation for completed steps;
+`ctx.flows.terminate(id)` aborts and closes the execution without compensation. Both leave the
+execution in the terminal `cancelled` state, never `completed`; applications should audit the
+operator, reason, and which action was chosen in their recovery capability.
+
 ## Compiled definitions
 
 Scheduled flows use `createFlowScheduler` and `flow_schedules`. Set `schedule.catchUpPolicy` to `catch-up` for bounded missed-tick catch-up; default is `skip`. Do not add a second scheduler.

package/instructions/framework.md

@@ -117,6 +117,10 @@ package.json          # Private root — delegates scripts via pnpm -r
 
 In monorepo mode the `app/` and `config/` directories live under `backend/`. The CLI auto-detects the layout.
 
+### Discovery
+
+The CLI registers every capability, entity, flow, event, prompt, and translation **exported** from a file under the matching `app/` directory (file names and nesting are free). An exported array, or a plain object without a `name` field, is expanded one level, so an add-on's collections register with one line each — for example `export const paymentCapabilities = payments.capabilities` and `export { paymentEntities } from '@plumbus/payments'`. A definition exported both alone and inside a collection is registered once.
+
 ## Framework-Provided Dependencies
 
 The framework provides common dependencies — **consumer apps must NOT install them separately**. Import through the framework's subpath exports:
@@ -141,20 +145,24 @@ The framework provides common dependencies — **consumer apps must NOT install
 
 ## Server Extensions (`app/server.ts`)
 
-The optional `app/server.ts` file exports hooks that customize server behavior. The framework auto-discovers this file on `plumbus dev` and `plumbus start`.
+The optional `app/server.ts` file exports hooks that customize server behavior. The framework auto-discovers this file on `plumbus dev`, `plumbus start`, and `plumbus worker`.
 
 ### Available Hooks
 
 | Hook | When it fires | Use for |
 |------|--------------|---------|
 | `onRoutesRegistered` | After capability routes are registered | Adding custom routes (e.g. streaming endpoints) |
-| `onCapabilityError` | After a capability returns a non-success result | Logging capability failures to a system log table |
+| `onCapabilityError` | After a capability returns a non-success result in an HTTP route, flow step, job, or event handler (`info.source`: `'http'`, `'flow'`, `'job'`, `'event'`) | Logging capability failures to a system log table |
 | `onFlowError` | After a flow fails permanently (retries exhausted) | Logging flow failures to a system log table |
 | `onProcessError` | On uncaught exceptions, unhandled rejections, and Fastify-level errors | Logging process-level crashes that bypass capability/flow hooks |
 | `resolveAiOverrides` | Before each AI call | Dynamic model/provider configuration from DB |
 | `onAICostRecorded` | After each AI cost record is written | Custom cost analytics or billing hooks |
+| `aiProviderConcurrency` | Around each provider attempt | Immediate per-tenant/provider/package concurrency admission |
+| `resolveAIProviderHeaders` | Before each provider attempt | Trusted W3C propagation headers |
+| `onAIProviderSpan` | After each provider attempt | Export provider client spans |
 | `enableStrictStructuredOutputs` | Server bootstrap | Global toggle for strict structured-output mode |
 | `credentials` | Server bootstrap | Optional host credential catalog (`export const credentials`). Passed to `createServer({ credentials })`. Names, types, refs, and public labels only — secrets stay in the host resolver. |
+| `authenticationRuntime` | Server bootstrap (included in the 0.8 beta family; stable core 0.7.8+) | Browser sign-in with `@plumbus/auth` (`createAuthRuntime(...)`): the same value `createServer({ authenticationRuntime })` takes |
 
 ### Error Capture Coverage
 
@@ -162,12 +170,14 @@ The framework provides hooks for **every error category**:
 
 | Error Type | Hook | Source Field |
 |------------|------|-------------|
-| Capability failure (handler throw, validation, access) | `onCapabilityError` | capability name, domain, error code |
+| Capability failure (handler throw, validation, access) in HTTP routes, flow steps, jobs, and event handlers | `onCapabilityError` | capability name, domain, error code, `source` |
 | Flow permanent failure (retries exhausted) | `onFlowError` | flow name, step, execution ID |
 | Uncaught exception (process crash) | `onProcessError` | `source: 'uncaughtException'` |
 | Unhandled promise rejection | `onProcessError` | `source: 'unhandledRejection'` |
 | Fastify request error (malformed request, timeout) | `onProcessError` | `source: 'fastify'` |
 
+`onCapabilityError` fires once per failed attempt: an event handler that fails on all N delivery attempts fires N times, and a retried flow step fires once per failed attempt. A failed job fires once. `sourceIp` and `userAgent` are set only for `source: 'http'`. Rejections before the capability runs (HTTP authentication, the worker's event/job payload and access checks) and nested `ctx.capabilities.invoke()` calls do not fire it.
+
 ### Example: Full Error Logging
 
 ```ts

package/instructions/peer-dependencies.md

@@ -22,6 +22,7 @@ The previous family remains on core 0.7.x, UI 0.8.x, MCP 0.6.x, voice 0.5.x, and
 | `@plumbus/chat-ui` | `@plumbus/chat` | `">=0.3.0-beta.0 <0.4.0"` (stable: `"0.3.x"`) |
 | `@plumbus/auth-cognito` | `@plumbus/auth` | `">=0.3.0-beta.0 <0.4.0"` (stable: `"0.3.x"`) |
 | Every `@plumbus/voice-*` provider | `@plumbus/voice` | `">=0.6.0-beta.0 <0.7.0"` (stable: `"0.6.x"`) |
+| `@plumbus/payments-stripe` | `@plumbus/payments` | `">=0.3.0-beta.0 <0.4.0"` (stable: `"0.3.x"`) |
 
 UI 0.9.x keeps the required core peer (no direct core dependency) and uses `workspace:*` only for development. This prevents npm from accepting old application core plus a hidden new core nested inside UI. Install core and UI together. All Plumbus packages share the application runtime through peers.
 
@@ -43,4 +44,4 @@ Run lint, format checking, typechecking, tests, and packed npm install checks be
 
 ## Consumer upgrade
 
-Read [upgrading-security-release.md](./upgrading-security-release.md) and the 0.8 notes in the root docs, explicitly select the new package versions for every installed Plumbus add-on, and run `plumbus init --patch` for agent wiring **v16**. Keep application business logic in Plumbus primitives and `ctx.*`; do not bypass security checks to make a migration pass.
+Read [upgrading-security-release.md](./upgrading-security-release.md) and the 0.8 notes in the root docs, explicitly select the new package versions for every installed Plumbus add-on, and run `plumbus init --patch --agent all` for current agent wiring (**v19** in this beta family and stable core 0.7.9+; v17 added the classification recipe). For classification/provider/model selection, read [ai-classification.md](./ai-classification.md). Keep application business logic in Plumbus primitives and `ctx.*`; do not bypass security checks to make a migration pass.

package/instructions/prompts.md

@@ -58,12 +58,13 @@ By default, any input keys not referenced as `{{key}}` in `system`/`description`
 | `maxTokens` | number? | Max output tokens |
 | `reasoning` | `{ mode:'disabled' } \| { mode:'effort', effort } \| { mode:'budget', maxTokens }?` | Provider-neutral reasoning intent; the selected adapter translates or explicitly rejects it |
 | `reasoningEffort` | `'low' \| 'medium' \| 'high'?` | Deprecated OpenAI-only shorthand; unchanged for source/runtime compatibility |
+| `timeoutMs` | number? | How long one provider request may take, in ms (whole number, 1–2147483647), the whole answer included; unset keeps the provider's `requestTimeout` (default 120 000). Raise it for long answers (large `maxTokens`, reasoning); a request it ends fails with a non-retryable `ProviderAPIError` carrying `timeoutMs` |
 
 **Recommended convention:** omit `provider` and `name` in the prompt definition and resolve them via env (`AI_DEFAULT_PROVIDER`, `AI_DEFAULT_MODEL`, `PROMPT_{NAME}_*`) or the `resolveAiOverrides` hook in `app/server.ts`. Set only `temperature`, `maxTokens`, and (when needed) `reasoning` in the prompt when you want per-prompt tuning baked into the contract.
 
 Bare `z.string()` prompt `output` schemas run in plain text mode (same as a single-string-field object). Prefer that for free-text prompts; use an object schema when you need structured fields.
 
-Resolution order: `resolveAiOverrides` → per-prompt env vars → prompt `model` fields → `AI_DEFAULT_MODEL` / `AI_DEFAULT_PROVIDER`.
+Resolution order, field by field (each of `provider`, `model`, `temperature`, `maxTokens`, `reasoning`, `timeoutMs` on its own): per-call value → `resolveAiOverrides` → per-prompt env vars → prompt `model` fields → defaults (the hook's `defaultModel` / `defaultProvider`, else `AI_DEFAULT_MODEL` / `AI_DEFAULT_PROVIDER`). A layer decides only the fields it sets, so a hook override of `model` keeps `PROMPT_{NAME}_TIMEOUT_MS` and `_MAX_TOKENS`; the hook's `promptOverrides` may be keyed by the prompt name or its env-style key (`report_summarize`), the name winning.
 
 ## Structured output and streaming flags
 

package/migrations/durable-tenant/0002_approval_cancellation.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "core_plumbus"."approval_request"
+  ADD COLUMN IF NOT EXISTS cancelled_by_account_id text,
+  ADD COLUMN IF NOT EXISTS cancellation_reason text;

package/migrations/durable-tenant/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1787184060000,
       "tag": "0001_human_task",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1787184120000,
+      "tag": "0002_approval_cancellation",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.10",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -89,7 +89,8 @@
     "xml-crypto": "^6.1.2",
     "xpath": "^0.0.34",
     "zod": "^3.24.0",
-    "zod-to-json-schema": "^3.25.2"
+    "zod-to-json-schema": "^3.25.2",
+    "@plumbus/ai-decision": "~0.3.0-beta.1"
   },
   "peerDependencies": {
     "@plumbus/api": ">=0.3.0-beta.0 <0.4.0",
@@ -121,10 +122,10 @@
     "@vitest/browser": "^3.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
-    "@plumbus/ai-bedrock": "0.3.0-beta.0",
-    "@plumbus/voice": "0.6.0-beta.0",
+    "@plumbus/api": "0.3.0-beta.0",
+    "@plumbus/voice": "0.6.0-beta.1",
     "@plumbus/mcp": "0.7.0-beta.0",
-    "@plumbus/api": "0.3.0-beta.0"
+    "@plumbus/ai-bedrock": "0.3.0-beta.1"
   },
   "scripts": {
     "build": "tsc -b",

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts

@@ -1,5 +0,0 @@
-import { type AIService, type RAGPipelineConfig, type RunToolLoopParams } from '@plumbus/core';
-export declare function legacyConsumer(ai: AIService, params: RunToolLoopParams): Promise<number>;
-export declare const legacyEmbeddingCallback: RAGPipelineConfig['onEmbeddingCost'];
-export declare const uncheckedEstimate: number;
-//# sourceMappingURL=legacy-cost-api.d.ts.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"legacy-cost-api.d.ts","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,wBAAsB,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9F;AAED,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,iBAAiB,CAGxE,CAAC;AAGF,eAAO,MAAM,iBAAiB,EAAE,MAAyC,CAAC"}

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js

@@ -1,15 +0,0 @@
-import { calculateModelCost, estimateModelCost, runToolLoop, } from '@plumbus/core';
-export async function legacyConsumer(ai, params) {
-    const result = await ai.generateWithUsage({ prompt: 'p', input: {} });
-    const cost = result.cost;
-    const loop = await runToolLoop(ai, params);
-    const total = loop.aggregatedCost;
-    return cost + total + calculateModelCost(1, 1, 'local');
-}
-export const legacyEmbeddingCallback = (info) => {
-    const numericCost = info.cost;
-    void numericCost;
-};
-// @ts-expect-error Unknown-aware estimates cannot be treated as definitely priced.
-export const uncheckedEstimate = estimateModelCost(1, 1, 'local');
-//# sourceMappingURL=legacy-cost-api.js.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"legacy-cost-api.js","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,GAIZ,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAa,EAAE,MAAyB;IAC3E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACtE,MAAM,IAAI,GAAW,MAAM,CAAC,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAW,IAAI,CAAC,cAAc,CAAC;IAC1C,OAAO,IAAI,GAAG,KAAK,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAyC,CAAC,IAAI,EAAE,EAAE;IACpF,MAAM,WAAW,GAAW,IAAI,CAAC,IAAI,CAAC;IACtC,KAAK,WAAW,CAAC;AACnB,CAAC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC"}