@bytespell/amux-client 0.0.28 → 0.0.30

package/dist/accumulator.d.ts

@@ -0,0 +1,77 @@
+import type { SessionUpdate } from '@bytespell/amux-types';
+import type { Message, Turn } from './types.js';
+/**
+ * Message and Turn accumulator
+ *
+ * Processes streaming session updates and builds structured conversation data.
+ */
+export declare class Accumulator {
+    private _messages;
+    private _turns;
+    private _currentTurn;
+    /**
+     * All accumulated messages
+     */
+    get messages(): Message[];
+    /**
+     * All turns (grouped user/assistant pairs)
+     */
+    get turns(): Turn[];
+    /**
+     * Current active turn (if streaming)
+     */
+    get currentTurn(): Turn | null;
+    /**
+     * Last user message
+     */
+    get lastUserMessage(): Message | null;
+    /**
+     * Last assistant message
+     */
+    get lastAssistantMessage(): Message | null;
+    /**
+     * Start a new turn
+     */
+    startTurn(): void;
+    /**
+     * End the current turn
+     */
+    endTurn(): void;
+    /**
+     * Set turn status to awaiting permission
+     */
+    setAwaitingPermission(): void;
+    /**
+     * Resume streaming after permission
+     */
+    resumeStreaming(): void;
+    /**
+     * Process a session update
+     */
+    processUpdate(update: SessionUpdate): void;
+    /**
+     * Process user message chunk
+     */
+    private processUserChunk;
+    /**
+     * Process assistant message chunk
+     */
+    private processAssistantChunk;
+    /**
+     * Process tool call
+     */
+    private processToolCall;
+    /**
+     * Process tool call update
+     */
+    private processToolCallUpdate;
+    /**
+     * Replay history events
+     */
+    replayHistory(events: unknown[]): void;
+    /**
+     * Clear all accumulated data
+     */
+    clear(): void;
+}
+//# sourceMappingURL=accumulator.d.ts.map

package/dist/client.d.ts

@@ -0,0 +1,155 @@
+import type { AgentInfo, ModelInfo, SessionMetadata } from '@bytespell/amux-types';
+import type { AmuxClientOptions, AmuxClientEvents, ConnectionStatus, Message, Turn } from './types.js';
+/**
+ * AmuxClient - WebSocket client for consuming amux
+ *
+ * Provides:
+ * - Connection management with auto-reconnect
+ * - Type-safe event subscription
+ * - Command methods for server interaction
+ * - Message accumulation for UI rendering
+ *
+ * @example
+ * ```typescript
+ * const client = new AmuxClient({ url: 'ws://localhost:3000/ws' });
+ *
+ * client.on('ready', (data) => console.log('Ready:', data.cwd));
+ * client.on('update', (update) => console.log('Update:', update));
+ *
+ * client.connect();
+ * client.prompt('Hello!');
+ * ```
+ */
+export declare class AmuxClient {
+    private connection;
+    private accumulator;
+    private handlers;
+    private _cwd;
+    private _sessionId;
+    private _agent;
+    private _availableAgents;
+    private _availableModels;
+    private _currentModelId;
+    private _capabilities;
+    private _sessions;
+    private _isReady;
+    private _isProcessing;
+    private _pendingPermission;
+    constructor(options: AmuxClientOptions);
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): void;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Whether WebSocket is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Whether client is ready (connected and received 'ready' event)
+     */
+    get isReady(): boolean;
+    /**
+     * Current connection status
+     */
+    get connectionStatus(): ConnectionStatus;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof AmuxClientEvents>(event: K, handler: (data: AmuxClientEvents[K]) => void): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends keyof AmuxClientEvents>(event: K, handler: (data: AmuxClientEvents[K]) => void): void;
+    /**
+     * Emit an event to handlers
+     */
+    private emit;
+    /** Current working directory */
+    get cwd(): string | null;
+    /** Current session ID */
+    get sessionId(): string | null;
+    /** Current agent info */
+    get agent(): AgentInfo | null;
+    /** Available agents */
+    get availableAgents(): Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Available models */
+    get availableModels(): ModelInfo[];
+    /** Current model ID */
+    get currentModelId(): string | null;
+    /** Agent capabilities */
+    get capabilities(): unknown;
+    /** List of sessions (from list_sessions response) */
+    get sessions(): SessionMetadata[];
+    /** Whether currently processing a turn */
+    get isProcessing(): boolean;
+    /** Whether agent is actively streaming */
+    get isStreaming(): boolean;
+    /** Whether blocked on permission request */
+    get isAwaitingPermission(): boolean;
+    /** Current pending permission request */
+    get pendingPermission(): AmuxClientEvents['permission_request'] | null;
+    /** All accumulated messages */
+    get messages(): Message[];
+    /** All turns */
+    get turns(): Turn[];
+    /** Current active turn */
+    get currentTurn(): Turn | null;
+    /** Last user message */
+    get lastUserMessage(): Message | null;
+    /** Last assistant message */
+    get lastAssistantMessage(): Message | null;
+    /**
+     * Send a prompt to the agent
+     */
+    prompt(message: string): void;
+    /**
+     * Cancel current operation
+     */
+    cancel(): void;
+    /**
+     * Respond to a permission request
+     */
+    respondToPermission(requestId: string, optionId: string): void;
+    /**
+     * Change working directory
+     */
+    changeCwd(path: string): void;
+    /**
+     * Create a new session
+     */
+    newSession(): void;
+    /**
+     * Change agent type
+     */
+    changeAgent(agentType: string): void;
+    /**
+     * Set session mode
+     */
+    setMode(modeId: string): void;
+    /**
+     * Set model
+     */
+    setModel(modelId: string): void;
+    /**
+     * Request list of sessions
+     */
+    requestSessions(): void;
+    /**
+     * Switch to a different session
+     */
+    switchSession(sessionId: string): void;
+    /**
+     * Request history for current session
+     */
+    requestHistory(): void;
+    private handleMessage;
+    private handleStatusChange;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/connection.d.ts

@@ -0,0 +1,81 @@
+import type { ClientMessage, ServerMessage } from '@bytespell/amux-types';
+import type { ConnectionStatus } from './types.js';
+/**
+ * Event handler types for Connection
+ */
+export interface ConnectionEvents {
+    open: () => void;
+    close: (event: {
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }) => void;
+    message: (message: ServerMessage) => void;
+    error: (error: Event) => void;
+    status: (status: ConnectionStatus) => void;
+}
+/**
+ * Connection options
+ */
+export interface ConnectionOptions {
+    url: string;
+    reconnect?: boolean;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+}
+/**
+ * WebSocket connection manager with auto-reconnect
+ */
+export declare class Connection {
+    private ws;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private _status;
+    private handlers;
+    private readonly url;
+    private readonly reconnect;
+    private readonly reconnectInterval;
+    private readonly maxReconnectAttempts;
+    constructor(options: ConnectionOptions);
+    /**
+     * Current connection status
+     */
+    get status(): ConnectionStatus;
+    /**
+     * Whether the connection is open
+     */
+    get isConnected(): boolean;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof ConnectionEvents>(event: K, handler: ConnectionEvents[K]): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof ConnectionEvents>(event: K, handler: ConnectionEvents[K]): void;
+    /**
+     * Emit event to handlers
+     */
+    private emit;
+    /**
+     * Set and emit status change
+     */
+    private setStatus;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): void;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Send a message to the server
+     */
+    send(message: ClientMessage): void;
+    /**
+     * Schedule a reconnection attempt
+     */
+    private scheduleReconnect;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @bytespell/amux-client
+ *
+ * Client library for consuming amux over WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { AmuxClient } from '@bytespell/amux-client';
+ *
+ * const client = new AmuxClient({ url: 'ws://localhost:3000/ws' });
+ *
+ * client.on('ready', (data) => {
+ *   console.log('Ready:', data.cwd);
+ * });
+ *
+ * client.on('update', (update) => {
+ *   console.log('Update:', update);
+ * });
+ *
+ * client.connect();
+ * client.prompt('Hello!');
+ * ```
+ *
+ * For React integration, use:
+ * ```typescript
+ * import { AmuxProvider, useAmux } from '@bytespell/amux-client/react';
+ * ```
+ */
+export { AmuxClient } from './client.js';
+export { Connection } from './connection.js';
+export type { ConnectionOptions, ConnectionEvents } from './connection.js';
+export { Accumulator } from './accumulator.js';
+export type { AmuxClientOptions, AmuxClientEvents, ConnectionStatus, Message, Turn, ToolCallState, ContentBlock, } from './types.js';
+export type { ServerMessage, ClientMessage, SessionUpdate, AgentInfo, ModelInfo, SessionMetadata, PermissionRequest, } from '@bytespell/amux-types';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/context.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+import { AmuxClient } from '../client.js';
+import type { AmuxClientOptions, ConnectionStatus, Message, Turn, PermissionOptionData } from '../types.js';
+import type { ModelInfo, SessionMetadata } from '@bytespell/amux-types';
+/**
+ * Amux context value
+ */
+export interface AmuxContextValue {
+    client: AmuxClient;
+    connectionStatus: ConnectionStatus;
+    isConnected: boolean;
+    isReady: boolean;
+    cwd: string | null;
+    sessionId: string | null;
+    agent: {
+        type: string;
+        name: string;
+    } | null;
+    availableAgents: Array<{
+        id: string;
+        name: string;
+    }>;
+    availableModels: ModelInfo[];
+    currentModelId: string | null;
+    sessions: SessionMetadata[];
+    isProcessing: boolean;
+    isStreaming: boolean;
+    isAwaitingPermission: boolean;
+    pendingPermission: {
+        requestId: string;
+        toolCall?: unknown;
+        options: PermissionOptionData[];
+    } | null;
+    messages: Message[];
+    turns: Turn[];
+    currentTurn: Turn | null;
+    error: string | null;
+}
+/**
+ * Props for AmuxProvider
+ */
+export interface AmuxProviderProps extends AmuxClientOptions {
+    children: React.ReactNode;
+}
+/**
+ * AmuxProvider - Provides AmuxClient to React components
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <AmuxProvider url="ws://localhost:3000/ws" autoConnect>
+ *       <Chat />
+ *     </AmuxProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function AmuxProvider({ children, ...options }: AmuxProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Get the Amux context value
+ * @throws Error if used outside AmuxProvider
+ */
+export declare function useAmuxContext(): AmuxContextValue;
+//# sourceMappingURL=context.d.ts.map

package/dist/react/hooks.d.ts

@@ -0,0 +1,211 @@
+import type { AmuxClientEvents, ConnectionStatus, Message, Turn, PermissionOptionData } from '../types.js';
+import type { AmuxClient } from '../client.js';
+import type { ModelInfo, SessionMetadata } from '@bytespell/amux-types';
+/**
+ * Get the AmuxClient instance
+ *
+ * @example
+ * ```tsx
+ * function Chat() {
+ *   const client = useAmux();
+ *
+ *   const handleSubmit = (message: string) => {
+ *     client.prompt(message);
+ *   };
+ *
+ *   return <ChatUI onSubmit={handleSubmit} />;
+ * }
+ * ```
+ */
+export declare function useAmux(): AmuxClient;
+/**
+ * State returned by useAmuxState
+ */
+export interface AmuxState {
+    connectionStatus: ConnectionStatus;
+    isConnected: boolean;
+    isReady: boolean;
+    cwd: string | null;
+    sessionId: string | null;
+    agent: {
+        type: string;
+        name: string;
+    } | null;
+    availableAgents: Array<{
+        id: string;
+        name: string;
+    }>;
+    sessions: SessionMetadata[];
+    error: string | null;
+}
+/**
+ * Get reactive session state
+ *
+ * @example
+ * ```tsx
+ * function StatusBar() {
+ *   const { isConnected, isReady, cwd, agent, error } = useAmuxState();
+ *
+ *   if (error) return <div className="error">{error}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {isReady ? `${agent?.name} @ ${cwd}` : 'Connecting...'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAmuxState(): AmuxState;
+/**
+ * Model state returned by useAmuxModels
+ */
+export interface AmuxModels {
+    availableModels: ModelInfo[];
+    currentModelId: string | null;
+}
+/**
+ * Get reactive model state
+ *
+ * @example
+ * ```tsx
+ * function ModelPicker() {
+ *   const { availableModels, currentModelId } = useAmuxModels();
+ *   const client = useAmux();
+ *
+ *   return (
+ *     <select
+ *       value={currentModelId ?? ''}
+ *       onChange={e => client.setModel(e.target.value)}
+ *     >
+ *       {availableModels.map(m => (
+ *         <option key={m.id} value={m.id}>{m.name}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAmuxModels(): AmuxModels;
+/**
+ * Status returned by useAmuxStatus
+ */
+export interface AmuxStatus {
+    isProcessing: boolean;
+    isStreaming: boolean;
+    isAwaitingPermission: boolean;
+    pendingPermission: {
+        requestId: string;
+        toolCall?: unknown;
+        options: PermissionOptionData[];
+    } | null;
+}
+/**
+ * Get reactive processing status
+ *
+ * @example
+ * ```tsx
+ * function ChatInput() {
+ *   const { isProcessing, isAwaitingPermission } = useAmuxStatus();
+ *   const disabled = isProcessing || isAwaitingPermission;
+ *
+ *   return <input disabled={disabled} ... />;
+ * }
+ * ```
+ */
+export declare function useAmuxStatus(): AmuxStatus;
+/**
+ * Messages state returned by useAmuxMessages
+ */
+export interface AmuxMessages {
+    messages: Message[];
+    turns: Turn[];
+    currentTurn: Turn | null;
+}
+/**
+ * Get reactive messages and turns
+ *
+ * @example
+ * ```tsx
+ * function MessageList() {
+ *   const { turns, currentTurn } = useAmuxMessages();
+ *
+ *   return (
+ *     <>
+ *       {turns.map(turn => (
+ *         <Turn key={turn.id} turn={turn} />
+ *       ))}
+ *       {currentTurn?.status === 'streaming' && <StreamingIndicator />}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAmuxMessages(): AmuxMessages;
+/**
+ * Subscribe to specific client events
+ *
+ * @example
+ * ```tsx
+ * function PermissionDialog() {
+ *   const [pending, setPending] = useState<PermissionRequest | null>(null);
+ *   const client = useAmux();
+ *
+ *   useAmuxEvent('permission_request', (req) => {
+ *     setPending(req);
+ *   });
+ *
+ *   const handleResponse = (optionId: string) => {
+ *     if (pending) {
+ *       client.respondToPermission(pending.requestId, optionId);
+ *       setPending(null);
+ *     }
+ *   };
+ *
+ *   if (!pending) return null;
+ *   return <Dialog options={pending.options} onSelect={handleResponse} />;
+ * }
+ * ```
+ */
+export declare function useAmuxEvent<K extends keyof AmuxClientEvents>(event: K, handler: (data: AmuxClientEvents[K]) => void): void;
+/**
+ * Get a function to send prompts
+ *
+ * @example
+ * ```tsx
+ * function ChatInput() {
+ *   const sendPrompt = useAmuxPrompt();
+ *   const [message, setMessage] = useState('');
+ *
+ *   const handleSubmit = () => {
+ *     sendPrompt(message);
+ *     setMessage('');
+ *   };
+ *
+ *   return <input value={message} onChange={e => setMessage(e.target.value)} onSubmit={handleSubmit} />;
+ * }
+ * ```
+ */
+export declare function useAmuxPrompt(): (message: string) => void;
+/**
+ * Clear the current error
+ *
+ * @example
+ * ```tsx
+ * function ErrorBanner() {
+ *   const { error } = useAmuxState();
+ *   const clearError = useAmuxClearError();
+ *
+ *   if (!error) return null;
+ *
+ *   return (
+ *     <div className="error">
+ *       {error}
+ *       <button onClick={clearError}>Dismiss</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAmuxClearError(): () => void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/react/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * React integration for @bytespell/amux-client
+ *
+ * @example
+ * ```tsx
+ * import { AmuxProvider, useAmux, useAmuxState, useAmuxMessages, useAmuxModels } from '@bytespell/amux-client/react';
+ *
+ * function App() {
+ *   return (
+ *     <AmuxProvider url="ws://localhost:3000/ws" autoConnect>
+ *       <Chat />
+ *     </AmuxProvider>
+ *   );
+ * }
+ *
+ * function Chat() {
+ *   const client = useAmux();
+ *   const { isReady, cwd, agent, error } = useAmuxState();
+ *   const { turns, currentTurn } = useAmuxMessages();
+ *   const { availableModels, currentModelId } = useAmuxModels();
+ *
+ *   // ...
+ * }
+ * ```
+ */
+export { AmuxProvider, useAmuxContext } from './context.js';
+export type { AmuxContextValue, AmuxProviderProps } from './context.js';
+export { useAmux, useAmuxState, useAmuxStatus, useAmuxMessages, useAmuxModels, useAmuxEvent, useAmuxPrompt, useAmuxClearError, } from './hooks.js';
+export type { AmuxState, AmuxStatus, AmuxMessages, AmuxModels } from './hooks.js';
+export type { ModelInfo, SessionMetadata } from '@bytespell/amux-types';
+export type { Turn, Message, ContentBlock, ToolCallState, ConnectionStatus } from '../types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+import type { SessionUpdate } from '@bytespell/amux-types';
+export type { SessionUpdate };
+/**
+ * Content block types for accumulated messages
+ */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    toolUseId: string;
+    content: unknown;
+    isError?: boolean;
+} | {
+    type: 'diff';
+    path: string;
+    oldText: string;
+    newText: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        mediaType: string;
+        data: string;
+    };
+};
+/**
+ * Accumulated message
+ */
+export interface Message {
+    id: string;
+    role: 'user' | 'assistant';
+    content: ContentBlock[];
+    status: 'streaming' | 'complete';
+    timestamp: number;
+}
+/**
+ * Tool call state tracking
+ */
+export interface ToolCallState {
+    id: string;
+    name: string;
+    input: unknown;
+    status: 'pending' | 'running' | 'complete' | 'error';
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Turn state - groups user message and assistant response
+ */
+export interface Turn {
+    id: string;
+    userMessage: Message | null;
+    assistantMessage: Message | null;
+    toolCalls: ToolCallState[];
+    status: 'idle' | 'streaming' | 'awaiting_permission' | 'complete';
+}
+/**
+ * Connection status
+ */
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'ready';
+/**
+ * Permission option (from server)
+ */
+export interface PermissionOptionData {
+    id?: string;
+    optionId?: string;
+    label?: string;
+    title?: string;
+    description?: string;
+}
+/**
+ * Client event types
+ */
+export interface AmuxClientEvents {
+    ready: {
+        cwd: string;
+        sessionId: string | null;
+        capabilities: unknown;
+        agent: {
+            type: string;
+            name: string;
+        };
+        availableAgents: Array<{
+            id: string;
+            name: string;
+        }>;
+        availableModels?: Array<{
+            id: string;
+            name: string;
+            provider?: string;
+            supportsThinking?: boolean;
+        }>;
+        currentModelId?: string;
+    };
+    connecting: Record<string, never>;
+    update: SessionUpdate;
+    turn_start: Record<string, never>;
+    turn_end: Record<string, never>;
+    permission_request: {
+        requestId: string;
+        toolCall?: unknown;
+        options: PermissionOptionData[];
+    };
+    prompt_complete: {
+        stopReason?: string;
+    };
+    session_created: {
+        sessionId: string | null;
+    };
+    session_switched: {
+        sessionId: string;
+    };
+    history_replay: {
+        previousSessionId: string;
+        events: unknown[];
+        eventCount: number;
+    };
+    history: {
+        events: unknown[];
+        sessionId: string | null;
+    };
+    sessions: {
+        sessions: unknown[];
+    };
+    error: {
+        message: string;
+    };
+    agent_exit: {
+        code: number | null;
+        signal: string | null;
+    };
+    connection_status: {
+        status: ConnectionStatus;
+    };
+    messages_updated: {
+        messages: Message[];
+    };
+    turns_updated: {
+        turns: Turn[];
+    };
+}
+/**
+ * Options for creating an AmuxClient
+ */
+export interface AmuxClientOptions {
+    /** WebSocket URL to connect to */
+    url: string;
+    /** Auto-connect on creation (default: true) */
+    autoConnect?: boolean;
+    /** Auto-reconnect on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Reconnect interval in ms (default: 1000) */
+    reconnectInterval?: number;
+    /** Max reconnect attempts (default: Infinity) */
+    maxReconnectAttempts?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytespell/amux-client",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Client library for consuming amux over WebSocket",
   "type": "module",
   "main": "dist/index.js",