@firtoz/chat-agent 1.0.1 → 2.1.0

package/dist/chat-messages.d.ts

@@ -0,0 +1,481 @@
+import * as z from 'zod/v4';
+
+/**
+ * JSON Schema for tool parameters (subset of JSON Schema 7)
+ */
+declare const JSONSchemaSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+type JSONSchema = z.infer<typeof JSONSchemaSchema>;
+/**
+ * Tool definition following OpenAI/OpenRouter format
+ * The schema is for wire format (no execute function)
+ */
+declare const ToolDefinitionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    function: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        strict: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Execute function signature for server-side tools
+ * Takes parsed arguments, returns JSON-serializable result
+ */
+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
+ */
+type ToolNeedsApprovalFn = (args: Record<string, unknown>) => boolean | Promise<boolean>;
+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;
+};
+/**
+ * A tool call from the AI (complete, after streaming)
+ */
+declare const ToolCallSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"function">;
+    function: z.ZodObject<{
+        name: z.ZodString;
+        arguments: z.ZodString;
+    }, z.core.$strip>;
+    providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type ToolCall = z.infer<typeof ToolCallSchema>;
+/**
+ * Tool call delta during streaming
+ */
+declare const ToolCallDeltaSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodLiteral<"function">>;
+    function: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        arguments: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type ToolCallDelta = z.infer<typeof ToolCallDeltaSchema>;
+/**
+ * Tool result from client-side execution
+ */
+declare const ToolResultSchema: z.ZodObject<{
+    toolCallId: z.ZodString;
+    output: z.ZodUnknown;
+}, z.core.$strip>;
+type ToolResult = z.infer<typeof ToolResultSchema>;
+/**
+ * User message
+ */
+declare const UserMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+type UserMessage = z.infer<typeof UserMessageSchema>;
+/**
+ * Assistant message - can have content, tool calls, or both
+ */
+declare const AssistantMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"assistant">;
+    content: z.ZodNullable<z.ZodString>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strip>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+type AssistantMessage = z.infer<typeof AssistantMessageSchema>;
+/**
+ * Tool response message (sent back to AI after tool execution)
+ */
+declare const ToolMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"tool">;
+    toolCallId: z.ZodString;
+    content: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+type ToolMessage = z.infer<typeof ToolMessageSchema>;
+/**
+ * Union of all chat message types
+ */
+declare const ChatMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"assistant">;
+    content: z.ZodNullable<z.ZodString>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strip>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodLiteral<"tool">;
+    toolCallId: z.ZodString;
+    content: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>], "role">;
+type ChatMessage = z.infer<typeof ChatMessageSchema>;
+declare const TokenUsageSchema: z.ZodObject<{
+    prompt_tokens: z.ZodNumber;
+    completion_tokens: z.ZodNumber;
+    total_tokens: z.ZodNumber;
+}, z.core.$strip>;
+type TokenUsage = z.infer<typeof TokenUsageSchema>;
+declare const SendMessageTriggerSchema: z.ZodEnum<{
+    "submit-message": "submit-message";
+    "regenerate-message": "regenerate-message";
+}>;
+type SendMessageTrigger = z.infer<typeof SendMessageTriggerSchema>;
+declare const ClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sendMessage">;
+    content: z.ZodOptional<z.ZodString>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"user">;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"assistant">;
+        content: z.ZodNullable<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"function">;
+            function: z.ZodObject<{
+                name: z.ZodString;
+                arguments: z.ZodString;
+            }, z.core.$strip>;
+            providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"tool">;
+        toolCallId: z.ZodString;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>], "role">>>;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        "submit-message": "submit-message";
+        "regenerate-message": "regenerate-message";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"clearHistory">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"getHistory">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resumeStream">;
+    streamId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cancelRequest">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolResult">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    output: z.ZodUnknown;
+    autoContinue: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolApprovalResponse">;
+    approvalId: z.ZodString;
+    approved: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"registerTools">;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+type ClientMessage = z.infer<typeof ClientMessageSchema>;
+type SendMessagePayload = Extract<ClientMessage, {
+    type: "sendMessage";
+}>;
+type ClearHistoryPayload = Extract<ClientMessage, {
+    type: "clearHistory";
+}>;
+type GetHistoryPayload = Extract<ClientMessage, {
+    type: "getHistory";
+}>;
+type ResumeStreamPayload = Extract<ClientMessage, {
+    type: "resumeStream";
+}>;
+type CancelRequestPayload = Extract<ClientMessage, {
+    type: "cancelRequest";
+}>;
+type ToolResultPayload = Extract<ClientMessage, {
+    type: "toolResult";
+}>;
+type ToolApprovalResponsePayload = Extract<ClientMessage, {
+    type: "toolApprovalResponse";
+}>;
+type RegisterToolsPayload = Extract<ClientMessage, {
+    type: "registerTools";
+}>;
+declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"history">;
+    messages: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"user">;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"assistant">;
+        content: z.ZodNullable<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"function">;
+            function: z.ZodObject<{
+                name: z.ZodString;
+                arguments: z.ZodString;
+            }, z.core.$strip>;
+            providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"tool">;
+        toolCallId: z.ZodString;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>], "role">>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"messageStart">;
+    id: z.ZodString;
+    streamId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"messageChunk">;
+    id: z.ZodString;
+    chunk: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolCallDelta">;
+    id: z.ZodString;
+    delta: z.ZodObject<{
+        index: z.ZodNumber;
+        id: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodLiteral<"function">>;
+        function: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            arguments: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolCall">;
+    id: z.ZodString;
+    toolCall: z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strip>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"messageEnd">;
+    id: z.ZodString;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strip>;
+        providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodNumber;
+    usage: z.ZodOptional<z.ZodObject<{
+        prompt_tokens: z.ZodNumber;
+        completion_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"streamResume">;
+    streamId: z.ZodString;
+    chunks: z.ZodArray<z.ZodString>;
+    done: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"streamResuming">;
+    id: z.ZodString;
+    streamId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"messageUpdated">;
+    message: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"user">;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"assistant">;
+        content: z.ZodNullable<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"function">;
+            function: z.ZodObject<{
+                name: z.ZodString;
+                arguments: z.ZodString;
+            }, z.core.$strip>;
+            providerMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodLiteral<"tool">;
+        toolCallId: z.ZodString;
+        content: z.ZodString;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>], "role">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolError">;
+    errorType: z.ZodEnum<{
+        input: "input";
+        output: "output";
+        not_found: "not_found";
+    }>;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"toolApprovalRequest">;
+    approvalId: z.ZodString;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    arguments: z.ZodString;
+}, z.core.$strip>], "type">;
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+type HistoryMessage = Extract<ServerMessage, {
+    type: "history";
+}>;
+type MessageStartMessage = Extract<ServerMessage, {
+    type: "messageStart";
+}>;
+type MessageChunkMessage = Extract<ServerMessage, {
+    type: "messageChunk";
+}>;
+type ToolCallDeltaMessage = Extract<ServerMessage, {
+    type: "toolCallDelta";
+}>;
+type ToolCallMessage = Extract<ServerMessage, {
+    type: "toolCall";
+}>;
+type MessageEndMessage = Extract<ServerMessage, {
+    type: "messageEnd";
+}>;
+type StreamResumeMessage = Extract<ServerMessage, {
+    type: "streamResume";
+}>;
+type StreamResumingMessage = Extract<ServerMessage, {
+    type: "streamResuming";
+}>;
+type MessageUpdatedMessage = Extract<ServerMessage, {
+    type: "messageUpdated";
+}>;
+type ErrorMessage = Extract<ServerMessage, {
+    type: "error";
+}>;
+type ToolErrorMessage = Extract<ServerMessage, {
+    type: "toolError";
+}>;
+type ToolApprovalRequestMessage = Extract<ServerMessage, {
+    type: "toolApprovalRequest";
+}>;
+/**
+ * Parse and validate a client message from JSON string
+ * @throws ZodError if validation fails
+ */
+declare function parseClientMessage(json: string): ClientMessage;
+/**
+ * Safely parse a client message, returning null on failure
+ */
+declare function safeParseClientMessage(json: string): ClientMessage | null;
+/**
+ * Parse and validate a server message from JSON string
+ * @throws ZodError if validation fails
+ */
+declare function parseServerMessage(json: string): ServerMessage;
+/**
+ * Safely parse a server message, returning null on failure
+ */
+declare function safeParseServerMessage(json: string): ServerMessage | null;
+declare function isClientMessage(data: unknown): data is ClientMessage;
+declare function isServerMessage(data: unknown): data is ServerMessage;
+declare function isUserMessage(msg: ChatMessage): msg is UserMessage;
+declare function isAssistantMessage(msg: ChatMessage): msg is AssistantMessage;
+declare function isToolMessage(msg: ChatMessage): msg is ToolMessage;
+declare function hasToolCalls(msg: AssistantMessage): boolean;
+/**
+ * Parse tool call arguments from JSON string
+ */
+declare function parseToolArguments<T = unknown>(toolCall: ToolCall): 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
+ * })
+ * ```
+ */
+declare function defineTool(config: {
+    name: string;
+    description?: string;
+    parameters?: JSONSchema;
+    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;
+
+export { type AssistantMessage, AssistantMessageSchema, type CancelRequestPayload, type ChatMessage, ChatMessageSchema, type ClearHistoryPayload, type ClientMessage, ClientMessageSchema, type ErrorMessage, type GetHistoryPayload, type HistoryMessage, type JSONSchema, JSONSchemaSchema, type MessageChunkMessage, type MessageEndMessage, type MessageStartMessage, type MessageUpdatedMessage, type RegisterToolsPayload, type ResumeStreamPayload, type SendMessagePayload, type SendMessageTrigger, SendMessageTriggerSchema, type ServerMessage, ServerMessageSchema, type StreamResumeMessage, type StreamResumingMessage, type TokenUsage, TokenUsageSchema, type ToolApprovalRequestMessage, type ToolApprovalResponsePayload, type ToolCall, type ToolCallDelta, type ToolCallDeltaMessage, ToolCallDeltaSchema, type ToolCallMessage, ToolCallSchema, type ToolDefinition, ToolDefinitionSchema, type ToolErrorMessage, type ToolExecuteFunction, type ToolMessage, ToolMessageSchema, type ToolNeedsApprovalFn, type ToolResult, type ToolResultPayload, ToolResultSchema, type UserMessage, UserMessageSchema, defineTool, hasToolCalls, isAssistantMessage, isClientMessage, isServerMessage, isToolMessage, isUserMessage, parseClientMessage, parseServerMessage, parseToolArguments, safeParseClientMessage, safeParseServerMessage };

package/dist/chat-messages.js

@@ -0,0 +1,3 @@
+export { AssistantMessageSchema, ChatMessageSchema, ClientMessageSchema, JSONSchemaSchema, SendMessageTriggerSchema, ServerMessageSchema, TokenUsageSchema, ToolCallDeltaSchema, ToolCallSchema, ToolDefinitionSchema, ToolMessageSchema, ToolResultSchema, UserMessageSchema, defineTool, hasToolCalls, isAssistantMessage, isClientMessage, isServerMessage, isToolMessage, isUserMessage, parseClientMessage, parseServerMessage, parseToolArguments, safeParseClientMessage, safeParseServerMessage } from './chunk-OEX3D4WL.js';
+//# sourceMappingURL=chat-messages.js.map
+//# sourceMappingURL=chat-messages.js.map

package/dist/chat-messages.js.map

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