@scottwalker/claude-connector 0.2.0 → 0.3.0

package/dist/client/chat-handle.js

@@ -0,0 +1,246 @@
+import { spawn } from 'node:child_process';
+import { Readable, Duplex } from 'node:stream';
+import { parseStreamLine } from '../parser/stream-parser.js';
+import { EVENT_TEXT, EVENT_TOOL_USE, EVENT_RESULT, EVENT_ERROR, EVENT_SYSTEM, CHAT_USER_MESSAGE, SIGNAL_SIGTERM, } from '../constants.js';
+/**
+ * Bidirectional streaming handle for real-time conversation.
+ *
+ * Uses `--input-format stream-json` to maintain a persistent CLI process.
+ * Send prompts with `.send()`, receive responses via callbacks or Node.js streams.
+ *
+ * ## Fluent callbacks
+ *
+ * ```ts
+ * const chat = claude.chat()
+ *   .on('text', (text) => process.stdout.write(text))
+ *   .on('result', (event) => console.log('Turn done'))
+ *
+ * await chat.send('What files are in src?')
+ * await chat.send('Fix the largest one')
+ * chat.end()
+ * ```
+ *
+ * ## Node.js Duplex stream
+ *
+ * ```ts
+ * const duplex = claude.chat().toDuplex()
+ * inputStream.pipe(duplex).pipe(process.stdout)
+ * ```
+ */
+export class ChatHandle {
+    child;
+    textCallbacks = [];
+    toolUseCallbacks = [];
+    resultCallbacks = [];
+    errorCallbacks = [];
+    systemCallbacks = [];
+    buffer = '';
+    _closed = false;
+    _sessionId = null;
+    _turnCount = 0;
+    constructor(executable, args, options) {
+        this.child = spawn(executable, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.startReading();
+    }
+    /** Session ID (populated after the first result). */
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Number of completed turns. */
+    get turnCount() {
+        return this._turnCount;
+    }
+    /** Whether the chat has been closed. */
+    get closed() {
+        return this._closed;
+    }
+    on(type, callback) {
+        switch (type) {
+            case EVENT_TEXT:
+                this.textCallbacks.push(callback);
+                break;
+            case EVENT_TOOL_USE:
+                this.toolUseCallbacks.push(callback);
+                break;
+            case EVENT_RESULT:
+                this.resultCallbacks.push(callback);
+                break;
+            case EVENT_ERROR:
+                this.errorCallbacks.push(callback);
+                break;
+            case EVENT_SYSTEM:
+                this.systemCallbacks.push(callback);
+                break;
+        }
+        return this;
+    }
+    /**
+     * Send a prompt and wait for the complete response.
+     * Returns the result event when this turn finishes.
+     *
+     * ```ts
+     * const result = await chat.send('Find bugs in auth.ts')
+     * console.log(result.durationMs)
+     *
+     * const result2 = await chat.send('Now fix them')
+     * ```
+     */
+    send(prompt) {
+        if (this._closed) {
+            return Promise.reject(new Error('Chat is closed'));
+        }
+        const message = JSON.stringify({ type: CHAT_USER_MESSAGE, content: prompt });
+        this.child.stdin.write(message + '\n');
+        return new Promise((resolve, reject) => {
+            const onResult = (event) => {
+                const idx = this.resultCallbacks.indexOf(onResult);
+                if (idx >= 0)
+                    this.resultCallbacks.splice(idx, 1);
+                resolve(event);
+            };
+            const onError = (event) => {
+                const idx = this.errorCallbacks.indexOf(onError);
+                if (idx >= 0)
+                    this.errorCallbacks.splice(idx, 1);
+                reject(new Error(event.message));
+            };
+            this.resultCallbacks.push(onResult);
+            this.errorCallbacks.push(onError);
+        });
+    }
+    /**
+     * Pipe text output to a writable stream.
+     * Returns the destination for chaining (Node.js convention).
+     *
+     * ```ts
+     * chat.pipe(process.stdout)
+     * chat.pipe(fs.createWriteStream('log.txt'))
+     * ```
+     */
+    pipe(dest) {
+        this.textCallbacks.push((text) => dest.write(text));
+        return dest;
+    }
+    /**
+     * Get a Node.js Readable that emits text chunks.
+     *
+     * ```ts
+     * claude.chat().toReadable().pipe(res)
+     * ```
+     */
+    toReadable() {
+        const readable = new Readable({
+            encoding: 'utf-8',
+            read() { },
+        });
+        this.textCallbacks.push((text) => readable.push(text));
+        this.child.on('close', () => readable.push(null));
+        return readable;
+    }
+    /**
+     * Get a Node.js Duplex stream.
+     * Write side accepts prompts (one per write). Read side emits text.
+     *
+     * ```ts
+     * const duplex = claude.chat().toDuplex()
+     * inputStream.pipe(duplex).pipe(process.stdout)
+     * ```
+     */
+    toDuplex() {
+        const chat = this;
+        const duplex = new Duplex({
+            encoding: 'utf-8',
+            write(chunk, _encoding, callback) {
+                const prompt = chunk.toString().trim();
+                if (prompt) {
+                    const message = JSON.stringify({ type: CHAT_USER_MESSAGE, content: prompt });
+                    chat.child.stdin.write(message + '\n');
+                }
+                callback();
+            },
+            read() { },
+        });
+        this.textCallbacks.push((text) => duplex.push(text));
+        this.child.on('close', () => duplex.push(null));
+        return duplex;
+    }
+    /**
+     * Close the chat gracefully — signals EOF to the CLI process.
+     */
+    end() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        if (this.child.stdin && !this.child.stdin.destroyed) {
+            this.child.stdin.end();
+        }
+    }
+    /**
+     * Abort the chat — kills the CLI process immediately.
+     */
+    abort() {
+        this._closed = true;
+        if (!this.child.killed) {
+            this.child.kill(SIGNAL_SIGTERM);
+        }
+    }
+    // ── Private ───────────────────────────────────────────────────────
+    startReading() {
+        this.child.stdout.on('data', (chunk) => {
+            this.buffer += chunk.toString('utf-8');
+            const lines = this.buffer.split('\n');
+            this.buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const event = parseStreamLine(trimmed);
+                if (event) {
+                    if (event.type === EVENT_RESULT) {
+                        this._sessionId = event.sessionId || this._sessionId;
+                        this._turnCount++;
+                    }
+                    this.dispatch(event);
+                }
+            }
+        });
+        // Flush remaining buffer on close
+        this.child.stdout.on('end', () => {
+            const trimmed = this.buffer.trim();
+            if (trimmed) {
+                const event = parseStreamLine(trimmed);
+                if (event)
+                    this.dispatch(event);
+            }
+        });
+    }
+    dispatch(event) {
+        switch (event.type) {
+            case EVENT_TEXT:
+                for (const cb of this.textCallbacks)
+                    cb(event.text);
+                break;
+            case EVENT_TOOL_USE:
+                for (const cb of this.toolUseCallbacks)
+                    cb(event);
+                break;
+            case EVENT_RESULT:
+                for (const cb of this.resultCallbacks)
+                    cb(event);
+                break;
+            case EVENT_ERROR:
+                for (const cb of this.errorCallbacks)
+                    cb(event);
+                break;
+            case EVENT_SYSTEM:
+                for (const cb of this.systemCallbacks)
+                    cb(event);
+                break;
+        }
+    }
+}
+//# sourceMappingURL=chat-handle.js.map

package/dist/client/chat-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-handle.js","sourceRoot":"","sources":["../../src/client/chat-handle.ts"],"names":[],"mappings":"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"}

package/dist/client/claude.d.ts

@@ -1,93 +1,92 @@
-import type { ClientOptions, QueryOptions, QueryResult, StreamEvent } from '../types/index.js';
+import type { ClientOptions, QueryOptions, QueryResult } from '../types/index.js';
 import type { SessionOptions } from '../types/session.js';
 import type { IExecutor } from '../executor/interface.js';
 import { type InitStage } from '../executor/sdk-executor.js';
+import { INIT_EVENT_STAGE, INIT_EVENT_READY, INIT_EVENT_ERROR } from '../constants.js';
 import { Session } from './session.js';
+import { StreamHandle } from './stream-handle.js';
+import { ChatHandle } from './chat-handle.js';
 import { type ScheduledJob } from '../scheduler/scheduler.js';
 /**
  * Main entry point for claude-connector.
  *
- * `Claude` is a **facade** that orchestrates the executor, argument builder,
- * and parsers behind a clean, minimal API.
- *
- * ## Execution modes
- *
- * - **CLI mode** (default): each query spawns a new `claude -p` process.
- *   Simple, no warm-up needed, but slower for interactive use.
- *
- * - **SDK mode** (`useSdk: true`): creates a persistent session via the
- *   Claude Agent SDK. First query requires warm-up (~5-10s), but subsequent
- *   queries are near-instant. Best for interactive and high-throughput use.
- *
  * @example
  * ```ts
- * // CLI mode (default)
  * const claude = new Claude({ model: 'sonnet' })
+ * const result = await claude.query('Fix bugs')
  *
- * // SDK mode (persistent session, fast queries)
- * const claude = new Claude({ useSdk: true, model: 'sonnet' })
- * claude.on('init:stage', (stage, msg) => console.log(`[${stage}] ${msg}`))
- * await claude.init()  // warm up once
- * const result = await claude.query('Fix bugs')  // fast!
+ * // Streaming with fluent API
+ * await claude.stream('Explain auth.ts')
+ *   .on('text', (t) => process.stdout.write(t))
+ *   .done()
+ *
+ * // Bidirectional chat
+ * const chat = claude.chat()
+ * await chat.send('What files are in src?')
+ * await chat.send('Fix the largest one')
+ * chat.end()
  * ```
  */
 export declare class Claude {
-    /** Frozen client-level options. */
     private readonly options;
-    /** Executor responsible for running CLI commands. */
     private readonly executor;
-    /** SdkExecutor reference (only when useSdk: true) for lifecycle control. */
     private readonly sdkExecutor;
     constructor(options?: ClientOptions, executor?: IExecutor);
     /**
      * Initialize the SDK session (warm up).
-     *
      * Only needed when `useSdk: true`. In CLI mode this is a no-op.
-     *
-     * Subscribe to initialization events before calling:
-     * ```ts
-     * claude.on('init:stage', (stage, message) => {
-     *   console.log(`[${stage}] ${message}`)
-     * })
-     * claude.on('init:ready', () => console.log('Ready!'))
-     * claude.on('init:error', (err) => console.error(err))
-     *
-     * await claude.init()
-     * ```
-     *
-     * Safe to call multiple times — only initializes once.
      */
     init(): Promise<void>;
     /** Whether the SDK session is initialized and ready (always true for CLI mode). */
     get ready(): boolean;
     /**
      * Subscribe to initialization events.
-     *
-     * Events:
-     * - `init:stage` `(stage: InitStage, message: string)` — progress updates
-     *    Stages: `'importing'` → `'creating'` → `'connecting'` → `'ready'`
-     * - `init:ready` — session is warm and queries will be fast
-     * - `init:error` `(error: Error)` — initialization failed
-     *
-     * Only meaningful when `useSdk: true`. In CLI mode, listeners are never called.
      */
-    on(event: 'init:stage', listener: (stage: InitStage, message: string) => void): this;
-    on(event: 'init:ready', listener: () => void): this;
-    on(event: 'init:error', listener: (error: Error) => void): this;
+    on(event: typeof INIT_EVENT_STAGE, listener: (stage: InitStage, message: string) => void): this;
+    on(event: typeof INIT_EVENT_READY, listener: () => void): this;
+    on(event: typeof INIT_EVENT_ERROR, listener: (error: Error) => void): this;
     on(event: string, listener: (...args: never[]) => void): this;
     /**
      * Execute a one-shot query and return the complete result.
-     *
-     * In SDK mode, auto-initializes if `init()` hasn't been called yet.
      */
     query(prompt: string, options?: QueryOptions): Promise<QueryResult>;
     /**
      * Execute a query with streaming response.
+     * Returns a {@link StreamHandle} with fluent callbacks, Node.js stream support,
+     * and backward-compatible async iteration.
      *
-     * Returns an async iterable that yields events as they arrive.
-     * The final event is always `type: 'result'` or `type: 'error'`.
+     * ```ts
+     * // Fluent
+     * await claude.stream('Fix bugs').on('text', t => process.stdout.write(t)).done()
+     *
+     * // Collect text
+     * const text = await claude.stream('Summarize').text()
+     *
+     * // Pipe
+     * const result = await claude.stream('Explain').pipe(process.stdout)
+     *
+     * // Node.js Readable
+     * claude.stream('Generate').toReadable().pipe(createWriteStream('out.txt'))
+     *
+     * // Raw iteration (backward compat)
+     * for await (const event of claude.stream('Analyze')) { ... }
+     * ```
      */
-    stream(prompt: string, options?: QueryOptions): AsyncIterable<StreamEvent>;
+    stream(prompt: string, options?: QueryOptions): StreamHandle;
+    /**
+     * Open a bidirectional chat — a persistent CLI process for real-time conversation.
+     * Uses `--input-format stream-json` for multi-turn dialogue over a single process.
+     *
+     * ```ts
+     * const chat = claude.chat()
+     *   .on('text', (t) => process.stdout.write(t))
+     *
+     * await chat.send('What files are in src?')
+     * await chat.send('Now fix the bugs')
+     * chat.end()
+     * ```
+     */
+    chat(options?: QueryOptions): ChatHandle;
     /**
      * Create a session for multi-turn conversation.
      */
@@ -109,7 +108,6 @@ export declare class Claude {
     abort(): void;
     /**
      * Close the SDK session and free resources.
-     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
      */
     close(): void;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAe,KAAK,SAAS,EAA2B,MAAM,6BAA6B,CAAC;AAGnG,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IACjB,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IAErC,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;gBAE5C,OAAO,GAAE,aAAkB,EAAE,QAAQ,CAAC,EAAE,SAAS;IA2B7D;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,mFAAmF;IACnF,IAAI,KAAK,IAAI,OAAO,CAGnB;IAED;;;;;;;;;;OAUG;IACH,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IACpF,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IACnD,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAC/D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAQ7D;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAmBzE;;;;;OAKG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC;IAmBjF;;OAEG;IACH,OAAO,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO;IAIjD;;OAEG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY;IAKrF;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,EAAE,GAC7D,OAAO,CAAC,WAAW,EAAE,CAAC;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,WAAW,IAAI,SAAS;CAGzB"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAe,KAAK,SAAS,EAA2B,MAAM,6BAA6B,CAAC;AAGnG,OAAO,EAIL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;gBAE5C,OAAO,GAAE,aAAkB,EAAE,QAAQ,CAAC,EAAE,SAAS;IA2B7D;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,mFAAmF;IACnF,IAAI,KAAK,IAAI,OAAO,CAGnB;IAED;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAC/F,EAAE,CAAC,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAC9D,EAAE,CAAC,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAC1E,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAQ7D;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAmBzE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY;IAsB5D;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,UAAU;IAwBxC;;OAEG;IACH,OAAO,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO;IAIjD;;OAEG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY;IAKrF;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,EAAE,GAC7D,OAAO,CAAC,WAAW,EAAE,CAAC;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,WAAW,IAAI,SAAS;CAGzB"}

package/dist/client/claude.js

@@ -2,46 +2,39 @@ import { CliExecutor } from '../executor/cli-executor.js';
 import { SdkExecutor } from '../executor/sdk-executor.js';
 import { buildArgs, mergeOptions, resolveEnv } from '../builder/args-builder.js';
 import { validateClientOptions, validateQueryOptions, validatePrompt } from '../utils/validation.js';
+import { FORMAT_JSON, FORMAT_STREAM_JSON, DEFAULT_EXECUTABLE, } from '../constants.js';
 import { Session } from './session.js';
+import { StreamHandle } from './stream-handle.js';
+import { ChatHandle } from './chat-handle.js';
 import { Scheduler } from '../scheduler/scheduler.js';
 /**
  * Main entry point for claude-connector.
  *
- * `Claude` is a **facade** that orchestrates the executor, argument builder,
- * and parsers behind a clean, minimal API.
- *
- * ## Execution modes
- *
- * - **CLI mode** (default): each query spawns a new `claude -p` process.
- *   Simple, no warm-up needed, but slower for interactive use.
- *
- * - **SDK mode** (`useSdk: true`): creates a persistent session via the
- *   Claude Agent SDK. First query requires warm-up (~5-10s), but subsequent
- *   queries are near-instant. Best for interactive and high-throughput use.
- *
  * @example
  * ```ts
- * // CLI mode (default)
  * const claude = new Claude({ model: 'sonnet' })
+ * const result = await claude.query('Fix bugs')
+ *
+ * // Streaming with fluent API
+ * await claude.stream('Explain auth.ts')
+ *   .on('text', (t) => process.stdout.write(t))
+ *   .done()
  *
- * // SDK mode (persistent session, fast queries)
- * const claude = new Claude({ useSdk: true, model: 'sonnet' })
- * claude.on('init:stage', (stage, msg) => console.log(`[${stage}] ${msg}`))
- * await claude.init()  // warm up once
- * const result = await claude.query('Fix bugs')  // fast!
+ * // Bidirectional chat
+ * const chat = claude.chat()
+ * await chat.send('What files are in src?')
+ * await chat.send('Fix the largest one')
+ * chat.end()
  * ```
  */
 export class Claude {
-    /** Frozen client-level options. */
     options;
-    /** Executor responsible for running CLI commands. */
     executor;
-    /** SdkExecutor reference (only when useSdk: true) for lifecycle control. */
     sdkExecutor = null;
     constructor(options = {}, executor) {
         validateClientOptions(options);
         this.options = Object.freeze({ ...options });
-        const useSdk = options.useSdk !== false; // default: true
+        const useSdk = options.useSdk !== false;
         if (executor) {
             this.executor = executor;
         }
@@ -66,21 +59,7 @@ export class Claude {
     }
     /**
      * Initialize the SDK session (warm up).
-     *
      * Only needed when `useSdk: true`. In CLI mode this is a no-op.
-     *
-     * Subscribe to initialization events before calling:
-     * ```ts
-     * claude.on('init:stage', (stage, message) => {
-     *   console.log(`[${stage}] ${message}`)
-     * })
-     * claude.on('init:ready', () => console.log('Ready!'))
-     * claude.on('init:error', (err) => console.error(err))
-     *
-     * await claude.init()
-     * ```
-     *
-     * Safe to call multiple times — only initializes once.
      */
     async init() {
         if (this.sdkExecutor) {
@@ -101,8 +80,6 @@ export class Claude {
     }
     /**
      * Execute a one-shot query and return the complete result.
-     *
-     * In SDK mode, auto-initializes if `init()` hasn't been called yet.
      */
     async query(prompt, options) {
         validatePrompt(prompt);
@@ -110,7 +87,7 @@ export class Claude {
             validateQueryOptions(options);
         const resolved = mergeOptions(this.options, options, {
             prompt,
-            outputFormat: 'json',
+            outputFormat: FORMAT_JSON,
         });
         const args = buildArgs(resolved);
         const env = resolveEnv(this.options, options);
@@ -123,25 +100,76 @@ export class Claude {
     }
     /**
      * Execute a query with streaming response.
+     * Returns a {@link StreamHandle} with fluent callbacks, Node.js stream support,
+     * and backward-compatible async iteration.
+     *
+     * ```ts
+     * // Fluent
+     * await claude.stream('Fix bugs').on('text', t => process.stdout.write(t)).done()
+     *
+     * // Collect text
+     * const text = await claude.stream('Summarize').text()
+     *
+     * // Pipe
+     * const result = await claude.stream('Explain').pipe(process.stdout)
+     *
+     * // Node.js Readable
+     * claude.stream('Generate').toReadable().pipe(createWriteStream('out.txt'))
      *
-     * Returns an async iterable that yields events as they arrive.
-     * The final event is always `type: 'result'` or `type: 'error'`.
+     * // Raw iteration (backward compat)
+     * for await (const event of claude.stream('Analyze')) { ... }
+     * ```
      */
-    async *stream(prompt, options) {
+    stream(prompt, options) {
         validatePrompt(prompt);
         if (options)
             validateQueryOptions(options);
         const resolved = mergeOptions(this.options, options, {
             prompt,
-            outputFormat: 'stream-json',
+            outputFormat: FORMAT_STREAM_JSON,
         });
         const args = buildArgs(resolved);
         const env = resolveEnv(this.options, options);
-        yield* this.executor.stream(args, {
+        const executor = this.executor;
+        const execOpts = {
             cwd: resolved.cwd,
             env,
             input: options?.input,
             systemPrompt: resolved.systemPrompt,
+        };
+        return new StreamHandle(() => executor.stream(args, execOpts));
+    }
+    /**
+     * Open a bidirectional chat — a persistent CLI process for real-time conversation.
+     * Uses `--input-format stream-json` for multi-turn dialogue over a single process.
+     *
+     * ```ts
+     * const chat = claude.chat()
+     *   .on('text', (t) => process.stdout.write(t))
+     *
+     * await chat.send('What files are in src?')
+     * await chat.send('Now fix the bugs')
+     * chat.end()
+     * ```
+     */
+    chat(options) {
+        if (options)
+            validateQueryOptions(options);
+        const resolved = mergeOptions(this.options, options, {
+            prompt: undefined,
+            outputFormat: FORMAT_STREAM_JSON,
+        });
+        // Override: chat mode uses bidirectional stream-json
+        const args = buildArgs({
+            ...resolved,
+            prompt: undefined,
+            inputFormat: FORMAT_STREAM_JSON,
+        });
+        const env = resolveEnv(this.options, options);
+        const executable = this.options.executable ?? DEFAULT_EXECUTABLE;
+        return new ChatHandle(executable, args, {
+            cwd: resolved.cwd,
+            env: { ...process.env, ...env },
         });
     }
     /**
@@ -171,7 +199,6 @@ export class Claude {
     }
     /**
      * Close the SDK session and free resources.
-     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
      */
     close() {
         if (this.sdkExecutor) {

package/dist/client/claude.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"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"}

package/dist/client/session.d.ts

@@ -1,6 +1,7 @@
-import type { ClientOptions, QueryOptions, QueryResult, StreamEvent } from '../types/index.js';
+import type { ClientOptions, QueryOptions, QueryResult } from '../types/index.js';
 import type { SessionOptions } from '../types/session.js';
 import type { IExecutor } from '../executor/interface.js';
+import { StreamHandle } from './stream-handle.js';
 /**
  * A stateful conversation session.
  *
@@ -52,8 +53,9 @@ export declare class Session {
     query(prompt: string, options?: QueryOptions): Promise<QueryResult>;
     /**
      * Send a query with streaming response within this session.
+     * Returns a {@link StreamHandle} with fluent callbacks and Node.js stream support.
      */
-    stream(prompt: string, options?: QueryOptions): AsyncIterable<StreamEvent>;
+    stream(prompt: string, options?: QueryOptions): StreamHandle;
     /**
      * Abort the current running query in this session.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD,6DAA6D;IAC7D,OAAO,CAAC,UAAU,CAAgB;IAElC,kDAAkD;IAClD,OAAO,CAAC,WAAW,CAAK;gBAGtB,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,EACtC,QAAQ,EAAE,SAAS,EACnB,cAAc,GAAE,cAAmB;IAQrC,iEAAiE;IACjE,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAsBzE;;OAEG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC;IAyBjF;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,kBAAkB;CAM3B"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAI1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD,6DAA6D;IAC7D,OAAO,CAAC,UAAU,CAAgB;IAElC,kDAAkD;IAClD,OAAO,CAAC,WAAW,CAAK;gBAGtB,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,EACtC,QAAQ,EAAE,SAAS,EACnB,cAAc,GAAE,cAAmB;IAQrC,iEAAiE;IACjE,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAsBzE;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY;IA8B5D;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,kBAAkB;CAM3B"}