@jxburros/ai-nugget 0.3.1 → 0.6.0

package/README.md

@@ -1,316 +1,179 @@
 # AI Nugget
 
-`AI Nugget` is a small, zero-dependency, isomorphic TypeScript nugget for
-talking to AI model providers through one pipeline:
+**Version 0.6.0** · [What's changed since 0.5.0](#whats-changed-since-050) · [Changelog](./CHANGELOG.md) · [Upgrading](./UPGRADING.md)
+
+A small, zero-dependency, isomorphic TypeScript nugget for talking to AI model
+providers through one pipeline:
 
 ```
 policy → key resolution → beforeCall hook → concurrency/retry → provider adapter → redacted telemetry
 ```
 
-It runs identically in Node ≥ 20, the browser main thread, and Web Workers using
-only `fetch`, `ReadableStream`, `AbortController`, and `TextDecoder`. It is
-intentionally **not** a router, prompt library, memory system, or secrets vault:
-apps choose models, own prompts, store secrets, and decide what policy to enforce.
-The package is MIT licensed.
+19 provider profiles over 4 protocol engines. Runs identically in Node, the
+browser main thread, and Web Workers using only `fetch`, `ReadableStream`,
+`AbortController`, and `TextDecoder`. MIT licensed.
+
+It is intentionally **not** a router, prompt library, memory system, or secrets
+vault: apps choose models, own prompts, store secrets, and decide policy.
+
+## Quick start
 
-See `design.md` for the full contract. The original evidence base, phased
-build/adoption plan, and dev handoff are archived under `docs/archive/`.
+Requires Node `^20.19.0` or `>=22.12.0` ([why](./docs/distribution.md#requirements)).
 
-## Install / use
+```bash
+npm install @jxburros/ai-nugget
+```
 
 ```ts
 import { AIHandler, envKeySource } from '@jxburros/ai-nugget';
 
 const handler = new AIHandler({ keySource: envKeySource() });
 
+const conn = { id: 'main', provider: 'openai', keyRef: { kind: 'env', name: 'OPENAI_API_KEY' } };
+const req = { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] };
+
 // Non-streaming
-const result = await handler.chat(
-  { id: 'main', provider: 'openai', keyRef: { kind: 'env', name: 'OPENAI_API_KEY' } },
-  { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] },
-);
+const result = await handler.chat(conn, req);
 console.log(result.text, result.usage, result.finishReason);
 
-// Streaming (works in Node route handlers, React, and Web Workers)
+// Streaming (Node route handlers, React, Web Workers — same code)
 for await (const event of handler.stream(conn, req)) {
   if (event.type === 'delta') process.stdout.write(event.text);
   if (event.type === 'done') console.log('\n', event.result.usage);
+  if (event.type === 'error') console.error(event.error.kind, event.error.message);
 }
 ```
 
-Repos that cannot take a package dependency can vendor the generated `nugget/`
-folder (see below).
+No key? Point at a local model instead — same code, no `keyRef`:
 
-## Providers
-
-Four **protocol engines** own the wire formats; a data-driven **profile table**
-turns each named provider into defaults + quirks on top of an engine, so adding
-an OpenAI-compatible provider is a table row, not another copy of the SSE loop.
+```ts
+const conn = { id: 'local', provider: 'ollama', baseUrl: 'http://127.0.0.1:11434' };
+```
 
-| Engine | Providers | Streaming | Tools | JSON mode |
-|---|---|---|---|---|
-| `openaiChat` | `openai`, `azure-openai`, `openrouter`, `groq`, `deepseek`, `mistral`, `together`, `fireworks`, `lmstudio`, `llamacpp`, `vllm`, `openai-compat` | SSE + `stream_options.include_usage` | `tools`/`tool_calls` deltas | `response_format` (`json_schema` where supported, otherwise `json_object`) |
-| `anthropic` | `anthropic` | SSE (`content_block_delta`) | `tool_use` blocks (streamed) | forced-tool JSON mode |
-| `google` | `google` | SSE (`streamGenerateContent`) | `functionDeclarations` | `responseMimeType` |
-| `ollama` | `ollama` | NDJSON | native `tools` | `format: json` |
+CommonJS works too: `const { AIHandler } = require('@jxburros/ai-nugget')`.
 
-`adapterFor(provider)` lives once, in `adapters/index.ts`. Unknown provider keys
-with a `baseUrl` resolve to the `openai-compat` escape hatch. **Grok/xAI is not
-blocked and is never officially integrated** — point `openai-compat` at any
-endpoint if you must; that is your configuration, not a supported profile.
+For a running server, copy a starter from
+[`examples/integrations/`](./examples/integrations/) — Express, Next.js,
+Cloudflare Workers, or local Ollama.
 
-Model identity is always `(source, model)` — `modelRef(source, model)` gives the
-canonical `provider/model` key so the same weights served by different hosts stay
-distinct and comparable.
+## Two things to configure before production
 
-### Provider capabilities
+Both are seams the library leaves open on purpose, and both are easy to miss:
 
-Beyond wire-format `quirks` (auth, URL templates, whether a stream reports
-usage), each profile also carries `capabilities` — the higher-level questions
-apps need answered before they pick behavior:
+1. **Never take `provider` or `baseUrl` from client input.** They decide where
+   your resolved API key gets sent. Keep connections on a server-side allowlist
+   and let clients pick an id. → [security.md](./docs/security.md#ssrf-caller-controlled-baseurl)
+2. **Configure a `GovernancePolicy`.** With none, every provider and model is
+   allowed; the handler logs a startup notice so this is visible at runtime.
+   → [security.md](./docs/security.md#governance-is-neutral-by-default)
 
 ```ts
-interface ProviderCapabilities {
-  nativeTools: boolean;   // reliable native tool/function-calling for this
-                          // provider's protocol (not just model-dependent)
-  jsonMode: boolean;      // a provider-enforced structured-output mode exists
-  local: boolean;         // runs on localhost / user-controlled infra
-  embeddable: boolean;    // meant to run as a local sidecar, not a hosted service
-}
+new AIHandler({
+  keySource: envKeySource(),
+  policy: allowlistPolicy({ openai: ['gpt-4o', 'gpt-4o-mini'], ollama: ['*'] }),
+});
 ```
 
-Hosted cloud providers (`openai`, `azure-openai`, `openrouter`, `groq`,
-`deepseek`, `mistral`, `together`, `fireworks`, `anthropic`, `google`) ship
-`{ nativeTools: true, jsonMode: true, local: false, embeddable: false }`. Local
-runtimes (`lmstudio`, `llamacpp`, `vllm`, and the `openai-compat` escape hatch)
-ship the conservative `{ nativeTools: false, jsonMode: false, local: true,
-embeddable: true }`, since native tool support there is model-dependent, not
-protocol-guaranteed. `ollama` is the one exception with `jsonMode: true` —
-its `format: 'json'` is engine-enforced regardless of which model is loaded.
-These are per-provider defaults, not per-model guarantees: a caller that knows
-its specific loaded model better should configure behavior explicitly (e.g.
-`toolMode: 'native'`) rather than rely on the default.
-
-Access via `profileFor(provider, baseUrl).capabilities`.
-
-**These are provider-level defaults, not per-model guarantees.** A specific
-model behind a "hosted" provider can still lack reliable native tool-calling
-(and a specific local model behind a "local" provider can have it) — this
-matters most for OpenRouter, Ollama, LM Studio, vLLM, and any
-`openai-compat` endpoint, where the model actually loaded is opaque to the
-profile table. A caller that knows its model better should pass an explicit
-`toolMode` (agent layer) rather than rely on the capability default.
-
-**`listModels()` is optional per adapter — two engines never return anything.**
-`ProviderAdapter.listModels` is `?`-optional, and `AIHandler.listModels()`
-falls back to `[]` when an adapter doesn't implement it. Concretely: the
-`openaiChat` and `ollama` engines implement it (`GET /models` /
-`GET /api/tags`); the `anthropic` and `google` engines currently don't, so
-`handler.listModels()` for those providers always resolves to `[]`, not an
-error. This is easy to miss because `capabilities` doesn't surface it — an
-app building a model picker on top of `listModels()` should treat an empty
-result as "this provider doesn't support discovery," not "this provider has
-no models," and have a fallback (e.g. an app-configured default model per
-connection) ready for `anthropic`/`google` rather than showing an empty list.
-
-### Letting an app's users pick a model (best practice)
-
-The nugget deliberately has no concept of "the app's currently selected
-model" — that's app policy, same as governance (see Non-goals). The pattern
-that has worked well for apps building a model-picker UI on top of the
-AI Nugget handler:
-
-1. **Keep `provider`/`baseUrl` on a server-side allowlist; never take them
-   from client input.** A `Connection`'s `provider`/`baseUrl` decide where
-   the server's resolved API key gets sent (via `KeySource` → `applyAuth`);
-   letting a client control either directly is effectively letting it
-   redirect a real credential to an arbitrary endpoint (SSRF plus key
-   exposure). Define your app's available connections server-side (e.g. a
-   small config list, each with its own `KeyRef`), and only let the client
-   choose a `connectionId` out of that list.
-2. **`model` is fine as ordinary client input.** Unlike `provider`/`baseUrl`,
-   a bad or unexpected `model` string just comes back as a normal provider
-   error (unknown model) from `chat()`/`stream()` — there's no equivalent
-   security concern, so there's no need to allowlist it server-side beyond
-   what the provider itself enforces.
-3. **Use `handler.listModels(connection)` to populate the picker live**, and
-   fall back to an app-configured default model for connections whose engine
-   doesn't implement discovery (see above).
-
-See `examples/model-picker.mjs` for a minimal runnable reference implementing
-this pattern.
-
-## What's implemented
-
-- **Core:** message-based contracts (`types.ts`), typed `AIError` + `classify()`,
-  timeout/abort merging and SSE/NDJSON readers (`transport.ts`), defensive JSON
-  extraction with array support + schema guards (`json.ts`), token estimation with
-  an explicit `estimated` flag (`tokens.ts`).
-- **Adapters:** all four engines with streaming, native tool-calling, JSON modes,
-  `finishReason` mapping, buffered-`stream:true` fallback, first-token latency,
-  and usage normalization; the full v1 provider profile table. The
-  OpenAI-compatible engine only sends `stream_options: { include_usage: true }`
-  when the profile's `supportsUsageInStream` quirk confirms the server expects
-  it — local servers (llama.cpp, LM Studio, vLLM) that don't have the quirk set
-  never receive the option. The OpenAI and Azure OpenAI profiles send
-  `max_completion_tokens` for `maxTokens`; local/OpenAI-compatible profiles keep
-  `max_tokens` for compatibility. Google receives `responseSchema` for JSON mode
-  only when native tools are absent, avoiding Gemini's JSON-with-tools rejection.
-- **Pipeline (`AIHandler`):** policy → keys → `beforeCall` → concurrency/min-interval
-  → jittered retry (honoring `Retry-After`) → redacted `CallRecord` telemetry →
-  `afterCall`, with `chat`, `stream`, `listModels`, `testConnection`. Every call —
-  success, failure, or consumer-abandoned stream — produces one redacted telemetry
-  record. Retries stop once user-visible output has been emitted, and telemetry
-  or `afterCall` failures never re-execute an already-successful provider call.
-  `listModels()` and `testConnection()` use explicit operation IDs
-  (`__listModels__`, `__testConnection__`) so policy and telemetry can see those
-  key-bearing probes too.
-- **Seams:** `KeySource` (`env`/`literal`/`memory`/chain + ref parsing),
-  `Redactor` (default secret patterns + session-resolved key redaction),
-  neutral `GovernancePolicy` (`blocklistPolicy`/`allowlistPolicy`/`composePolicies`).
-  `allowlistPolicy` fails closed for providers omitted from the configured map;
-  use `'*'` in a provider's prefix list to allow non-chat operation IDs.
-  The default redactor covers common provider token formats and generic bearer
-  tokens, with session-resolved keys always added exactly.
-- **Agent layer (`@jxburros/ai-nugget/agent`):** `defineTool` + light JSON-schema
-  arg validation (object-ness, `required`, top-level `properties[key].type` —
-  not full JSON Schema: no `enum`, nested schemas, `oneOf`, bounds, `pattern`,
-  array `items`, or `additionalProperties`; validate again inside
-  `tool.execute` if you need stricter guarantees), `runAgent()` model↔tool loop
-  over the full handler pipeline,
-  streamed `AgentEvent`s, budgets (`maxSteps`/`maxTokens`/`deadlineMs`) with honest
-  `stopReason`s, `ApprovalGate` for side-effecting tools (deny is fed back to the
-  model as data), and `native` / `promptJson` / `auto` tool modes. `auto` (the
-  default) resolves per call from the connection's provider capability profile
-  (`profileFor(provider).capabilities.nativeTools`) — hosted providers get
-  `native`, local runtimes and the `openai-compat` escape hatch get
-  `promptJson`, and an explicit `toolMode` always overrides the default.
-  `promptJson` mode accepts a single `{"tool","input"}` directive or a batched
-  `{"tools":[…]}` (a bare array works too), so the model can request several
-  tools in one turn just like native tool-calling. Prompt-JSON history is
-  serialized as plain text turns, not provider-native tool-call wire format.
-
-```ts
-import { runAgent, defineTool } from '@jxburros/ai-nugget/agent';
-```
-
-## Commands
+## Documentation
+
+| Doc | Covers |
+|---|---|
+| [providers.md](./docs/providers.md) | The 19 profiles, which are **live-verified vs mock-verified vs config-only**, capabilities, JSON-mode/tools limits, `openai-compat`, model discovery |
+| [reliability.md](./docs/reliability.md) | `timeoutMs` vs `idleTimeoutMs`, why retries stop after output is emitted, double-billing and idempotency, why limits are per-instance |
+| [security.md](./docs/security.md) | Key handling, redaction coverage, SSRF, opt-in injection defenses, the secure-tool recipe |
+| [agent-loop.md](./docs/agent-loop.md) | `runAgent`, tool modes, budgets and what happens mid-step, the approval gate |
+| [recipes.md](./docs/recipes.md) | Env-based connections, JSON output + validation, the error-handling matrix, telemetry |
+| [integrations.md](./docs/integrations.md) | The host matrix CI runs (Node, Next.js, Workers, local runtime, packaging) |
+| [distribution.md](./docs/distribution.md) | Commands, live smoke tests, CI workflows, npm/GitHub Packages/vendored `nugget/`, bundler notes |
+| [design.md](./design.md) | The full contract |
+| [state-of-the-nugget.md](./docs/state-of-the-nugget.md) | Current health snapshot: architecture, safety and reliability posture, coverage gaps, what's next |
+| [UPGRADING.md](./UPGRADING.md) | Version-by-version changes |
+
+## What's in the box
+
+- **Core** — message-based contracts (`types.ts`), typed `AIError` + `classify()`
+  with wire-boundary redaction, timeout/idle-timeout/abort merging and SSE/NDJSON
+  readers (`transport.ts`), defensive JSON extraction with schema guards
+  (`json.ts`), token estimation with an explicit `estimated` flag.
+- **Adapters** — four engines (`openaiChat`, `anthropic`, `google`, `ollama`)
+  with streaming, native tool-calling, JSON modes, `finishReason` mapping,
+  buffered-`stream:true` fallback, reasoning-token channel, first-token latency,
+  usage normalization, and truncation detection (`stream_anomaly`). Provider
+  differences live in a data-driven profile table, not in copies of the SSE loop.
+- **Pipeline (`AIHandler`)** — `chat`, `stream`, `chatParsed`, `embed`,
+  `listModels`, `testConnection`, `prewarm`. Every call — success, failure, or
+  abandoned stream — produces exactly one redacted `CallRecord`. Retries are
+  jittered and honor `Retry-After`; telemetry or `afterCall` failures never
+  re-run a completed provider call.
+- **Seams** — `KeySource` (env/literal/memory/chain + ref parsing), `Redactor`,
+  neutral `GovernancePolicy` (`blocklistPolicy`/`allowlistPolicy`/`composePolicies`),
+  `TelemetrySink`, and an optional `pricing` hook. `providerOptions` passes
+  provider-native fields through without waiting for a library release.
+- **Agent layer** (`@jxburros/ai-nugget/agent`) — `defineTool`, `runAgent()`
+  model↔tool loop over the full pipeline, streamed `AgentEvent`s, budgets with
+  honest `stopReason`s, an `ApprovalGate` for side-effecting tools, and
+  `native`/`promptJson`/`auto` tool modes.
+
+## What's changed since 0.5.0
+
+**0.6.0 is backward-compatible** — every change below is additive. The one thing
+to check is the new `not_found` error kind if you `switch` exhaustively over
+`AIErrorKind`; see [UPGRADING.md](./UPGRADING.md#05x--060). Full detail lives in
+the [changelog](./CHANGELOG.md).
+
+- **Security & correctness** — `beforeCall` hooks now receive a scrubbed
+  connection (masked literal `keyRef` and auth headers, safe to log);
+  `classify()` redacts provider response excerpts at the wire boundary so an
+  `AIError` can never carry an unredacted secret; label-anchored redaction
+  covers unprefixed secrets (Azure `api-key`, AWS keys, `client_secret`, session
+  tokens); a new `not_found` error kind distinguishes 404/410 from a malformed
+  request; and Ollama tool-call arguments coerce through the shared parser so a
+  llama.cpp-style backend sending JSON-as-string no longer fails.
+- **Observability** — `stream_anomaly` detection now fires on all four engines
+  (not just `openaiChat`); Google and Anthropic emit `json_mode_downgraded` when
+  a JSON mode is dropped for tools; `AIHandler` logs a startup notice when no
+  `GovernancePolicy` is configured; and OpenAI requests carry a stable
+  `Idempotency-Key` across retries to mitigate double-billing.
+- **Providers & types** — `openai-compat` is now `keyOptional`, matching the
+  other local-runtime profiles, so keyless servers (including JX Runtime) work
+  without a `keyRef`; `Connection.provider` is typed `KnownProvider | (string &
+  {})` for autocomplete and typo-catching with the escape hatch still open.
+- **Docs & examples** — `README.md` was trimmed to a front door with reference
+  material moved under [`docs/`](./docs/) (`providers`, `reliability`,
+  `security`, `agent-loop`, `recipes`, `integrations`, `distribution`), and
+  [`examples/integrations/`](./examples/integrations/) added five CI-verified
+  starters (Express, Next.js, Cloudflare Workers, local Ollama, ESM/CJS
+  packaging check).
+
+## Contributing
+
+`AGENTS.md` is the always-on baseline — invariants, required reading, and the
+[admission test](./AGENTS.md#feature-admission-test) a new feature has to pass.
+`.claude/skills/` holds task-specific guides (`use-ai-nugget`,
+`build-agent-loop`, `add-provider`, `develop-nugget`) that Claude Code loads
+automatically and any agent or human can read as plain Markdown.
 
 ```bash
-npm install
-npm test            # Vitest contract suite in Node (97 tests; live tests skipped unless env-gated)
-npm run test:browser   # same suite in headless Chromium (proves isomorphism)
-npm run build       # tsc → dist/ (also the typecheck)
-npm run build:nugget   # writes a vendorable nugget/ stamped with version + content hash
+npm test              # Node contract suite
+npm run test:browser  # same suite in headless Chromium (isomorphism)
+npm run build && npm run build:nugget
 ```
 
-### Live smoke tests (optional, env-gated)
-
-`tests/live-smoke.test.ts` exercises the real wire path against a live provider.
-It is **skipped unless `AI_HANDLER_LIVE=1`**, so it never runs in the default
-suite or in CI:
-
-```bash
-# Local Ollama (defaults: provider=ollama, model=llama3.2)
-AI_HANDLER_LIVE=1 npm run test:live
-
-# A cloud provider, with JSON-mode and agent tool-loop checks enabled
-AI_HANDLER_LIVE=1 AI_HANDLER_LIVE_PROVIDER=openai AI_HANDLER_LIVE_MODEL=gpt-4o-mini \
-  AI_HANDLER_LIVE_KEY_ENV=OPENAI_API_KEY AI_HANDLER_LIVE_JSON=1 AI_HANDLER_LIVE_TOOLS=1 \
-  npm run test:live
-```
-
-Config env vars: `AI_HANDLER_LIVE_PROVIDER`, `AI_HANDLER_LIVE_MODEL`,
-`AI_HANDLER_LIVE_BASE_URL`, `AI_HANDLER_LIVE_KEY` (literal) or
-`AI_HANDLER_LIVE_KEY_ENV` (key from an env var), `AI_HANDLER_LIVE_JSON`,
-`AI_HANDLER_LIVE_TOOLS`.
-
-**Live provider matrix (`.github/workflows/live-matrix.yml`).** The default
-CI workflow only exercises mocked fetch responses, so subtle live-wire
-behavior differences (OpenAI, Anthropic, Google, OpenRouter, and local
-runtimes each drift independently) can't surface there. `live-matrix.yml`
-runs the same `tests/live-smoke.test.ts` suite against real endpoints —
-manually (`workflow_dispatch`) or on a weekly schedule — never on push/PR, so
-it can't block or flake a normal CI run. Each matrix entry reads its API key
-from a same-named repository secret (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
-`GOOGLE_API_KEY`, `OPENROUTER_API_KEY`) and skips itself with a notice if that
-secret isn't configured, so you only need to add secrets for the providers
-you actually use. Local runtimes (Ollama, llama.cpp, LM Studio, vLLM) aren't
-in the matrix since they need a reachable server; smoke-test those manually
-with the local `test:live` invocation above.
-
-## Distribution
-
-Three supported paths, in order of preference:
-
-1. **npm registry (primary).** `@jxburros/ai-nugget` publishes to
-   [npmjs.org](https://www.npmjs.com/package/@jxburros/ai-nugget) on every
-   published GitHub release (`.github/workflows/publish.yml`). Consumers install
-   from the normal npm registry:
-
-   ```bash
-   npm install @jxburros/ai-nugget@^0.3.1
-   ```
-
-   This is the default dependency path for apps: fix once here, bump the
-   dependency in each app, and let npm resolve it normally.
-2. **GitHub Packages (kept).** The same release workflow also publishes
-   `@jxburros/ai-nugget` to GitHub Packages for GitHub-native workflows and
-   existing portfolio consumers that already point at that registry. Those apps
-   add a project `.npmrc`:
-
-   ```
-   @jxburros:registry=https://npm.pkg.github.com
-   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-   ```
-
-   (GitHub Packages requires an authenticated token even for public-repo
-   packages.) Then `npm install @jxburros/ai-nugget@^0.3.1`.
-3. **Vendored `nugget/` (fallback).** `nugget/` is a generated single-folder
-   build (`src/` + `VERSION.txt` with a version + content-hash stamp) for repos
-   that cannot take a package dependency. Copy it in; `VERSION.txt` makes drift
-   from the source of truth detectable. (Bundlers that don't resolve
-   `.ts`+`.js`-suffixed imports the way `tsc` does — e.g. Turbopack — should
-   vendor `dist/` instead; see below.)
-
-`dist/` (ESM + `.d.ts`) is the package's own build output. `dist/` and
-`nugget/` are both committed and regenerated from `src/`; `prepublishOnly`
-rebuilds both, and CI fails if either is stale.
-
-**Bundler compatibility for the vendored `nugget/` path.** `nugget/src/*.ts`
-uses NodeNext-style relative imports with explicit `.js` extensions (e.g.
-`export * from './types.js'`), which `tsc` needs to resolve `.ts` files under
-`moduleResolution: bundler`/`nodenext`. Not every bundler's runtime module
-graph treats `.ts`/`.js` as interchangeable the way `tsc` does — confirmed
-with Next.js 16's Turbopack: aliasing straight at `nugget/src/index.ts`
-type-checks but fails to resolve at build/dev time (`Module not found: Can't
-resolve './types.js'`), and aliasing at the compiled `dist/index.d.ts` builds
-but silently resolves some named exports to `undefined` at runtime. If your
-bundler hits this, vendor `dist/` (real `.js` + `.d.ts` pairs) instead of
-`nugget/`, and point path aliases at its `.js` entry points (e.g.
-`dist/index.js`, `dist/agent/index.js`) — TypeScript picks up the sibling
-`.d.ts` automatically.
+Full command list and CI layout: [distribution.md](./docs/distribution.md).
 
 ## Examples
 
-`examples/` has runnable scripts against local Ollama and llama.cpp servers,
-`promptJson` vs. native tool-calling, an `ApprovalGate`, and telemetry — see
+`examples/` has runnable scripts (local Ollama, llama.cpp, `promptJson` vs
+native tools, approval gates, telemetry, a model picker), a small chat demo
+(`npm run demo:steel-chat`), three mini-apps consuming the published package,
+and the CI-verified [integration starters](./examples/integrations/). See
 `examples/README.md`.
 
-## Agent skills
-
-`.claude/skills/` contains Agent Skills — task-specific guides that Claude Code
-picks up automatically and that any AI agent (or human) can read as plain
-Markdown: `use-ai-nugget` (integrating the nugget into an app),
-`build-agent-loop` (the agent/tool-calling layer), `add-provider` (extending
-the provider profile table), and `develop-nugget` (invariants and validation
-for changes to this repo). `AGENTS.md` remains the always-on baseline; the
-skills carry the per-task detail.
-
 ## Non-goals
 
-Not a full agent framework (no planning/memory/RAG/multi-agent — the loop
-consumes `messages` and stops there), not a router/recommender (apps choose
-models; the handler exposes a `route`/`context` event so apps can report what they
-chose), not a secrets vault (`KeySource` is a seam), and not a UI. The governance
-seam ships neutral: it is where an app *can* enforce rules, not a place the
-library imposes its own.
+Not a full agent framework (no planning/memory/RAG/multi-agent), not a
+router/recommender (apps choose models), not a secrets vault (`KeySource` is a
+seam), and not a UI. The governance seam ships neutral: it is where an app *can*
+enforce rules, not a place the library imposes its own.
+
+<!-- GitHub Pages deployment is configured in .github/workflows/pages.yml. -->

package/UPGRADING.md

@@ -0,0 +1,158 @@
+# Upgrading
+
+## 0.5.x → 0.6.0
+
+Behavior-compatible for ordinary consumers, with **two things worth checking**.
+
+### 1. `not_found` is a new `AIErrorKind`
+
+404 and 410 responses now classify as `not_found` instead of
+`invalid_request`, so a wrong `baseUrl`/model or a misrouted edge is
+distinguishable from a malformed request body. It is non-retryable by default.
+
+- **If you `switch` exhaustively over `AIErrorKind`** (with a `never` default),
+  TypeScript will require a new branch. Map it like `auth`/`key_unavailable` —
+  it's a *server-side configuration* problem, not the caller's fault:
+
+  ```ts
+  case 'not_found': return { status: 502, message: 'The AI service is not configured correctly.' };
+  ```
+
+- **If you switch non-exhaustively** with a fallback, nothing breaks: a 404 that
+  used to produce "that request was invalid" now falls into your default branch
+  instead. That is the intended improvement, but check the resulting message
+  still reads correctly.
+
+### 2. A startup notice when no policy is configured
+
+`new AIHandler({ keySource })` with no `policy` now logs one line at
+construction: every provider and model is allowed. `allowAllPolicy()` is still
+the default — nothing is blocked. To silence it, say what you mean:
+
+```ts
+new AIHandler({ keySource, policy: allowAllPolicy() });        // deliberate, no warning
+new AIHandler({ keySource, silencePolicyWarning: true });      // same, if you prefer
+```
+
+### Also new, no action required
+
+- **`Connection.provider` is now typed** `KnownProvider | (string & {})`. You get
+  autocomplete and typo-catching; arbitrary strings still compile and still
+  resolve through `openai-compat`.
+- **`beforeCall` hooks get a scrubbed connection.** `info.connection.keyRef` is
+  masked for literal refs, and `info.resolved.headers` masks auth headers. If a
+  hook was reading `info.connection.keyRef.value` to get the key — don't; resolve
+  it through your `KeySource` instead.
+- **`Idempotency-Key` on OpenAI requests.** One key per logical call, reused
+  across retries. A header you set yourself on `Connection.headers` wins.
+- **New `context` stream events**: `json_mode_downgraded` (Google/Anthropic drop
+  JSON mode when tools are present) and `stream_anomaly` on all four engines
+  (previously `openaiChat` only). Both are informational; ignoring them keeps
+  the old behavior.
+- **Documentation moved.** `README.md` is now a front door; reference material
+  lives under `docs/` (`providers`, `reliability`, `security`, `agent-loop`,
+  `recipes`, `integrations`, `distribution`). Deep links into the old README
+  anchors will need updating.
+
+## 0.4.x → 0.5.0
+
+**0.5.0 is backward-compatible.** Every change below is additive — new optional
+fields, new methods, new exports, and a new `require` entry point. No existing
+signature changed and no default behavior changed, so an app on 0.4.x can bump
+without code edits and adopt the new capabilities as needed.
+
+The numbers in brackets are the suggestion numbers from the AI Server Studio
+production friction report (`docs/reviews/2026-08-09-ai-server-studio-friction-report.md`),
+so you can trace each change back to the friction it resolves.
+
+### Packaging
+
+- **[1] Dual ESM + CommonJS build.** The package now exposes a `require`
+  condition (`dist/cjs/`) in addition to ESM. CommonJS hosts can
+  `const { AIHandler } = require('@jxburros/ai-nugget')` with no dynamic-import
+  shim. ESM consumers are unaffected.
+- **[2] Vendorable compiled output.** `npm run build:nugget` now emits both
+  `nugget/src` (TypeScript) and `nugget/dist` (compiled ESM `.js` + `.d.ts`), so
+  bundlers that can't resolve `.ts` via `.js`-suffixed imports (e.g. Turbopack)
+  can vendor `nugget/dist`.
+
+### Requests & providers
+
+- **[4] `ChatRequest.providerOptions`.** A provider-native passthrough merged
+  into the outgoing request body (shallow top-level; one level deep into Ollama
+  `options` and Google `generationConfig`). Reach fields the nugget doesn't
+  model — Ollama `num_ctx`/`keep_alive`, OpenAI `reasoning_effort`, Anthropic
+  `thinking`, Google `safetySettings` — without waiting for a release.
+- **[16] `Connection.idleTimeoutMs`.** An idle timeout for streams, distinct from
+  the total `timeoutMs`: it aborts only when no chunk arrives for that long, and
+  resets on every chunk — so a slow-but-healthy long local generation isn't
+  killed mid-stream.
+- **[17] `reasoning` stream events.** Reasoning/thinking tokens (Anthropic
+  `thinking_delta`, OpenAI `reasoning_content`, Gemini `thought` parts, Ollama
+  `thinking`) surface as `{ type: 'reasoning', text }` instead of being dropped
+  or blended into `delta`.
+- **[18] `listModels()` for Anthropic & Google.** Both now query the real
+  endpoints (`/v1/models`, `/v1beta/models`) instead of returning `[]`.
+- **[19] Faster Ollama discovery.** `/api/show` probes run with bounded
+  concurrency instead of serially.
+- **[20] New provider profiles + Azure api-version override.** Added `cerebras`,
+  `moonshot`, `cohere`, and `perplexity`. The Azure `api-version` is now
+  overridable per call via `providerOptions.apiVersion` (default unchanged).
+- **[21] Safer URL joining** in the `openai-compat` engine (no accidental double
+  slash even if `baseUrl` ends in `/`).
+- **[23] Embeddings.** `AIHandler.embed(conn, req)` plus `EmbedRequest` /
+  `EmbedResult`, implemented for Ollama (`/api/embed`) and OpenAI-compatible
+  providers (`/embeddings`) — through the same policy/key/telemetry pipeline as
+  chat. Providers without embeddings throw a typed `invalid_request` error.
+
+### Structured output & typed results
+
+- **[15] `AIHandler.chatParsed(conn, req, schema)`.** Requests JSON, extracts it,
+  and validates against any [Standard Schema](https://standardschema.dev)
+  validator (Zod / Valibot / ArkType) — with one automatic corrective retry on a
+  validation miss. No schema library is bundled; you pass your own.
+
+### Agent loop (`@jxburros/ai-nugget/agent`)
+
+- **[5] Option passthrough.** `AgentOptions` now forwards `temperature`,
+  `maxTokens`, `topP`, `stopSequences`, and `providerOptions` to every turn.
+- **[6] Capability-aware `toolMode`.** `AgentOptions.modelCapabilities` — when
+  `toolMode: 'auto'`, a model advertising `"tools"` uses native tool-calling even
+  on a local runtime whose profile default is `promptJson`.
+- **[7] No leaked directives + `tool_mode` event.** In `promptJson` mode, tool
+  directives are withheld from the visible `delta` stream, and a `tool_mode`
+  event discloses the resolved protocol.
+- **[8] Parameter schemas in the `promptJson` prompt**, so the model isn't
+  guessing argument shape.
+- **[9] `undefined` tool results no longer crash a run.**
+- **[10] `AgentResult.error`** is populated when `stopReason === 'error'`.
+- **[11] Structured tool errors.** A tool returning `{ ok: false, ... }` is
+  surfaced with `isError: true` so the model can recover in-turn.
+- **[12] `AgentOptions.toolResult`.** Opt-in `maxChars` cap and `wrapUntrusted`
+  framing for tool results re-entering context.
+- **[14] `AgentOptions.approvalMode: 'all'`.** Gate every tool (not just
+  `sideEffects` ones) so `tool_denied` is reachable without per-tool flags.
+
+### Handler, telemetry & security
+
+- **[3] `AIHandler.prewarm(conn)`.** A no-throw warm-up (health probe) to move
+  cold DNS/TLS/daemon-spin-up cost off the first real call.
+- **[22] `CallInfo.resolved`.** The `beforeCall` hook now receives the resolved
+  connection (base URL + headers, key omitted) so it can validate the effective
+  endpoint — e.g. a request-time SSRF re-check — without hijacking `keySource`.
+- **[24] `HandlerOptions.pricing`.** An optional cost estimator whose result is
+  recorded on `CallRecord.costUsd`.
+
+### Tooling & hygiene
+
+- **[25]** Assistant messages with both content parts and tool calls no longer
+  drop their text/image parts on replay (Anthropic & Google); dead `role:'tool'`
+  branches removed; the `403 → non-retryable` policy is documented; ESLint and
+  Vitest coverage are wired up (`npm run lint`, `npm run test:coverage`).
+
+### Not changed (deliberately)
+
+- No provider policy ships as a library default (blocklists/allowlists remain the
+  app's configuration at the seam).
+- Zero runtime dependencies — everything above is implemented with the isomorphic
+  core (`fetch`/`ReadableStream`/`AbortController`/`TextDecoder`) only.