@firtoz/chat-agent 1.0.1 → 2.1.0

package/dist/chat-agent-base.d.ts

@@ -0,0 +1,253 @@
+import { Agent, AgentContext, Connection, ConnectionContext } from 'agents';
+import { ChatMessage, ToolDefinition } from './chat-messages.js';
+export { AssistantMessage, ClientMessage, SendMessagePayload, SendMessageTrigger, ServerMessage, TokenUsage, ToolApprovalRequestMessage, ToolApprovalResponsePayload, ToolCall, ToolMessage, ToolNeedsApprovalFn, UserMessage, defineTool } from './chat-messages.js';
+import 'zod/v4';
+
+/**
+ * ChatAgentBase - Abstract base class for AI chat agents
+ *
+ * Features:
+ * - DB-agnostic SQLite persistence in Durable Objects
+ * - Resumable streaming with chunk buffering (like @cloudflare/ai-chat)
+ * - Broadcast of stream and history updates to all WebSocket connections (multi-tab)
+ * - Serialized chat turns + batched client tool auto-continue
+ * - OpenRouter via Cloudflare AI Gateway
+ *
+ * Subclasses must implement database operations via abstract methods.
+ *
+ * @template Env - Environment bindings type (must include OPENROUTER_API_KEY, optionally AI Gateway config)
+ */
+declare abstract class ChatAgentBase<Env extends Cloudflare.Env & {
+    OPENROUTER_API_KEY: string;
+} = Cloudflare.Env & {
+    OPENROUTER_API_KEY: string;
+}> extends Agent<Env> {
+    /** In-memory cache of messages */
+    messages: ChatMessage[];
+    /**
+     * When set, oldest messages are deleted from storage after each save so only the last N remain.
+     * Does not change what is sent to the model unless you prune separately.
+     */
+    protected maxPersistedMessages?: number;
+    /** Map of message IDs to AbortControllers for request cancellation */
+    private _abortControllers;
+    /** Currently active stream ID */
+    private _activeStreamId;
+    /** Message ID being streamed */
+    private _activeMessageId;
+    /** True only while the OpenRouter async iterator for the active stream is running */
+    private _openRouterStreamLive;
+    /** Current chunk index for active stream */
+    private _streamChunkIndex;
+    /** Buffer for chunks pending write */
+    private _chunkBuffer;
+    /** Lock for flush operations */
+    private _isFlushingChunks;
+    /** Last cleanup timestamp */
+    private _lastCleanupTime;
+    /** Client-registered tools (tools defined at runtime from frontend) */
+    private _clientTools;
+    /** FIFO serialization of chat turns (user sends, tool continuations, etc.) */
+    private _turnTail;
+    /** Bumped by {@link resetTurnState} to ignore stale async work */
+    private _turnGeneration;
+    /** Connection id that last queued an auto-continue after client tools (for multi-tab hints) */
+    private _continuationOriginConnectionId;
+    private _pendingClientToolAutoContinue;
+    private _clientToolAutoContinueFlushScheduled;
+    /** Human-in-the-loop: server tools awaiting `toolApprovalResponse` (not queued — avoids deadlock). */
+    private _pendingToolApprovals;
+    constructor(ctx: AgentContext, env: Env);
+    /**
+     * Initialize database and run migrations
+     * Called once during constructor
+     */
+    protected abstract dbInitialize(): void;
+    /**
+     * Load all messages from database
+     * @returns Array of chat messages ordered by createdAt
+     */
+    protected abstract dbLoadMessages(): ChatMessage[];
+    /**
+     * Save or update a message in database
+     * @param msg - The message to save
+     */
+    protected abstract dbSaveMessage(msg: ChatMessage): void;
+    /**
+     * Clear all data (messages, streams, chunks)
+     */
+    protected abstract dbClearAll(): void;
+    /**
+     * Find an active streaming session
+     * @returns Stream info or null if none active
+     */
+    protected abstract dbFindActiveStream(): {
+        id: string;
+        messageId: string;
+        createdAt: Date;
+    } | null;
+    /**
+     * Delete a stream and all its chunks
+     * @param streamId - The stream to delete
+     */
+    protected abstract dbDeleteStreamWithChunks(streamId: string): void;
+    /**
+     * Create a new stream metadata entry
+     * @param streamId - Unique stream identifier
+     * @param messageId - Associated message ID
+     */
+    protected abstract dbInsertStreamMetadata(streamId: string, messageId: string): void;
+    /**
+     * Update stream status to completed or error
+     * @param streamId - The stream to update
+     * @param status - New status
+     */
+    protected abstract dbUpdateStreamStatus(streamId: string, status: "completed" | "error"): void;
+    /**
+     * Delete old completed streams older than cutoff
+     * @param cutoffMs - Timestamp in milliseconds
+     */
+    protected abstract dbDeleteOldCompletedStreams(cutoffMs: number): void;
+    /**
+     * Find the maximum chunk index for a stream
+     * @param streamId - The stream to query
+     * @returns Max chunk index or null if no chunks
+     */
+    protected abstract dbFindMaxChunkIndex(streamId: string): number | null;
+    /**
+     * Insert multiple stream chunks
+     * @param chunks - Array of chunks to insert
+     */
+    protected abstract dbInsertChunks(chunks: Array<{
+        id: string;
+        streamId: string;
+        content: string;
+        chunkIndex: number;
+    }>): void;
+    /**
+     * Get all chunks for a stream, ordered by index
+     * @param streamId - The stream to query
+     * @returns Array of chunk content strings
+     */
+    protected abstract dbGetChunks(streamId: string): string[];
+    /**
+     * Delete all chunks for a stream
+     * @param streamId - The stream to clean up
+     */
+    protected abstract dbDeleteChunks(streamId: string): void;
+    /**
+     * Whether stream metadata or chunks exist for this stream id
+     */
+    protected abstract dbIsStreamKnown(streamId: string): boolean;
+    /**
+     * Delete oldest messages until at most `maxMessages` rows remain
+     */
+    protected abstract dbTrimMessagesToMax(maxMessages: number): void;
+    /**
+     * Replace all chat messages (used for client sync / regenerate). Implementations should delete existing rows then insert.
+     */
+    protected abstract dbReplaceAllMessages(messages: ChatMessage[]): void;
+    /**
+     * Transform a message immediately before it is written to storage.
+     * Default: return the message unchanged.
+     */
+    protected sanitizeMessageForPersistence(msg: ChatMessage): ChatMessage;
+    /**
+     * Resolves after all queued turns have finished and no OpenRouter stream is active.
+     */
+    protected waitUntilStable(): Promise<void>;
+    /**
+     * Abort in-flight generation, clear pending client tool auto-continue batch, and invalidate queued async work.
+     * Call from custom clear handlers; {@link clearHistory} path also resets state.
+     */
+    protected resetTurnState(): void;
+    /**
+     * True when the last assistant message still has tool calls without matching tool role replies.
+     */
+    protected hasPendingInteraction(): boolean;
+    private _persistMessage;
+    private _maybeTruncateToolMessageContent;
+    private _clearMessages;
+    /**
+     * Restore active stream state if the agent was restarted during streaming.
+     * Called during construction to recover any interrupted streams.
+     */
+    private _restoreActiveStream;
+    /**
+     * Notify a connection about an active stream that can be resumed.
+     */
+    private _notifyStreamResuming;
+    private _storeChunk;
+    private _flushChunkBuffer;
+    private _startStream;
+    /**
+     * Complete stream with a full message (supports tool calls)
+     */
+    private _completeStreamWithMessage;
+    private _markStreamError;
+    /**
+     * Clean up old completed streams periodically.
+     */
+    private _maybeCleanupOldStreams;
+    private _getStreamChunks;
+    /**
+     * Finalize a stream that has buffered chunks but no live OpenRouter reader (e.g. after DO restart).
+     */
+    private _finalizeOrphanedStreamFromChunks;
+    private _getAbortSignal;
+    private _cancelRequest;
+    private _removeAbortController;
+    private _broadcast;
+    private _sendTo;
+    private _enqueueTurn;
+    private _resolveToolApproval;
+    private _mergeProviderMetadata;
+    private _replaceMessagesFromClient;
+    private _getOpenRouter;
+    onConnect(connection: Connection, _ctx: ConnectionContext): Promise<void>;
+    onClose(connection: Connection, _code: number, _reason: string, _wasClean: boolean): Promise<void>;
+    onMessage(connection: Connection, message: string): Promise<void>;
+    /**
+     * Get the system prompt for the AI
+     * Override this method to customize the AI's behavior
+     */
+    protected getSystemPrompt(): string;
+    /**
+     * Get the AI model to use
+     * Override this method to use a different model
+     */
+    protected getModel(): string;
+    /**
+     * Get available tools for the AI
+     * Override this method to provide custom tools
+     */
+    protected getTools(): ToolDefinition[];
+    private _handleSendMessagePayload;
+    private _handleToolResultMessage;
+    private _scheduleClientToolAutoContinueFlush;
+    private _applyClientToolResult;
+    /**
+     * Generate AI response (can be called for initial message or after tool results)
+     */
+    private _generateAIResponse;
+    /**
+     * Build API messages from our message history
+     */
+    private _buildApiMessages;
+    /**
+     * Build a map of tool definitions by name for quick lookup
+     */
+    private _getToolsMap;
+    /**
+     * Register tools from the client at runtime
+     */
+    private _registerClientTools;
+    /**
+     * Execute server-side tools and continue the conversation
+     */
+    private _executeServerSideTools;
+    private _handleResumeStream;
+    destroy(): Promise<void>;
+}
+
+export { ChatAgentBase, ChatMessage, ToolDefinition };

package/dist/chat-agent-base.js

@@ -0,0 +1,4 @@
+export { ChatAgentBase } from './chunk-G5P5JXRF.js';
+export { defineTool } from './chunk-OEX3D4WL.js';
+//# sourceMappingURL=chat-agent-base.js.map
+//# sourceMappingURL=chat-agent-base.js.map

package/dist/chat-agent-base.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chat-agent-base.js"}