@tensorcost/sdk 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # Changelog
 
+## Unreleased
+
+## 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
+
+**`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
+you select "Group by deployment" in the Traces view.
+
+```ts
+const client = wrap(new OpenAI({ apiKey: "..." }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  deployment: process.env.GIT_SHA ?? "local",
+});
+```
+
+Falls back to `TENSORCOST_DEPLOYMENT` env var. When absent, no deployment field
+is written and the group-by row shows as "(unset)".
+
+**`promptTemplateId` option** — per-client default template marker. Useful when
+one SDK client always drives the same call-site template.
+
+```ts
+const client = wrap(new Anthropic({ apiKey: "..." }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  promptTemplateId: "onboarding-email-v2",
+});
+```
+
+Falls back to `TENSORCOST_PROMPT_TEMPLATE_ID` env var.
+
+**`client.withMeta(overrides)` helper** — per-call metadata override. Returns a
+thin proxy of the wrapped client with the metadata overridden for that single
+call. The wrap-time `deployment` default is still inherited unless you explicitly
+pass a new `deployment` here; `promptTemplateId` is also overridable.
+
+```ts
+// One client, multiple templates:
+const baseClient = wrap(new OpenAI({ apiKey: "..." }), {
+  apiKey: process.env.TENSORCOST_API_KEY,
+  deployment: process.env.GIT_SHA,
+});
+
+// Template override per call-site:
+const result = await (baseClient as any)
+  .withMeta({ promptTemplateId: "personalization-rerank-v3" })
+  .chat.completions.create({ model: "gpt-4o", messages });
+```
+
+Both fields are stored as `metadata.deployment` and `metadata.prompt_template_id`
+in the `trace_span` row. The backend's `GET /api/ai/traces?group_by=deployment`
+and `group_by=prompt_template` endpoints index these keys.
+
+### No breaking changes
+
+All new options are optional. Existing `wrap()` calls without metadata options
+are completely unaffected — the metadata field is absent from the observation
+envelope when nothing is configured.
+
+## 0.5.0 — 2026-05-13
+
+Phase A4 batch 5 (environment + connectionId GA). See 0.2.1 for the original
+`connectionId` addition; this entry is a placeholder for any 0.5.x patches.
+
 ## 0.4.0 — 2026-05-13
 
 Applied-mode hardening. Five new subsystems sit between `wrap()` and the

package/README.md

@@ -1,6 +1,6 @@
 # @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 SDK for TensorCost — fire-and-forget LLM observability and optional inference control for OpenAI, Anthropic, AWS Bedrock, and Google Vertex AI clients in Node.js.
 
 ## Install
 
@@ -28,7 +28,7 @@ const resp = await client.chat.completions.create({
 });
 ```
 
-Anthropic is just as simple:
+Anthropic works the same way:
 
 ```ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -52,9 +52,11 @@ await client.messages.create({
 | `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_PROXY_URL` | Inference-proxy base URL | Required when `maxLayer` is `steer` or `route` |
 | `TENSORCOST_ENVIRONMENT` | Environment tag stamped on every observation | No |
 | `TENSORCOST_CONNECTION_ID` | Provider-connection identifier | No |
+| `TENSORCOST_AGENT_ID` / `TENSORCOST_WORKFLOW_ID` | Agent-run attribution defaults | No |
+| `TENSORCOST_CUSTOMER` / `TENSORCOST_FEATURE` | Chargeback tag defaults | No |
 
 Or pass explicitly:
 
@@ -65,32 +67,37 @@ const client = wrap(new OpenAI(...), {
 });
 ```
 
-## Applied mode (Layer 2)
+## Control layers (`maxLayer`)
 
-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.
+v1.0 replaces the old `appliedMode` boolean with a **control-layer ceiling**. A layer is a ceiling, not a mode — the effective layer is always `min(your maxLayer, console published layer)`.
+
+| Layer | Behavior |
+|---|---|
+| `off` | No SDK wiring; client returned unchanged |
+| `observe` | Telemetry only (**default** when `maxLayer` is omitted) |
+| `govern` | Metadata-only `POST /admit` before the provider call; may refuse unsafe calls |
+| `steer` | Proxy on the path; proxy may steer without full live routing |
+| `route` | Full applied-mode routing through the inference-proxy |
 
 ```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
-});
-
-// 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" }],
+  maxLayer: "route",
+  proxyUrl: "https://api.my-instance.tensorcost.com", // or 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.
+`wrap()` throws `TensorCostConfigError` when `maxLayer` is `steer` or `route` and no `proxyUrl` / `TENSORCOST_PROXY_URL` is set.
 
-See [`docs/features/inference-proxy-applied-mode.md`](../../docs/features/inference-proxy-applied-mode.md) for the proxy-side design.
+The SDK fetches the console-published ceiling from `GET /api/inference-proxy/v1/sdk-layer` (30s cache, decays to `govern` after 5 minutes unreachable). Govern refusals and proxy decisions surface in the `x-tc-decision` response header.
 
-## Applied-mode hardening (v0.4.0)
+`appliedMode: true` still works but is **deprecated** — it maps to `maxLayer: "route"` with a console warning. Prefer `maxLayer` in new code.
 
-When `appliedMode: true`, you can configure retry policy, timeouts, lifecycle hooks, and the fail-open circuit breaker.
+See [ADR-0026](https://github.com/vaadhlabs/tensorcost/blob/main/docs/adr/0026-sdk-control-layer-ceilings.md) and [`docs/features/inference-proxy-applied-mode.md`](../../docs/features/inference-proxy-applied-mode.md).
+
+## Proxy hardening
+
+When `maxLayer` is `govern`, `steer`, or `route`, you can configure retries, timeouts, lifecycle hooks, and the fail-open circuit breaker.
 
 ### Retries
 
@@ -98,7 +105,7 @@ 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 },
 });
@@ -110,9 +117,9 @@ const client = wrap(new OpenAI(...), {
 
 ```ts
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
+  maxLayer: "route",
   proxyUrl: "...",
-  timeoutMs: 30_000, // 30 seconds; default 60_000
+  timeoutMs: 30_000, // default 60_000
 });
 ```
 
@@ -124,22 +131,20 @@ Surfaces as `TensorCostTimeoutError` (with `timeoutKind: "total"`) when exceeded
 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.
+Events contain only request metadata — never prompt content, response bodies, or credentials.
 
 ### Typed errors
 
-Every failure from the proxy path is a subclass of `TensorCostError`. Import the classes from `@tensorcost/sdk`:
+Every failure from the proxy path is a subclass of `TensorCostError`:
 
 ```ts
 import {
@@ -150,115 +155,78 @@ import {
   TensorCostQuotaError,
   TensorCostProviderError,
 } 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
 
-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.
+After consecutive proxy failures the circuit opens and requests route directly to the provider (fail-open). Set `failOpenEnabled: false` when direct provider access is unavailable — proxy failures then surface as `TensorCostProxyError` instead of falling back.
 
-Set `failOpenEnabled: false` if direct provider access is unavailable (e.g. in-VPC deployments) — proxy failures then surface as `TensorCostProxyError` instead of falling back.
+## Agent-run attribution
+
+Tag spend so **Router · Agent runs** can roll up cost per workflow:
 
 ```ts
 const client = wrap(new OpenAI(...), {
-  appliedMode: true,
-  proxyUrl: "...",
-  failOpenEnabled: false, // raise on proxy error instead of falling through
+  apiKey: "tc_live_xxx",
+  agentId: "support-bot",
 });
+
+const scoped = client.withMeta({ workflowId: crypto.randomUUID() });
+await scoped.chat.completions.create({ model: "gpt-4o-mini", messages: [...] });
 ```
 
+`customer` / `feature` are separate chargeback tags — not substitutes for `agentId` / `workflowId`.
+
 ## Fail-open guarantee
 
-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.
+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.
 
 ## What is captured
 
 Only metadata — never prompt or completion content:
 
-- Provider + model
-- Operation (`chat.completions`, `completions`, `messages`)
-- Request / response timestamps
-- Input / output token counts (from the provider's `usage` field)
+- Provider + model + operation + modality
+- Request / response timestamps and token counts
 - Status (`success` / `error`) and error class/message on failure
-- A correlation UUID
+- Correlation UUID, environment, agent/workflow ids, chargeback tags
 
 ## AWS Bedrock (observe-only)
 
 ```ts
-import {
-  BedrockRuntimeClient,
-  InvokeModelCommand,
-} from "@aws-sdk/client-bedrock-runtime";
+import { BedrockRuntimeClient, InvokeModelCommand } from "@aws-sdk/client-bedrock-runtime";
 import { wrap } from "@tensorcost/sdk";
 
-// 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",
-  }),
-);
 ```
 
-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.
-
-### Supported commands
+Supported commands: `InvokeModelCommand`, `ConverseCommand`, and their streaming counterparts (streaming records latency/status; per-chunk token accounting is a follow-up).
 
-| 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 |
+**Steer/route are not supported for Bedrock** — SigV4 signing happens inside the AWS SDK before the proxy can intercept. Use `maxLayer: "govern"` or lower for Bedrock telemetry.
 
-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.
+`@aws-sdk/client-bedrock-runtime` is an optional peer dependency.
 
-### Applied mode
+## Google Vertex AI (observe-only)
 
-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.
+Wrap `@google/genai` clients constructed with `vertexai: true`. `models.generateContent` and streaming variants emit observations with `provider: "vertex"`. Steer/route are not supported (same signing constraint as Bedrock).
 
-### Installation
+## Framework adapters
 
-`@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.
+Optional helpers for common LLM frameworks (observe + proxy paths where supported):
 
-```bash
-npm install @aws-sdk/client-bedrock-runtime
-# or
-pnpm add @aws-sdk/client-bedrock-runtime
+```ts
+import { wrapLangChain, wrapLlamaIndex, wrapCrewAI, wrapVercelAi } from "@tensorcost/sdk";
 ```
 
 ## Currently supported
 
-- 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)
-
-## Coming soon
-
-- Azure OpenAI, Vertex
-- Streaming token accounting for Bedrock (`InvokeModelWithResponseStreamCommand`, `ConverseStreamCommand`)
-- Tool / function calling (multi-call trace stitching)
+- OpenAI (`openai` >= 4.x) — chat, completions, embeddings, responses
+- Anthropic (`@anthropic-ai/sdk`) — messages
+- AWS Bedrock (`@aws-sdk/client-bedrock-runtime`) — invoke/converse (+ streaming placeholders)
+- Google Vertex AI (`@google/genai` with `vertexai: true`) — generateContent
+- Azure OpenAI — wrap the standard `AzureOpenAI` client (observations report `provider: "openai"`)
 
 ## 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

package/dist/adapters/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../src/adapters/langchain.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAI,MAAS,EAAE,OAAqB;IAC/D,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/adapters/llamaindex.d.ts

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

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

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

package/dist/adapters/llamaindex.js

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

package/dist/adapters/llamaindex.js.map

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

package/dist/adapters/vercel-ai.d.ts

@@ -0,0 +1,4 @@
+import type { WrapOptions } from "../types.js";
+/** Thin passthrough — wraps the provider client passed to Vercel AI SDK. */
+export declare function wrapVercelAi<T>(client: T, options?: WrapOptions): T;
+//# sourceMappingURL=vercel-ai.d.ts.map

package/dist/adapters/vercel-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,CAEnE"}

package/dist/adapters/vercel-ai.js

@@ -0,0 +1,6 @@
+import { wrap } from "../wrap.js";
+/** Thin passthrough — wraps the provider client passed to Vercel AI SDK. */
+export function wrapVercelAi(client, options) {
+    return wrap(client, options);
+}
+//# sourceMappingURL=vercel-ai.js.map

package/dist/adapters/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.js","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAI,MAAS,EAAE,OAAqB;IAC9D,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/admit-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Govern-layer admit — metadata-only POST /api/inference-proxy/v1/admit.
+ *
+ * Fail-open on transport failure: the customer's call proceeds to the
+ * provider and an error observation is emitted when transport is available.
+ */
+import type { ControlLayer } from "./layer.js";
+import type { Operation, Provider } from "./types.js";
+import type { ObservationTransport } from "./transport.js";
+export interface AdmitMetadata {
+    provider: Provider;
+    model: string;
+    operation: Operation;
+    correlation_id: string;
+    environment?: string | null;
+    connection_id?: string | null;
+    agent_id?: string;
+    workflow_id?: string;
+    customer?: string;
+    feature?: string;
+    application?: string | null;
+    tags?: string[];
+}
+export interface AdmitRequestOptions {
+    baseUrl: string;
+    bearerToken: string;
+    maxLayer: ControlLayer;
+    metadata: AdmitMetadata;
+    transport?: ObservationTransport;
+    failOpen?: boolean;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface AdmitResult {
+    allowed: boolean;
+    decisionHeader: string | null;
+}
+export declare function admitRequest(opts: AdmitRequestOptions): Promise<AdmitResult>;
+//# sourceMappingURL=admit-client.d.ts.map

package/dist/admit-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-client.d.ts","sourceRoot":"","sources":["../src/admit-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAI3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,WAAW,CAAC,CA8DtB"}

package/dist/admit-client.js

@@ -0,0 +1,93 @@
+/**
+ * Govern-layer admit — metadata-only POST /api/inference-proxy/v1/admit.
+ *
+ * Fail-open on transport failure: the customer's call proceeds to the
+ * provider and an error observation is emitted when transport is available.
+ */
+import { ADMIT_PATH } from "./layer.js";
+import { SDK_VERSION, sdkCapabilityHeader } from "./version.js";
+export async function admitRequest(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const url = `${opts.baseUrl.replace(/\/+$/, "")}${ADMIT_PATH}`;
+    const headers = {
+        Authorization: `Bearer ${opts.bearerToken}`,
+        "Content-Type": "application/json",
+        "x-tc-sdk-version": SDK_VERSION,
+        "x-tc-sdk-capabilities": sdkCapabilityHeader(),
+        "x-tc-max-layer": opts.maxLayer,
+    };
+    const body = {
+        provider: opts.metadata.provider,
+        model: opts.metadata.model,
+        operation: opts.metadata.operation,
+        correlation_id: opts.metadata.correlation_id,
+        ...(opts.metadata.environment ? { environment: opts.metadata.environment } : {}),
+        ...(opts.metadata.connection_id ? { connection_id: opts.metadata.connection_id } : {}),
+        ...(opts.metadata.agent_id ? { agent_id: opts.metadata.agent_id } : {}),
+        ...(opts.metadata.workflow_id ? { workflow_id: opts.metadata.workflow_id } : {}),
+        ...(opts.metadata.customer ? { customer: opts.metadata.customer } : {}),
+        ...(opts.metadata.feature ? { feature: opts.metadata.feature } : {}),
+        ...(opts.metadata.application ? { application: opts.metadata.application } : {}),
+        ...(opts.metadata.tags && opts.metadata.tags.length > 0
+            ? { tags: opts.metadata.tags.join(",") }
+            : {}),
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5_000);
+    try {
+        const resp = await fetchImpl(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const decisionHeader = resp.headers.get("x-tc-decision");
+        if (resp.status === 403) {
+            return { allowed: false, decisionHeader };
+        }
+        if (!resp.ok) {
+            throw new Error(`admit POST failed status=${resp.status}`);
+        }
+        return { allowed: true, decisionHeader };
+    }
+    catch (err) {
+        if (opts.failOpen !== false) {
+            postAdmitFailureObservation(opts, err);
+            return { allowed: true, decisionHeader: null };
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function postAdmitFailureObservation(opts, err) {
+    if (!opts.transport)
+        return;
+    try {
+        opts.transport.post({
+            sdk_version: SDK_VERSION,
+            provider: opts.metadata.provider,
+            model: opts.metadata.model,
+            operation: opts.metadata.operation,
+            request_at: new Date().toISOString(),
+            response_at: new Date().toISOString(),
+            input_tokens: null,
+            output_tokens: null,
+            cost_usd_cents: null,
+            status: "success",
+            error_message: null,
+            correlation_id: opts.metadata.correlation_id,
+            ...(opts.metadata.environment ? { environment: opts.metadata.environment } : {}),
+            ...(opts.metadata.connection_id ? { connection_id: opts.metadata.connection_id } : {}),
+            metadata: {
+                decision_action: "allow",
+                decision_reason: "admit_unavailable",
+            },
+        });
+    }
+    catch {
+        /* belt-and-suspenders */
+    }
+}
+//# sourceMappingURL=admit-client.js.map

package/dist/admit-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit-client.js","sourceRoot":"","sources":["../src/admit-client.ts"],"names":[],"mappings":"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"}