bashkit 0.3.1 → 0.3.2

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/task.d.ts

@@ -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/utils/debug.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Debug logging utilities for bashkit tools.
+ *
+ * Enable debug logging via environment variable:
+ * - BASHKIT_DEBUG=1 or BASHKIT_DEBUG=stderr - Human readable output to stderr
+ * - BASHKIT_DEBUG=json - JSON lines to stderr
+ * - BASHKIT_DEBUG=memory - In-memory array (retrieve via getDebugLogs())
+ * - BASHKIT_DEBUG=file:/path/to/trace.jsonl - Write to file
+ */
+/** Debug event structure for tool execution tracing */
+export interface DebugEvent {
+    /** Unique ID to correlate start/end events (e.g., "grep-1") */
+    id: string;
+    /** Timestamp in milliseconds */
+    ts: number;
+    /** Tool name */
+    tool: string;
+    /** Event type */
+    event: "start" | "end" | "error";
+    /** Input parameters (start events only, summarized) */
+    input?: unknown;
+    /** Output data (end events only, summarized) */
+    output?: unknown;
+    /** Key metrics like exitCode, matchCount, etc. */
+    summary?: Record<string, unknown>;
+    /** Duration in milliseconds (end events only) */
+    duration_ms?: number;
+    /** Parent event ID for nested tool calls (e.g., task → subagent tools) */
+    parent?: string;
+    /** Error message (error events only) */
+    error?: string;
+}
+/**
+ * Checks if debug mode is enabled (any mode except "off").
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Summarize data for debug output.
+ * - Truncates strings to 1000 chars
+ * - Limits arrays to 10 items
+ * - Recursively summarizes nested objects
+ */
+export declare function summarize(data: unknown, depth?: number): unknown;
+/**
+ * Record the start of a tool execution.
+ * @returns Event ID to correlate with debugEnd/debugError
+ */
+export declare function debugStart(tool: string, input?: Record<string, unknown>): string;
+/**
+ * Record the successful end of a tool execution.
+ */
+export declare function debugEnd(id: string, tool: string, options: {
+    output?: unknown;
+    summary?: Record<string, unknown>;
+    duration_ms: number;
+}): void;
+/**
+ * Record an error during tool execution.
+ */
+export declare function debugError(id: string, tool: string, error: string | Error): void;
+/**
+ * Push a parent context for nested tool calls (e.g., when Task starts a subagent).
+ */
+export declare function pushParent(id: string): void;
+/**
+ * Pop the current parent context.
+ */
+export declare function popParent(): void;
+/**
+ * Get all debug logs (memory mode only).
+ * @returns Array of debug events, or empty array if not in memory mode
+ */
+export declare function getDebugLogs(): DebugEvent[];
+/**
+ * Clear all debug logs (memory mode).
+ * Call this between agent runs to reset the trace.
+ */
+export declare function clearDebugLogs(): void;
+/**
+ * Force re-initialization of debug mode from environment.
+ * Useful for testing or when environment changes.
+ */
+export declare function reinitDebugMode(): void;

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
 export { type CompactConversationConfig, type CompactConversationResult, type CompactConversationState, compactConversation, createCompactConfig, MODEL_CONTEXT_LIMITS, type ModelContextLimit, } from "./compact-conversation";
 export { type ContextMetrics, type ContextStatus, type ContextStatusConfig, type ContextStatusLevel, contextNeedsAttention, contextNeedsCompaction, getContextStatus, } from "./context-status";
+export { type DebugEvent, clearDebugLogs, getDebugLogs, isDebugEnabled, reinitDebugMode, } from "./debug";
 export { estimateMessagesTokens, estimateMessageTokens, estimateTokens, type PruneMessagesConfig, pruneMessagesByTokens, } from "./prune-messages";