@dex-ai/sdk 0.1.30

package/src/messages.ts

@@ -0,0 +1,423 @@
+/**
+ * Messages — a guarded, ordered collection of conversation messages.
+ *
+ * Wraps the internal message array with controlled mutation methods and
+ * validates structural invariants on every write. Direct array mutation
+ * (via index assignment, push, splice, etc.) is trapped by a Proxy and
+ * throws at runtime — extensions MUST use the provided mutation API.
+ *
+ * Invariants enforced:
+ *   1. System messages appear only at the front (contiguous prefix).
+ *   2. First non-system message has role "user".
+ *   3. Role alternation: assistant follows user, tool follows assistant.
+ *   4. Every tool-call must have a matching tool-result before the next user turn.
+ *   5. No orphaned tool-result without a preceding tool-call.
+ *   6. Every message has an `id`.
+ *
+ * NOTE: Trailing tool-calls (at the end of the sequence) are allowed — the
+ * generate loop commits the assistant message before dispatching tools.
+ */
+
+import type { Content, Message, Role, ToolCallContent } from "./message";
+
+/* ------------------------------------------------------------------ */
+/* Validation                                                          */
+/* ------------------------------------------------------------------ */
+
+export interface ValidationError {
+	readonly index: number;
+	readonly message: string;
+}
+
+/**
+ * Validate the full message sequence. Returns an empty array if valid.
+ */
+export function validateMessages(
+	messages: ReadonlyArray<Message>,
+): ValidationError[] {
+	const errors: ValidationError[] = [];
+
+	if (messages.length === 0) return errors;
+
+	// 1. System messages only at front.
+	let systemEnd = 0;
+	for (let i = 0; i < messages.length; i++) {
+		if (messages[i]!.role === "system") {
+			if (i !== systemEnd) {
+				errors.push({
+					index: i,
+					message: `System message at index ${i} after non-system message at index ${systemEnd}`,
+				});
+			}
+			systemEnd = i + 1;
+		}
+	}
+
+	// 2. First non-system message must be user role.
+	if (systemEnd < messages.length) {
+		const first = messages[systemEnd]!;
+		if (first.role !== "user") {
+			errors.push({
+				index: systemEnd,
+				message: `First non-system message must be "user", got "${first.role}"`,
+			});
+		}
+	}
+
+	// 3. Role alternation + tool-call/tool-result pairing.
+	let pendingToolCalls = new Map<string, number>(); // toolCallId → assistant msg index
+
+	for (let i = systemEnd; i < messages.length; i++) {
+		const msg = messages[i]!;
+		const prev = i > systemEnd ? messages[i - 1]! : null;
+
+		switch (msg.role) {
+			case "user": {
+				// user can follow: nothing (first), assistant, or tool
+				if (prev && prev.role !== "assistant" && prev.role !== "tool") {
+					errors.push({
+						index: i,
+						message: `"user" message follows "${prev.role}" (expected after "assistant" or "tool")`,
+					});
+				}
+				// If we still have pending tool calls from a previous assistant, that's an error
+				if (pendingToolCalls.size > 0) {
+					for (const [id, idx] of pendingToolCalls) {
+						errors.push({
+							index: idx,
+							message: `Orphaned tool-call "${id}" — no matching tool-result before next user turn`,
+						});
+					}
+					pendingToolCalls = new Map();
+				}
+				break;
+			}
+			case "assistant": {
+				// assistant follows user or tool
+				if (prev && prev.role !== "user" && prev.role !== "tool") {
+					errors.push({
+						index: i,
+						message: `"assistant" message follows "${prev.role}" (expected after "user" or "tool")`,
+					});
+				}
+				// Collect tool calls
+				for (const c of msg.content) {
+					if (c.type === "tool-call") {
+						pendingToolCalls.set(
+							(c as ToolCallContent).toolCallId,
+							i,
+						);
+					}
+				}
+				break;
+			}
+			case "tool": {
+				// tool follows assistant or tool
+				if (prev && prev.role !== "assistant" && prev.role !== "tool") {
+					errors.push({
+						index: i,
+						message: `"tool" message follows "${prev.role}" (expected after "assistant" or "tool")`,
+					});
+				}
+				// Match tool-results to pending tool-calls
+				for (const c of msg.content) {
+					if (c.type === "tool-result") {
+						const id = c.toolCallId;
+						if (!pendingToolCalls.has(id)) {
+							errors.push({
+								index: i,
+								message: `Orphaned tool-result "${id}" — no matching tool-call`,
+							});
+						} else {
+							pendingToolCalls.delete(id);
+						}
+					}
+				}
+				break;
+			}
+		}
+	}
+
+	// NOTE: We intentionally do NOT flag pending tool-calls at the end of the
+	// sequence. The generate loop commits the assistant message (with tool-calls)
+	// before dispatching tools and committing their results. This intermediate
+	// state is valid — the tool-results will arrive on subsequent appends.
+	// The real invariant violation (tool-calls that never get results) is caught
+	// at line 81-89 when a "user" message arrives while tool-calls are still
+	// pending.
+
+	return errors;
+}
+
+/* ------------------------------------------------------------------ */
+/* Messages class                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Mutation mode controls when validation runs:
+ * - "strict": validate after every mutation, throw on failure
+ * - "batch": defer validation until `commit()` is called
+ */
+type MutationMode = "strict" | "batch";
+
+const TRAPPED_MUTATORS = new Set([
+	"push",
+	"pop",
+	"shift",
+	"unshift",
+	"splice",
+	"sort",
+	"reverse",
+	"fill",
+	"copyWithin",
+]);
+
+export class Messages {
+	private readonly _internal: Message[];
+	private readonly _proxy: ReadonlyArray<Message>;
+	private _batchDepth = 0;
+
+	constructor(initial?: ReadonlyArray<Message>) {
+		this._internal = initial ? [...initial] : [];
+
+		// Create a Proxy that traps all mutating operations
+		this._proxy = new Proxy(this._internal, {
+			set(_target, prop, _value) {
+				// Allow length to be read but not set externally
+				if (prop === "length") {
+					throw new Error(
+						"[Messages] Direct array mutation is not allowed. " +
+							"Use messages.splice() or messages.append() instead.",
+					);
+				}
+				// Block numeric index assignment
+				if (typeof prop === "string" && /^\d+$/.test(prop)) {
+					throw new Error(
+						"[Messages] Direct index assignment is not allowed. " +
+							"Use messages.replace() instead.",
+					);
+				}
+				return false;
+			},
+			get(target, prop, receiver) {
+				// Trap mutating array methods
+				if (typeof prop === "string" && TRAPPED_MUTATORS.has(prop)) {
+					return () => {
+						throw new Error(
+							`[Messages] Direct .${prop}() is not allowed. ` +
+								"Use the Messages API (append, splice, replaceRange) instead.",
+						);
+					};
+				}
+				return Reflect.get(target, prop, receiver);
+			},
+			deleteProperty(_target, prop) {
+				throw new Error(
+					`[Messages] Cannot delete index ${String(prop)}. ` +
+						"Use messages.splice() instead.",
+				);
+			},
+		}) as ReadonlyArray<Message>;
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Read access                                                       */
+	/* ---------------------------------------------------------------- */
+
+	/** The proxied read-only view. Safe to expose on AgentContext. */
+	get array(): ReadonlyArray<Message> {
+		return this._proxy;
+	}
+
+	get length(): number {
+		return this._internal.length;
+	}
+
+	at(index: number): Message | undefined {
+		return this._internal.at(index);
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Controlled mutations                                              */
+	/* ---------------------------------------------------------------- */
+
+	/**
+	 * Append one or more messages. Assigns IDs if missing.
+	 * Validates invariants after append (unless in a batch).
+	 */
+	append(message: Message | ReadonlyArray<Message>): void {
+		const msgs = Array.isArray(message) ? message : [message];
+		const prepared: Message[] = [];
+		for (const m of msgs) {
+			const withId: Message =
+				m.id !== undefined ? m : { ...m, id: crypto.randomUUID() };
+			prepared.push(withId);
+		}
+		this._internal.push(...prepared);
+		this._validateIfStrict();
+	}
+
+	/**
+	 * Replace a range of messages. Like Array.splice but validates afterward.
+	 * Returns the removed messages.
+	 */
+	splice(
+		start: number,
+		deleteCount: number,
+		...items: Message[]
+	): Message[] {
+		// Assign IDs to inserted items
+		const prepared = items.map((m) =>
+			m.id !== undefined ? m : { ...m, id: crypto.randomUUID() },
+		);
+		const removed = this._internal.splice(start, deleteCount, ...prepared);
+		this._validateIfStrict();
+		return removed;
+	}
+
+	/**
+	 * Replace a contiguous range with new messages.
+	 * Convenience wrapper over splice.
+	 */
+	replaceRange(
+		start: number,
+		end: number,
+		replacement: ReadonlyArray<Message>,
+	): Message[] {
+		const deleteCount = end - start;
+		return this.splice(start, deleteCount, ...(replacement as Message[]));
+	}
+
+	/**
+	 * Replace a single message at an index.
+	 */
+	replace(index: number, message: Message): void {
+		if (index < 0 || index >= this._internal.length) {
+			throw new RangeError(
+				`[Messages] Index ${index} out of bounds (length=${this._internal.length})`,
+			);
+		}
+		const withId: Message =
+			message.id !== undefined ? message : { ...message, id: crypto.randomUUID() };
+		this._internal[index] = withId;
+		this._validateIfStrict();
+	}
+
+	/**
+	 * Set the length of the internal array (truncation).
+	 * Used for reordering during agent creation.
+	 */
+	truncate(length: number): void {
+		if (length < 0) {
+			throw new RangeError(`[Messages] Cannot truncate to negative length`);
+		}
+		this._internal.length = length;
+		this._validateIfStrict();
+	}
+
+	/**
+	 * Direct push without validation — used only by the internal
+	 * reorder step during agent creation where system messages are
+	 * moved to front. Caller MUST call validate() afterward.
+	 */
+	_unsafePush(...messages: Message[]): void {
+		this._internal.push(...messages);
+	}
+
+	/**
+	 * Set length without validation — used only during agent creation reorder.
+	 */
+	_unsafeSetLength(length: number): void {
+		this._internal.length = length;
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Batch mode                                                        */
+	/* ---------------------------------------------------------------- */
+
+	/**
+	 * Begin a batch — validation is deferred until `commit()`.
+	 * Batches can nest; validation runs when the outermost batch commits.
+	 */
+	batch(): void {
+		this._batchDepth++;
+	}
+
+	/**
+	 * End a batch and validate. Throws if invariants are violated.
+	 * On failure the messages are left as-is (caller must fix or rollback).
+	 */
+	commit(): void {
+		if (this._batchDepth <= 0) {
+			throw new Error("[Messages] commit() called without matching batch()");
+		}
+		this._batchDepth--;
+		if (this._batchDepth === 0) {
+			this._validate();
+		}
+	}
+
+	/**
+	 * Perform a batch operation with automatic commit.
+	 * If the function throws, the batch is still ended (but not validated).
+	 */
+	transaction(fn: () => void): void {
+		this.batch();
+		try {
+			fn();
+			this.commit();
+		} catch (err) {
+			this._batchDepth = Math.max(0, this._batchDepth - 1);
+			throw err;
+		}
+	}
+
+	/* ---------------------------------------------------------------- */
+	/* Validation                                                        */
+	/* ---------------------------------------------------------------- */
+
+	/**
+	 * Explicitly validate the current state. Returns errors or throws.
+	 */
+	validate(): ValidationError[] {
+		return validateMessages(this._internal);
+	}
+
+	/**
+	 * Validate and throw if invalid.
+	 */
+	assertValid(): void {
+		const errors = this.validate();
+		if (errors.length > 0) {
+			const details = errors
+				.slice(0, 5)
+				.map((e) => `  [${e.index}] ${e.message}`)
+				.join("\n");
+			const suffix =
+				errors.length > 5 ? `\n  ... and ${errors.length - 5} more` : "";
+			throw new Error(
+				`[Messages] Invalid message sequence (${errors.length} error(s)):\n${details}${suffix}`,
+			);
+		}
+	}
+
+	private _validateIfStrict(): void {
+		if (this._batchDepth > 0) return;
+		this._validate();
+	}
+
+	private _validate(): void {
+		const errors = validateMessages(this._internal);
+		if (errors.length > 0) {
+			const details = errors
+				.slice(0, 5)
+				.map((e) => `  [${e.index}] ${e.message}`)
+				.join("\n");
+			const suffix =
+				errors.length > 5 ? `\n  ... and ${errors.length - 5} more` : "";
+			throw new Error(
+				`[Messages] Invalid message sequence (${errors.length} error(s)):\n${details}${suffix}`,
+			);
+		}
+	}
+}

package/src/model.ts

@@ -0,0 +1,43 @@
+/**
+ * Model — a callable model instance registered by a provider extension.
+ *
+ * The extension pre-binds connection config (baseUrl, apiKey, protocol logic)
+ * into the `stream` method. The loop just calls `model.stream(req)`.
+ *
+ * Provider packages own the wire translation (SDK shapes ↔ API-specific JSON).
+ * The SDK only defines the interface — it never imports protocol-specific code.
+ */
+
+import type { StreamPart } from "./provider";
+import type { ModelRequest } from "./provider";
+
+export type ThinkingLevel = "off" | "min" | "low" | "med" | "high" | "max";
+
+export interface Model {
+	/** Model identifier within the provider extension, e.g. 'gpt-4.1'. */
+	readonly id: string;
+	/** Display name for UIs. */
+	readonly name?: string;
+	/** Maximum context window in tokens. */
+	readonly contextWindow?: number;
+	/** Maximum output tokens per response. */
+	readonly maxTokens?: number;
+	/** Whether this model supports extended thinking / chain-of-thought. */
+	readonly reasoning?: boolean;
+	/** Available thinking levels for this model. Empty or undefined means no thinking support. */
+	readonly thinkingLevels?: ReadonlyArray<ThinkingLevel>;
+	/** Supported input modalities. */
+	readonly input?: ReadonlyArray<"text" | "image">;
+
+	/**
+	 * Stream a completion. The provider extension pre-binds auth, baseUrl, and
+	 * protocol translation into this method. The loop calls it directly.
+	 */
+	stream(req: ModelRequest): AsyncIterable<StreamPart>;
+
+	/**
+	 * Optional: verify the model is reachable. Throws on failure.
+	 * Provider extensions can implement this by hitting a lightweight endpoint.
+	 */
+	ping?(): Promise<void>;
+}

package/src/provider.ts

@@ -0,0 +1,187 @@
+/**
+ * Provider — the model boundary.
+ *
+ * Typed, streaming-first (ai-sdk lean). StreamPart is what the PROVIDER
+ * emits — provider-only, no synthetic parts. Every provider-level span
+ * has a start/stop pair so tracers can build spans from the stream:
+ *
+ *   response-start       ── begins a provider call
+ *     message-start      ── begins the assistant message
+ *       text-delta
+ *       reasoning-delta
+ *       tool-call-delta
+ *       tool-call
+ *     message-stop
+ *     finish             ── terminal accounting for this response
+ *   response-stop        ── ends a provider call
+ *
+ *   raw-chunk            ── opaque wire payload (optional)
+ *   error, abort         ── control
+ *
+ * Loop-level lifecycle (iteration boundaries, tool-execute spans) is NOT
+ * part of StreamPart. That flows through extension hooks only.
+ */
+
+import type { Message } from "./message";
+import type { AnyTool } from "./tool";
+import type { ThinkingLevel } from "./model";
+
+export type FinishReason =
+	| "stop"
+	| "length"
+	| "tool-calls"
+	| "content-filter"
+	| "error"
+	| "abort";
+
+export interface Usage {
+	readonly inputTokens: number;
+	readonly outputTokens: number;
+	readonly totalTokens?: number;
+	readonly cachedInputTokens?: number;
+	readonly cacheCreationInputTokens?: number;
+	readonly reasoningTokens?: number;
+}
+
+export type ToolChoice =
+	| "auto"
+	| "required"
+	| "none"
+	| { readonly toolName: string };
+
+export interface ModelRequest {
+	readonly messages: ReadonlyArray<Message>;
+	readonly tools?: ReadonlyArray<AnyTool>;
+	readonly toolChoice?: ToolChoice;
+	readonly temperature?: number;
+	readonly topP?: number;
+	readonly maxTokens?: number;
+	readonly stopSequences?: ReadonlyArray<string>;
+	readonly seed?: number;
+	readonly signal?: AbortSignal;
+	readonly providerOptions?: Readonly<Record<string, unknown>>;
+	/**
+	 * Enable extended thinking / chain-of-thought reasoning.
+	 * Pass a ThinkingLevel or `{ budgetTokens: N }` for explicit budget.
+	 * The provider maps levels to token budgets.
+	 */
+	readonly thinking?: ThinkingLevel | { readonly budgetTokens: number };
+	/**
+	 * Cache breakpoint hints for providers that support explicit prompt caching.
+	 * Each entry is an index into `messages` whose last content block should be
+	 * marked as a cache breakpoint. Providers that don't support explicit caching
+	 * (e.g. OpenAI, which auto-caches by prefix) ignore this field.
+	 */
+	readonly cacheBreakpoints?: ReadonlyArray<number>;
+}
+
+export interface ResponseMeta {
+	readonly id?: string;
+	readonly providerName: string;
+	readonly modelId: string;
+	readonly startedAt: number;
+	readonly endedAt?: number;
+	readonly providerMetadata?: Readonly<Record<string, unknown>>;
+}
+
+/* -------------------------- StreamPart (provider-emitted) ---------- */
+
+export type ResponseStartPart = {
+	readonly type: "response-start";
+	readonly meta: ResponseMeta;
+};
+export type ResponseStopPart = {
+	readonly type: "response-stop";
+	readonly meta: ResponseMeta;
+	readonly usage: Usage;
+	readonly finishReason: FinishReason;
+};
+export type MessageStartPart = {
+	readonly type: "message-start";
+	readonly role: "assistant";
+};
+export type MessageStopPart = {
+	readonly type: "message-stop";
+	readonly message: Message;
+};
+export type TextDeltaPart = {
+	readonly type: "text-delta";
+	readonly delta: string;
+};
+export type ReasoningDeltaPart = {
+	readonly type: "reasoning-delta";
+	readonly delta: string;
+};
+export type ToolCallDeltaPart = {
+	readonly type: "tool-call-delta";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly inputDelta: string;
+};
+export type ToolCallPart = {
+	readonly type: "tool-call";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: unknown;
+};
+export type FinishPart = {
+	readonly type: "finish";
+	readonly reason: FinishReason;
+	readonly usage: Usage;
+};
+export type RawChunkPart = {
+	readonly type: "raw-chunk";
+	readonly providerName: string;
+	readonly data: unknown;
+};
+export type ErrorPart = {
+	readonly type: "error";
+	readonly error: unknown;
+	readonly recoverable?: boolean;
+};
+export type AbortPart = { readonly type: "abort"; readonly reason?: unknown };
+
+export type StreamPart =
+	| ResponseStartPart
+	| ResponseStopPart
+	| MessageStartPart
+	| MessageStopPart
+	| TextDeltaPart
+	| ReasoningDeltaPart
+	| ToolCallDeltaPart
+	| ToolCallPart
+	| FinishPart
+	| RawChunkPart
+	| ErrorPart
+	| AbortPart;
+
+export interface ModelResponse {
+	readonly message: Message;
+	readonly usage: Usage;
+	readonly finishReason: FinishReason;
+	readonly meta: ResponseMeta;
+	readonly raw?: unknown;
+}
+
+export interface Provider {
+	readonly name: string;
+	readonly modelId: string;
+	generate(req: ModelRequest): Promise<ModelResponse>;
+	stream(req: ModelRequest): AsyncIterable<StreamPart>;
+}
+
+/**
+ * Provider namespace — identity-typed declaration helper.
+ *
+ * Use `Provider.define({...})` when implementing a custom provider to
+ * get full contextual typing. Runtime behavior: returns the argument
+ * unchanged. Note that concrete provider factories (e.g. `openai()`
+ * from `@dex-ai/openai`) are separate; this helper is only useful
+ * when authoring your own provider.
+ */
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const Provider = {
+	define<P extends Provider>(provider: P): P {
+		return provider;
+	},
+};