@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/src/config.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 const DEFAULT_API_URL = "https://api.to11.ai";
+// The gateway *root* — no `/v1` version path. Provider helpers add the path each
+// provider SDK expects (`openaiOptions()` appends `/v1`; the Anthropic SDK adds
+// `/v1/messages` itself), so users configure only the host.
+export const DEFAULT_GATEWAY_URL = "https://gw.to11.ai";

package/src/context.ts

@@ -0,0 +1,196 @@
+/**
+ * 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,
+	gatewayAuthHeaders,
+	gatewayPromptHeaders,
+} 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 };
+
+function randomHex(bytes: number): string {
+	const buf = new Uint8Array(bytes);
+	crypto.getRandomValues(buf);
+	let out = "";
+	for (const b of buf) out += b.toString(16).padStart(2, "0");
+	return out;
+}
+
+/** A fresh, sampled W3C `traceparent` (`00-<32hex>-<16hex>-01`). */
+function newTraceparent(): string {
+	return `00-${randomHex(16)}-${randomHex(8)}-01`;
+}
+
+function newId(): string {
+	return crypto.randomUUID();
+}
+
+/**
+ * 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 class Turn {
+	/** The fixed W3C traceparent for this turn (one trace). */
+	readonly traceparent: string;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		readonly sessionId: string,
+		readonly conversationId: string,
+		traceparent?: string,
+	) {
+		this.traceparent = traceparent ?? newTraceparent();
+	}
+
+	/**
+	 * 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> {
+		const headers: Record<string, string> = {
+			...gatewayAuthHeaders({
+				apiKey: this.auth.apiKey,
+				projectId: this.auth.projectId,
+				...(this.auth.env !== undefined ? { env: this.auth.env } : {}),
+			}),
+			"x-to11-session-id": this.sessionId,
+			"x-to11-conversation-id": this.conversationId,
+			traceparent: this.traceparent,
+		};
+		if (prompt !== undefined) {
+			// gatewayPromptHeaders accepts a RenderedPrompt or a format-shaped
+			// result and unwraps `metadata` itself.
+			Object.assign(headers, gatewayPromptHeaders(prompt));
+		}
+		return headers;
+	}
+}
+
+/** One agent thread — a stable conversation id shared across all its turns. */
+export class Conversation {
+	/** Stable conversation id, reused by every turn created from this object. */
+	readonly id: string;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		readonly sessionId: string,
+		id?: string,
+	) {
+		this.id = id ?? newId();
+	}
+
+	/** Start a new turn (fresh trace) in this conversation. */
+	turn(): Turn {
+		return new Turn(this.auth, this.sessionId, this.id);
+	}
+}
+
+/**
+ * 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 class Session {
+	/** Stable session id, carried by every conversation and turn beneath it. */
+	readonly id: string;
+	private defaultConversation: Conversation | undefined;
+
+	constructor(
+		private readonly auth: TurnAuthContext,
+		id?: string,
+	) {
+		this.id = id ?? newId();
+	}
+
+	/**
+	 * 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 {
+		return new Conversation(this.auth, this.id, id);
+	}
+
+	/**
+	 * 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 {
+		if (this.defaultConversation === undefined) {
+			this.defaultConversation = this.conversation();
+		}
+		return this.defaultConversation.turn();
+	}
+}

package/src/errors.ts

@@ -113,6 +113,36 @@ export class To11aiResponseValidationError extends To11aiError {
 	}
 }
 
+/**
+ * Thrown by the provider-shape converters (`toOpenAIMessages` /
+ * `toAnthropicMessages`, and `render({ format })`) in `onUnknownRole: "error"`
+ * mode when a message carries a role outside the known set
+ * (`system | user | assistant | developer | tool`). `code` is the stable
+ * `"unknown_role"` slug; `role` / `index` locate the offending turn.
+ *
+ * A client-side conversion error — it extends `To11aiError` (not
+ * `To11aiApiError`), so it never carries an HTTP status.
+ */
+export class UnknownRoleError extends To11aiError {
+	readonly code = "unknown_role";
+	readonly role: string;
+	readonly index: number;
+
+	constructor(role: string, index: number) {
+		super(
+			`[to11ai/sdk] message[${index}] has unknown role ${JSON.stringify(role)}; expected system|user|assistant|developer|tool`,
+		);
+		this.name = "UnknownRoleError";
+		this.role = role;
+		this.index = index;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is UnknownRoleError {
+		return err instanceof UnknownRoleError;
+	}
+}
+
 /**
  * Thrown when strict-mode rejects a label move for an unregistered label.
  *
@@ -252,7 +282,7 @@ export class EnvNotEnabledForProviderError extends To11aiApiError {
 
 // ─── Prompt resolution typed errors (TO11-980 / S9) ────────────────────────
 //
-// These four subclasses give `prompts.fetch()` callers a discriminable error
+// These four subclasses give `prompts.render()` callers a discriminable error
 // family for prompt resolution. Each:
 //   - extends `To11aiApiError`, so existing broad `catch (err instanceof
 //     To11aiApiError)` blocks keep matching (AC8),
@@ -312,60 +342,54 @@ export class PromptNotFoundError extends To11aiApiError {
 }
 
 /**
- * Reason payload for `EnvNotFoundError`.
- *
- * `source` discriminates the two failure modes (D2):
- *   - `"missing"` — no env was supplied at init OR at call time. Raised
- *     CLIENT-side, eagerly, before any request (R4 / AC4); `env` is absent.
- *   - `"unknown"` — an env was supplied but the server's registry has no
- *     such (active) env. Surfaced from the `ENV_NOT_FOUND` server code; `env`
- *     carries the rejected slug when the server echoes it.
- */
-export interface EnvNotFoundReason {
-	env?: string;
-	source: "missing" | "unknown";
-}
-
-/**
- * Thrown when no serving environment can be resolved for a `prompts.fetch()`
- * call. One class, two `reason.source` discriminants (see
- * `EnvNotFoundReason`): client-eager `"missing"` (R4) and server-forwarded
- * `"unknown"` (`ENV_NOT_FOUND`).
+ * Thrown when the label supplied to `prompts.render()` does not resolve to an
+ * existing (active) label on the server. Surfaced from the server's
+ * `ENV_NOT_FOUND` code; `label` carries the rejected slug when the server
+ * echoes it.
  *
- * The client-eager variant carries no `statusCode`/`errorCode` from the wire
- * (no request was made); it reports status `0` and errorCode `ENV_NOT_FOUND`
- * for a uniform catch surface.
+ * This is distinct from `MissingLabelError`, which is raised client-side when
+ * no label was supplied at all.
  */
-export class EnvNotFoundError extends To11aiApiError {
-	readonly reason: EnvNotFoundReason;
+export class LabelNotFoundError extends To11aiApiError {
+	/** The label slug that could not be found, when the server echoes it. */
+	readonly label?: string;
 
 	constructor(
 		message: string,
-		reason: EnvNotFoundReason,
+		label: string | undefined,
 		details: unknown,
-		// Required (no misleading default): the client-eager `missing()` variant
-		// passes 0 (no HTTP call) and the transport mapper passes the real server
-		// status, so a hardcoded default would never reflect reality.
 		statusCode: number,
 	) {
+		// The wire code is unchanged (`ENV_NOT_FOUND`); only the SDK class name
+		// is label-oriented, decoupled from the server error code.
 		super(message, statusCode, "ENV_NOT_FOUND", details);
-		this.name = "EnvNotFoundError";
-		this.reason = reason;
+		this.name = "LabelNotFoundError";
+		this.label = label;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 
-	/** Build the client-eager (missing-at-both) variant — no transport call. */
-	static missing(env?: string): EnvNotFoundError {
-		return new EnvNotFoundError(
-			"[to11ai/sdk] No environment resolvable for prompts.fetch(): none supplied at client init and none supplied per call. Pass `env` to createClient or fetch(slug, { env }).",
-			{ env, source: "missing" },
-			undefined,
-			0,
-		);
+	static is(err: unknown): err is LabelNotFoundError {
+		return err instanceof LabelNotFoundError;
+	}
+}
+
+/**
+ * Thrown CLIENT-side, eagerly (before any request), when `prompts.render()` is
+ * called but no label is resolvable at all: none supplied per call, and no
+ * client `env` (or `TO11_ENV`) to fall back to. A usage error, not a lookup
+ * failure — distinct from `LabelNotFoundError`.
+ */
+export class MissingLabelError extends To11aiError {
+	constructor(
+		message = "[to11ai/sdk] No label resolvable for prompts.render(): none supplied per call, and no client env (or TO11_ENV) to fall back to. Pass `label` to render(slug, { label }) or set `env` on createClient.",
+	) {
+		super(message);
+		this.name = "MissingLabelError";
+		Object.setPrototypeOf(this, new.target.prototype);
 	}
 
-	static is(err: unknown): err is EnvNotFoundError {
-		return err instanceof EnvNotFoundError;
+	static is(err: unknown): err is MissingLabelError {
+		return err instanceof MissingLabelError;
 	}
 }
 
@@ -450,44 +474,6 @@ export class PromptPolicyViolationError extends To11aiApiError {
 	}
 }
 
-/**
- * Reason payload for `AmbiguousEnvLabelsError`.
- *
- * Carried when the supplied env-label matched more than one candidate
- * version and the server cannot pick deterministically
- * (`AMBIGUOUS_ENV_LABELS`).
- */
-export interface AmbiguousEnvLabelsReason {
-	env?: string;
-	slug?: string;
-}
-
-/**
- * Thrown when the env→label resolution is ambiguous on the server
- * (`AMBIGUOUS_ENV_LABELS`) — the label matched multiple candidates and the
- * server declines to guess. Surfaces (rather than 500ing) so callers get a
- * typed, actionable error.
- */
-export class AmbiguousEnvLabelsError extends To11aiApiError {
-	readonly reason: AmbiguousEnvLabelsReason;
-
-	constructor(
-		message: string,
-		reason: AmbiguousEnvLabelsReason,
-		details?: unknown,
-		statusCode = 409,
-	) {
-		super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
-		this.name = "AmbiguousEnvLabelsError";
-		this.reason = reason;
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-
-	static is(err: unknown): err is AmbiguousEnvLabelsError {
-		return err instanceof AmbiguousEnvLabelsError;
-	}
-}
-
 /**
  * Thrown when version create rejects the snapshot for a structural
  * reason — invalid variant params, malformed `when` clause, illegal