@firtoz/chat-agent 1.0.0 → 2.0.0

package/src/chat-messages.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod/v4";
 
 // ============================================================================
 // Tool Definitions (for sending to OpenRouter)
@@ -37,9 +37,18 @@ export type ToolExecuteFunction = (args: any) => unknown | Promise<unknown>;
  * - If `execute` is provided: server runs it automatically and continues
  * - If `execute` is omitted: tool call is sent to client for execution
  */
+export type ToolNeedsApprovalFn = (
+	args: Record<string, unknown>,
+) => boolean | Promise<boolean>;
+
 export type ToolDefinition = z.infer<typeof ToolDefinitionSchema> & {
 	/** Optional server-side execute function. If omitted, tool call goes to client. */
 	execute?: ToolExecuteFunction;
+	/**
+	 * When `execute` is set, if this returns true the server waits for a client
+	 * `toolApprovalResponse` before running `execute` (human-in-the-loop).
+	 */
+	needsApproval?: ToolNeedsApprovalFn;
 };
 
 // ============================================================================
@@ -56,6 +65,11 @@ export const ToolCallSchema = z.object({
 		name: z.string(),
 		arguments: z.string(), // JSON string
 	}),
+	/**
+	 * Opaque provider-specific fields from the upstream stream (e.g. Gemini / Anthropic extras).
+	 * Forwarded on the wire when calling the model again after tool results.
+	 */
+	providerMetadata: z.record(z.string(), z.unknown()).optional(),
 });
 
 export type ToolCall = z.infer<typeof ToolCallSchema>;
@@ -73,6 +87,7 @@ export const ToolCallDeltaSchema = z.object({
 			arguments: z.string().optional(),
 		})
 		.optional(),
+	providerMetadata: z.record(z.string(), z.unknown()).optional(),
 });
 
 export type ToolCallDelta = z.infer<typeof ToolCallDeltaSchema>;
@@ -160,11 +175,47 @@ export type TokenUsage = z.infer<typeof TokenUsageSchema>;
 // Client → Server Messages (Discriminated Union)
 // ============================================================================
 
+export const SendMessageTriggerSchema = z.enum([
+	"submit-message",
+	"regenerate-message",
+]);
+
+export type SendMessageTrigger = z.infer<typeof SendMessageTriggerSchema>;
+
 export const ClientMessageSchema = z.discriminatedUnion("type", [
-	z.object({
-		type: z.literal("sendMessage"),
-		content: z.string(),
-	}),
+	z
+		.object({
+			type: z.literal("sendMessage"),
+			content: z.string().optional(),
+			/** Full conversation snapshot; used with `regenerate-message` or to reconcile before a new user turn */
+			messages: z.array(ChatMessageSchema).optional(),
+			trigger: SendMessageTriggerSchema.optional(),
+		})
+		.superRefine((data, ctx) => {
+			const trigger = data.trigger ?? "submit-message";
+			if (trigger === "regenerate-message") {
+				if (!data.messages || data.messages.length === 0) {
+					ctx.addIssue({
+						code: z.ZodIssueCode.custom,
+						message:
+							"sendMessage with trigger regenerate-message requires non-empty messages",
+					});
+				}
+			} else {
+				const hasContent = data.content !== undefined && data.content !== "";
+				const messagesEndWithUser =
+					!!data.messages &&
+					data.messages.length > 0 &&
+					data.messages[data.messages.length - 1].role === "user";
+				if (!hasContent && !messagesEndWithUser) {
+					ctx.addIssue({
+						code: z.ZodIssueCode.custom,
+						message:
+							"sendMessage requires non-empty content, or messages ending with a user message",
+					});
+				}
+			}
+		}),
 	z.object({
 		type: z.literal("clearHistory"),
 	}),
@@ -188,6 +239,11 @@ export const ClientMessageSchema = z.discriminatedUnion("type", [
 		// If true, server should continue the conversation after tool result
 		autoContinue: z.boolean().optional(),
 	}),
+	z.object({
+		type: z.literal("toolApprovalResponse"),
+		approvalId: z.string(),
+		approved: z.boolean(),
+	}),
 	// Register client-defined tools at runtime
 	z.object({
 		type: z.literal("registerTools"),
@@ -222,6 +278,10 @@ export type CancelRequestPayload = Extract<
 	{ type: "cancelRequest" }
 >;
 export type ToolResultPayload = Extract<ClientMessage, { type: "toolResult" }>;
+export type ToolApprovalResponsePayload = Extract<
+	ClientMessage,
+	{ type: "toolApprovalResponse" }
+>;
 export type RegisterToolsPayload = Extract<
 	ClientMessage,
 	{ type: "registerTools" }
@@ -300,6 +360,13 @@ export const ServerMessageSchema = z.discriminatedUnion("type", [
 		toolName: z.string(),
 		message: z.string(),
 	}),
+	z.object({
+		type: z.literal("toolApprovalRequest"),
+		approvalId: z.string(),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		arguments: z.string(),
+	}),
 ]);
 
 export type ServerMessage = z.infer<typeof ServerMessageSchema>;
@@ -334,6 +401,10 @@ export type MessageUpdatedMessage = Extract<
 >;
 export type ErrorMessage = Extract<ServerMessage, { type: "error" }>;
 export type ToolErrorMessage = Extract<ServerMessage, { type: "toolError" }>;
+export type ToolApprovalRequestMessage = Extract<
+	ServerMessage,
+	{ type: "toolApprovalRequest" }
+>;
 
 // ============================================================================
 // Parsing Helpers
@@ -455,6 +526,8 @@ export function defineTool(config: {
 	strict?: boolean;
 	/** Server-side execute function. If omitted, tool call goes to client. */
 	execute?: ToolExecuteFunction;
+	/** If set with `execute`, client must approve before the server runs `execute`. */
+	needsApproval?: ToolNeedsApprovalFn;
 }): ToolDefinition {
 	const tool: ToolDefinition = {
 		type: "function",
@@ -468,5 +541,8 @@ export function defineTool(config: {
 	if (config.execute) {
 		tool.execute = config.execute;
 	}
+	if (config.needsApproval) {
+		tool.needsApproval = config.needsApproval;
+	}
 	return tool;
 }

package/src/index.ts

@@ -1,14 +1,16 @@
 /**
- * @firtoz/chat-agent - ChatAgent for Cloudflare Durable Objects with OpenRouter
+ * @firtoz/chat-agent — wire protocol, tool helpers, and abstract `ChatAgentBase`.
  *
- * A simplified alternative to @cloudflare/ai-chat's AIChatAgent that uses OpenRouter
- * directly instead of Vercel AI SDK.
+ * Install a persistence package separately:
+ * - `@firtoz/chat-agent-drizzle` — Drizzle ORM (recommended)
+ * - `@firtoz/chat-agent-sql` — raw `this.sql`
  *
  * @example
  * ```typescript
- * import { ChatAgent, defineTool, type ToolDefinition } from "@firtoz/chat-agent";
+ * import { ChatAgentBase, defineTool, type ToolDefinition } from "@firtoz/chat-agent";
+ * import { DrizzleChatAgent } from "@firtoz/chat-agent-drizzle";
  *
- * class MyAgent extends ChatAgent {
+ * class MyAgent extends DrizzleChatAgent<Env> {
  *   protected override getSystemPrompt(): string {
  *     return "You are a helpful assistant.";
  *   }
@@ -31,30 +33,18 @@
  * ```
  */
 
-// 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,
@@ -64,6 +54,10 @@ export type {
 	CancelRequestPayload,
 	ToolResultPayload,
 	RegisterToolsPayload,
+	ToolApprovalResponsePayload,
+	ToolApprovalRequestMessage,
+	SendMessageTrigger,
+	ToolNeedsApprovalFn,
 	HistoryMessage,
 	MessageStartMessage,
 	MessageChunkMessage,
@@ -75,25 +69,20 @@ export type {
 	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";

package/src/chat-agent-drizzle.ts

@@ -1,227 +0,0 @@
-import { and, asc, eq, lt } from "drizzle-orm";
-import { migrate } from "drizzle-orm/durable-sqlite/migrator";
-import { createDb, type Database } from "./db/index";
-import {
-	messagesTable,
-	type NewMessage,
-	streamChunksTable,
-	streamMetadataTable,
-} from "./db/schema";
-import type { ChatMessage } from "./chat-messages";
-import { ChatAgentBase } from "./chat-agent-base";
-import migrations from "../drizzle/migrations.js";
-
-/**
- * ChatAgent implementation using Drizzle ORM
- *
- * Uses Drizzle's type-safe query builder for database operations.
- */
-export class DrizzleChatAgent<
-	Env extends Cloudflare.Env & {
-		OPENROUTER_API_KEY: string;
-	} = Cloudflare.Env & { OPENROUTER_API_KEY: string },
-> extends ChatAgentBase<Env> {
-	private db!: Database;
-
-	// ============================================================================
-	// Database Implementation - Drizzle ORM
-	// ============================================================================
-
-	protected dbInitialize(): void {
-		// Initialize Drizzle DB
-		this.db = createDb(this.ctx.storage);
-
-		// Run migrations
-		migrate(this.db, migrations);
-	}
-
-	protected dbLoadMessages(): ChatMessage[] {
-		const rows = this.db
-			.select()
-			.from(messagesTable)
-			.orderBy(asc(messagesTable.createdAt))
-			.all();
-
-		return rows
-			.map((row) => {
-				try {
-					return JSON.parse(row.messageJson) as ChatMessage;
-				} catch (err) {
-					console.error(`Failed to parse message ${row.id}:`, err);
-					return null;
-				}
-			})
-			.filter((msg): msg is ChatMessage => msg !== null);
-	}
-
-	protected dbSaveMessage(msg: ChatMessage): void {
-		const newMsg: NewMessage = {
-			id: msg.id,
-			role: msg.role,
-			messageJson: JSON.stringify(msg),
-			createdAt: new Date(msg.createdAt),
-		};
-
-		this.db
-			.insert(messagesTable)
-			.values(newMsg)
-			.onConflictDoUpdate({
-				target: messagesTable.id,
-				set: { messageJson: newMsg.messageJson },
-			})
-			.run();
-	}
-
-	protected dbClearAll(): void {
-		this.db.delete(messagesTable).run();
-		this.db.delete(streamChunksTable).run();
-		this.db.delete(streamMetadataTable).run();
-	}
-
-	protected dbFindActiveStream(): {
-		id: string;
-		messageId: string;
-		createdAt: Date;
-	} | null {
-		const activeStreams = this.db
-			.select()
-			.from(streamMetadataTable)
-			.where(eq(streamMetadataTable.status, "streaming"))
-			.orderBy(asc(streamMetadataTable.createdAt))
-			.limit(1)
-			.all();
-
-		if (activeStreams.length === 0) {
-			return null;
-		}
-
-		const stream = activeStreams[0];
-		return {
-			id: stream.id,
-			messageId: stream.messageId,
-			createdAt: stream.createdAt,
-		};
-	}
-
-	protected dbDeleteStreamWithChunks(streamId: string): void {
-		this.db
-			.delete(streamChunksTable)
-			.where(eq(streamChunksTable.streamId, streamId))
-			.run();
-		this.db
-			.delete(streamMetadataTable)
-			.where(eq(streamMetadataTable.id, streamId))
-			.run();
-	}
-
-	protected dbInsertStreamMetadata(streamId: string, messageId: string): void {
-		this.db
-			.insert(streamMetadataTable)
-			.values({
-				id: streamId,
-				messageId,
-				status: "streaming",
-				createdAt: new Date(),
-			})
-			.run();
-	}
-
-	protected dbUpdateStreamStatus(
-		streamId: string,
-		status: "completed" | "error",
-	): void {
-		this.db
-			.update(streamMetadataTable)
-			.set({ status, completedAt: new Date() })
-			.where(eq(streamMetadataTable.id, streamId))
-			.run();
-	}
-
-	protected dbDeleteOldCompletedStreams(cutoffMs: number): void {
-		const cutoff = new Date(cutoffMs);
-
-		// Delete old stream chunks for completed streams
-		const oldStreams = this.db
-			.select({ id: streamMetadataTable.id })
-			.from(streamMetadataTable)
-			.where(
-				and(
-					eq(streamMetadataTable.status, "completed"),
-					lt(streamMetadataTable.completedAt, cutoff),
-				),
-			)
-			.all();
-
-		for (const stream of oldStreams) {
-			this.db
-				.delete(streamChunksTable)
-				.where(eq(streamChunksTable.streamId, stream.id))
-				.run();
-		}
-
-		// Delete old stream metadata
-		this.db
-			.delete(streamMetadataTable)
-			.where(
-				and(
-					eq(streamMetadataTable.status, "completed"),
-					lt(streamMetadataTable.completedAt, cutoff),
-				),
-			)
-			.run();
-	}
-
-	protected dbFindMaxChunkIndex(streamId: string): number | null {
-		const lastChunk = this.db
-			.select({ maxIndex: streamChunksTable.chunkIndex })
-			.from(streamChunksTable)
-			.where(eq(streamChunksTable.streamId, streamId))
-			.orderBy(asc(streamChunksTable.chunkIndex))
-			.limit(1)
-			.all();
-
-		const firstChunk = lastChunk[0];
-		return firstChunk?.maxIndex != null ? firstChunk.maxIndex : null;
-	}
-
-	protected dbInsertChunks(
-		chunks: Array<{
-			id: string;
-			streamId: string;
-			content: string;
-			chunkIndex: number;
-		}>,
-	): void {
-		const now = new Date();
-		for (const chunk of chunks) {
-			this.db
-				.insert(streamChunksTable)
-				.values({
-					id: chunk.id,
-					streamId: chunk.streamId,
-					content: chunk.content,
-					chunkIndex: chunk.chunkIndex,
-					createdAt: now,
-				})
-				.run();
-		}
-	}
-
-	protected dbGetChunks(streamId: string): string[] {
-		const rows = this.db
-			.select()
-			.from(streamChunksTable)
-			.where(eq(streamChunksTable.streamId, streamId))
-			.orderBy(asc(streamChunksTable.chunkIndex))
-			.all();
-
-		return rows.map((r) => r.content);
-	}
-
-	protected dbDeleteChunks(streamId: string): void {
-		this.db
-			.delete(streamChunksTable)
-			.where(eq(streamChunksTable.streamId, streamId))
-			.run();
-	}
-}

package/src/chat-agent-sql.ts

@@ -1,199 +0,0 @@
-import type { ChatMessage } from "./chat-messages";
-import { ChatAgentBase } from "./chat-agent-base";
-
-/**
- * ChatAgent implementation using raw SQL (like @cloudflare/ai-chat)
- *
- * Uses Agent's built-in `this.sql` template tag for database operations.
- */
-export class SqlChatAgent<
-	Env extends Cloudflare.Env & {
-		OPENROUTER_API_KEY: string;
-	} = Cloudflare.Env & { OPENROUTER_API_KEY: string },
-> extends ChatAgentBase<Env> {
-	// ============================================================================
-	// Database Implementation - Raw SQL
-	// ============================================================================
-
-	protected dbInitialize(): void {
-		// Create tables for chat messages and resumable streaming
-		// Based on @cloudflare/ai-chat pattern from reference
-		this.sql`create table if not exists cf_ai_chat_agent_messages (
-			id text primary key,
-			message text not null,
-			created_at datetime default current_timestamp
-		)`;
-
-		this.sql`create table if not exists cf_ai_chat_stream_chunks (
-			id text primary key,
-			stream_id text not null,
-			body text not null,
-			chunk_index integer not null,
-			created_at integer not null
-		)`;
-
-		this.sql`create table if not exists cf_ai_chat_stream_metadata (
-			id text primary key,
-			request_id text not null,
-			status text not null,
-			created_at integer not null,
-			completed_at integer
-		)`;
-
-		this.sql`create index if not exists idx_stream_chunks_stream_id 
-			on cf_ai_chat_stream_chunks(stream_id, chunk_index)`;
-	}
-
-	protected dbLoadMessages(): ChatMessage[] {
-		const rows =
-			(this
-				.sql`select * from cf_ai_chat_agent_messages order by created_at` as Array<{
-				id: string;
-				message: string;
-			}>) || [];
-
-		return rows
-			.map((row) => {
-				try {
-					return JSON.parse(row.message) as ChatMessage;
-				} catch (err) {
-					console.error(`Failed to parse message ${row.id}:`, err);
-					return null;
-				}
-			})
-			.filter((msg): msg is ChatMessage => msg !== null);
-	}
-
-	protected dbSaveMessage(msg: ChatMessage): void {
-		const messageJson = JSON.stringify(msg);
-		this.sql`
-			insert into cf_ai_chat_agent_messages (id, message)
-			values (${msg.id}, ${messageJson})
-			on conflict(id) do update set message = excluded.message
-		`;
-	}
-
-	protected dbClearAll(): void {
-		this.sql`delete from cf_ai_chat_agent_messages`;
-		this.sql`delete from cf_ai_chat_stream_chunks`;
-		this.sql`delete from cf_ai_chat_stream_metadata`;
-	}
-
-	protected dbFindActiveStream(): {
-		id: string;
-		messageId: string;
-		createdAt: Date;
-	} | null {
-		const activeStreams = this.sql`
-			select * from cf_ai_chat_stream_metadata 
-			where status = 'streaming' 
-			order by created_at desc 
-			limit 1
-		` as Array<{
-			id: string;
-			request_id: string;
-			status: string;
-			created_at: number;
-			completed_at: number | null;
-		}>;
-
-		if (!activeStreams || activeStreams.length === 0) {
-			return null;
-		}
-
-		const stream = activeStreams[0];
-		return {
-			id: stream.id,
-			messageId: stream.request_id,
-			createdAt: new Date(stream.created_at),
-		};
-	}
-
-	protected dbDeleteStreamWithChunks(streamId: string): void {
-		this
-			.sql`delete from cf_ai_chat_stream_chunks where stream_id = ${streamId}`;
-		this.sql`delete from cf_ai_chat_stream_metadata where id = ${streamId}`;
-	}
-
-	protected dbInsertStreamMetadata(streamId: string, messageId: string): void {
-		const now = Date.now();
-		this.sql`
-			insert into cf_ai_chat_stream_metadata (id, request_id, status, created_at)
-			values (${streamId}, ${messageId}, 'streaming', ${now})
-		`;
-	}
-
-	protected dbUpdateStreamStatus(
-		streamId: string,
-		status: "completed" | "error",
-	): void {
-		const now = Date.now();
-		this.sql`
-			update cf_ai_chat_stream_metadata 
-			set status = ${status}, completed_at = ${now} 
-			where id = ${streamId}
-		`;
-	}
-
-	protected dbDeleteOldCompletedStreams(cutoffMs: number): void {
-		// Delete old stream chunks first
-		this.sql`
-			delete from cf_ai_chat_stream_chunks 
-			where stream_id in (
-				select id from cf_ai_chat_stream_metadata 
-				where status = 'completed' and completed_at < ${cutoffMs}
-			)
-		`;
-		// Then delete the metadata
-		this.sql`
-			delete from cf_ai_chat_stream_metadata 
-			where status = 'completed' and completed_at < ${cutoffMs}
-		`;
-	}
-
-	protected dbFindMaxChunkIndex(streamId: string): number | null {
-		const result = this.sql`
-			select max(chunk_index) as max_index 
-			from cf_ai_chat_stream_chunks 
-			where stream_id = ${streamId}
-		` as Array<{ max_index: number | null }>;
-
-		if (!result || result.length === 0 || result[0].max_index == null) {
-			return null;
-		}
-
-		return result[0].max_index;
-	}
-
-	protected dbInsertChunks(
-		chunks: Array<{
-			id: string;
-			streamId: string;
-			content: string;
-			chunkIndex: number;
-		}>,
-	): void {
-		const now = Date.now();
-		for (const chunk of chunks) {
-			this.sql`
-				insert into cf_ai_chat_stream_chunks (id, stream_id, body, chunk_index, created_at)
-				values (${chunk.id}, ${chunk.streamId}, ${chunk.content}, ${chunk.chunkIndex}, ${now})
-			`;
-		}
-	}
-
-	protected dbGetChunks(streamId: string): string[] {
-		const rows = this.sql`
-			select body from cf_ai_chat_stream_chunks 
-			where stream_id = ${streamId} 
-			order by chunk_index asc
-		` as Array<{ body: string }>;
-
-		return (rows || []).map((r) => r.body);
-	}
-
-	protected dbDeleteChunks(streamId: string): void {
-		this
-			.sql`delete from cf_ai_chat_stream_chunks where stream_id = ${streamId}`;
-	}
-}

package/src/db/index.ts

@@ -1,21 +0,0 @@
-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>;