@fronx/use-claude-code 0.1.0

package/README.md

@@ -0,0 +1,273 @@
+# @anthropic/claude-code-lib
+
+A reusable library for integrating Claude Code CLI conversations into applications.
+
+## Features
+
+- **Server-side**: Spawn and manage Claude CLI processes, handle conversation lifecycle, stream responses via SSE
+- **Client-side**: Parse SSE streams, manage connection state, handle reconnection with exponential backoff
+- **React**: `useClaudeConversation` hook for easy integration
+
+## Installation
+
+```bash
+npm install @anthropic/claude-code-lib
+```
+
+## Usage
+
+### Server (Node.js)
+
+```typescript
+import { ClaudeManager } from '@anthropic/claude-code-lib/server';
+
+const manager = new ClaudeManager({
+  sessionDir: './data/sessions',
+});
+
+// Start a conversation
+const conversation = manager.start('user-123', {
+  systemPrompt: 'You are a helpful assistant.',
+  cwd: process.cwd(),
+  initialMessage: 'Hello!',
+});
+
+// Subscribe to SSE events
+conversation.subscribe(res);
+
+// Send additional messages
+conversation.send('How does this work?');
+
+// Stop generation (SIGINT)
+conversation.stop();
+
+// Clear conversation
+manager.clear('user-123');
+```
+
+### Client (Browser)
+
+```typescript
+import { ClaudeConnection } from '@anthropic/claude-code-lib/client';
+
+const connection = new ClaudeConnection({
+  baseUrl: '/api/claude',
+  conversationId: 'user-123',
+});
+
+connection.on('stateChange', () => {
+  console.log('Messages:', connection.messages);
+  console.log('Streaming:', connection.streamingSegments);
+});
+
+connection.on('result', () => {
+  console.log('Response complete');
+});
+
+// Check status and connect
+await connection.connect();
+
+// Start a new conversation
+await connection.start('Hello!');
+
+// Send a message
+await connection.send('How does this work?');
+
+// Stop generation
+await connection.stop();
+
+// Clear session
+await connection.clear();
+```
+
+### React
+
+```tsx
+import { useClaudeConversation } from '@anthropic/claude-code-lib/react';
+
+function Chat({ projectId }) {
+  const {
+    messages,
+    status,
+    isStreaming,
+    streamingSegments,
+    hasPersistedSession,
+    start,
+    send,
+    stop,
+    clear,
+    resume,
+  } = useClaudeConversation({
+    baseUrl: '/api/claude',
+    conversationId: projectId,
+    onResult: () => console.log('Response complete'),
+  });
+
+  return (
+    <div>
+      {/* Completed messages */}
+      {messages.map(msg => (
+        <div key={msg.id} className={msg.role}>
+          {msg.content}
+        </div>
+      ))}
+
+      {/* Streaming content */}
+      {streamingSegments.map((seg, i) =>
+        seg.type === 'text' ? (
+          <div key={i}>{seg.content}</div>
+        ) : (
+          <div key={i}>Running: {seg.name} {seg.param}</div>
+        )
+      )}
+
+      {/* Resume link for persisted sessions */}
+      {status === 'disconnected' && hasPersistedSession && (
+        <button onClick={resume}>Resume Previous Session</button>
+      )}
+
+      {/* Controls */}
+      <input type="text" id="message" />
+      <button onClick={() => send(document.getElementById('message').value)}>
+        Send
+      </button>
+      {isStreaming && <button onClick={stop}>Stop</button>}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Server
+
+#### `ClaudeManager`
+
+Main class for managing Claude conversations.
+
+```typescript
+interface ClaudeManagerConfig {
+  sessionDir: string;           // Where to persist sessions
+  claudePath?: string;          // Path to claude CLI (default: 'claude')
+  defaultAllowedTools?: string[]; // Default tools to allow
+  autoPrewarm?: boolean;        // Auto-prewarm after clear (default: false)
+}
+
+interface StartOptions {
+  systemPrompt: string | { file: string };
+  cwd: string;
+  allowedTools?: string[];
+  initialMessage?: string;
+}
+```
+
+Methods:
+- `start(id, options)` - Start a new conversation
+- `get(id)` - Get an active conversation
+- `resume(id, options)` - Resume from persisted session
+- `stop(id)` - Stop current response (SIGINT)
+- `clear(id)` - Kill process and delete session
+- `prewarm(id, options)` - Spawn without sending message
+- `getStatus(id)` - Get conversation status
+- `hasPersistedSession(id)` - Check for saved session
+
+### Client
+
+#### `ClaudeConnection`
+
+Event-emitter based connection manager.
+
+```typescript
+interface ClaudeConnectionConfig {
+  baseUrl: string;
+  conversationId: string;
+  reconnect?: {
+    maxRetries?: number;    // Default: 10
+    baseDelay?: number;     // Default: 1000ms
+    maxDelay?: number;      // Default: 30000ms
+  };
+}
+```
+
+Properties (read-only):
+- `status` - 'checking' | 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+- `messages` - Array of completed messages
+- `isStreaming` - Whether currently streaming
+- `streamingSegments` - Current streaming content (text and tools)
+- `hasPersistedSession` - Whether a saved session exists
+- `lastError` - Most recent error
+
+Methods:
+- `connect()` - Check status and connect
+- `disconnect()` - Close connection
+- `start(message?)` - Start new conversation
+- `send(message)` - Send message
+- `stop()` - Stop generation
+- `clear()` - Clear session
+- `resume()` - Resume saved session
+- `prewarm()` - Prewarm for faster response
+
+Events:
+- `stateChange` - Any state property changed
+- `message` - New message added
+- `streaming` - Streaming segments updated
+- `tool` - Tool invocation
+- `result` - Response complete
+- `error` - Error occurred
+
+### React
+
+#### `useClaudeConversation`
+
+```typescript
+interface UseClaudeConversationOptions {
+  baseUrl: string;
+  conversationId: string;
+  autoConnect?: boolean;    // Default: true
+  reconnect?: ReconnectConfig;
+  onResult?: () => void;    // Called when response completes
+}
+```
+
+Returns all ClaudeConnection properties and methods as React state.
+
+## HTTP API
+
+The package expects these server endpoints:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/:id/status` | GET | Check conversation status |
+| `/:id/start` | POST | Start new conversation |
+| `/:id/connect` | GET | SSE stream for updates |
+| `/:id/message` | POST | Send message |
+| `/:id/stop` | POST | Stop generation |
+| `/:id/clear` | POST | Clear session |
+| `/:id/resume` | POST | Resume saved session |
+| `/:id/prewarm` | POST | Prewarm conversation |
+
+## Architecture
+
+### Streaming
+
+When Claude runs tools, the streaming behavior differs from simple responses:
+
+1. `assistant` events stream the **full** response content
+2. `result` events may only contain the **final** portion after tool execution
+
+The state machine accumulates streaming content correctly. Always use `streamingSegments` for display, not just the `result` event.
+
+### Session Persistence
+
+Sessions are saved to disk after each message, enabling:
+- Resume after page reload
+- Resume after server restart
+- Multi-device continuation
+
+### Prewarming
+
+Call `prewarm()` before the user is likely to start a conversation. This spawns Claude without sending a message, making the first response faster.
+
+## License
+
+MIT

package/dist/client/connection.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ClaudeConnection - Framework-agnostic core for Claude Code integration.
+ *
+ * Handles:
+ * - Dual-connection pattern: POST+SSE for start/resume, then EventSource for ongoing
+ * - Reconnection with exponential backoff
+ * - Session ID filtering to ignore stale events after clear
+ * - Streaming segments accumulation (text interleaved with tools)
+ */
+import { EventEmitter } from './event-emitter.js';
+import { type ConnectionStatus } from './state-machine.js';
+import type { Message, StreamSegment, ClaudeError, ReconnectConfig } from '../shared/types.js';
+export interface ClaudeConnectionConfig {
+    baseUrl: string;
+    conversationId: string;
+    reconnect?: ReconnectConfig;
+}
+export interface ClaudeConnectionEvents {
+    stateChange: () => void;
+    message: (message: Message) => void;
+    streaming: (segments: StreamSegment[]) => void;
+    tool: (tool: {
+        name: string;
+        param?: string;
+    }) => void;
+    result: () => void;
+    error: (error: ClaudeError) => void;
+}
+/**
+ * ClaudeConnection manages the connection to a Claude conversation.
+ *
+ * @example
+ * const connection = new ClaudeConnection({
+ *   baseUrl: '/api/claude',
+ *   conversationId: 'user-123',
+ * });
+ *
+ * connection.on('message', (msg) => console.log(msg));
+ * connection.on('result', () => console.log('Response complete'));
+ * connection.connect();
+ *
+ * // Later
+ * await connection.send('Hello!');
+ */
+export declare class ClaudeConnection extends EventEmitter<ClaudeConnectionEvents> {
+    private config;
+    private reconnectConfig;
+    private eventSource;
+    private state;
+    private needNewTextSegment;
+    private reconnectAttempt;
+    constructor(config: ClaudeConnectionConfig);
+    get status(): ConnectionStatus;
+    get messages(): Message[];
+    get isStreaming(): boolean;
+    get streamingSegments(): StreamSegment[];
+    get hasPersistedSession(): boolean;
+    get lastError(): ClaudeError | null;
+    /**
+     * Check status and connect if active.
+     * Call this on mount to restore state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the conversation.
+     */
+    disconnect(): void;
+    /**
+     * Start a new conversation.
+     */
+    start(initialMessage?: string): Promise<void>;
+    /**
+     * Send a message in an active conversation.
+     */
+    send(message: string): Promise<void>;
+    /**
+     * Stop the current response generation (SIGINT).
+     */
+    stop(): Promise<void>;
+    /**
+     * Clear the session history and delete persisted session.
+     */
+    clear(): Promise<void>;
+    /**
+     * Resume a persisted session.
+     */
+    resume(): Promise<void>;
+    /**
+     * Prewarm the conversation for faster first response.
+     */
+    prewarm(): Promise<void>;
+    private updateState;
+    private handleEvent;
+    private processResponseStream;
+    private connectEventSource;
+    private closeEventSource;
+    private attemptReconnect;
+    private calculateRetryDelay;
+    private sleep;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/client/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/client/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAEL,KAAK,gBAAgB,EAStB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAY,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQzG,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,SAAS,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAC/C,IAAI,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACvD,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;IACxE,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,kBAAkB,CAAQ;IAClC,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,MAAM,EAAE,sBAAsB;IAW1C,IAAI,MAAM,IAAI,gBAAgB,CAE7B;IAED,IAAI,QAAQ,IAAI,OAAO,EAAE,CAExB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,iBAAiB,IAAI,aAAa,EAAE,CAEvC;IAED,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED,IAAI,SAAS,IAAI,WAAW,GAAG,IAAI,CAElC;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACG,KAAK,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BnD;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B1C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B7B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,WAAW;YAiBL,qBAAqB;IA8BnC,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,gBAAgB;YAOV,gBAAgB;IAmD9B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,KAAK;CAGd"}