@firtoz/chat-agent 1.0.0

package/src/chat-messages.ts

@@ -0,0 +1,472 @@
+import { z } from "zod";
+
+// ============================================================================
+// Tool Definitions (for sending to OpenRouter)
+// ============================================================================
+
+/**
+ * JSON Schema for tool parameters (subset of JSON Schema 7)
+ */
+export const JSONSchemaSchema = z.record(z.string(), z.unknown());
+
+export type JSONSchema = z.infer<typeof JSONSchemaSchema>;
+
+/**
+ * Tool definition following OpenAI/OpenRouter format
+ * The schema is for wire format (no execute function)
+ */
+export const ToolDefinitionSchema = z.object({
+	type: z.literal("function"),
+	function: z.object({
+		name: z.string(),
+		description: z.string().optional(),
+		parameters: JSONSchemaSchema.optional(),
+		strict: z.boolean().optional(),
+	}),
+});
+
+/**
+ * Execute function signature for server-side tools
+ * Takes parsed arguments, returns JSON-serializable result
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Tool execute functions need flexible typing
+export type ToolExecuteFunction = (args: any) => unknown | Promise<unknown>;
+
+/**
+ * Tool definition with optional execute function for server-side execution
+ * - If `execute` is provided: server runs it automatically and continues
+ * - If `execute` is omitted: tool call is sent to client for execution
+ */
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema> & {
+	/** Optional server-side execute function. If omitted, tool call goes to client. */
+	execute?: ToolExecuteFunction;
+};
+
+// ============================================================================
+// Tool Calls (from AI responses)
+// ============================================================================
+
+/**
+ * A tool call from the AI (complete, after streaming)
+ */
+export const ToolCallSchema = z.object({
+	id: z.string(),
+	type: z.literal("function"),
+	function: z.object({
+		name: z.string(),
+		arguments: z.string(), // JSON string
+	}),
+});
+
+export type ToolCall = z.infer<typeof ToolCallSchema>;
+
+/**
+ * Tool call delta during streaming
+ */
+export const ToolCallDeltaSchema = z.object({
+	index: z.number(),
+	id: z.string().optional(),
+	type: z.literal("function").optional(),
+	function: z
+		.object({
+			name: z.string().optional(),
+			arguments: z.string().optional(),
+		})
+		.optional(),
+});
+
+export type ToolCallDelta = z.infer<typeof ToolCallDeltaSchema>;
+
+// ============================================================================
+// Tool Results (from client execution)
+// ============================================================================
+
+/**
+ * Tool result from client-side execution
+ */
+export const ToolResultSchema = z.object({
+	toolCallId: z.string(),
+	output: z.unknown(), // Can be any JSON-serializable value
+});
+
+export type ToolResult = z.infer<typeof ToolResultSchema>;
+
+// ============================================================================
+// Chat Message Schema (supports text + tool calls)
+// ============================================================================
+
+/**
+ * User message
+ */
+export const UserMessageSchema = z.object({
+	id: z.string(),
+	role: z.literal("user"),
+	content: z.string(),
+	createdAt: z.number(),
+});
+
+export type UserMessage = z.infer<typeof UserMessageSchema>;
+
+/**
+ * Assistant message - can have content, tool calls, or both
+ */
+export const AssistantMessageSchema = z.object({
+	id: z.string(),
+	role: z.literal("assistant"),
+	content: z.string().nullable(), // null when only tool calls
+	toolCalls: z.array(ToolCallSchema).optional(),
+	createdAt: z.number(),
+});
+
+export type AssistantMessage = z.infer<typeof AssistantMessageSchema>;
+
+/**
+ * Tool response message (sent back to AI after tool execution)
+ */
+export const ToolMessageSchema = z.object({
+	id: z.string(),
+	role: z.literal("tool"),
+	toolCallId: z.string(),
+	content: z.string(), // JSON stringified result
+	createdAt: z.number(),
+});
+
+export type ToolMessage = z.infer<typeof ToolMessageSchema>;
+
+/**
+ * Union of all chat message types
+ */
+export const ChatMessageSchema = z.discriminatedUnion("role", [
+	UserMessageSchema,
+	AssistantMessageSchema,
+	ToolMessageSchema,
+]);
+
+export type ChatMessage = z.infer<typeof ChatMessageSchema>;
+
+// ============================================================================
+// Token Usage Schema
+// ============================================================================
+
+export const TokenUsageSchema = z.object({
+	prompt_tokens: z.number(),
+	completion_tokens: z.number(),
+	total_tokens: z.number(),
+});
+
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+
+// ============================================================================
+// Client → Server Messages (Discriminated Union)
+// ============================================================================
+
+export const ClientMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("sendMessage"),
+		content: z.string(),
+	}),
+	z.object({
+		type: z.literal("clearHistory"),
+	}),
+	z.object({
+		type: z.literal("getHistory"),
+	}),
+	z.object({
+		type: z.literal("resumeStream"),
+		streamId: z.string(),
+	}),
+	z.object({
+		type: z.literal("cancelRequest"),
+		id: z.string(),
+	}),
+	// Tool result from client-side tool execution
+	z.object({
+		type: z.literal("toolResult"),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		output: z.unknown(),
+		// If true, server should continue the conversation after tool result
+		autoContinue: z.boolean().optional(),
+	}),
+	// Register client-defined tools at runtime
+	z.object({
+		type: z.literal("registerTools"),
+		tools: z.array(
+			z.object({
+				name: z.string(),
+				description: z.string().optional(),
+				parameters: JSONSchemaSchema.optional(),
+			}),
+		),
+	}),
+]);
+
+export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+
+// Individual message types for convenience
+export type SendMessagePayload = Extract<
+	ClientMessage,
+	{ type: "sendMessage" }
+>;
+export type ClearHistoryPayload = Extract<
+	ClientMessage,
+	{ type: "clearHistory" }
+>;
+export type GetHistoryPayload = Extract<ClientMessage, { type: "getHistory" }>;
+export type ResumeStreamPayload = Extract<
+	ClientMessage,
+	{ type: "resumeStream" }
+>;
+export type CancelRequestPayload = Extract<
+	ClientMessage,
+	{ type: "cancelRequest" }
+>;
+export type ToolResultPayload = Extract<ClientMessage, { type: "toolResult" }>;
+export type RegisterToolsPayload = Extract<
+	ClientMessage,
+	{ type: "registerTools" }
+>;
+
+// ============================================================================
+// Server → Client Messages (Discriminated Union)
+// ============================================================================
+
+export const ServerMessageSchema = z.discriminatedUnion("type", [
+	// Full message history
+	z.object({
+		type: z.literal("history"),
+		messages: z.array(ChatMessageSchema),
+	}),
+	// Stream start
+	z.object({
+		type: z.literal("messageStart"),
+		id: z.string(),
+		streamId: z.string(),
+	}),
+	// Text content chunk
+	z.object({
+		type: z.literal("messageChunk"),
+		id: z.string(),
+		chunk: z.string(),
+	}),
+	// Tool call streaming delta
+	z.object({
+		type: z.literal("toolCallDelta"),
+		id: z.string(),
+		delta: ToolCallDeltaSchema,
+	}),
+	// Tool call complete (full tool call ready for execution)
+	z.object({
+		type: z.literal("toolCall"),
+		id: z.string(), // message id
+		toolCall: ToolCallSchema,
+	}),
+	// Stream end
+	z.object({
+		type: z.literal("messageEnd"),
+		id: z.string(),
+		// Final message state (with tool calls if any)
+		toolCalls: z.array(ToolCallSchema).optional(),
+		createdAt: z.number(),
+		usage: TokenUsageSchema.optional(),
+	}),
+	// Stream resumption
+	z.object({
+		type: z.literal("streamResume"),
+		streamId: z.string(),
+		chunks: z.array(z.string()),
+		done: z.boolean(),
+	}),
+	z.object({
+		type: z.literal("streamResuming"),
+		id: z.string(),
+		streamId: z.string(),
+	}),
+	// Message updated (e.g., tool result applied)
+	z.object({
+		type: z.literal("messageUpdated"),
+		message: ChatMessageSchema,
+	}),
+	// General error
+	z.object({
+		type: z.literal("error"),
+		message: z.string(),
+	}),
+	// Tool input error (arguments validation failed)
+	z.object({
+		type: z.literal("toolError"),
+		errorType: z.enum(["input", "output", "not_found"]),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		message: z.string(),
+	}),
+]);
+
+export type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+// Individual message types for convenience
+export type HistoryMessage = Extract<ServerMessage, { type: "history" }>;
+export type MessageStartMessage = Extract<
+	ServerMessage,
+	{ type: "messageStart" }
+>;
+export type MessageChunkMessage = Extract<
+	ServerMessage,
+	{ type: "messageChunk" }
+>;
+export type ToolCallDeltaMessage = Extract<
+	ServerMessage,
+	{ type: "toolCallDelta" }
+>;
+export type ToolCallMessage = Extract<ServerMessage, { type: "toolCall" }>;
+export type MessageEndMessage = Extract<ServerMessage, { type: "messageEnd" }>;
+export type StreamResumeMessage = Extract<
+	ServerMessage,
+	{ type: "streamResume" }
+>;
+export type StreamResumingMessage = Extract<
+	ServerMessage,
+	{ type: "streamResuming" }
+>;
+export type MessageUpdatedMessage = Extract<
+	ServerMessage,
+	{ type: "messageUpdated" }
+>;
+export type ErrorMessage = Extract<ServerMessage, { type: "error" }>;
+export type ToolErrorMessage = Extract<ServerMessage, { type: "toolError" }>;
+
+// ============================================================================
+// Parsing Helpers
+// ============================================================================
+
+/**
+ * Parse and validate a client message from JSON string
+ * @throws ZodError if validation fails
+ */
+export function parseClientMessage(json: string): ClientMessage {
+	const data = JSON.parse(json);
+	return ClientMessageSchema.parse(data);
+}
+
+/**
+ * Safely parse a client message, returning null on failure
+ */
+export function safeParseClientMessage(json: string): ClientMessage | null {
+	try {
+		const data = JSON.parse(json);
+		const result = ClientMessageSchema.safeParse(data);
+		return result.success ? result.data : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Parse and validate a server message from JSON string
+ * @throws ZodError if validation fails
+ */
+export function parseServerMessage(json: string): ServerMessage {
+	const data = JSON.parse(json);
+	return ServerMessageSchema.parse(data);
+}
+
+/**
+ * Safely parse a server message, returning null on failure
+ */
+export function safeParseServerMessage(json: string): ServerMessage | null {
+	try {
+		const data = JSON.parse(json);
+		const result = ServerMessageSchema.safeParse(data);
+		return result.success ? result.data : null;
+	} catch {
+		return null;
+	}
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isClientMessage(data: unknown): data is ClientMessage {
+	return ClientMessageSchema.safeParse(data).success;
+}
+
+export function isServerMessage(data: unknown): data is ServerMessage {
+	return ServerMessageSchema.safeParse(data).success;
+}
+
+export function isUserMessage(msg: ChatMessage): msg is UserMessage {
+	return msg.role === "user";
+}
+
+export function isAssistantMessage(msg: ChatMessage): msg is AssistantMessage {
+	return msg.role === "assistant";
+}
+
+export function isToolMessage(msg: ChatMessage): msg is ToolMessage {
+	return msg.role === "tool";
+}
+
+export function hasToolCalls(msg: AssistantMessage): boolean {
+	return !!msg.toolCalls && msg.toolCalls.length > 0;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Parse tool call arguments from JSON string
+ */
+export function parseToolArguments<T = unknown>(toolCall: ToolCall): T {
+	return JSON.parse(toolCall.function.arguments) as T;
+}
+
+/**
+ * Create a tool definition helper
+ *
+ * @example Server-side tool (executes automatically on server)
+ * ```ts
+ * defineTool({
+ *   name: "get_weather",
+ *   description: "Get current weather",
+ *   parameters: { type: "object", properties: { location: { type: "string" } } },
+ *   execute: async (args) => {
+ *     const weather = await fetchWeather(args.location);
+ *     return { temp: weather.temp, conditions: weather.desc };
+ *   }
+ * })
+ * ```
+ *
+ * @example Client-side tool (sent to client for execution)
+ * ```ts
+ * defineTool({
+ *   name: "get_user_location",
+ *   description: "Get user's current location",
+ *   parameters: { type: "object", properties: {} },
+ *   // No execute function - client handles this
+ * })
+ * ```
+ */
+export function defineTool(config: {
+	name: string;
+	description?: string;
+	parameters?: JSONSchema;
+	strict?: boolean;
+	/** Server-side execute function. If omitted, tool call goes to client. */
+	execute?: ToolExecuteFunction;
+}): ToolDefinition {
+	const tool: ToolDefinition = {
+		type: "function",
+		function: {
+			name: config.name,
+			description: config.description,
+			parameters: config.parameters,
+			strict: config.strict,
+		},
+	};
+	if (config.execute) {
+		tool.execute = config.execute;
+	}
+	return tool;
+}

package/src/db/index.ts

@@ -0,0 +1,21 @@
+import {
+	type DrizzleSqliteDODatabase,
+	drizzle,
+} from "drizzle-orm/durable-sqlite";
+import * as schema from "./schema";
+
+export * from "./schema";
+
+/**
+ * Creates a Drizzle instance for Durable Object SQLite storage
+ * Uses the native drizzle-orm/durable-sqlite driver
+ *
+ * @see https://orm.drizzle.team/docs/connect-cloudflare-do
+ */
+export function createDb(
+	storage: DurableObjectStorage,
+): DrizzleSqliteDODatabase<typeof schema> {
+	return drizzle(storage, { schema, logger: false });
+}
+
+export type Database = DrizzleSqliteDODatabase<typeof schema>;

package/src/db/schema.ts

@@ -0,0 +1,47 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+/**
+ * Chat messages table
+ * Stores the full conversation history for each agent session
+ * Messages are stored as JSON to support complex structures (tool calls, etc.)
+ */
+export const messagesTable = sqliteTable("messages", {
+	id: text("id").primaryKey(),
+	role: text("role", { enum: ["user", "assistant", "tool"] }).notNull(),
+	// JSON-serialized message data (content, toolCalls, toolCallId, etc.)
+	messageJson: text("message_json").notNull(),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
+});
+
+/**
+ * Stream chunks table for resumable streaming
+ * Buffers streamed content so clients can resume mid-stream
+ */
+export const streamChunksTable = sqliteTable("stream_chunks", {
+	id: text("id").primaryKey(),
+	streamId: text("stream_id").notNull(),
+	content: text("content").notNull(),
+	chunkIndex: integer("chunk_index").notNull(),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
+});
+
+/**
+ * Stream metadata table for tracking active/completed streams
+ */
+export const streamMetadataTable = sqliteTable("stream_metadata", {
+	id: text("id").primaryKey(),
+	messageId: text("message_id").notNull(), // The assistant message being streamed
+	status: text("status", {
+		enum: ["streaming", "completed", "error"],
+	}).notNull(),
+	createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
+	completedAt: integer("completed_at", { mode: "timestamp_ms" }),
+});
+
+// Type exports for use in the agent
+export type Message = typeof messagesTable.$inferSelect;
+export type NewMessage = typeof messagesTable.$inferInsert;
+export type StreamChunk = typeof streamChunksTable.$inferSelect;
+export type NewStreamChunk = typeof streamChunksTable.$inferInsert;
+export type StreamMeta = typeof streamMetadataTable.$inferSelect;
+export type NewStreamMeta = typeof streamMetadataTable.$inferInsert;

package/src/index.ts

@@ -0,0 +1,99 @@
+/**
+ * @firtoz/chat-agent - ChatAgent for Cloudflare Durable Objects with OpenRouter
+ *
+ * A simplified alternative to @cloudflare/ai-chat's AIChatAgent that uses OpenRouter
+ * directly instead of Vercel AI SDK.
+ *
+ * @example
+ * ```typescript
+ * import { ChatAgent, defineTool, type ToolDefinition } from "@firtoz/chat-agent";
+ *
+ * class MyAgent extends ChatAgent {
+ *   protected override getSystemPrompt(): string {
+ *     return "You are a helpful assistant.";
+ *   }
+ *
+ *   protected override getModel(): string {
+ *     return "anthropic/claude-sonnet-4.5";
+ *   }
+ *
+ *   protected override getTools(): ToolDefinition[] {
+ *     return [
+ *       defineTool({
+ *         name: "get_time",
+ *         description: "Get current time",
+ *         parameters: { type: "object", properties: {} },
+ *         execute: async () => ({ time: new Date().toISOString() })
+ *       })
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+
+// Export the abstract base class
+export { ChatAgentBase } from "./chat-agent-base";
+
+// Export concrete implementations
+export { DrizzleChatAgent } from "./chat-agent-drizzle";
+export { SqlChatAgent } from "./chat-agent-sql";
+
+// Alias DrizzleChatAgent as ChatAgent for convenience (Drizzle is recommended)
+export { DrizzleChatAgent as ChatAgent } from "./chat-agent-drizzle";
+
+// Re-export all types and utilities from chat-messages
+export type {
+	// Message types
+	AssistantMessage,
+	ChatMessage,
+	UserMessage,
+	ToolMessage,
+	// Tool types
+	ToolCall,
+	ToolCallDelta,
+	ToolDefinition,
+	ToolResult,
+	JSONSchema,
+	// Client/Server message types
+	ClientMessage,
+	ServerMessage,
+	SendMessagePayload,
+	ClearHistoryPayload,
+	GetHistoryPayload,
+	ResumeStreamPayload,
+	CancelRequestPayload,
+	ToolResultPayload,
+	RegisterToolsPayload,
+	HistoryMessage,
+	MessageStartMessage,
+	MessageChunkMessage,
+	ToolCallDeltaMessage,
+	ToolCallMessage,
+	MessageEndMessage,
+	StreamResumeMessage,
+	StreamResumingMessage,
+	MessageUpdatedMessage,
+	ErrorMessage,
+	ToolErrorMessage,
+	// Usage types
+	TokenUsage,
+} from "./chat-messages";
+
+export {
+	// Tool definition helper
+	defineTool,
+	// Parsing helpers
+	parseClientMessage,
+	safeParseClientMessage,
+	parseServerMessage,
+	safeParseServerMessage,
+	// Type guards
+	isClientMessage,
+	isServerMessage,
+	isUserMessage,
+	isAssistantMessage,
+	isToolMessage,
+	hasToolCalls,
+	// Helper functions
+	parseToolArguments,
+} from "./chat-messages";