@dex-ai/sdk 0.1.30

package/src/index.ts

@@ -0,0 +1,113 @@
+/**
+ * @dex-ai/sdk — public barrel.
+ *
+ * Core types: Extension, Model, Tool, Message, Content, Agent.
+ * Extensions register event handlers; the loop emits events.
+ */
+
+// Messages & content
+export type {
+	Role,
+	Content,
+	ContentPayload,
+	TextContent,
+	CacheControl,
+	ImageContent,
+	FileContent,
+	ReasoningContent,
+	ToolCallContent,
+	ToolResultContent,
+	ToolOutput,
+	Message,
+	MessageType,
+} from "./message";
+
+// Schema
+export type { StandardSchemaV1, InferInput, InferOutput } from "./schema";
+export { Schema } from "./schema";
+export { resolveJsonSchema, validateToolSchemas } from "./resolve-schema";
+export type { JsonSchemaObject, ToolSchemaDiagnostic } from "./resolve-schema";
+
+// Tool
+export type {
+	ToolCall,
+	ToolResult,
+	ExecuteResult,
+	AnyTool,
+	ToolStreamPart,
+} from "./tool";
+export { Tool } from "./tool";
+
+// Provider types (StreamPart, ModelRequest, etc. — still used by Model.stream)
+export type {
+	ModelRequest,
+	ModelResponse,
+	ResponseMeta,
+	FinishReason,
+	Usage,
+	ToolChoice,
+	StreamPart,
+	ResponseStartPart,
+	ResponseStopPart,
+	MessageStartPart,
+	MessageStopPart,
+	TextDeltaPart,
+	ReasoningDeltaPart,
+	ToolCallDeltaPart,
+	ToolCallPart,
+	FinishPart,
+	RawChunkPart,
+	ErrorPart,
+	AbortPart,
+} from "./provider";
+// Provider type kept for extensions that need to wrap legacy providers
+export type { Provider } from "./provider";
+
+// Model
+export type { Model, ThinkingLevel } from "./model";
+
+// Extension
+export type {
+	ExtensionEvents,
+	MaybePromise,
+	ErrorSource,
+	Skill,
+	ConfigField,
+	ConfigSchema,
+	ProviderConfigField,
+	ProviderDescriptor,
+} from "./extension";
+export { Extension } from "./extension";
+
+// Context
+export type { AgentContext, GenerateContext } from "./context";
+
+// Messages
+export { Messages, validateMessages } from "./messages";
+export type { ValidationError } from "./messages";
+
+// Agent
+export type {
+	AgentStream,
+	AgentStreamPart,
+	LoopStreamPart,
+	CreateAgent,
+	CreateAgentOptions,
+	GenerateOptions,
+	GenerateResult,
+	GenerateStartPart,
+	GenerateFinishPart,
+	IterationStartPart,
+	IterationFinishPart,
+	ToolExecuteStartPart,
+	ToolExecuteFinishPart,
+	MessageCommittedPart,
+	ExtensionInfoPart,
+} from "./agent";
+export { Agent } from "./agent";
+
+// Tool Result Cache
+export type { ToolResultCacheConfig } from "./tool-result-cache";
+
+// Utilities
+export { formatError } from "./util";

package/src/message.ts

@@ -0,0 +1,114 @@
+/**
+ * Message & Content model.
+ *
+ * Content is a flat discriminated union aligned with ai-sdk:
+ *   text, image, file, reasoning, tool-call, tool-result.
+ *
+ * Messages carry Content[]. ToolResult (see tool.ts) uses tagged-variant
+ * output rather than Content[], because tool outputs span more shapes
+ * (rich content, structured JSON, plain text, error text, error JSON).
+ *
+ * Conversation state is kept well-typed end to end:
+ *   AgentContext.messages   : Message[]           (persistent)
+ *   GenerateContext.content : Content[]           (in-flight output)
+ *   Tool output             : ToolOutput (tagged) (see tool.ts)
+ */
+
+export type Role = "system" | "user" | "assistant" | "tool";
+
+/* ------------------------------------------------------------------ */
+/* Content — flat union (ai-sdk aligned)                              */
+/* ------------------------------------------------------------------ */
+
+export interface TextContent {
+	readonly type: "text";
+	readonly text: string;
+	/** Cache control hint for providers that support prompt caching (e.g. Anthropic). */
+	readonly cacheControl?: CacheControl | undefined;
+}
+
+/** Cache control — instructs the provider to cache content up to this point. */
+export interface CacheControl {
+	/** Cache strategy. 'ephemeral' = cache for the provider's default TTL. */
+	readonly type: "ephemeral";
+}
+
+export interface ImageContent {
+	readonly type: "image";
+	readonly image: string | Uint8Array | URL;
+	readonly mediaType?: string;
+}
+
+/** Binary file: PDF, spreadsheet, arbitrary blob. ai-sdk-aligned name. */
+export interface FileContent {
+	readonly type: "file";
+	readonly data: string | Uint8Array | URL;
+	readonly mediaType: string;
+	readonly name?: string;
+}
+
+/** Assistant chain-of-thought / reasoning trace. */
+export interface ReasoningContent {
+	readonly type: "reasoning";
+	readonly text: string;
+}
+
+/** Assistant requests a tool. */
+export interface ToolCallContent {
+	readonly type: "tool-call";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: unknown;
+}
+
+/** Tool response content part. See tool.ts for the ToolOutput variant shape. */
+export interface ToolResultContent {
+	readonly type: "tool-result";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly output: ToolOutput;
+}
+
+/* ToolOutput — tagged variant (ai-sdk v5 aligned). */
+export type ToolOutput =
+	| { readonly type: "content"; readonly value: ReadonlyArray<ContentPayload> }
+	| { readonly type: "json"; readonly value: unknown }
+	| { readonly type: "text"; readonly value: string }
+	| { readonly type: "error-text"; readonly value: string }
+	| { readonly type: "error-json"; readonly value: unknown };
+
+/** What a ToolOutput of type "content" carries. Text | Image | File only — not tool-call/tool-result. */
+export type ContentPayload = TextContent | ImageContent | FileContent;
+
+/* ------------------------------------------------------------------ */
+/* Content union & Message                                            */
+/* ------------------------------------------------------------------ */
+
+export type Content =
+	| TextContent
+	| ImageContent
+	| FileContent
+	| ReasoningContent
+	| ToolCallContent
+	| ToolResultContent;
+
+export type MessageType =
+	| "user"
+	| "assistant"
+	| "tool-result"
+	| "system"
+	| "context-session"
+	| "context-skills"
+	| "context-turn"
+	| "info";
+
+export interface Message {
+	readonly role: Role;
+	readonly content: ReadonlyArray<Content>;
+	/** Semantic type — controls persistence, display, and LLM routing. Defaults to role. */
+	readonly type?: MessageType;
+	readonly name?: string;
+	readonly id?: string;
+	/** Identifies the generate() call that produced this message. All messages committed during a single generate() share the same generateId. */
+	readonly generateId?: string;
+}

package/src/messages.test.ts

@@ -0,0 +1,299 @@
+import { describe, it, expect } from "bun:test";
+import { Messages, validateMessages } from "./messages";
+import type { Message } from "./message";
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                              */
+/* ------------------------------------------------------------------ */
+
+function systemMsg(text = "system"): Message {
+	return { role: "system", content: [{ type: "text", text }], id: "sys-1" };
+}
+
+function userMsg(text = "hello"): Message {
+	return { role: "user", content: [{ type: "text", text }], id: "user-1" };
+}
+
+function assistantMsg(text = "hi"): Message {
+	return { role: "assistant", content: [{ type: "text", text }], id: "asst-1" };
+}
+
+function assistantWithToolCall(
+	toolCallId = "tc-1",
+	toolName = "my_tool",
+): Message {
+	return {
+		role: "assistant",
+		content: [
+			{ type: "tool-call", toolCallId, toolName, input: {} },
+		],
+		id: "asst-tc-1",
+	};
+}
+
+function toolResultMsg(
+	toolCallId = "tc-1",
+	toolName = "my_tool",
+): Message {
+	return {
+		role: "tool",
+		content: [
+			{
+				type: "tool-result",
+				toolCallId,
+				toolName,
+				output: { type: "text", value: "done" },
+			},
+		],
+		id: "tool-1",
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* validateMessages                                                     */
+/* ------------------------------------------------------------------ */
+
+describe("validateMessages", () => {
+	it("accepts empty array", () => {
+		expect(validateMessages([])).toEqual([]);
+	});
+
+	it("accepts valid system → user → assistant sequence", () => {
+		const msgs = [systemMsg(), userMsg(), assistantMsg()];
+		expect(validateMessages(msgs)).toEqual([]);
+	});
+
+	it("accepts valid tool-call → tool-result pairing", () => {
+		const msgs = [
+			systemMsg(),
+			userMsg(),
+			assistantWithToolCall("tc-1"),
+			toolResultMsg("tc-1"),
+		];
+		expect(validateMessages(msgs)).toEqual([]);
+	});
+
+	it("rejects system message after non-system", () => {
+		const msgs = [userMsg(), systemMsg()];
+		const errors = validateMessages(msgs);
+		expect(errors.length).toBeGreaterThan(0);
+		expect(errors.some((e) => e.message.includes("System message"))).toBe(
+			true,
+		);
+	});
+
+	it("rejects first non-system message being assistant", () => {
+		const msgs = [systemMsg(), assistantMsg()];
+		const errors = validateMessages(msgs);
+		expect(errors.some((e) => e.message.includes('must be "user"'))).toBe(
+			true,
+		);
+	});
+
+	it("rejects orphaned tool-call without tool-result", () => {
+		const msgs = [
+			systemMsg(),
+			userMsg(),
+			assistantWithToolCall("tc-1"),
+			// no tool-result
+			userMsg(),
+		];
+		const errors = validateMessages(msgs);
+		expect(
+			errors.some((e) => e.message.includes("Orphaned tool-call")),
+		).toBe(true);
+	});
+
+	it("rejects orphaned tool-result without tool-call", () => {
+		const msgs = [systemMsg(), userMsg(), assistantMsg(), toolResultMsg("tc-orphan")];
+		const errors = validateMessages(msgs);
+		expect(
+			errors.some((e) => e.message.includes("Orphaned tool-result")),
+		).toBe(true);
+	});
+
+	it("rejects user following user", () => {
+		const msgs: Message[] = [
+			{ role: "user", content: [{ type: "text", text: "a" }], id: "u1" },
+			{ role: "user", content: [{ type: "text", text: "b" }], id: "u2" },
+		];
+		const errors = validateMessages(msgs);
+		expect(
+			errors.some((e) => e.message.includes('"user" message follows "user"')),
+		).toBe(true);
+	});
+
+	it("rejects assistant following assistant", () => {
+		const msgs: Message[] = [
+			userMsg(),
+			{ role: "assistant", content: [{ type: "text", text: "a" }], id: "a1" },
+			{ role: "assistant", content: [{ type: "text", text: "b" }], id: "a2" },
+		];
+		const errors = validateMessages(msgs);
+		expect(errors.length).toBeGreaterThan(0);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Messages class — Proxy trapping                                     */
+/* ------------------------------------------------------------------ */
+
+describe("Messages proxy", () => {
+	it("blocks direct .push()", () => {
+		const msgs = new Messages();
+		// Start with valid state to test proxy blocking
+		msgs.append(userMsg());
+		const arr = msgs.array as any;
+		expect(() => arr.push(assistantMsg())).toThrow("Direct .push()");
+	});
+
+	it("blocks direct .splice()", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		const arr = msgs.array as any;
+		expect(() => arr.splice(0, 1)).toThrow("Direct .splice()");
+	});
+
+	it("blocks index assignment", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		const arr = msgs.array as any;
+		expect(() => {
+			arr[0] = assistantMsg();
+		}).toThrow("Direct index assignment");
+	});
+
+	it("blocks length assignment", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		const arr = msgs.array as any;
+		expect(() => {
+			arr.length = 0;
+		}).toThrow("Direct array mutation");
+	});
+
+	it("allows read operations (indexing, iteration, length)", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+		const arr = msgs.array;
+		expect(arr.length).toBe(2);
+		expect(arr[0]!.role).toBe("user");
+		expect([...arr].length).toBe(2);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Messages class — controlled mutations                               */
+/* ------------------------------------------------------------------ */
+
+describe("Messages.append", () => {
+	it("appends a valid message", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		expect(msgs.length).toBe(1);
+		expect(msgs.array[0]!.role).toBe("user");
+	});
+
+	it("assigns ID if missing", () => {
+		const msgs = new Messages();
+		const noId: Message = { role: "user", content: [{ type: "text", text: "hi" }] };
+		msgs.append(noId);
+		expect(msgs.array[0]!.id).toBeDefined();
+	});
+
+	it("throws on invalid append (e.g. tool after user)", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		expect(() =>
+			msgs.append(toolResultMsg("tc-1")),
+		).toThrow("Invalid message sequence");
+	});
+});
+
+describe("Messages.splice", () => {
+	it("removes and inserts messages with validation", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+		// Replace assistant with a new one
+		const removed = msgs.splice(1, 1, {
+			role: "assistant",
+			content: [{ type: "text", text: "replaced" }],
+			id: "a-new",
+		});
+		expect(removed.length).toBe(1);
+		expect(msgs.array[1]!.content[0]!.type).toBe("text");
+	});
+
+	it("throws if splice leaves invalid state", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+		// Remove the user message → assistant is first non-system = invalid
+		expect(() => msgs.splice(0, 1)).toThrow("Invalid message sequence");
+	});
+});
+
+describe("Messages.batch", () => {
+	it("defers validation during batch", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+
+		msgs.batch();
+		// This would be invalid mid-way but we're batching
+		msgs.splice(0, 2); // empty — no first-user check since empty is valid
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+		msgs.commit(); // should not throw
+		expect(msgs.length).toBe(2);
+	});
+
+	it("throws on commit if batch leaves invalid state", () => {
+		const msgs = new Messages();
+		msgs.batch();
+		msgs.append(assistantMsg()); // invalid: first non-system must be user
+		expect(() => msgs.commit()).toThrow("Invalid message sequence");
+	});
+
+	it("transaction auto-commits on success", () => {
+		const msgs = new Messages();
+		msgs.transaction(() => {
+			msgs.append(userMsg());
+			msgs.append(assistantMsg());
+		});
+		expect(msgs.length).toBe(2);
+	});
+
+	it("transaction does not validate on throw", () => {
+		const msgs = new Messages();
+		expect(() =>
+			msgs.transaction(() => {
+				msgs.append(userMsg());
+				throw new Error("bail");
+			}),
+		).toThrow("bail");
+		// Messages still contains the user msg (no rollback, but no validation either)
+		expect(msgs.length).toBe(1);
+	});
+});
+
+describe("Messages.replace", () => {
+	it("replaces a message at index", () => {
+		const msgs = new Messages();
+		msgs.append(userMsg());
+		msgs.append(assistantMsg());
+		msgs.replace(1, {
+			role: "assistant",
+			content: [{ type: "text", text: "new" }],
+			id: "a-replaced",
+		});
+		expect((msgs.array[1]!.content[0] as any).text).toBe("new");
+	});
+
+	it("throws on out-of-bounds index", () => {
+		const msgs = new Messages();
+		expect(() => msgs.replace(0, userMsg())).toThrow("out of bounds");
+	});
+});