@scottwalker/claude-connector 0.2.0 → 0.4.0

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')
  *
- * // 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 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;
         }
@@ -49,6 +42,7 @@ export class Claude {
             const sdkOpts = {
                 model: options.model,
                 pathToClaudeCodeExecutable: options.executable,
+                cwd: options.cwd,
                 permissionMode: options.permissionMode,
                 allowedTools: options.allowedTools ? [...options.allowedTools] : undefined,
                 disallowedTools: options.disallowedTools ? [...options.disallowedTools] : undefined,
@@ -56,6 +50,35 @@ export class Claude {
                 systemPrompt: options.systemPrompt,
                 appendSystemPrompt: options.appendSystemPrompt,
                 maxTurns: options.maxTurns,
+                maxBudget: options.maxBudget,
+                effortLevel: options.effortLevel,
+                fallbackModel: options.fallbackModel,
+                // New SDK-level options
+                canUseTool: options.canUseTool,
+                thinking: options.thinking,
+                enableFileCheckpointing: options.enableFileCheckpointing,
+                onElicitation: options.onElicitation,
+                hookCallbacks: options.hookCallbacks,
+                mcpServers: options.mcpServers,
+                agents: options.agents,
+                agent: options.agent,
+                tools: options.tools ? [...options.tools] : undefined,
+                additionalDirs: options.additionalDirs ? [...options.additionalDirs] : undefined,
+                noSessionPersistence: options.noSessionPersistence,
+                strictMcpConfig: options.strictMcpConfig,
+                betas: options.betas ? [...options.betas] : undefined,
+                includePartialMessages: options.includePartialMessages,
+                promptSuggestions: options.promptSuggestions,
+                agentProgressSummaries: options.agentProgressSummaries,
+                debug: options.debug,
+                debugFile: options.debugFile,
+                // New passthrough options
+                stderr: options.stderr,
+                allowDangerouslySkipPermissions: options.allowDangerouslySkipPermissions,
+                settingSources: options.settingSources,
+                settings: options.settings,
+                plugins: options.plugins,
+                spawnClaudeCodeProcess: options.spawnClaudeCodeProcess,
             };
             this.sdkExecutor = new SdkExecutor(sdkOpts);
             this.executor = this.sdkExecutor;
@@ -66,21 +89,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 +110,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 +117,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);
@@ -119,29 +126,56 @@ export class Claude {
             env,
             input: options?.input,
             systemPrompt: resolved.systemPrompt,
+            signal: options?.signal,
         });
     }
     /**
      * Execute a query with streaming response.
-     *
-     * Returns an async iterable that yields events as they arrive.
-     * The final event is always `type: 'result'` or `type: 'error'`.
+     * Returns a {@link StreamHandle} with fluent callbacks, Node.js stream support,
+     * and backward-compatible async iteration.
      */
-    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,
+            signal: options?.signal,
+        };
+        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.
+     */
+    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 +205,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) {
@@ -184,5 +217,118 @@ export class Claude {
     getExecutor() {
         return this.executor;
     }
+    // ── SDK Control Methods ─────────────────────────────────────────
+    // These methods delegate to the underlying SdkExecutor.
+    // In CLI mode they throw an error.
+    /**
+     * Change the model for subsequent responses.
+     * SDK mode only — throws in CLI mode.
+     */
+    async setModel(model) {
+        this.requireSdk('setModel');
+        await this.sdkExecutor.setModel(model);
+    }
+    /**
+     * Change the permission mode for the session.
+     * SDK mode only — throws in CLI mode.
+     */
+    async setPermissionMode(mode) {
+        this.requireSdk('setPermissionMode');
+        await this.sdkExecutor.setPermissionMode(mode);
+    }
+    /**
+     * Rewind files to their state at a specific user message.
+     * Requires `enableFileCheckpointing: true`.
+     * SDK mode only — throws in CLI mode.
+     */
+    async rewindFiles(userMessageId, options) {
+        this.requireSdk('rewindFiles');
+        return this.sdkExecutor.rewindFiles(userMessageId, options);
+    }
+    /**
+     * Stop a running subagent task.
+     * SDK mode only — throws in CLI mode.
+     */
+    async stopTask(taskId) {
+        this.requireSdk('stopTask');
+        await this.sdkExecutor.stopTask(taskId);
+    }
+    /**
+     * Dynamically set MCP servers for this session.
+     * SDK mode only — throws in CLI mode.
+     */
+    async setMcpServers(servers) {
+        this.requireSdk('setMcpServers');
+        return this.sdkExecutor.setMcpServers(servers);
+    }
+    /**
+     * Reconnect a disconnected MCP server.
+     * SDK mode only — throws in CLI mode.
+     */
+    async reconnectMcpServer(serverName) {
+        this.requireSdk('reconnectMcpServer');
+        await this.sdkExecutor.reconnectMcpServer(serverName);
+    }
+    /**
+     * Enable or disable an MCP server.
+     * SDK mode only — throws in CLI mode.
+     */
+    async toggleMcpServer(serverName, enabled) {
+        this.requireSdk('toggleMcpServer');
+        await this.sdkExecutor.toggleMcpServer(serverName, enabled);
+    }
+    /**
+     * Get account information (email, org, subscription).
+     * SDK mode only — throws in CLI mode.
+     */
+    async accountInfo() {
+        this.requireSdk('accountInfo');
+        return this.sdkExecutor.accountInfo();
+    }
+    /**
+     * Get available models with their capabilities.
+     * SDK mode only — throws in CLI mode.
+     */
+    async supportedModels() {
+        this.requireSdk('supportedModels');
+        return this.sdkExecutor.supportedModels();
+    }
+    /**
+     * Get available slash commands.
+     * SDK mode only — throws in CLI mode.
+     */
+    async supportedCommands() {
+        this.requireSdk('supportedCommands');
+        return this.sdkExecutor.supportedCommands();
+    }
+    /**
+     * Get available subagents.
+     * SDK mode only — throws in CLI mode.
+     */
+    async supportedAgents() {
+        this.requireSdk('supportedAgents');
+        return this.sdkExecutor.supportedAgents();
+    }
+    /**
+     * Get MCP server connection statuses.
+     * SDK mode only — throws in CLI mode.
+     */
+    async mcpServerStatus() {
+        this.requireSdk('mcpServerStatus');
+        return this.sdkExecutor.mcpServerStatus();
+    }
+    /**
+     * Interrupt the current query execution.
+     * SDK mode only — throws in CLI mode.
+     */
+    async interrupt() {
+        this.requireSdk('interrupt');
+        await this.sdkExecutor.interrupt();
+    }
+    requireSdk(method) {
+        if (!this.sdkExecutor) {
+            throw new Error(`${method}() is only available in SDK mode. Set useSdk: true (default) to use this method.`);
+        }
+    }
 }
 //# sourceMappingURL=claude.js.map

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":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAA2C,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACrG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,kBAAkB,GAInB,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,EAAE,SAAS,EAAqB,MAAM,2BAA2B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,MAAM;IACA,OAAO,CAA0B;IACjC,QAAQ,CAAY;IACpB,WAAW,GAAuB,IAAI,CAAC;IAExD,YAAY,UAAyB,EAAE,EAAE,QAAoB;QAC3D,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QAE7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC;QAExC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3B,CAAC;aAAM,IAAI,MAAM,EAAE,CAAC;YAClB,MAAM,OAAO,GAAuB;gBAClC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,0BAA0B,EAAE,OAAO,CAAC,UAAU;gBAC9C,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC1E,eAAe,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS;gBACnF,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;gBAC9C,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,wBAAwB;gBACxB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;gBACxD,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;gBACrD,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS;gBAChF,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;gBAClD,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;gBACrD,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;gBACtD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;gBAC5C,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;gBACtD,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,0BAA0B;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,+BAA+B,EAAE,OAAO,CAAC,+BAA+B;gBACxE,cAAc,EAAE,OAAO,CAAC,cAAc;gBACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,sBAAsB,EAAE,OAAO,CAAC,sBAAqE;aACtG,CAAC;YACF,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED,mFAAmF;IACnF,IAAI,KAAK;QACP,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IASD,EAAE,CAAC,KAAa,EAAE,QAAoC;QACpD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,KAAgC,EAAE,QAAuD,CAAC,CAAC;QACjH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,OAAsB;QAChD,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,OAAO;YAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE3C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE;YACnD,MAAM;YACN,YAAY,EAAE,WAAW;SAC1B,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAE9C,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE;YACjC,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,GAAG;YACH,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAc,EAAE,OAAsB;QAC3C,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,OAAO;YAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE3C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE;YACnD,MAAM;YACN,YAAY,EAAE,kBAAkB;SACjC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,MAAM,QAAQ,GAAG;YACf,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,GAAG;YACH,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC;QAEF,OAAO,IAAI,YAAY,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,OAAsB;QACzB,IAAI,OAAO;YAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE3C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE;YACnD,MAAM,EAAE,SAA8B;YACtC,YAAY,EAAE,kBAAkB;SACjC,CAAC,CAAC;QAEH,qDAAqD;QACrD,MAAM,IAAI,GAAG,SAAS,CAAC;YACrB,GAAG,QAAQ;YACX,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,kBAAkB;SAChC,CAAC,CAAC;QAEH,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;QAEjE,OAAO,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE;YACtC,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,EAA4B;SAC1D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,cAA+B;QACrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,QAAyB,EAAE,MAAc,EAAE,OAAsB;QACpE,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CACZ,OAA8D;QAE9D,OAAO,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAClE,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,mEAAmE;IACnE,wDAAwD;IACxD,mCAAmC;IAEnC;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAc;QAC3B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC5B,MAAM,IAAI,CAAC,WAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB,CAAC,IAAoB;QAC1C,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;QACrC,MAAM,IAAI,CAAC,WAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,aAAqB,EAAE,OAA8B;QACrE,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC,WAAY,CAAC,WAAW,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAc;QAC3B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC5B,MAAM,IAAI,CAAC,WAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,OAA6D;QAC/E,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,WAAY,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,kBAAkB,CAAC,UAAkB;QACzC,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;QACtC,MAAM,IAAI,CAAC,WAAY,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACzD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,UAAkB,EAAE,OAAgB;QACxD,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACnC,MAAM,IAAI,CAAC,WAAY,CAAC,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC,WAAY,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,WAAY,CAAC,eAAe,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB;QACrB,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,WAAY,CAAC,iBAAiB,EAAE,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,WAAY,CAAC,eAAe,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,WAAY,CAAC,eAAe,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAC7B,MAAM,IAAI,CAAC,WAAY,CAAC,SAAS,EAAE,CAAC;IACtC,CAAC;IAEO,UAAU,CAAC,MAAc;QAC/B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,kFAAkF,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC;CACF"}

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"}

package/dist/client/session.js

@@ -1,5 +1,7 @@
 import { buildArgs, mergeOptions, resolveEnv } from '../builder/args-builder.js';
 import { validateQueryOptions, validatePrompt } from '../utils/validation.js';
+import { FORMAT_JSON, FORMAT_STREAM_JSON, EVENT_RESULT } from '../constants.js';
+import { StreamHandle } from './stream-handle.js';
 /**
  * A stateful conversation session.
  *
@@ -61,11 +63,11 @@ export class Session {
         validatePrompt(prompt);
         if (options)
             validateQueryOptions(options);
-        const args = this.buildSessionArgs(prompt, 'json', options);
+        const args = this.buildSessionArgs(prompt, FORMAT_JSON, options);
         const env = resolveEnv(this.clientOptions, options);
         const resolved = mergeOptions(this.clientOptions, options, {
             prompt,
-            outputFormat: 'json',
+            outputFormat: FORMAT_JSON,
         });
         const result = await this.executor.execute(args, {
             cwd: resolved.cwd,
@@ -78,29 +80,34 @@ export class Session {
     }
     /**
      * Send a query with streaming response within this session.
+     * Returns a {@link StreamHandle} with fluent callbacks and Node.js stream support.
      */
-    async *stream(prompt, options) {
+    stream(prompt, options) {
         validatePrompt(prompt);
         if (options)
             validateQueryOptions(options);
-        const args = this.buildSessionArgs(prompt, 'stream-json', options);
+        const args = this.buildSessionArgs(prompt, FORMAT_STREAM_JSON, options);
         const env = resolveEnv(this.clientOptions, options);
         const resolved = mergeOptions(this.clientOptions, options, {
             prompt,
-            outputFormat: 'stream-json',
+            outputFormat: FORMAT_STREAM_JSON,
         });
-        for await (const event of this.executor.stream(args, {
+        const executor = this.executor;
+        const updateState = (id) => this.updateSessionState(id);
+        const execOpts = {
             cwd: resolved.cwd,
             env,
             input: options?.input,
             systemPrompt: resolved.systemPrompt,
-        })) {
-            // Capture session ID from result events
-            if (event.type === 'result' && event.sessionId) {
-                this.updateSessionState(event.sessionId);
+        };
+        return new StreamHandle(async function* () {
+            for await (const event of executor.stream(args, execOpts)) {
+                if (event.type === EVENT_RESULT && event.sessionId) {
+                    updateState(event.sessionId);
+                }
+                yield event;
             }
-            yield event;
-        }
+        });
     }
     /**
      * Abort the current running query in this session.

package/dist/client/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,OAAO;IACD,aAAa,CAA0B;IACvC,QAAQ,CAAY;IACpB,cAAc,CAAiB;IAEhD,6DAA6D;IACrD,UAAU,CAAgB;IAElC,kDAAkD;IAC1C,WAAW,GAAG,CAAC,CAAC;IAExB,YACE,aAAsC,EACtC,QAAmB,EACnB,iBAAiC,EAAE;QAEnC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,cAAc,CAAC,MAAM,IAAI,IAAI,CAAC;IAClD,CAAC;IAED,iEAAiE;IACjE,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,yCAAyC;IACzC,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,OAAsB;QAChD,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,OAAO;YAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE3C,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE;YACzD,MAAM;YACN,YAAY,EAAE,WAAW;SAC1B,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE;YAC/C,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,GAAG;YACH,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;SACpC,CAAC,CAAC;QAEH,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAAc,EAAE,OAAsB;QAC3C,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,IAAI,OAAO;YAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE3C,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACxE,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE;YACzD,MAAM;YACN,YAAY,EAAE,kBAAkB;SACjC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,MAAM,WAAW,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG;YACf,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,GAAG;YACH,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;SACpC,CAAC;QAEF,OAAO,IAAI,YAAY,CAAC,KAAK,SAAS,CAAC;YACrC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC1D,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oBACnD,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC/B,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;IAC1B,CAAC;IAED,qEAAqE;IAE7D,gBAAgB,CACtB,MAAc,EACd,YAAoC,EACpC,YAA2B;QAE3B,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,KAAK,CAAC,CAAC;QAE5C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,EAAE;YAC9D,MAAM;YACN,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,UAAU,IAAI,SAAS;YACvC,eAAe,EAAE,YAAY,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ;YAC7D,WAAW,EAAE,YAAY,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI;SACtD,CAAC,CAAC;QAEH,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAEO,kBAAkB,CAAC,SAAiB;QAC1C,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/client/stream-handle.d.ts

@@ -0,0 +1,99 @@
+import { Readable } from 'node:stream';
+import { EVENT_TEXT, EVENT_TOOL_USE, EVENT_RESULT, EVENT_ERROR, EVENT_SYSTEM, EVENT_TASK_STARTED, EVENT_TASK_PROGRESS, EVENT_TASK_NOTIFICATION } from '../constants.js';
+import type { StreamEvent, StreamToolUseEvent, StreamResultEvent, StreamErrorEvent, StreamSystemEvent, StreamTaskStartedEvent, StreamTaskProgressEvent, StreamTaskNotificationEvent } from '../types/index.js';
+type TextCallback = (text: string) => void;
+type ToolUseCallback = (event: StreamToolUseEvent) => void;
+type ResultCallback = (event: StreamResultEvent) => void;
+type ErrorCallback = (event: StreamErrorEvent) => void;
+type SystemCallback = (event: StreamSystemEvent) => void;
+type TaskStartedCallback = (event: StreamTaskStartedEvent) => void;
+type TaskProgressCallback = (event: StreamTaskProgressEvent) => void;
+type TaskNotificationCallback = (event: StreamTaskNotificationEvent) => void;
+/**
+ * A streaming response handle with fluent callback API and Node.js stream support.
+ *
+ * ## 1. Fluent callbacks
+ *
+ * ```ts
+ * await claude.stream('Refactor auth')
+ *   .on('text', (text) => process.stdout.write(text))
+ *   .on('tool_use', (event) => console.log(event.toolName))
+ *   .on('task_started', (event) => console.log(`Task: ${event.description}`))
+ *   .done()
+ * ```
+ *
+ * ## 2. Convenience methods
+ *
+ * ```ts
+ * const text = await claude.stream('Summarize').text()
+ * const result = await claude.stream('Explain').pipe(process.stdout)
+ * ```
+ *
+ * ## 3. Node.js Readable stream
+ *
+ * ```ts
+ * import { pipeline } from 'node:stream/promises'
+ * await pipeline(claude.stream('Generate').toReadable(), createGzip(), file)
+ * ```
+ *
+ * ## 4. Raw async iteration (backward compat)
+ *
+ * ```ts
+ * for await (const event of claude.stream('Analyze')) { ... }
+ * ```
+ */
+export declare class StreamHandle implements AsyncIterable<StreamEvent> {
+    private readonly source;
+    private readonly textCallbacks;
+    private readonly toolUseCallbacks;
+    private readonly resultCallbacks;
+    private readonly errorCallbacks;
+    private readonly systemCallbacks;
+    private readonly taskStartedCallbacks;
+    private readonly taskProgressCallbacks;
+    private readonly taskNotificationCallbacks;
+    constructor(source: () => AsyncIterable<StreamEvent>);
+    /**
+     * Register a callback for a specific event type. Returns `this` for chaining.
+     *
+     * `text` callback receives just the string. All others receive the full event.
+     */
+    on(type: typeof EVENT_TEXT, callback: TextCallback): this;
+    on(type: typeof EVENT_TOOL_USE, callback: ToolUseCallback): this;
+    on(type: typeof EVENT_RESULT, callback: ResultCallback): this;
+    on(type: typeof EVENT_ERROR, callback: ErrorCallback): this;
+    on(type: typeof EVENT_SYSTEM, callback: SystemCallback): this;
+    on(type: typeof EVENT_TASK_STARTED, callback: TaskStartedCallback): this;
+    on(type: typeof EVENT_TASK_PROGRESS, callback: TaskProgressCallback): this;
+    on(type: typeof EVENT_TASK_NOTIFICATION, callback: TaskNotificationCallback): this;
+    /**
+     * Consume the stream, fire all registered callbacks, return the final result.
+     */
+    done(): Promise<StreamResultEvent>;
+    /**
+     * Collect all text chunks into a single string.
+     */
+    text(): Promise<string>;
+    /**
+     * Pipe text to a writable stream. Returns the final result.
+     *
+     * ```ts
+     * const result = await claude.stream('Explain').pipe(process.stdout)
+     * ```
+     */
+    pipe(writable: {
+        write(chunk: string): unknown;
+    }): Promise<StreamResultEvent>;
+    /**
+     * Get a Node.js Readable that emits text chunks.
+     * Use for `pipeline()`, standard `.pipe()` chaining, HTTP responses, etc.
+     */
+    toReadable(): Readable;
+    /**
+     * Async iteration — yields StreamEvent objects. Backward compatible with `for await`.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    private dispatch;
+}
+export {};
+//# sourceMappingURL=stream-handle.d.ts.map

package/dist/client/stream-handle.d.ts.map

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