@tensorcost/sdk 0.6.0 → 1.1.0

package/CHANGELOG.md

@@ -2,18 +2,89 @@
 
 ## Unreleased
 
-## 0.6.0 — 2026-08-04
+## 1.1.0 — 2026-09-19
 
-SDK metadata story — lets you group traces by prompt template or deployment in
-the TensorCost dashboard — plus observe-only Google Vertex AI wrap.
+Agent hot-path hardening: fail-open faster on wedged proxy connections, optional
+cold-start warmup, and non-blocking sdk-layer refresh.
+
+### Added
+
+**`prewarm()`** — prefetch JWT + console published layer at Lambda/container
+init. Shares the same process-wide runtime cache as `wrap()`.
+
+**`headersTimeoutMs`** (default 2s) — separate deadline for proxy response
+headers vs body read (`timeoutMs`, default 60s). Missing headers within the
+budget fail-open to the direct provider without retry.
+
+### Changed
+
+**Sdk-layer fetch** — 250ms cap on cold `GET /sdk-layer`; stale-while-revalidate
+after the 30s TTL so refresh never blocks a model call.
+
+**Admit** — HTTP timeout tightened to 500ms (still fail-open on errors).
+
+**`wrap()`** — background-warms the shared runtime on first use.
+
+### Fixed
+
+Body JSON parse no longer leaves an unhandled rejection when the body-read
+deadline fires before `response.json()` settles.
+
+## 1.0.0 — 2026-09-13
+
+Major release: control-layer ceilings replace the `appliedMode` boolean.
+Effective layer is always `min(code.maxLayer, console published layer)`.
+
+### Added
+
+**Control layers (`maxLayer`)** — `off`, `observe`, `govern`, `steer`, `route`.
+At `govern`, metadata-only `POST /admit` may refuse before the provider is
+called. SDK fetches console ceiling via `GET /sdk-layer` (30s cache).
+
+**Wire headers** — `x-tc-sdk-version`, `x-tc-sdk-capabilities`, `x-tc-max-layer`
+on proxied requests; parses `x-tc-decision` on responses.
+
+**Framework adapters** — `wrapLangChain`, `wrapLlamaIndex`, `wrapCrewAI`,
+`wrapVercelAi`.
+
+**Google Vertex AI (observe-only)** — `@google/genai` clients with
+`vertexai: true`; `models.generateContent` / streaming variants.
+
+**Grant intersection** — `maxGrants` caps console data grants from code;
+prompt cache writes gated on `retain_completions`.
+
+### Changed
+
+**Breaking:** `appliedMode` is deprecated — use `maxLayer: "route"`. Default
+proxy header `x-tc-max-layer` is now `observe` (was `route`).
+
+### Fixed
+
+Circuit breaker re-probes proxy after fail-open; cold-start layer cache no
+longer skips decay window.
+
+## 0.7.0 — 2026-08-22
+
+A-04 chargeback attribution — stamp end-customer cohort and product feature on
+every observation and forward them through applied-mode proxy headers.
 
 ### Added
 
-**Google Vertex AI support (observe-only)** — `wrap()` detects `@google/genai`
-`GoogleGenAI` clients with `vertexai: true` and patches
-`models.generateContent` / `models.generateContentStream`. Observations use
-`provider: "vertex"`. Applied mode raises `TensorCostConfigError`.
-Gemini Developer API clients (`vertexai: false`) are not detected.
+**`customer` / `feature` options** — optional chargeback dimensions (max 128
+chars each). Set at wrap time via `wrap({ customer, feature })` or
+`TENSORCOST_CUSTOMER` / `TENSORCOST_FEATURE` env vars. Per-call overrides via
+`.withMeta({ customer, feature })` on OpenAI and Anthropic clients. Values land
+as top-level `customer` / `feature` fields on observations (not inside
+`metadata`) and as `x-tc-customer` / `x-tc-feature` in applied mode.
+
+Bedrock and Vertex clients support wrap-time defaults only (no `withMeta()`).
+
+## 0.6.0 — 2026-05-28
+
+SDK metadata story — lets you group traces by prompt template or deployment in
+the TensorCost dashboard.
+
+### Added
 
 **`deployment` option** — stamp a git SHA, CI run id, or release label on every
 observation emitted by a wrapped client. The backend groups by this value when

package/README.md

@@ -1,6 +1,8 @@
 # @tensorcost/sdk
 
-One-line wrapper SDK for TensorCost — fire-and-forget LLM observability for OpenAI, Anthropic, and AWS Bedrock clients in Node.js.
+One-line wrapper for TensorCost — fire-and-forget LLM observability and optional inference control for OpenAI, Anthropic, AWS Bedrock, and Google Vertex AI clients in Node.js.
+
+**Current version:** 1.1.0 — adds `prewarm()`, separate proxy headers timeout, and non-blocking sdk-layer refresh. See [CHANGELOG](./CHANGELOG.md) and [Migrating from 0.x](#migrating-from-0x).
 
 ## Install
 
@@ -10,31 +12,35 @@ npm install @tensorcost/sdk
 pnpm add @tensorcost/sdk
 ```
 
-Requires Node.js 18+ (uses native `fetch`).
+Requires Node.js 18+ (native `fetch`).
+
+## Quick start (observe)
 
-## Use
+The default layer is **`observe`**: telemetry only, provider call unchanged.
 
 ```ts
 import OpenAI from "openai";
 import { wrap } from "@tensorcost/sdk";
 
-const client = wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+const client = wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+});
 
-// Use the client exactly as before — TensorCost observes every call
-// and ships fire-and-forget observations to the platform.
 const resp = await client.chat.completions.create({
   model: "gpt-4o-mini",
   messages: [{ role: "user", content: "hi" }],
 });
 ```
 
-Anthropic is just as simple:
+Anthropic works the same way:
 
 ```ts
 import Anthropic from "@anthropic-ai/sdk";
 import { wrap } from "@tensorcost/sdk";
 
-const client = wrap(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }));
+const client = wrap(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+});
 
 await client.messages.create({
   model: "claude-3-5-sonnet-20241022",
@@ -43,54 +49,142 @@ await client.messages.create({
 });
 ```
 
-## Configuration
+Create a long-lived SDK key in the TensorCost console (**Setup → Keys**). The SDK exchanges it for a short-lived JWT via `POST /api/inference-proxy/sdk-token/exchange` and refreshes ~60s before expiry.
 
-`wrap()` reads from the environment by default:
+## Control layers (`maxLayer`)
 
-| Variable | Purpose | Required |
-|---|---|---|
-| `TENSORCOST_API_KEY` | Long-lived API key from the TensorCost console | Yes |
-| `TENSORCOST_BASE_URL` | Backend base URL | No (default `https://api.tensorcost.com`) |
-| `TENSORCOST_TENANT_ID` | Optional explicit tenant id | No |
-| `TENSORCOST_PROXY_URL` | Proxy base URL for applied mode | Required when `appliedMode: true` |
-| `TENSORCOST_ENVIRONMENT` | Environment tag stamped on every observation | No |
-| `TENSORCOST_CONNECTION_ID` | Provider-connection identifier | No |
+v1.0 uses a single ladder for how much TensorCost may intervene on a call:
+
+`off → observe → govern → steer → route`
+
+A layer is a **ceiling**, not a mode switch. The effective layer is always:
 
-Or pass explicitly:
+```text
+min(your maxLayer, console published layer)
+```
+
+When routing is paused in the console, the published ceiling is capped at `govern`.
+
+| Layer | Provider path | Behavior |
+|---|---|---|
+| `off` | Direct | No SDK wiring; client returned unchanged |
+| `observe` | Direct | Telemetry only (**default** when `maxLayer` is omitted) |
+| `govern` | Direct | Metadata-only `POST /v1/admit` before the provider call; may refuse unsafe calls |
+| `steer` | Via proxy | Proxy on the path; may steer without full live routing |
+| `route` | Via proxy | Full applied-mode routing through inference-proxy |
 
 ```ts
-const client = wrap(new OpenAI(...), {
-  apiKey: "tc_live_xxx",
-  baseUrl: "https://api.tensorcost.com",
+const client = wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  maxLayer: "route",
+  proxyUrl: process.env.TENSORCOST_PROXY_URL, // required for steer | route
 });
 ```
 
-## Applied mode (Layer 2)
+`wrap()` throws `TensorCostConfigError` when `maxLayer` is `steer` or `route` and no `proxyUrl` / `TENSORCOST_PROXY_URL` is set. **`govern` does not require `proxyUrl`** — admit uses `baseUrl`.
+
+### Console-published ceiling
+
+Operators set the tenant ceiling in the console (**Policy → Routing**) or via `PATCH /api/ai/router/layer` (`published_layer`, default `observe`). The SDK fetches the effective value from `GET /api/inference-proxy/v1/sdk-layer`:
+
+- **30s cache** while the endpoint is reachable
+- **250ms cap** on a cold fetch — a hung TensorCost cannot block the model call
+- **Stale-while-revalidate** after TTL: serve the last snapshot immediately and refresh in the background
+- **Decays to `govern`** after 5 minutes unreachable (fail-safe: still run admit, never silently upgrade to route)
+
+Publishing `steer` or `route` in the console requires a **content-retention data grant** (`retain_completions`, etc.). Steer/route without a grant returns **409**.
+
+### Govern admission
+
+At `govern` and above, the SDK calls `POST /api/inference-proxy/v1/admit` with metadata only — **no prompt or completion bodies**:
+
+- **204** + `x-tc-decision: layer=govern; action=allow` → proceed to the provider
+- **403** + `x-tc-decision: layer=govern; action=refuse; reason=…` → call blocked (budget, model governance, etc.)
 
-When you enable applied mode, the SDK routes inference requests through the TensorCost inference-proxy instead of directly to the AI provider. The proxy decides per-request whether to re-route to an alternate provider or pass through unchanged — the SDK doesn't make that call.
+Admit is **fail-open** on transport errors: the provider call proceeds and an `admit_unavailable` observation is emitted when transport recovers. The admit HTTP call is capped at **500ms**.
+
+### Route layer prerequisites
+
+`maxLayer: "route"` is necessary but not sufficient for live provider swaps. ADR-0016 gates still apply on the proxy side: LaunchDarkly flag, `AI_ROUTING_LIVE_EXECUTION_PERMITTED`, non-`dry_run` policy with rollout, and routing not paused. When gated off, traffic pass-throughs to the original provider and the decision is recorded.
+
+See [ADR-0026](https://github.com/vaadhlabs/tensorcost/blob/main/docs/adr/0026-sdk-control-layer-ceilings.md) and [inference-proxy applied mode](https://github.com/vaadhlabs/tensorcost/blob/main/docs/features/inference-proxy-applied-mode.md).
+
+## Cold start (`prewarm`)
+
+At Lambda/container init, the first steer/route call can otherwise pay for JWT exchange and sdk-layer fetch on the hot path. Call `prewarm()` once at module scope — it shares the same process-wide runtime that `wrap()` uses, so a later `wrap()` hits a warm cache.
+
+`wrap()` also background-warms that shared runtime on first use; explicit `prewarm()` is recommended when you know traffic is about to arrive (e.g. before the handler is invoked).
 
 ```ts
-const client = wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
-  apiKey: "tc_live_xxx",
-  appliedMode: true,
-  proxyUrl: "https://proxy.tensorcost.com", // or set TENSORCOST_PROXY_URL
+import { prewarm, wrap } from "@tensorcost/sdk";
+
+await prewarm({
+  apiKey: process.env.TENSORCOST_API_KEY,
+  baseUrl: process.env.TENSORCOST_BASE_URL,
+  maxLayer: "route",
 });
 
-// Use normally — the SDK redirects the client to the proxy transparently.
-// Observe-only telemetry still fires after every call.
-const resp = await client.chat.completions.create({
-  model: "gpt-4o-mini",
-  messages: [{ role: "user", content: "hi" }],
+export const client = wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  maxLayer: "route",
+  proxyUrl: process.env.TENSORCOST_PROXY_URL,
 });
 ```
 
-`wrap()` throws `TensorCostConfigError` at `wrap()` time if `appliedMode: true` and neither `proxyUrl` nor `TENSORCOST_PROXY_URL` is set. AWS Bedrock is not supported in applied mode — SigV4 signing happens inside the AWS SDK before the proxy layer can intercept it; passing a Bedrock client with `appliedMode: true` throws `TensorCostConfigError` immediately. Observe-only mode works fine for Bedrock.
+`prewarm()` is best-effort: failures are swallowed and the first real call retries the fetches.
+
+## Migrating from 0.x
+
+| 0.x | 1.0 |
+|---|---|
+| `appliedMode: true` | `maxLayer: "route"` (deprecated alias still works with a console warning) |
+| Default `x-tc-max-layer: route` on proxy calls | Default is now `observe` |
+| Boolean on/off | Full layer ladder + console ceiling |
+
+```ts
+// Before (0.6.x)
+wrap(client, { appliedMode: true, proxyUrl: "..." });
+
+// After (1.0)
+wrap(client, { maxLayer: "route", proxyUrl: "..." });
+```
+
+Recommended rollout: **`observe` → `govern` → `route`**, raising the console `published_layer` only after each stage is validated.
+
+## Configuration
+
+`wrap()` resolves options in order: explicit kwargs → environment variables → defaults.
+
+| Variable | Purpose | Required |
+|---|---|---|
+| `TENSORCOST_API_KEY` | Long-lived SDK key from **Setup → Keys** | Yes |
+| `TENSORCOST_BASE_URL` | Backend base URL (admit, sdk-layer, token exchange) | No (default `https://api.tensorcost.com`) |
+| `TENSORCOST_PROXY_URL` | Inference-proxy base URL | Required when `maxLayer` is `steer` or `route` |
+| `TENSORCOST_TENANT_ID` | Explicit tenant id (multi-tenant tests) | No |
+| `TENSORCOST_ENVIRONMENT` | Environment tag on every observation | No |
+| `TENSORCOST_CONNECTION_ID` | Provider-connection id for environment resolution | No |
+| `TENSORCOST_AGENT_ID` / `TENSORCOST_WORKFLOW_ID` | Agent-run attribution defaults | No |
+| `TENSORCOST_CUSTOMER` / `TENSORCOST_FEATURE` | Chargeback tag defaults | No |
+| `TENSORCOST_DEPLOYMENT` | Git SHA / release label (`metadata.deployment`) | No |
+| `TENSORCOST_PROMPT_TEMPLATE_ID` | Default prompt-template id | No |
+| `TC_APPLICATION` / `TENSORCOST_APPLICATION` | Routing-policy application scope (proxy) | No |
+| `TC_TAGS` / `TENSORCOST_TAGS` | Comma-separated routing tags (proxy) | No |
 
-See [`docs/features/inference-proxy-applied-mode.md`](../../docs/features/inference-proxy-applied-mode.md) for the proxy-side design.
+```ts
+const client = wrap(new OpenAI(...), {
+  apiKey: "tc_live_xxx",
+  baseUrl: "https://api.tensorcost.com",
+  maxLayer: "govern",
+  deployment: process.env.GIT_SHA,
+  promptTemplateId: "support-chat-v2",
+  application: "customer-support",
+  tags: ["tier:enterprise"],
+});
+```
 
-## Applied-mode hardening (v0.4.0)
+## Proxy hardening
 
-When `appliedMode: true`, you can configure retry policy, timeouts, lifecycle hooks, and the fail-open circuit breaker.
+Applies when `maxLayer` is `govern`, `steer`, or `route` (admit + proxy paths).
 
 ### Retries
 
@@ -98,48 +192,60 @@ When `appliedMode: true`, you can configure retry policy, timeouts, lifecycle ho
 import { wrap, RetryConfig } from "@tensorcost/sdk";
 
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
+  maxLayer: "route",
   proxyUrl: "...",
   retry: { maxAttempts: 5, baseDelayMs: 500, maxDelayMs: 30_000 },
 });
 ```
 
-5xx responses, network errors, and 429 are retried with jittered exponential backoff. A `Retry-After` header on 429 is honoured. 4xx errors (except 429) are never retried.
+5xx, network errors, and 429 are retried with jittered exponential backoff. `Retry-After` on 429 is honoured. 4xx (except 429) are never retried.
 
 ### Timeouts
 
+Proxy timeouts are split so a wedged TCP connection fails open quickly while slow model bodies still get a full budget:
+
 ```ts
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
+  maxLayer: "route",
   proxyUrl: "...",
-  timeoutMs: 30_000, // 30 seconds; default 60_000
+  headersTimeoutMs: 2_000, // wait for response headers (default 2_000)
+  timeoutMs: 60_000,       // non-streaming body read (default 60_000)
+  idleTimeoutMs: 30_000,   // streaming idle (default 30_000)
 });
 ```
 
-Surfaces as `TensorCostTimeoutError` (with `timeoutKind: "total"`) when exceeded.
+| Option | Default | `TensorCostTimeoutError.kind` | On timeout (steer/route) |
+|---|---|---|---|
+| `headersTimeoutMs` | 2s | `"headers"` | Fail-open to direct provider (no retry) |
+| `timeoutMs` | 60s | `"total"` | Fail-open when `failOpenEnabled: true` |
+| `idleTimeoutMs` | 30s | `"idle"` | Fail-open when `failOpenEnabled: true` |
 
-### Lifecycle telemetry hooks
+The headers deadline targets wedged proxy connections, not slow upstream models — body read uses `timeoutMs` independently once headers arrive.
+
+### Lifecycle hooks
 
 ```ts
 import { wrap, LifecycleEvent } from "@tensorcost/sdk";
 
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
+  maxLayer: "route",
   proxyUrl: "...",
   onLifecycleEvent(event: LifecycleEvent) {
-    // event.kind is one of:
-    //   "before_request" | "after_response" | "on_retry"
-    //   | "on_error" | "on_fallback"
+    // "before_request" | "after_response" | "on_retry" | "on_error" | "on_fallback"
     console.log(event.kind, event.model, event.attemptNumber);
   },
 });
 ```
 
-Events contain only request metadata — never prompt content, response bodies, or credentials. Errors thrown by the callback are swallowed.
+Payloads contain request metadata only — never prompt content, response bodies, or credentials.
 
-### Typed errors
+### Circuit breaker
 
-Every failure from the proxy path is a subclass of `TensorCostError`. Import the classes from `@tensorcost/sdk`:
+After consecutive proxy 5xx failures (default 3), the circuit opens and requests route directly to the provider (fail-open). After consecutive successful probe calls (default 5), the circuit closes.
+
+Set `failOpenEnabled: false` when direct provider access is unavailable (e.g. in-VPC sidecar-only). Proxy failures then surface as `TensorCostProxyError` instead of falling back.
+
+### Typed errors
 
 ```ts
 import {
@@ -149,120 +255,130 @@ import {
   TensorCostProxyError,
   TensorCostQuotaError,
   TensorCostProviderError,
+  TensorCostRunBudgetExceededError,
+  TensorCostModelGovernanceDeniedError,
+  TensorCostGuardrailHardStopError,
 } from "@tensorcost/sdk";
-
-try {
-  await client.chat.completions.create({ model: "gpt-4o-mini", messages: [] });
-} catch (err) {
-  if (err instanceof TensorCostQuotaError) {
-    console.log("rate limited; retry after", err.retryAfterMs, "ms");
-  } else if (err instanceof TensorCostError) {
-    console.log("tensorcost error", err.status, err.attempt);
-  }
-}
 ```
 
-### Circuit breaker
+Govern refusals and proxy decisions are also reflected in the `x-tc-decision` header and attached to observations as `decision_action` / `decision_reason` metadata when present.
 
-After 3 consecutive proxy 5xx responses the circuit opens and requests route directly to the provider (fail-open). The circuit closes after 5 consecutive probe successes.
+## Data grants (`maxGrants`)
 
-Set `failOpenEnabled: false` if direct provider access is unavailable (e.g. in-VPC deployments) — proxy failures then surface as `TensorCostProxyError` instead of falling back.
+Code can cap which console data grants apply:
 
 ```ts
+import { wrap, intersectGrants } from "@tensorcost/sdk";
+
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
-  proxyUrl: "...",
-  failOpenEnabled: false, // raise on proxy error instead of falling through
+  apiKey: "...",
+  maxGrants: ["telemetry", "retain_completions"],
 });
 ```
 
-## Fail-open guarantee
+Effective grants = `intersect(maxGrants, console.data_grants)`. Omit `maxGrants` to allow all console grants. An empty array allows none. Grant vocabulary: `telemetry`, `retain_completions`, `retain_prompts`, `retain_tools`.
 
-If TensorCost is slow, down, or misconfigured, your customer call STILL succeeds. The SDK swallows internal errors and surfaces them via `console.warn`. The one exception: a missing API key throws `MissingConfigError` at `wrap()` time — silently dropping every observation would be worse than a loud import-time failure.
+## Trace metadata & attribution
 
-## What is captured
+### Deployment & prompt templates
 
-Only metadata — never prompt or completion content:
+Group traces in the dashboard by deploy or template:
 
-- Provider + model
-- Operation (`chat.completions`, `completions`, `messages`)
-- Request / response timestamps
-- Input / output token counts (from the provider's `usage` field)
-- Status (`success` / `error`) and error class/message on failure
-- A correlation UUID
+```ts
+const client = wrap(new OpenAI(...), {
+  apiKey: "...",
+  deployment: process.env.GIT_SHA ?? "local",
+  promptTemplateId: "onboarding-email-v2",
+});
+
+// Per-call override (OpenAI + Anthropic)
+await client.withMeta({ promptTemplateId: "research-agent-v5" }).chat.completions.create({ ... });
+```
 
-## AWS Bedrock (observe-only)
+### Agent runs
+
+Tag spend for **Router · Agent runs**:
 
 ```ts
-import {
-  BedrockRuntimeClient,
-  InvokeModelCommand,
-} from "@aws-sdk/client-bedrock-runtime";
-import { wrap } from "@tensorcost/sdk";
+const client = wrap(new OpenAI(...), {
+  apiKey: "...",
+  agentId: "support-bot",
+});
 
-// The only change: wrap() before passing the client to the rest of your code.
-const client = wrap(
-  new BedrockRuntimeClient({ region: process.env.AWS_REGION ?? "us-east-1" }),
-);
-
-// Everything else is unchanged.
-const response = await client.send(
-  new InvokeModelCommand({
-    modelId: "anthropic.claude-3-haiku-20240307-v1:0",
-    body: JSON.stringify({
-      anthropic_version: "bedrock-2023-05-31",
-      max_tokens: 64,
-      messages: [{ role: "user", content: "What is 2 + 2?" }],
-    }),
-    contentType: "application/json",
-    accept: "application/json",
-  }),
-);
+const scoped = client.withMeta({ workflowId: crypto.randomUUID() });
+await scoped.chat.completions.create({ model: "gpt-4o-mini", messages: [...] });
 ```
 
-The SDK registers a Smithy middleware on `client.middlewareStack` that intercepts every `client.send()` call and emits a fire-and-forget observation with the model id, token counts, latency, and status. Your code is otherwise unchanged.
+`customer` / `feature` are separate chargeback dimensions — not substitutes for `agentId` / `workflowId`. Bedrock and Vertex accept wrap-time defaults only (no `withMeta()`).
 
-### Supported commands
+## Fail-open guarantee
 
-| Command | Operation recorded | Token counts |
-|---|---|---|
-| `InvokeModelCommand` | `bedrock.invoke_model` | Parsed from response body (Anthropic-on-Bedrock and Nova/Titan shapes) |
-| `ConverseCommand` | `bedrock.converse` | Read from `response.usage.inputTokens / outputTokens` |
-| `InvokeModelWithResponseStreamCommand` | `bedrock.invoke_model_stream` | Not yet — placeholder observation with `null` tokens |
-| `ConverseStreamCommand` | `bedrock.converse_stream` | Not yet — placeholder observation with `null` tokens |
+If TensorCost is slow, down, or misconfigured, your customer call still succeeds. Internal errors are swallowed and logged via `console.warn` (or your lifecycle hook). On steer/route, missing proxy headers within **2s** also fail-open to the direct provider so agents are not blocked behind a wedged sidecar. Exceptions:
 
-Per-chunk token accounting for streaming commands is a follow-up workstream. The placeholder observations record latency and success/error status, which is enough for alerting and anomaly detection. Token cost attribution will arrive once per-model pricing is wired in on the backend.
+- Missing `TENSORCOST_API_KEY` → `MissingConfigError` at `wrap()` time
+- Missing `proxyUrl` when `maxLayer` is `steer` or `route` → `TensorCostConfigError` at `wrap()` time
+- Govern **refusals** (403 from `/admit`) → call blocked by design
 
-### Applied mode
+Set `failOpen: false` only in tests to surface observation-pipeline errors.
 
-Applied mode (`{ appliedMode: true }`) is not supported for Bedrock. AWS Bedrock uses SigV4 request signing inside the AWS SDK before our middleware sees the request, so we cannot intercept and re-route it the way we do for OpenAI/Anthropic HTTP-Bearer clients. Calling `wrap(bedrockClient, { appliedMode: true })` throws `TensorCostConfigError` immediately.
+## What is captured
 
-### Installation
+Metadata only — never prompt or completion content:
 
-`@aws-sdk/client-bedrock-runtime` is an optional peer dependency — you only need it if you're using Bedrock. The SDK will not pull it in for OpenAI/Anthropic-only users.
+- SDK version, provider, model, operation, modality
+- Request / response timestamps and token counts
+- Status (`success` / `error`) and error class/message on failure
+- Correlation UUID, environment, agent/workflow ids, chargeback tags
+- `decision_action` / `decision_reason` when `x-tc-decision` is present
 
-```bash
-npm install @aws-sdk/client-bedrock-runtime
-# or
-pnpm add @aws-sdk/client-bedrock-runtime
+Proxied requests include `x-tc-sdk-version`, `x-tc-sdk-capabilities`, and `x-tc-max-layer`.
+
+## Supported providers & operations
+
+| Provider | Package | Layers | Operations |
+|---|---|---|---|
+| OpenAI | `openai` ≥ 4.x | observe → route | chat, completions, embeddings, responses (+ streaming) |
+| Anthropic | `@anthropic-ai/sdk` | observe → route | messages (+ streaming) |
+| Azure OpenAI | `openai` (`AzureOpenAI`) | observe → route | same as OpenAI (`provider: "openai"`) |
+| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | observe, govern only | InvokeModel, Converse (+ streaming placeholders) |
+| Google Vertex | `@google/genai` (`vertexai: true`) | observe, govern only | generateContent (+ streaming) |
+
+**Bedrock and Vertex:** SigV4 / Vertex signing happens inside the AWS / Google SDK before the proxy can intercept — **`steer` and `route` are not supported**. Use `maxLayer: "govern"` or lower.
+
+Bedrock peer dependency is optional:
+
+```ts
+import { BedrockRuntimeClient, InvokeModelCommand } from "@aws-sdk/client-bedrock-runtime";
+import { wrap } from "@tensorcost/sdk";
+
+const client = wrap(new BedrockRuntimeClient({ region: "us-east-1" }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+});
 ```
 
-## Currently supported
+## Framework adapters
+
+Thin passthroughs that call `wrap()` on the underlying LLM client:
+
+```ts
+import { ChatOpenAI } from "@langchain/openai";
+import { wrapLangChain } from "@tensorcost/sdk";
 
-- OpenAI (`openai` >= 4.x) — `chat.completions.create`, `completions.create`
-- Anthropic (`@anthropic-ai/sdk` >= 0.x) — `messages.create`
-- AWS Bedrock (`@aws-sdk/client-bedrock-runtime` >= 3.x) — `InvokeModelCommand`, `ConverseCommand` (observe-only)
-- Google Vertex AI (`@google/genai` with `vertexai: true`) — `models.generateContent` (observe-only). Optional peer: `@google/genai`.
+const llm = wrapLangChain(new ChatOpenAI({ model: "gpt-4o-mini" }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  maxLayer: "observe",
+});
+```
 
-## Coming soon
+Also exported: `wrapLlamaIndex`, `wrapCrewAI`, `wrapVercelAi`.
 
-- Gemini Developer API wrap (`vertexai: false`)
-- Streaming token accounting for Bedrock (`InvokeModelWithResponseStreamCommand`, `ConverseStreamCommand`)
-- Tool / function calling (multi-call trace stitching)
+## Further reading
 
-Note: **Azure OpenAI** is supported by wrapping the standard `AzureOpenAI`
-client (observations report `provider: "openai"`).
+- [ADR-0026 — SDK control-layer ceilings](https://github.com/vaadhlabs/tensorcost/blob/main/docs/adr/0026-sdk-control-layer-ceilings.md)
+- [Inference proxy SDK feature doc](https://github.com/vaadhlabs/tensorcost/blob/main/docs/features/inference-proxy-sdk.md)
+- [Applied mode / live routing](https://github.com/vaadhlabs/tensorcost/blob/main/docs/features/inference-proxy-applied-mode.md)
+- [CHANGELOG](./CHANGELOG.md)
 
 ## License
 
-Proprietary — TensorCost.
+Apache-2.0

package/dist/adapters/crewai.d.ts

@@ -0,0 +1,4 @@
+import type { WrapOptions } from "../types.js";
+/** Thin passthrough — wraps the LLM used by CrewAI agents. */
+export declare function wrapCrewAI<T>(client: T, options?: WrapOptions): T;
+//# sourceMappingURL=crewai.d.ts.map

package/dist/adapters/crewai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crewai.d.ts","sourceRoot":"","sources":["../../src/adapters/crewai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,CAEjE"}

package/dist/adapters/crewai.js

@@ -0,0 +1,6 @@
+import { wrap } from "../wrap.js";
+/** Thin passthrough — wraps the LLM used by CrewAI agents. */
+export function wrapCrewAI(client, options) {
+    return wrap(client, options);
+}
+//# sourceMappingURL=crewai.js.map

package/dist/adapters/crewai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crewai.js","sourceRoot":"","sources":["../../src/adapters/crewai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAI,MAAS,EAAE,OAAqB;IAC5D,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,4 @@
+import type { WrapOptions } from "../types.js";
+/** Thin passthrough — wraps the underlying OpenAI/Anthropic client. */
+export declare function wrapLangChain<T>(client: T, options?: WrapOptions): T;
+//# sourceMappingURL=langchain.d.ts.map

package/dist/adapters/langchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../src/adapters/langchain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,CAEpE"}

package/dist/adapters/langchain.js

@@ -0,0 +1,6 @@
+import { wrap } from "../wrap.js";
+/** Thin passthrough — wraps the underlying OpenAI/Anthropic client. */
+export function wrapLangChain(client, options) {
+    return wrap(client, options);
+}
+//# sourceMappingURL=langchain.js.map