@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/dist/client.d.ts

@@ -1,87 +1,175 @@
+import { type Conversation, Session, type Turn } from "./context";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
-import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
-import { RoutingRulesResource } from "./routingRules/resource";
-export { BehaviorStore, type BehaviorStoreOptions, envVarNameForKey, type SdkBehaviorEnvelope, } from "./behaviors/store";
-export type { AmbiguousEnvLabelsReason, EnvNotFoundReason, NoActiveReleaseReason, NoApplicableRouteReason, PromptNotFoundReason, PromptPolicyViolationReason, } from "./errors";
-export { AmbiguousEnvLabelsError, EnvNotEnabledForProviderError, EnvNotFoundError, NoActiveReleaseError, NoApplicableRouteError, PromptLabelNotRegisteredError, PromptNotFoundError, PromptPolicyViolationError, RuleNotFoundError, RuleVersionInvalidSnapshotError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, } from "./errors";
-export type { GatewayAuthOptions } from "./gateway";
+import { type RenderFormat, type UnknownRoleMode } from "./prompts/types";
+export type { TurnAuthContext } from "./context";
+export { Conversation, Session, Turn } from "./context";
+export type { NoActiveReleaseReason, PromptNotFoundReason, PromptPolicyViolationReason, } from "./errors";
+export { LabelNotFoundError, MissingLabelError, NoActiveReleaseError, PromptLabelNotRegisteredError, PromptNotFoundError, PromptPolicyViolationError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, UnknownRoleError, } from "./errors";
+export type { ConvertMessagesOptions, GatewayAuthOptions } from "./gateway";
 export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 export type { ArchiveProjectEnvironmentInput, ArchiveProjectEnvironmentResult, CreateProjectEnvironmentInput, CreateProjectEnvironmentResult, GetProjectEnvironmentInput, GetProjectEnvironmentResult, ListProjectEnvironmentsInput, ListProjectEnvironmentsResult, LivePointerCounts, ProjectEnvironment, RestoreProjectEnvironmentInput, RestoreProjectEnvironmentResult, UpdateProjectEnvironmentInput, UpdateProjectEnvironmentResult, } from "./projectEnvironments/resource";
 export { ProjectEnvironmentResource } from "./projectEnvironments/resource";
-export type { CacheConfig } from "./prompts/cache";
 export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
-export type { BlockRenderRecord, DeveloperRole, FetchedPrompt, FetchPromptOptions, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvedPromptEnvelope, } from "./prompts/types";
+export type { AnthropicRenderedPrompt, OpenAiRenderedPrompt, PromptConfig, PromptMetadata, RenderResult, } from "./prompts/shape";
+export type { BlockRenderRecord, RenderedChatMessage, RenderedPrompt, RenderFormat, RenderOptions, UnknownRoleMode, } from "./prompts/types";
 export { ENV_SLUG_REGEX } from "./prompts/types";
-export type { CreateRuleVersionInput, CreateRuleVersionResult, GetRuleVersionInput, GetRuleVersionResult, ListRuleReleasesInput, ListRuleReleasesResult, ListRuleVersionsInput, ListRuleVersionsResult, RollbackRuleReleaseInput, RollbackRuleReleaseResult, RuleModelBinding, RuleProviderRef, RuleRelease, RuleReleaseActorType, RuleReleaseApprovalStatus, RuleReleaseChangeKind, RuleReleaseStrategy, RuleReleaseWeight, RuleSnapshot, RuleStrategy, RuleVersion, SetRuleReleaseInput, SetRuleReleaseResult, } from "./routingRules/resource";
-export { RoutingRuleReleaseResource, RoutingRulesResource, RoutingRuleVersionResource, } from "./routingRules/resource";
-export type { Transport } from "./transport";
-interface ServerAuthOptions {
-    /** API key for server-side use. Must not be used in browser contexts. */
-    apiKey: string;
-    getAccessToken?: never;
-}
-interface BrowserAuthOptions {
-    /** Token callback for browser / edge contexts — avoids static secrets. */
-    getAccessToken: () => Promise<string>;
-    apiKey?: never;
-}
-type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
-export type ClientOptions = AuthOptions & {
-    baseUrl: string;
+export interface ClientOptions {
+    /**
+     * Control-plane base URL. Precedence: this option → `TO11_API_URL` env →
+     * `https://api.to11.ai`.
+     */
+    baseUrl?: string;
+    /**
+     * Data-plane gateway URL (the app's provider-client `baseURL`). Precedence:
+     * this option → `TO11_GATEWAY_URL` env → `https://gw.to11.ai`.
+     */
+    gatewayUrl?: string;
+    /**
+     * API key for server-side use (server, CLI, backend job). Precedence: this
+     * option → `TO11_API_KEY` env. Required. Rejected in browser contexts — a
+     * to11 API key carries gateway access and must never ship in client code.
+     */
+    apiKey?: string;
     /**
-     * Project the client is bound to (TO11-980 / S9). Required for the
-     * env-aware `prompts.fetch(slug, …)` surface, which builds the
-     * project-scoped resolve path from it. Validated non-empty at
-     * construction. The deprecated `prompts.resolve()` keeps its per-call
-     * `projectId` and ignores this.
+     * Provider API key (BYOK) carried by `openaiOptions()` / `anthropicOptions()`
+     * as the provider client's `apiKey`, so a BYOK call is a single
+     * `new OpenAI(to11.openaiOptions())`. When omitted, those helpers fall back to
+     * the to11 `apiKey` as a placeholder (the managed / server-side-credential
+     * path). Option only — no env fallback. Whether the gateway actually uses this
+     * key depends on the provider's passthrough mode; otherwise the project's
+     * stored credential wins.
+     */
+    providerApiKey?: string;
+    /**
+     * Project the client is bound to. Precedence: this option → `TO11_PROJECT_ID`
+     * env. Required for `prompts.render()` and the gateway context helpers.
      */
     projectId?: string;
     /**
-     * Default serving environment for `prompts.fetch(slug)` (TO11-980 / S9,
-     * Style-A). When set, every `fetch()` call inherits it unless overridden
-     * per call. Validated eagerly against the project-environments registry
-     * rule (lowercase-kebab, `^[a-z0-9-]{1,63}$`): empty / whitespace-only /
-     * uppercase / 64+-char values throw at construction with a loud
-     * `[to11ai/sdk]` message before any request hits the wire.
+     * Default serving environment for `prompts.render(slug)`, inherited by every
+     * render unless overridden per call. Precedence: this option → `TO11_ENV`
+     * env. Validated eagerly against the project-environments slug rule
+     * (`^[a-z0-9-]{1,63}$`).
      */
     env?: string;
-    /** LRU cache configuration for resolve(). Defaults: ttlSeconds=300, maxEntries=100 */
-    cache?: CacheConfig;
+    /**
+     * Default provider shape for `prompts.render()` output (`"openai"` |
+     * `"anthropic"`). Omit for the neutral result. Per-call override allowed.
+     */
+    format?: RenderFormat;
+    /**
+     * Default policy for a message with an unrecognized role while shaping
+     * `render({ format })` output: `"drop"` (default, silent), `"warn"` (drop +
+     * `console.warn`), or `"error"` (throw `UnknownRoleError`). Per-call override
+     * via `render(slug, { onUnknownRole })`.
+     */
+    onUnknownRole?: UnknownRoleMode;
     /** Request timeout in milliseconds. Default: 30_000 */
     timeoutMs?: number;
     /** Max retry attempts for network errors / 5xx. Default: 3 */
     maxRetries?: number;
-    /**
-     * Purely local overrides for server-evaluated SDK-behavior flags (TO11-2100),
-     * keyed by namespaced flag key (e.g. `{ "sdk.retry-v2": true }`). These take
-     * precedence over server-delivered values and the SDK's coded defaults. For
-     * the same flag key, an init option here wins over a `TO11_SDK_BEHAVIOR_*`
-     * environment variable. Published-SDK only — no LaunchDarkly involved.
-     */
-    behaviorOverrides?: Record<string, unknown>;
+}
+/**
+ * Overrides accepted by `openaiOptions()` / `anthropicOptions()`. The three
+ * known fields are merged (`apiKey` / `baseURL` override; `defaultHeaders`
+ * shallow-merges over the tenant-auth headers, caller wins); any other keys —
+ * `timeout`, `maxRetries`, `fetch`, … — pass through untouched to the provider
+ * client, so `new OpenAI(to11.openaiOptions({ apiKey, timeout }))` needs no
+ * outer spread.
+ */
+export interface ProviderClientOverrides {
+    apiKey?: string;
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * The spread-ready result of `openaiOptions()` / `anthropicOptions()`: the three
+ * managed fields plus whatever passthrough keys the caller supplied (their types
+ * preserved), so it drops straight into `new OpenAI(...)` / `new Anthropic(...)`.
+ */
+export type ProviderClientOptions<T extends ProviderClientOverrides = ProviderClientOverrides> = Omit<T, "apiKey" | "baseURL" | "defaultHeaders"> & {
+    baseURL: string;
+    apiKey: string;
+    defaultHeaders: Record<string, string>;
 };
-export interface To11aiClient {
-    readonly prompts: PromptResource;
+export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
+    readonly prompts: PromptResource<F>;
     readonly projectEnvironments: ProjectEnvironmentResource;
-    readonly routingRules: RoutingRulesResource;
+    /** Resolved API key (option → `TO11_API_KEY`). */
+    readonly apiKey: string;
+    /** Resolved control-plane base URL (option → `TO11_API_URL` → default). */
+    readonly baseUrl: string;
+    /** Resolved data-plane gateway URL (option → `TO11_GATEWAY_URL` → default). */
+    readonly gatewayUrl: string;
+    /**
+     * Resolved project id (option → `TO11_PROJECT_ID`); `undefined` when none is
+     * configured. Read-only, for your own logging / manual headers — `prompts.*`
+     * already default to it, so you don't need to pass it back into calls.
+     */
+    readonly projectId: string | undefined;
+    /**
+     * Resolved default serving environment (option → `TO11_ENV`); `undefined`
+     * when none is configured. `prompts.render()` already defaults to it.
+     */
+    readonly env: string | undefined;
+    /** A new session (unit of work). Pass an id to group telemetry by your own id. */
+    session(id?: string): Session;
+    /**
+     * A conversation in the client's default session (for side / parallel agents).
+     *
+     * @example Two agents under one session
+     * const research = to11.conversation();   // a separate thread from to11.turn()'s default
+     * const res = await openai.chat.completions.create(
+     *   { ...researchPrompt.config, messages },
+     *   { headers: research.turn().headers(researchPrompt) },
+     * );
+     */
+    conversation(id?: string): Conversation;
+    /** A turn in the client's default session + default conversation. */
+    turn(): Turn;
+    /**
+     * Spread-ready options for `new OpenAI(...)` targeting the gateway:
+     * `{ baseURL, apiKey, defaultHeaders }` (baseURL carries `/v1`). `defaultHeaders`
+     * holds the static tenant auth, so the client authenticates on its own; add
+     * `turn().headers(prompt)` per call for trace + prompt provenance. Pass
+     * `overrides` to change `apiKey`/`baseURL`, merge extra `defaultHeaders`, or
+     * forward any other provider-SDK option (`timeout`, …).
+     *
+     * @example
+     * const openai = new OpenAI(to11.openaiOptions());
+     * @example BYOK + a provider-SDK option, no outer spread
+     * const openai = new OpenAI(to11.openaiOptions({ apiKey: MY_KEY, timeout: 60_000 }));
+     */
+    openaiOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(overrides?: T): ProviderClientOptions<T>;
     /**
-     * Resolve a server-evaluated SDK-behavior flag value (TO11-2100) under the
-     * fixed precedence: local override (init option → `TO11_SDK_BEHAVIOR_*` env
-     * var) → server-delivered value (captured from responses the client has
-     * already made) → the `codedDefault` passed here. A value whose runtime type
-     * disagrees with `codedDefault` falls through to the next tier. The SDK
-     * carries no LaunchDarkly dependency; this only reads what the server
-     * delivered on the envelope.
+     * Spread-ready options for `new Anthropic(...)` targeting the gateway root
+     * (the Anthropic SDK appends `/v1/messages` itself). Same shape and merge
+     * rules as {@link To11aiClient.openaiOptions}.
      */
-    readonly resolveBehavior: <T>(key: string, codedDefault: T) => T;
+    anthropicOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(overrides?: T): ProviderClientOptions<T>;
 }
 /**
- * Create a to11ai SDK client.
+ * Create a to11ai SDK client. Resolution precedence differs per option:
+ *  - URLs (`baseUrl` / `gatewayUrl`) — option → env var → built-in default.
+ *  - `apiKey` / `projectId` — option → env var (no default).
+ *  - `env` / `format` — option only.
+ * Authenticate with `apiKey` (or `TO11_API_KEY`) — required, and server-side
+ * only (server, CLI, backend job); constructing with `apiKey` in a browser throws.
+ *
+ * @example Minimal setup (single call)
+ * import { createClient } from "@to11ai/sdk";
+ * import OpenAI from "openai";
  *
- * Auth mode is inferred from options:
- *  - `apiKey`          → server-side; rejected in browser contexts.
- *  - `getAccessToken`  → browser-safe; token fetched per request.
+ * const to11   = createClient({ env: "prod", format: "openai" });
+ * const openai = new OpenAI(to11.openaiOptions());
+ * const prompt = await to11.prompts.render("weather-concierge", { variables: { city: "NYC" } });
+ * const res = await openai.chat.completions.create(
+ *   { ...prompt.config, messages: prompt.messages },
+ *   { headers: to11.turn().headers(prompt) },
+ * );
  */
-export declare function createClient(options: ClientOptions): To11aiClient;
+export declare function createClient<const F extends RenderFormat | undefined = undefined>(options?: Omit<ClientOptions, "format"> & {
+    format?: F;
+}): To11aiClient<F>;

package/dist/client.js

@@ -1,48 +1,58 @@
 // src/client.ts
 import { BehaviorStore } from "./behaviors/store";
+import { DEFAULT_API_URL, DEFAULT_GATEWAY_URL } from "./config";
+import {
+  Session
+} from "./context";
+import { gatewayAuthHeaders } from "./gateway";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import { PromptResource } from "./prompts/resource";
-import { ENV_SLUG_REGEX } from "./prompts/types";
-import { RoutingRulesResource } from "./routingRules/resource";
-import { Transport } from "./transport";
 import {
-  BehaviorStore as BehaviorStore2,
-  envVarNameForKey
-} from "./behaviors/store";
+  ENV_SLUG_REGEX
+} from "./prompts/types";
+import { Transport } from "./transport";
+import { Conversation, Session as Session2, Turn } from "./context";
 import {
-  AmbiguousEnvLabelsError,
-  EnvNotEnabledForProviderError,
-  EnvNotFoundError,
+  LabelNotFoundError,
+  MissingLabelError,
   NoActiveReleaseError,
-  NoApplicableRouteError,
   PromptLabelNotRegisteredError,
   PromptNotFoundError,
   PromptPolicyViolationError,
-  RuleNotFoundError,
-  RuleVersionInvalidSnapshotError,
   To11aiApiError,
   To11aiAuthError,
   To11aiError,
   To11aiNetworkError,
   To11aiRateLimitError,
-  To11aiValidationError
+  To11aiValidationError,
+  UnknownRoleError
 } from "./errors";
-import { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
+import { gatewayAuthHeaders as gatewayAuthHeaders2, gatewayPromptHeaders } from "./gateway";
 import { ProjectEnvironmentResource as ProjectEnvironmentResource2 } from "./projectEnvironments/resource";
 import { PromptResource as PromptResource2 } from "./prompts/resource";
 import { ENV_SLUG_REGEX as ENV_SLUG_REGEX2 } from "./prompts/types";
-import {
-  RoutingRuleReleaseResource,
-  RoutingRulesResource as RoutingRulesResource2,
-  RoutingRuleVersionResource
-} from "./routingRules/resource";
-function createClient(options) {
+function createClient(options = {}) {
   const isDomBrowser = typeof globalThis === "object" && typeof globalThis.document !== "undefined";
   const workerLikeGlobal = globalThis;
   const isBunMainThread = workerLikeGlobal.Bun?.isMainThread === true;
   const isWorkerBrowser = typeof globalThis === "object" && (typeof workerLikeGlobal.importScripts === "function" || !isBunMainThread && typeof workerLikeGlobal.postMessage === "function" && typeof workerLikeGlobal.onmessage !== "undefined");
-  if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
-    throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
+  const isBrowser = isDomBrowser || isWorkerBrowser;
+  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const pick = (opt, envKey) => {
+    const fromOpt = opt?.trim();
+    if (fromOpt)
+      return fromOpt;
+    const fromEnv = processEnv?.[envKey]?.trim();
+    return fromEnv ? fromEnv : undefined;
+  };
+  const baseUrl = pick(options.baseUrl, "TO11_API_URL") ?? DEFAULT_API_URL;
+  const gatewayUrl = (pick(options.gatewayUrl, "TO11_GATEWAY_URL") ?? DEFAULT_GATEWAY_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  const apiKey = pick(options.apiKey, "TO11_API_KEY");
+  const projectId = pick(options.projectId, "TO11_PROJECT_ID");
+  const env = pick(options.env, "TO11_ENV");
+  const providerApiKey = options.providerApiKey?.trim() || undefined;
+  if (isBrowser && options.apiKey !== undefined) {
+    throw new Error("[to11ai/sdk] Do not use `apiKey` in a browser — a to11 API key carries gateway access and must stay server-side (server, CLI, or backend job).");
   }
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
     throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
@@ -50,68 +60,98 @@ function createClient(options) {
   if (options.projectId !== undefined && options.projectId.trim() === "") {
     throw new Error("[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.");
   }
-  if (options.env !== undefined && !ENV_SLUG_REGEX.test(options.env)) {
-    throw new Error(`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`);
+  if (options.env !== undefined && options.env.trim() === "") {
+    throw new Error("[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.");
   }
-  const hasApiKey = options.apiKey !== undefined;
-  const hasGetAccessToken = options.getAccessToken !== undefined;
-  const getAccessToken = options.getAccessToken;
-  if (hasApiKey === hasGetAccessToken) {
-    throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).");
+  if (env !== undefined && !ENV_SLUG_REGEX.test(env)) {
+    throw new Error(`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
   }
-  const auth = options.apiKey !== undefined ? { apiKey: options.apiKey } : { getAccessToken };
-  const isBrowser = isDomBrowser || isWorkerBrowser;
-  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
-  const behaviorStore = new BehaviorStore({
-    initOverrides: options.behaviorOverrides,
-    env: processEnv
-  });
+  if (apiKey === undefined) {
+    throw new Error("[to11ai/sdk] An `apiKey` (or `TO11_API_KEY`) is required.");
+  }
+  const auth = { apiKey };
+  const behaviorStore = new BehaviorStore({ env: processEnv });
   const transport = new Transport({
-    baseUrl: options.baseUrl,
+    baseUrl,
     auth,
     timeoutMs: options.timeoutMs,
     maxRetries: options.maxRetries,
     behaviorStore
   });
-  const prompts = new PromptResource(transport, options.cache, {
-    projectId: options.projectId,
-    env: options.env
+  const prompts = new PromptResource(transport, {
+    projectId,
+    env,
+    format: options.format,
+    onUnknownRole: options.onUnknownRole
   });
   const projectEnvironments = new ProjectEnvironmentResource(transport);
-  const routingRules = new RoutingRulesResource(transport);
+  const gatewayAuthContext = () => {
+    if (projectId === undefined) {
+      throw new Error("[to11ai/sdk] session()/turn() need a `projectId` (or `TO11_PROJECT_ID`).");
+    }
+    return env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId };
+  };
+  let defaultSession;
+  const clientDefaultSession = () => {
+    if (defaultSession === undefined) {
+      defaultSession = new Session(gatewayAuthContext());
+    }
+    return defaultSession;
+  };
+  const gatewayClientOptions = (defaultBaseURL, overrides) => {
+    if (projectId === undefined) {
+      throw new Error("[to11ai/sdk] openaiOptions()/anthropicOptions() need a `projectId` (or `TO11_PROJECT_ID`) — it authenticates the gateway call via `x-to11-project-id`.");
+    }
+    const authHeaders = gatewayAuthHeaders(env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId });
+    const {
+      apiKey: overrideApiKey,
+      baseURL: overrideBaseURL,
+      defaultHeaders: overrideHeaders,
+      ...passthrough
+    } = overrides ?? {};
+    return {
+      ...passthrough,
+      baseURL: overrideBaseURL ?? defaultBaseURL,
+      apiKey: overrideApiKey ?? providerApiKey ?? apiKey,
+      defaultHeaders: { ...authHeaders, ...overrideHeaders }
+    };
+  };
   return {
     prompts,
     projectEnvironments,
-    routingRules,
-    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault)
+    apiKey,
+    baseUrl,
+    gatewayUrl,
+    projectId,
+    env,
+    session: (id) => new Session(gatewayAuthContext(), id),
+    conversation: (id) => clientDefaultSession().conversation(id),
+    turn: () => clientDefaultSession().turn(),
+    openaiOptions: (overrides) => gatewayClientOptions(`${gatewayUrl}/v1`, overrides),
+    anthropicOptions: (overrides) => gatewayClientOptions(gatewayUrl, overrides)
   };
 }
 export {
   gatewayPromptHeaders,
-  gatewayAuthHeaders,
-  envVarNameForKey,
+  gatewayAuthHeaders2 as gatewayAuthHeaders,
   createClient,
+  UnknownRoleError,
+  Turn,
   To11aiValidationError,
   To11aiRateLimitError,
   To11aiNetworkError,
   To11aiError,
   To11aiAuthError,
   To11aiApiError,
-  RuleVersionInvalidSnapshotError,
-  RuleNotFoundError,
-  RoutingRulesResource2 as RoutingRulesResource,
-  RoutingRuleVersionResource,
-  RoutingRuleReleaseResource,
+  Session2 as Session,
   PromptResource2 as PromptResource,
   PromptPolicyViolationError,
   PromptNotFoundError,
   PromptLabelNotRegisteredError,
   ProjectEnvironmentResource2 as ProjectEnvironmentResource,
-  NoApplicableRouteError,
   NoActiveReleaseError,
-  EnvNotFoundError,
-  EnvNotEnabledForProviderError,
+  MissingLabelError,
+  LabelNotFoundError,
   ENV_SLUG_REGEX2 as ENV_SLUG_REGEX,
-  BehaviorStore2 as BehaviorStore,
-  AmbiguousEnvLabelsError
+  Conversation
 };

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal default endpoints. Deliberately NOT re-exported from the package
+ * root: `createClient` resolves the URLs (option → env → default) and exposes
+ * the resolved data-plane URL as `to11.gatewayUrl`, so app code never imports a
+ * bare URL constant. Keeping these out of the public surface avoids a JS-only
+ * exported symbol that would need a Python-parity record.
+ */
+export declare const DEFAULT_API_URL = "https://api.to11.ai";
+export declare const DEFAULT_GATEWAY_URL = "https://gw.to11.ai";

package/dist/context.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Observability context — the `session → conversation → turn` hierarchy that
+ * maps onto to11's telemetry grouping (Session → Conversation → Turn →
+ * LLM-Call). Each level provides a lazy default for the level below; explicit
+ * control is opt-in per use case. See
+ * docs/product-specs/2026-07-14-to11-2691-sdk-simpler-setup.md.
+ *
+ * Header-only: `turn.headers(prompt?)` returns a plain object the caller applies
+ * to their own provider client. It never sends a request.
+ */
+import { type GatewayPromptProvenance } from "./gateway";
+/** Auth/config the client hands to the context for gateway header building. */
+export interface TurnAuthContext {
+    readonly apiKey: string;
+    readonly projectId: string;
+    readonly env?: string;
+}
+/**
+ * A prompt argument accepted by `turn.headers()`. Either the flat provenance
+ * (a neutral `RenderedPrompt`) or a `format`-shaped result carrying it under
+ * `metadata` — both are accepted so the format and neutral render paths carry
+ * provenance identically.
+ */
+export type PromptForHeaders = GatewayPromptProvenance | {
+    metadata: GatewayPromptProvenance;
+};
+/**
+ * One agent turn — a single trace. A turn's `traceparent` is fixed for its
+ * lifetime, so every LLM-call made under it groups into one trace.
+ */
+export declare class Turn {
+    private readonly auth;
+    readonly sessionId: string;
+    readonly conversationId: string;
+    /** The fixed W3C traceparent for this turn (one trace). */
+    readonly traceparent: string;
+    constructor(auth: TurnAuthContext, sessionId: string, conversationId: string, traceparent?: string);
+    /**
+     * The complete gateway header bag: auth + session + conversation +
+     * traceparent, plus prompt provenance when a `prompt` is supplied. A pure
+     * read of the turn's fixed ids — reuse it across a tool-loop or call per
+     * request; the result is identical.
+     *
+     * Only valid for requests targeting the gateway (`GATEWAY_URL`); it carries
+     * the to11 API key and must never be attached to a direct provider endpoint.
+     *
+     * @example One call (inline turn)
+     * const res = await openai.chat.completions.create(
+     *   { ...prompt.config, messages: prompt.messages },
+     *   { headers: to11.turn().headers(prompt) },
+     * );
+     *
+     * @example Tool loop — hoist the turn so every call shares one trace
+     * const turn = to11.turn();
+     * const headers = turn.headers(prompt);
+     * while (true) {
+     *   const res = await openai.chat.completions.create({ ...prompt.config, messages, tools }, { headers });
+     *   // …reuse `headers` for every call in the loop…
+     * }
+     */
+    headers(prompt?: PromptForHeaders): Record<string, string>;
+}
+/** One agent thread — a stable conversation id shared across all its turns. */
+export declare class Conversation {
+    private readonly auth;
+    readonly sessionId: string;
+    /** Stable conversation id, reused by every turn created from this object. */
+    readonly id: string;
+    constructor(auth: TurnAuthContext, sessionId: string, id?: string);
+    /** Start a new turn (fresh trace) in this conversation. */
+    turn(): Turn;
+}
+/**
+ * One unit of work. Groups conversations under a single session id. A session
+ * lazily owns one default conversation, used by `session.turn()`; call
+ * `session.conversation()` for additional (side/parallel) agent threads.
+ */
+export declare class Session {
+    private readonly auth;
+    /** Stable session id, carried by every conversation and turn beneath it. */
+    readonly id: string;
+    private defaultConversation;
+    constructor(auth: TurnAuthContext, id?: string);
+    /**
+     * Create a distinct conversation (a separate agent thread) in this session.
+     * Use this when one unit of work runs multiple agents (side / parallel
+     * agents): each conversation gets its own `x-to11-conversation-id`, all under
+     * the one session.
+     *
+     * @example Multiple agents in one session
+     * const session  = to11.session();
+     * const main     = session.conversation();   // main agent thread
+     * const research = session.conversation();   // separate research thread, same session
+     *
+     * await openai.chat.completions.create(
+     *   { ...mainPrompt.config, messages: mainMessages },
+     *   { headers: main.turn().headers(mainPrompt) },
+     * );
+     * await openai.chat.completions.create(
+     *   { ...researchPrompt.config, messages: researchMessages },
+     *   { headers: research.turn().headers(researchPrompt) },
+     * );
+     */
+    conversation(id?: string): Conversation;
+    /**
+     * Start a turn in the session's single implicit conversation. The default
+     * conversation is created lazily on first call and reused, so consecutive
+     * `session.turn()` calls share one `x-to11-conversation-id` (each with its
+     * own `traceparent`).
+     *
+     * @example Multi-turn chat — every turn shares the session's conversation
+     * const session = to11.session();
+     * for await (const input of inputs) {
+     *   messages.push({ role: "user", content: input });
+     *   const turn = session.turn(); // fresh trace, same conversation id
+     *   const res = await openai.chat.completions.create(
+     *     { ...prompt.config, messages },
+     *     { headers: turn.headers(prompt) },
+     *   );
+     *   messages.push(res.choices[0].message);
+     * }
+     */
+    turn(): Turn;
+}