bashkit 0.3.1 → 0.4.0

package/dist/react/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * bashkit/react - React hooks for connecting to BashKit agents
+ *
+ * This module re-exports hooks from the Cloudflare Agents SDK for connecting
+ * to agents from React applications.
+ *
+ * @example
+ * ```tsx
+ * import { useAgent, useAgentChat } from 'bashkit/react';
+ *
+ * function Chat() {
+ *   // Connect to the agent
+ *   const agent = useAgent({
+ *     agent: 'my-agent',
+ *     name: sessionId,
+ *   });
+ *
+ *   // Use the chat hook for AI conversations
+ *   const { messages, input, handleSubmit, handleInputChange } = useAgentChat({
+ *     agent,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map((msg, i) => (
+ *         <div key={i}>
+ *           <strong>{msg.role}:</strong> {msg.content}
+ *         </div>
+ *       ))}
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={handleInputChange} />
+ *         <button type="submit">Send</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export { useAgent } from "agents/react";
+export { useAgentChat } from "agents/ai-react";
+export { AgentClient, agentFetch } from "agents/client";
+export type { UseAgentOptions } from "agents/react";

package/dist/react/index.js

@@ -0,0 +1,10 @@
+// src/react/index.ts
+import { useAgent } from "agents/react";
+import { useAgentChat } from "agents/ai-react";
+import { AgentClient, agentFetch } from "agents/client";
+export {
+  useAgentChat,
+  useAgent,
+  agentFetch,
+  AgentClient
+};

package/dist/react/types.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Connection status for the agent WebSocket.
+ */
+export type ConnectionStatus = "connecting" | "connected" | "disconnected" | "reconnecting";
+/**
+ * Configuration for the useAgent hook.
+ */
+export interface UseAgentConfig<TMessage = unknown> {
+    /**
+     * The WebSocket URL to connect to.
+     * Should be your Cloudflare Worker URL.
+     */
+    url: string;
+    /**
+     * The session ID to connect to.
+     * Each session ID maps to a separate Durable Object.
+     */
+    sessionId: string;
+    /**
+     * Called when a message is received from the server.
+     */
+    onMessage?: (message: TMessage) => void;
+    /**
+     * Called when the connection is established.
+     */
+    onConnect?: () => void;
+    /**
+     * Called when the connection is closed.
+     */
+    onDisconnect?: (event: CloseEvent) => void;
+    /**
+     * Called when an error occurs.
+     */
+    onError?: (error: Event) => void;
+    /**
+     * Called when reconnecting with buffered content.
+     * The buffered content is sent by the server's onReconnect handler.
+     */
+    onReconnect?: (bufferedChunks: string[]) => void;
+    /**
+     * Whether to automatically reconnect on disconnect.
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Delay in milliseconds before attempting to reconnect.
+     * @default 1000
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum number of reconnection attempts.
+     * @default 5
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Whether the hook should connect immediately.
+     * Set to false to manually control connection via `connect()`.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Return type of the useAgent hook.
+ */
+export interface UseAgentReturn<TMessage = unknown> {
+    /**
+     * Current connection status.
+     */
+    status: ConnectionStatus;
+    /**
+     * Whether the WebSocket is currently connected.
+     */
+    isConnected: boolean;
+    /**
+     * Accumulated messages received from the server.
+     */
+    messages: TMessage[];
+    /**
+     * Send a message to the server.
+     */
+    sendMessage: (message: unknown) => void;
+    /**
+     * Manually connect to the server.
+     * Only needed if `enabled: false` was passed.
+     */
+    connect: () => void;
+    /**
+     * Manually disconnect from the server.
+     */
+    disconnect: () => void;
+    /**
+     * Clear all accumulated messages.
+     */
+    clearMessages: () => void;
+    /**
+     * The raw WebSocket instance (for advanced use).
+     */
+    socket: WebSocket | null;
+    /**
+     * Number of reconnection attempts made.
+     */
+    reconnectAttempts: number;
+    /**
+     * Any error that occurred during connection.
+     */
+    error: Event | null;
+}
+/**
+ * Options for individual message sending.
+ */
+export interface SendMessageOptions {
+    /**
+     * Whether to wait for connection before sending.
+     * If true, the message will be queued and sent when connected.
+     * @default false
+     */
+    queue?: boolean;
+}
+/**
+ * Message types commonly sent between client and server.
+ */
+export interface AgentMessage<T = unknown> {
+    type: string;
+    data?: T;
+    timestamp?: number;
+}
+/**
+ * Common message types for agent communication.
+ */
+export interface ChunkMessage {
+    type: "chunk";
+    text: string;
+}
+export interface StatusMessage {
+    type: "status";
+    status: "thinking" | "executing" | "idle";
+}
+export interface ErrorMessage {
+    type: "error";
+    error: string;
+    message?: string;
+}
+export interface ReconnectMessage {
+    type: "reconnect";
+    bufferedChunks: string[];
+}
+export interface StateMessage<T = unknown> {
+    type: "state";
+    data: T;
+}
+/**
+ * Union of common message types.
+ */
+export type CommonAgentMessage<T = unknown> = ChunkMessage | StatusMessage | ErrorMessage | ReconnectMessage | StateMessage<T>;
+/**
+ * Status of the chat generation.
+ * Matches Vercel AI SDK useChat status values.
+ */
+export type DurableChatStatus = "ready" | "submitted" | "streaming" | "error";
+/**
+ * A part of a chat message (text, tool call, or tool result).
+ * Matches Vercel AI SDK UIMessagePart structure.
+ */
+export type DurableChatPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+};
+/**
+ * A chat message with parts.
+ * Matches Vercel AI SDK UIMessage structure.
+ */
+export interface DurableChatMessage {
+    id: string;
+    role: "user" | "assistant" | "system";
+    parts: DurableChatPart[];
+    createdAt?: Date;
+    metadata?: unknown;
+}
+/**
+ * Server-to-client message types for streaming chat.
+ */
+export type ServerMessage = {
+    type: "message-start";
+    id: string;
+    role: "assistant" | "system";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+} | {
+    type: "message-end";
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "aborted";
+};
+/**
+ * Client-to-server message types.
+ */
+export type ClientMessage = {
+    type: "chat";
+    content: string;
+    metadata?: unknown;
+    [key: string]: unknown;
+} | {
+    type: "abort";
+} | {
+    type: "regenerate";
+    messageId?: string;
+};
+/**
+ * Configuration for the useDurableChat hook.
+ */
+export interface UseDurableChatConfig {
+    /**
+     * The WebSocket URL to connect to.
+     */
+    url: string;
+    /**
+     * The session ID for the chat.
+     */
+    sessionId: string;
+    /**
+     * Called when any server message is received.
+     */
+    onMessage?: (message: ServerMessage) => void;
+    /**
+     * Called when an assistant message is complete.
+     */
+    onFinish?: (message: DurableChatMessage) => void;
+    /**
+     * Called when an error occurs.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Whether the hook should connect immediately.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Return type of the useDurableChat hook.
+ * API mirrors Vercel AI SDK useChat for familiarity.
+ */
+export interface UseDurableChatReturn {
+    /**
+     * The array of chat messages.
+     */
+    messages: DurableChatMessage[];
+    /**
+     * Current status of the chat generation.
+     */
+    status: DurableChatStatus;
+    /**
+     * Error if one occurred.
+     */
+    error: Error | null;
+    /**
+     * Whether the assistant is currently streaming a response.
+     */
+    isStreaming: boolean;
+    /**
+     * Whether a request is in progress (submitted or streaming).
+     */
+    isLoading: boolean;
+    /**
+     * Send a message to the chat.
+     */
+    sendMessage: (content: string | {
+        text: string;
+        [key: string]: unknown;
+    }, options?: {
+        body?: Record<string, unknown>;
+    }) => void;
+    /**
+     * Stop/abort the current generation.
+     */
+    stop: () => void;
+    /**
+     * Regenerate the last assistant message or a specific message.
+     */
+    regenerate: (options?: {
+        messageId?: string;
+    }) => void;
+    /**
+     * Update messages locally without sending to server.
+     */
+    setMessages: React.Dispatch<React.SetStateAction<DurableChatMessage[]>>;
+    /**
+     * Clear all messages.
+     */
+    clearMessages: () => void;
+    /**
+     * Clear the error state.
+     */
+    clearError: () => void;
+    /**
+     * WebSocket connection status.
+     */
+    connectionStatus: ConnectionStatus;
+    /**
+     * Whether the WebSocket is connected.
+     */
+    isConnected: boolean;
+    /**
+     * Manually connect to the server.
+     */
+    connect: () => void;
+    /**
+     * Manually disconnect from the server.
+     */
+    disconnect: () => void;
+}

package/dist/react/use-agent.d.ts

@@ -0,0 +1,33 @@
+import type { UseAgentConfig, UseAgentReturn } from "./types";
+/**
+ * React hook for connecting to a bashkit durable agent session.
+ *
+ * @example
+ * ```tsx
+ * import { useAgent } from 'bashkit/react';
+ *
+ * function ChatUI() {
+ *   const {
+ *     status,
+ *     messages,
+ *     sendMessage,
+ *     isConnected,
+ *   } = useAgent({
+ *     url: 'https://my-agent.workers.dev',
+ *     sessionId: 'conversation-123',
+ *     onMessage: (msg) => console.log('Received:', msg),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {status}</p>
+ *       {messages.map((msg, i) => <div key={i}>{JSON.stringify(msg)}</div>)}
+ *       <button onClick={() => sendMessage({ type: 'chat', text: 'Hello!' })}>
+ *         Send
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAgent<TMessage = unknown>(config: UseAgentConfig<TMessage>): UseAgentReturn<TMessage>;

package/dist/react/use-durable-chat.d.ts

@@ -0,0 +1,39 @@
+import type { UseDurableChatConfig, UseDurableChatReturn } from "./types";
+/**
+ * React hook for durable chat sessions with streaming support.
+ * Provides a similar API to Vercel AI SDK's useChat but over WebSockets
+ * with durable session support.
+ *
+ * @example
+ * ```tsx
+ * import { useDurableChat } from 'bashkit/react';
+ *
+ * function Chat() {
+ *   const {
+ *     messages,
+ *     status,
+ *     sendMessage,
+ *     stop,
+ *     isStreaming,
+ *   } = useDurableChat({
+ *     url: 'https://my-agent.workers.dev',
+ *     sessionId: 'conversation-123',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(msg => (
+ *         <div key={msg.id}>
+ *           <strong>{msg.role}:</strong>
+ *           {msg.parts.map((part, i) => (
+ *             part.type === 'text' ? <span key={i}>{part.text}</span> : null
+ *           ))}
+ *         </div>
+ *       ))}
+ *       <button onClick={stop} disabled={!isStreaming}>Stop</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDurableChat(config: UseDurableChatConfig): UseDurableChatReturn;

package/dist/tools/ask-user.d.ts

@@ -1,12 +1,12 @@
 export interface QuestionOption {
     label: string;
-    description?: string;
+    description: string | null;
 }
 export interface StructuredQuestion {
-    header?: string;
+    header: string | null;
     question: string;
-    options?: QuestionOption[];
-    multiSelect?: boolean;
+    options: QuestionOption[] | null;
+    multiSelect: boolean | null;
 }
 export interface AskUserSimpleOutput {
     question: string;
@@ -40,14 +40,14 @@ export interface AskUserToolConfig {
  * @param config - Configuration with optional handlers for questions
  */
 export declare function createAskUserTool(config?: AskUserToolConfig | AskUserResponseHandler): import("ai").Tool<{
-    question?: string | undefined;
-    questions?: {
+    question: string | null;
+    questions: {
+        header: string | null;
         question: string;
-        header?: string | undefined;
-        options?: {
+        options: {
             label: string;
-            description?: string | undefined;
-        }[] | undefined;
-        multiSelect?: boolean | undefined;
-    }[] | undefined;
+            description: string | null;
+        }[] | null;
+        multiSelect: boolean | null;
+    }[] | null;
 }, AskUserOutput | AskUserError | AskUserAnswerOutput>;

package/dist/tools/bash.d.ts

@@ -12,7 +12,7 @@ export interface BashError {
 }
 export declare function createBashTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     command: string;
-    timeout?: number | undefined;
-    description?: string | undefined;
-    run_in_background?: boolean | undefined;
+    timeout: number | null;
+    description: string | null;
+    run_in_background: boolean | null;
 }, BashOutput | BashError>;

package/dist/tools/edit.d.ts

@@ -12,5 +12,5 @@ export declare function createEditTool(sandbox: Sandbox, config?: ToolConfig): i
     file_path: string;
     old_string: string;
     new_string: string;
-    replace_all?: boolean | undefined;
+    replace_all: boolean | null;
 }, EditOutput | EditError>;

package/dist/tools/glob.d.ts

@@ -10,5 +10,5 @@ export interface GlobError {
 }
 export declare function createGlobTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
+    path: string | null;
 }, GlobOutput | GlobError>;

package/dist/tools/grep.d.ts

@@ -28,16 +28,16 @@ export interface GrepError {
 export type GrepOutput = GrepContentOutput | GrepFilesOutput | GrepCountOutput | GrepError;
 export declare function createGrepTool(sandbox: Sandbox, config?: GrepToolConfig): import("ai").Tool<{
     pattern: string;
-    path?: string | undefined;
-    glob?: string | undefined;
-    type?: string | undefined;
-    output_mode?: "content" | "count" | "files_with_matches" | undefined;
-    "-i"?: boolean | undefined;
-    "-n"?: boolean | undefined;
-    "-B"?: number | undefined;
-    "-A"?: number | undefined;
-    "-C"?: number | undefined;
-    head_limit?: number | undefined;
-    offset?: number | undefined;
-    multiline?: boolean | undefined;
+    path: string | null;
+    glob: string | null;
+    type: string | null;
+    output_mode: "content" | "count" | "files_with_matches" | null;
+    "-i": boolean | null;
+    "-n": boolean | null;
+    "-B": number | null;
+    "-A": number | null;
+    "-C": number | null;
+    head_limit: number | null;
+    offset: number | null;
+    multiline: boolean | null;
 }, GrepOutput>;

package/dist/tools/index.d.ts

@@ -47,7 +47,7 @@ export interface AgentToolsResult {
  * });
  */
 export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): AgentToolsResult;
-export type { AskUserError, AskUserOutput, AskUserResponseHandler, } from "./ask-user";
+export type { AskUserError, AskUserOutput, AskUserResponseHandler, QuestionOption, StructuredQuestion, } from "./ask-user";
 export { createAskUserTool } from "./ask-user";
 export type { BashError, BashOutput } from "./bash";
 export { createBashTool } from "./bash";

package/dist/tools/read.d.ts

@@ -20,6 +20,6 @@ export interface ReadError {
 export type ReadOutput = ReadTextOutput | ReadDirectoryOutput | ReadError;
 export declare function createReadTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
     file_path: string;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    offset: number | null;
+    limit: number | null;
 }, ReadOutput>;

package/dist/tools/task.d.ts

@@ -17,8 +17,8 @@ declare const taskInputSchema: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
     subagent_type: z.ZodString;
-    system_prompt: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    system_prompt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 type TaskInput = z.infer<typeof taskInputSchema>;
 /** Event emitted for each step a subagent takes */
@@ -43,8 +43,10 @@ export interface SubagentTypeConfig {
     systemPrompt?: string;
     /** Tool names this subagent can use (filters from parent tools) */
     tools?: string[];
-    /** Stop condition for this subagent (default: stepCountIs(15)) */
-    stopWhen?: StopCondition<ToolSet>;
+    /** Additional tools only this subagent can use (merged with filtered tools) */
+    additionalTools?: ToolSet;
+    /** Stop condition(s) for this subagent (default: stepCountIs(15)). Can be a single condition or array - stops when ANY condition is met. */
+    stopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
     /** Prepare step callback for dynamic control per step */
     prepareStep?: PrepareStepFunction<ToolSet>;
     /** Callback for each step this subagent takes */
@@ -57,8 +59,8 @@ export interface TaskToolConfig {
     tools: ToolSet;
     /** Configuration for each subagent type */
     subagentTypes?: Record<string, SubagentTypeConfig>;
-    /** Default stop condition for subagents (default: stepCountIs(15)) */
-    defaultStopWhen?: StopCondition<ToolSet>;
+    /** Default stop condition(s) for subagents (default: stepCountIs(15)). Can be a single condition or array - stops when ANY condition is met. */
+    defaultStopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
     /** Default callback for each step any subagent takes */
     defaultOnStepFinish?: (event: SubagentStepEvent) => void | Promise<void>;
     /** Optional stream writer for real-time subagent activity (uses streamText instead of generateText) */

package/dist/tools/web-search.d.ts

@@ -17,6 +17,6 @@ export interface WebSearchError {
 }
 export declare function createWebSearchTool(config: WebSearchConfig): import("ai").Tool<{
     query: string;
-    allowed_domains?: string[] | undefined;
-    blocked_domains?: string[] | undefined;
+    allowed_domains: string[] | null;
+    blocked_domains: string[] | null;
 }, WebSearchOutput | WebSearchError>;