@ruska/cli 0.1.4 → 0.1.6

package/README.md

@@ -176,11 +176,34 @@ $ ruska chat "Hello" -a <assistant-id> | jq '.type'
 | `-a, --assistant`  | Assistant ID (optional, uses default chat if omitted) |
 | `-t, --thread`     | Thread ID to continue an existing conversation        |
 | `-m, --message`    | Message to send (alternative to positional arg)       |
+| `--tools`          | Tools for the chat session (see below for modes)      |
 | `--json`           | Output as newline-delimited JSON (NDJSON)             |
 | `--truncate <n>`   | Max characters for tool output (default: 500)         |
 | `--truncate-lines` | Max lines for tool output (default: 10)               |
 | `--full-output`    | Disable truncation (show full output)                 |
 
+**Tool options:**
+
+| Value                 | Behavior                                                                                |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| (not provided)        | Uses default tools: web_search, web_scrape, math_calculator, think_tool, python_sandbox |
+| `--tools=disabled`    | Disables all tools                                                                      |
+| `--tools=tool1,tool2` | Uses only the specified tools                                                           |
+
+**Examples with tools:**
+
+```bash
+# Chat with default tools (web search, scrape, calculator, think, python)
+$ ruska chat "What's the weather in Dallas?"
+
+# Chat without any tools
+$ ruska chat "Tell me a joke" --tools=disabled
+
+# Chat with specific tools only
+$ ruska chat "Calculate 2+2" --tools=math_calculator
+$ ruska chat "Search and analyze" --tools=web_search,think_tool
+```
+
 **Exit codes:**
 
 | Code | Meaning               |

package/dist/cli.js

@@ -33,6 +33,9 @@ const cli = meow(`
 	  -a, --assistant   Assistant ID (optional, uses default chat if omitted)
 	  -t, --thread      Thread ID to continue a conversation
 	  -m, --message     Message (alternative to positional arg)
+	  --tools           Tools to enable (default: web_search,web_scrape,math_calculator,think_tool,python_sandbox)
+	                    Use --tools=disabled to disable all tools
+	                    Use --tools=tool1,tool2 for specific tools
 	  --json            Output as newline-delimited JSON (auto-enabled when piped)
 	  --truncate <n>    Max characters for tool output (default: 500)
 	  --truncate-lines  Max lines for tool output (default: 10)
@@ -50,7 +53,9 @@ const cli = meow(`
 	  $ ruska auth                                    # Configure API key and host
 	  $ ruska assistants                              # List your assistants
 	  $ ruska assistant abc-123                       # Get assistant details
-	  $ ruska chat "Hello"                           # Direct chat with default LLM
+	  $ ruska chat "Hello"                           # Chat with default tools enabled
+	  $ ruska chat "Hello" --tools=disabled          # Chat without any tools
+	  $ ruska chat "Search X" --tools=web_search     # Chat with specific tools
 	  $ ruska chat "Hello" -a <assistant-id>         # Chat with specific assistant
 	  $ ruska chat "Follow up" -t <thread-id>        # Continue existing thread
 	  $ ruska chat "Hello" -a <id> --json            # Output as NDJSON
@@ -116,7 +121,7 @@ const cli = meow(`
         },
     },
 });
-const [command, ...args] = cli.input;
+const [command, ...arguments_] = cli.input;
 // Route to appropriate command
 async function main() {
     if (cli.flags.ui) {
@@ -134,7 +139,7 @@ async function main() {
             break;
         }
         case 'assistant': {
-            const assistantId = args[0];
+            const assistantId = arguments_[0];
             if (!assistantId) {
                 console.error('Usage: ruska assistant <id>');
                 console.log('Run `ruska assistants` to list available assistants');
@@ -153,7 +158,7 @@ async function main() {
                 cli.flags['a']?.toString();
             const threadId = cli.flags.thread ??
                 cli.flags['t']?.toString();
-            const message = args.join(' ') || cli.flags.message;
+            const message = arguments_.join(' ') || cli.flags.message;
             if (!message) {
                 console.error('Error: Message is required');
                 console.error('Usage: ruska chat "<message>" [-a <assistant-id>]');
@@ -163,6 +168,7 @@ async function main() {
                 json: cli.flags.json,
                 assistantId,
                 threadId,
+                tools: cli.flags.tools,
                 truncateOptions: cli.flags.fullOutput
                     ? undefined
                     : {

package/dist/commands/chat.d.ts

@@ -10,5 +10,6 @@ export declare function runChatCommand(message: string, options?: {
     json?: boolean;
     assistantId?: string;
     threadId?: string;
+    tools?: string;
     truncateOptions?: TruncateOptions;
 }): Promise<void>;

package/dist/commands/chat.js

@@ -14,6 +14,7 @@ import { classifyError, exitCodes } from '../lib/output/error-handler.js';
 import { writeJson, checkIsTty } from '../lib/output/writers.js';
 import { StreamService, StreamConnectionError, } from '../lib/services/stream-service.js';
 import { truncate } from '../lib/output/truncate.js';
+import { parseToolsFlag } from '../lib/tools.js';
 /**
  * Group messages into blocks by type + name boundaries
  */
@@ -83,7 +84,7 @@ function StatusIndicator({ status }) {
 /**
  * TUI mode chat command using React hook
  */
-function ChatCommandTui({ message, assistantId, threadId, truncateOptions, }) {
+function ChatCommandTui({ message, assistantId, threadId, tools, truncateOptions, }) {
     const { exit } = useApp();
     const [config, setConfig] = useState();
     const [authError, setAuthError] = useState(false);
@@ -106,15 +107,16 @@ function ChatCommandTui({ message, assistantId, threadId, truncateOptions, }) {
     const request = useMemo(() => config
         ? {
             input: { messages: [{ role: 'user', content: message }] },
+            tools,
             metadata: {
                 ...(assistantId && { assistant_id: assistantId }),
                 ...(threadId && { thread_id: threadId }),
             },
         }
-        : undefined, [config, assistantId, message, threadId]);
+        : undefined, [config, assistantId, message, threadId, tools]);
     /* eslint-enable @typescript-eslint/naming-convention */
     // Stream
-    const { status, messages, events, error } = useStream(config, request);
+    const { status, messages, events, streamMetadata, error } = useStream(config, request);
     // Group messages into blocks by type + name boundaries
     const messageBlocks = useMemo(() => groupMessagesIntoBlocks(messages), [messages]);
     // Exit on completion
@@ -159,22 +161,23 @@ function ChatCommandTui({ message, assistantId, threadId, truncateOptions, }) {
             })()))) : (React.createElement(Text, null, block.content))))),
         status === 'done' && (React.createElement(Box, { marginTop: 1, flexDirection: "column" },
             React.createElement(Text, { color: "green" }, "Done"),
-            request?.metadata?.thread_id && (React.createElement(Text, { dimColor: true },
-                "Thread: ",
-                request.metadata.thread_id)),
             extractModelFromEvents(events) && (React.createElement(Text, { dimColor: true },
                 "Model: ",
                 extractModelFromEvents(events))),
-            request?.metadata?.thread_id && (React.createElement(Text, { dimColor: true },
-                "Continue: ruska chat \"message\" -t",
+            streamMetadata?.thread_id && (React.createElement(Text, { dimColor: true },
+                "Thread: ",
+                streamMetadata.thread_id)),
+            streamMetadata?.thread_id && (React.createElement(Text, { dimColor: true },
+                "Continue: ruska chat -t ",
+                streamMetadata.thread_id,
                 ' ',
-                request.metadata.thread_id))))));
+                "\"message\""))))));
 }
 /**
  * JSON mode chat command - direct streaming without React hooks
  * Outputs NDJSON for downstream consumption
  */
-async function runJsonMode(message, assistantId, threadId) {
+async function runJsonMode(message, assistantId, threadId, tools) {
     const config = await loadConfig();
     if (!config) {
         const formatter = new OutputFormatter();
@@ -190,6 +193,7 @@ async function runJsonMode(message, assistantId, threadId) {
         /* eslint-disable @typescript-eslint/naming-convention */
         const request = {
             input: { messages: [{ role: 'user', content: message }] },
+            tools,
             metadata: {
                 ...(assistantId && { assistant_id: assistantId }),
                 ...(threadId && { thread_id: threadId }),
@@ -244,22 +248,22 @@ async function runJsonMode(message, assistantId, threadId) {
 /**
  * Main chat command component - handles JSON mode branching
  */
-function ChatCommand({ message, isJsonMode, assistantId, threadId, truncateOptions, }) {
+function ChatCommand({ message, isJsonMode, assistantId, threadId, tools, truncateOptions, }) {
     const { exit } = useApp();
     useEffect(() => {
         if (isJsonMode) {
             // JSON mode runs outside React, just exit immediately
-            void runJsonMode(message, assistantId, threadId).finally(() => {
+            void runJsonMode(message, assistantId, threadId, tools).finally(() => {
                 exit();
             });
         }
-    }, [message, isJsonMode, assistantId, threadId, exit]);
+    }, [message, isJsonMode, assistantId, threadId, tools, exit]);
     // JSON mode: no UI (handled in useEffect)
     if (isJsonMode) {
         return null;
     }
     // TUI mode
-    return (React.createElement(ChatCommandTui, { message: message, assistantId: assistantId, threadId: threadId, truncateOptions: truncateOptions }));
+    return (React.createElement(ChatCommandTui, { message: message, assistantId: assistantId, threadId: threadId, tools: tools, truncateOptions: truncateOptions }));
 }
 /**
  * Run the chat command
@@ -267,6 +271,8 @@ function ChatCommand({ message, isJsonMode, assistantId, threadId, truncateOptio
 export async function runChatCommand(message, options = {}) {
     // Auto-detect: use JSON mode if not TTY (piped) or explicitly requested
     const isJsonMode = options.json ?? !checkIsTty();
-    const { waitUntilExit } = render(React.createElement(ChatCommand, { message: message, isJsonMode: isJsonMode, assistantId: options.assistantId, threadId: options.threadId, truncateOptions: options.truncateOptions }));
+    // Parse tools flag (undefined = defaults, 'disabled' = [], 'a,b' = ['a', 'b'])
+    const parsedTools = parseToolsFlag(options.tools);
+    const { waitUntilExit } = render(React.createElement(ChatCommand, { message: message, isJsonMode: isJsonMode, assistantId: options.assistantId, threadId: options.threadId, tools: parsedTools, truncateOptions: options.truncateOptions }));
     await waitUntilExit();
 }

package/dist/components/model-select.d.ts

@@ -1,10 +1,10 @@
 import React from 'react';
-type ModelSelectProps = {
+type ModelSelectProperties = {
     readonly models: string[];
     readonly value: string;
     readonly onChange: (value: string) => void;
     readonly onSubmit: (value: string) => void;
     readonly onEscape?: () => void;
 };
-export declare function ModelSelect({ models, value, onChange, onSubmit, onEscape, }: ModelSelectProps): React.JSX.Element;
+export declare function ModelSelect({ models, value, onChange, onSubmit, onEscape, }: ModelSelectProperties): React.JSX.Element;
 export {};

package/dist/components/model-select.js

@@ -61,8 +61,8 @@ export function ModelSelect({ models, value, onChange, onSubmit, onEscape, }) {
                 " \u2191 ",
                 startIndex,
                 " more"),
-            visibleModels.map((model, idx) => {
-                const actualIndex = startIndex + idx;
+            visibleModels.map((model, index) => {
+                const actualIndex = startIndex + index;
                 const isSelected = actualIndex === selectedIndex;
                 return (React.createElement(Box, { key: model },
                     React.createElement(Text, { color: isSelected ? 'cyan' : undefined }, isSelected ? '❯ ' : '  '),

package/dist/hooks/use-stream.d.ts

@@ -3,13 +3,14 @@
  * From Beta proposal with critical values event handling
  */
 import type { Config } from '../types/index.js';
-import { type MessagePayload, type StreamRequest, type StreamEvent, type ValuesPayload } from '../types/stream.js';
+import { type MessagePayload, type MetadataPayload, type StreamRequest, type StreamEvent, type ValuesPayload } from '../types/stream.js';
 export type StreamStatus = 'idle' | 'connecting' | 'streaming' | 'done' | 'error';
 export type UseStreamResult = {
     status: StreamStatus;
     events: StreamEvent[];
     messages: MessagePayload[];
     finalResponse: ValuesPayload | undefined;
+    streamMetadata: MetadataPayload | undefined;
     error: string | undefined;
     errorCode: number | undefined;
     abort: () => void;

package/dist/hooks/use-stream.js

@@ -3,7 +3,7 @@
  * From Beta proposal with critical values event handling
  */
 import { useState, useEffect, useRef, useCallback } from 'react';
-import { StreamService, StreamConnectionError, } from '../lib/services/stream-service.js';
+import { StreamService, StreamConnectionError, DistributedStreamError, MalformedDistributedResponse, } from '../lib/services/stream-service.js';
 /**
  * React hook for consuming LLM streams.
  * CRITICAL: Captures "values" event payload as finalResponse
@@ -13,11 +13,12 @@ export function useStream(config, request) {
     const [events, setEvents] = useState([]);
     const [messages, setMessages] = useState([]);
     const [finalResponse, setFinalResponse] = useState();
+    const [streamMetadata, setStreamMetadata] = useState();
     const [error, setError] = useState();
     const [errorCode, setErrorCode] = useState();
-    const handleRef = useRef();
+    const handleReference = useRef();
     const abort = useCallback(() => {
-        handleRef.current?.abort();
+        handleReference.current?.abort();
     }, []);
     useEffect(() => {
         if (!config || !request)
@@ -29,11 +30,12 @@ export function useStream(config, request) {
             setEvents([]);
             setMessages([]);
             setFinalResponse(undefined);
+            setStreamMetadata(undefined);
             setError(undefined);
             setErrorCode(undefined);
             try {
                 const handle = await service.connect(request);
-                handleRef.current = handle;
+                handleReference.current = handle;
                 if (cancelled) {
                     handle.abort();
                     return;
@@ -58,11 +60,21 @@ export function useStream(config, request) {
                             setFinalResponse(event.payload);
                             break;
                         }
+                        case 'metadata': {
+                            // Capture stream metadata (thread_id, etc.)
+                            setStreamMetadata(event.payload);
+                            break;
+                        }
                         case 'error': {
                             setError(event.payload.message);
                             setStatus('error');
                             return;
                         }
+                        case 'done': {
+                            // Terminal event from distributed mode
+                            // Stream will end naturally after this
+                            break;
+                        }
                         default: {
                             // Unknown event type - ignore
                             break;
@@ -77,6 +89,12 @@ export function useStream(config, request) {
                         setError(error_.message);
                         setErrorCode(error_.statusCode);
                     }
+                    else if (error_ instanceof DistributedStreamError) {
+                        setError(`Distributed error (${error_.phase}): ${error_.message}`);
+                    }
+                    else if (error_ instanceof MalformedDistributedResponse) {
+                        setError(`Invalid distributed response: ${error_.message}`);
+                    }
                     else if (error_ instanceof Error) {
                         setError(error_.message);
                     }
@@ -90,7 +108,7 @@ export function useStream(config, request) {
         void run();
         return () => {
             cancelled = true;
-            handleRef.current?.abort();
+            handleReference.current?.abort();
         };
     }, [config, request]);
     return {
@@ -98,6 +116,7 @@ export function useStream(config, request) {
         events,
         messages,
         finalResponse,
+        streamMetadata,
         error,
         errorCode,
         abort,

package/dist/lib/output/error-handler.d.ts

@@ -19,6 +19,8 @@ export declare const exitCodes: {
     readonly rateLimited: 3;
     readonly timeout: 4;
     readonly serverError: 5;
+    readonly distributedError: 6;
+    readonly distributedTimeout: 7;
 };
 /**
  * Map raw errors to structured error responses

package/dist/lib/output/error-handler.js

@@ -2,6 +2,7 @@
  * Error handler with taxonomy for CLI output
  * From Gamma proposal with structured error codes
  */
+import { DistributedStreamError, MalformedDistributedResponse, } from '../services/stream-service.js';
 /**
  * Exit codes for scripting
  */
@@ -12,6 +13,8 @@ export const exitCodes = {
     rateLimited: 3,
     timeout: 4,
     serverError: 5,
+    distributedError: 6,
+    distributedTimeout: 7,
 };
 /**
  * Map raw errors to structured error responses
@@ -45,6 +48,33 @@ export function classifyError(error, statusCode) {
         }
     }
     if (error instanceof Error) {
+        // Handle distributed mode specific errors
+        if (error instanceof DistributedStreamError) {
+            // Check if it's a timeout during distributed streaming
+            if (error.message.includes('timeout') ||
+                error.message.includes('aborted')) {
+                return {
+                    code: 'DISTRIBUTED_TIMEOUT',
+                    message: `Distributed stream timed out during ${error.phase} phase.`,
+                    recoverable: true,
+                    exitCode: exitCodes.distributedTimeout,
+                };
+            }
+            return {
+                code: 'DISTRIBUTED_ERROR',
+                message: `Distributed stream error (${error.phase}): ${error.message}`,
+                recoverable: error.phase === 'handshake',
+                exitCode: exitCodes.distributedError,
+            };
+        }
+        if (error instanceof MalformedDistributedResponse) {
+            return {
+                code: 'DISTRIBUTED_ERROR',
+                message: `Invalid distributed response: ${error.message}`,
+                recoverable: false,
+                exitCode: exitCodes.distributedError,
+            };
+        }
         const errorMessage = error.message.toLowerCase();
         // Network errors
         if (errorMessage.includes('fetch failed') ||

package/dist/lib/services/stream-service.d.ts

@@ -1,9 +1,11 @@
 /**
  * Stream service implementation for SSE consumption
- * Combines Beta's architecture with Alpha's timeout handling
+ * Supports both sync mode (HTTP 200) and distributed worker mode (HTTP 202)
+ * @see backend/src/routes/v0/llm.py - distributed mode detection
+ * @see backend/src/routes/v0/thread.py - thread stream endpoint
  */
 import type { Config } from '../../types/index.js';
-import type { StreamRequest, StreamHandle } from '../../types/stream.js';
+import { type StreamRequest, type StreamHandle } from '../../types/stream.js';
 import type { StreamServiceInterface } from './stream-service.interface.js';
 /**
  * Custom error for stream connection failures
@@ -12,16 +14,58 @@ export declare class StreamConnectionError extends Error {
     readonly statusCode: number;
     constructor(message: string, statusCode: number);
 }
+/**
+ * Error specific to distributed streaming mode
+ * Includes phase information for debugging
+ */
+export declare class DistributedStreamError extends Error {
+    readonly phase: 'handshake' | 'streaming';
+    readonly rawResponse?: string | undefined;
+    constructor(message: string, phase: 'handshake' | 'streaming', rawResponse?: string | undefined);
+}
+/**
+ * Error for malformed distributed response from initial POST
+ */
+export declare class MalformedDistributedResponse extends Error {
+    readonly rawResponse?: string | undefined;
+    constructor(message: string, rawResponse?: string | undefined);
+}
 /**
  * Production stream service using SSE
  */
 export declare class StreamService implements StreamServiceInterface {
     private readonly host;
     private readonly apiKey;
-    private readonly timeoutMs;
-    constructor(config: Config, timeoutMs?: number);
+    private readonly connectionTimeoutMs;
+    private readonly streamIdleTimeoutMs;
+    constructor(config: Config, connectionTimeoutMs?: number, streamIdleTimeoutMs?: number);
     connect(request: StreamRequest): Promise<StreamHandle>;
     private fetchStream;
+    /**
+     * Handle distributed worker mode (HTTP 202 response)
+     * Parses the initial response and connects to thread stream endpoint
+     */
+    private handleDistributedMode;
+    /**
+     * Connect to GET /api/threads/{thread_id}/stream for distributed mode
+     * URL-encodes thread_id to prevent path injection
+     */
+    private connectToThreadStream;
+    /**
+     * Parse SSE events from distributed worker stream
+     * Handles [DONE] marker, keep-alive comments, and error JSON
+     */
+    private parseDistributedEventStream;
+    /**
+     * Extract events from distributed stream buffer
+     * Handles keep-alive comments, [DONE] marker, and error JSON
+     */
+    private extractDistributedEvents;
+    /**
+     * Parse a single distributed event data payload
+     * Handles error JSON format and regular event format
+     */
+    private parseDistributedEvent;
     private parseEventStream;
     private extractEvents;
     private parseEvent;

package/dist/lib/services/stream-service.js

@@ -1,8 +1,12 @@
 /**
  * Stream service implementation for SSE consumption
- * Combines Beta's architecture with Alpha's timeout handling
+ * Supports both sync mode (HTTP 200) and distributed worker mode (HTTP 202)
+ * @see backend/src/routes/v0/llm.py - distributed mode detection
+ * @see backend/src/routes/v0/thread.py - thread stream endpoint
  */
-const defaultTimeoutMs = 30000;
+import { isDistributedResponse, isDistributedError, STREAM_DONE_MARKER, } from '../../types/stream.js';
+const defaultConnectionTimeoutMs = 30000;
+const defaultStreamIdleTimeoutMs = 60000;
 /**
  * Custom error for stream connection failures
  */
@@ -18,11 +22,48 @@ export class StreamConnectionError extends Error {
         this.name = 'StreamConnectionError';
     }
 }
+/**
+ * Error specific to distributed streaming mode
+ * Includes phase information for debugging
+ */
+export class DistributedStreamError extends Error {
+    constructor(message, phase, rawResponse) {
+        super(message);
+        Object.defineProperty(this, "phase", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: phase
+        });
+        Object.defineProperty(this, "rawResponse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: rawResponse
+        });
+        this.name = 'DistributedStreamError';
+    }
+}
+/**
+ * Error for malformed distributed response from initial POST
+ */
+export class MalformedDistributedResponse extends Error {
+    constructor(message, rawResponse) {
+        super(message);
+        Object.defineProperty(this, "rawResponse", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: rawResponse
+        });
+        this.name = 'MalformedDistributedResponse';
+    }
+}
 /**
  * Production stream service using SSE
  */
 export class StreamService {
-    constructor(config, timeoutMs = defaultTimeoutMs) {
+    constructor(config, connectionTimeoutMs = defaultConnectionTimeoutMs, streamIdleTimeoutMs = defaultStreamIdleTimeoutMs) {
         Object.defineProperty(this, "host", {
             enumerable: true,
             configurable: true,
@@ -35,7 +76,13 @@ export class StreamService {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "timeoutMs", {
+        Object.defineProperty(this, "connectionTimeoutMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "streamIdleTimeoutMs", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -43,17 +90,23 @@ export class StreamService {
         });
         this.host = config.host.replace(/\/$/, '');
         this.apiKey = config.apiKey;
-        this.timeoutMs = timeoutMs;
+        this.connectionTimeoutMs = connectionTimeoutMs;
+        this.streamIdleTimeoutMs = streamIdleTimeoutMs;
     }
     async connect(request) {
         const controller = new AbortController();
         // Set timeout for connection
         const timeoutId = setTimeout(() => {
             controller.abort();
-        }, this.timeoutMs);
+        }, this.connectionTimeoutMs);
         try {
             const response = await this.fetchStream(request, controller.signal);
             clearTimeout(timeoutId);
+            // Check for distributed mode (HTTP 202)
+            if (response.status === 202) {
+                return await this.handleDistributedMode(response, controller);
+            }
+            // Sync mode (HTTP 200)
             if (!response.body) {
                 throw new StreamConnectionError('No response body', 0);
             }
@@ -83,12 +136,207 @@ export class StreamService {
             body: JSON.stringify(request),
             signal,
         });
-        if (!response.ok) {
+        // Accept both 200 (sync) and 202 (distributed) as valid
+        if (!response.ok && response.status !== 202) {
             const error = await this.parseError(response);
             throw new StreamConnectionError(error, response.status);
         }
         return response;
     }
+    /**
+     * Handle distributed worker mode (HTTP 202 response)
+     * Parses the initial response and connects to thread stream endpoint
+     */
+    async handleDistributedMode(initialResponse, controller) {
+        // Parse the distributed response body
+        const rawText = await initialResponse.text();
+        let data;
+        try {
+            data = JSON.parse(rawText);
+        }
+        catch {
+            throw new MalformedDistributedResponse('Invalid JSON in distributed response', rawText);
+        }
+        // Validate the response shape
+        if (!isDistributedResponse(data)) {
+            throw new MalformedDistributedResponse('Invalid distributed response: missing or invalid thread_id', rawText);
+        }
+        // Check if already aborted before making second request
+        if (controller.signal.aborted) {
+            throw new DOMException('Aborted', 'AbortError');
+        }
+        // Connect to the thread stream endpoint
+        const streamHandle = await this.connectToThreadStream(data.thread_id, controller);
+        return streamHandle;
+    }
+    /**
+     * Connect to GET /api/threads/{thread_id}/stream for distributed mode
+     * URL-encodes thread_id to prevent path injection
+     */
+    async connectToThreadStream(threadId, controller) {
+        // URL-encode thread_id to prevent path injection
+        const encodedThreadId = encodeURIComponent(threadId);
+        const streamUrl = `${this.host}/api/threads/${encodedThreadId}/stream`;
+        // Set connection timeout for the GET request
+        const connectionTimeoutId = setTimeout(() => {
+            controller.abort();
+        }, this.connectionTimeoutMs);
+        try {
+            const streamResponse = await fetch(streamUrl, {
+                method: 'GET',
+                headers: {
+                    'x-api-key': this.apiKey,
+                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    Accept: 'text/event-stream',
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(connectionTimeoutId);
+            if (!streamResponse.ok) {
+                const error = await this.parseError(streamResponse);
+                throw new DistributedStreamError(`Failed to connect to thread stream: ${error}`, 'handshake');
+            }
+            if (!streamResponse.body) {
+                throw new DistributedStreamError('No response body from thread stream', 'handshake');
+            }
+            const events = this.parseDistributedEventStream(streamResponse.body, controller);
+            return {
+                events,
+                abort() {
+                    controller.abort();
+                },
+            };
+        }
+        catch (error) {
+            clearTimeout(connectionTimeoutId);
+            throw error;
+        }
+    }
+    /**
+     * Parse SSE events from distributed worker stream
+     * Handles [DONE] marker, keep-alive comments, and error JSON
+     */
+    async *parseDistributedEventStream(body, controller) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let idleTimeoutId;
+        // Reset idle timeout on data
+        const resetIdleTimeout = () => {
+            if (idleTimeoutId) {
+                clearTimeout(idleTimeoutId);
+            }
+            idleTimeoutId = setTimeout(() => {
+                controller.abort();
+            }, this.streamIdleTimeoutMs);
+        };
+        try {
+            resetIdleTimeout();
+            while (true) {
+                // eslint-disable-next-line no-await-in-loop
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                // Reset idle timeout on any data received
+                resetIdleTimeout();
+                buffer += decoder.decode(value, { stream: true });
+                const result = this.extractDistributedEvents(buffer);
+                buffer = result.remaining;
+                for (const event of result.parsed) {
+                    // Check for terminal [DONE] marker
+                    if (event.type === 'done') {
+                        return;
+                    }
+                    yield event;
+                }
+            }
+            // Process any remaining buffer
+            if (buffer.trim()) {
+                const result = this.extractDistributedEvents(buffer + '\n');
+                for (const event of result.parsed) {
+                    if (event.type === 'done') {
+                        return;
+                    }
+                    yield event;
+                }
+            }
+        }
+        finally {
+            if (idleTimeoutId) {
+                clearTimeout(idleTimeoutId);
+            }
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Extract events from distributed stream buffer
+     * Handles keep-alive comments, [DONE] marker, and error JSON
+     */
+    extractDistributedEvents(buffer) {
+        const parsed = [];
+        const lines = buffer.split('\n');
+        let remaining = '';
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Incomplete line at end (no newline after it)
+            if (i === lines.length - 1 && !buffer.endsWith('\n')) {
+                remaining = line;
+                break;
+            }
+            // Skip empty lines (SSE event separator)
+            if (line.trim() === '') {
+                continue;
+            }
+            // Skip keep-alive comments (lines starting with :)
+            if (line.startsWith(':')) {
+                continue;
+            }
+            // Parse data lines
+            if (line.startsWith('data: ')) {
+                const data = line.slice(6);
+                // Check for [DONE] marker
+                if (data === STREAM_DONE_MARKER) {
+                    parsed.push({ type: 'done', payload: undefined });
+                    continue;
+                }
+                // Try to parse as JSON
+                const event = this.parseDistributedEvent(data);
+                if (event) {
+                    parsed.push(event);
+                }
+            }
+        }
+        return { parsed, remaining };
+    }
+    /**
+     * Parse a single distributed event data payload
+     * Handles error JSON format and regular event format
+     */
+    parseDistributedEvent(data) {
+        try {
+            const parsed = JSON.parse(data);
+            // Check for distributed error format: {"error": "..."}
+            if (isDistributedError(parsed)) {
+                return {
+                    type: 'error',
+                    payload: { message: parsed.error },
+                };
+            }
+            // Regular event format: [type, payload]
+            if (Array.isArray(parsed) && parsed.length >= 2) {
+                const [type, payload] = parsed;
+                // Type assertion needed because we're parsing dynamic SSE data
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                return { type, payload };
+            }
+            // Unknown format - skip
+            return undefined;
+        }
+        catch {
+            // Parse error - skip this event
+            return undefined;
+        }
+    }
     async *parseEventStream(body) {
         const reader = body.getReader();
         const decoder = new TextDecoder();

package/dist/lib/tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Default tools and parsing for chat command
+ * @see frontend/src/components/menus/BaseToolMenu.tsx for frontend equivalent
+ */
+/**
+ * Default tools enabled for chat command
+ * Mirrors frontend DEFAULT_AGENT_TOOLS in BaseToolMenu.tsx
+ */
+export declare const defaultAgentTools: readonly ["web_search", "web_scrape", "math_calculator", "think_tool", "python_sandbox"];
+export type DefaultAgentTool = (typeof defaultAgentTools)[number];
+/**
+ * Parse --tools flag value into array of tool names
+ *
+ * @param value - Raw flag value (undefined, 'disabled', or comma-separated)
+ * @returns Array of tool names to send to API
+ *
+ * @example
+ * parseToolsFlag(undefined)             // returns DEFAULT_AGENT_TOOLS
+ * parseToolsFlag('')                    // returns DEFAULT_AGENT_TOOLS
+ * parseToolsFlag('disabled')            // returns []
+ * parseToolsFlag('web_search,think_tool') // returns ['web_search', 'think_tool']
+ */
+export declare function parseToolsFlag(value: string | undefined): string[];

package/dist/lib/tools.js

@@ -0,0 +1,42 @@
+/**
+ * Default tools and parsing for chat command
+ * @see frontend/src/components/menus/BaseToolMenu.tsx for frontend equivalent
+ */
+/**
+ * Default tools enabled for chat command
+ * Mirrors frontend DEFAULT_AGENT_TOOLS in BaseToolMenu.tsx
+ */
+export const defaultAgentTools = [
+    'web_search',
+    'web_scrape',
+    'math_calculator',
+    'think_tool',
+    'python_sandbox',
+];
+/**
+ * Parse --tools flag value into array of tool names
+ *
+ * @param value - Raw flag value (undefined, 'disabled', or comma-separated)
+ * @returns Array of tool names to send to API
+ *
+ * @example
+ * parseToolsFlag(undefined)             // returns DEFAULT_AGENT_TOOLS
+ * parseToolsFlag('')                    // returns DEFAULT_AGENT_TOOLS
+ * parseToolsFlag('disabled')            // returns []
+ * parseToolsFlag('web_search,think_tool') // returns ['web_search', 'think_tool']
+ */
+export function parseToolsFlag(value) {
+    // No flag or empty string: use defaults
+    if (value === undefined || value.trim() === '') {
+        return [...defaultAgentTools];
+    }
+    // Explicit disable
+    if (value.toLowerCase() === 'disabled') {
+        return [];
+    }
+    // Parse comma-separated list
+    return value
+        .split(',')
+        .map(t => t.trim())
+        .filter(Boolean);
+}

package/dist/types/output.d.ts

@@ -37,7 +37,7 @@ export type ErrorOutput = {
 /**
  * Typed error codes for programmatic handling
  */
-export type ErrorCode = 'AUTH_FAILED' | 'NETWORK_ERROR' | 'RATE_LIMITED' | 'INVALID_REQUEST' | 'STREAM_INTERRUPTED' | 'PARSE_ERROR' | 'SERVER_ERROR' | 'TIMEOUT';
+export type ErrorCode = 'AUTH_FAILED' | 'NETWORK_ERROR' | 'RATE_LIMITED' | 'INVALID_REQUEST' | 'STREAM_INTERRUPTED' | 'PARSE_ERROR' | 'SERVER_ERROR' | 'TIMEOUT' | 'DISTRIBUTED_ERROR' | 'DISTRIBUTED_TIMEOUT';
 /**
  * Union of all output types
  */

package/dist/types/stream.d.ts

@@ -5,7 +5,33 @@
 /**
  * Stream event types matching backend SSE format
  */
-export type StreamEventType = 'messages' | 'values' | 'error';
+export type StreamEventType = 'messages' | 'values' | 'error' | 'metadata' | 'done';
+/**
+ * Special SSE markers from distributed stream
+ */
+export declare const STREAM_DONE_MARKER = "[DONE]";
+/**
+ * Response from POST /llm/stream when DISTRIBUTED_WORKERS=true
+ */
+export type DistributedResponse = {
+    thread_id: string;
+    distributed: true;
+};
+/**
+ * Type guard for distributed response with strict validation
+ * Validates thread_id exists, is non-empty, and within bounds
+ */
+export declare function isDistributedResponse(data: unknown): data is DistributedResponse;
+/**
+ * Error response format from distributed stream
+ */
+export type DistributedErrorResponse = {
+    error: string;
+};
+/**
+ * Type guard for distributed error format
+ */
+export declare function isDistributedError(data: unknown): data is DistributedErrorResponse;
 /**
  * Content block for multi-modal messages
  */
@@ -49,6 +75,15 @@ export type ValuesPayload = {
 export type ErrorPayload = {
     message: string;
 };
+/**
+ * Metadata payload from 'metadata' events
+ * Sent at the start of stream with thread/session info
+ */
+export type MetadataPayload = {
+    thread_id?: string;
+    assistant_id?: string;
+    project_id?: string;
+};
 /**
  * Discriminated union for stream events
  */
@@ -62,6 +97,12 @@ export type StreamEvent = {
 } | {
     type: 'error';
     payload: ErrorPayload;
+} | {
+    type: 'metadata';
+    payload: MetadataPayload;
+} | {
+    type: 'done';
+    payload: undefined;
 };
 /**
  * Request body for /llm/stream endpoint

package/dist/types/stream.js

@@ -2,6 +2,43 @@
  * Stream types for /api/llm/stream endpoint
  * @see backend/src/utils/stream.py:handle_multi_mode
  */
+/**
+ * Special SSE markers from distributed stream
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const STREAM_DONE_MARKER = '[DONE]';
+/**
+ * Type guard for distributed response with strict validation
+ * Validates thread_id exists, is non-empty, and within bounds
+ */
+export function isDistributedResponse(data) {
+    if (typeof data !== 'object' || data === null) {
+        return false;
+    }
+    const obj = data;
+    if (obj['distributed'] !== true) {
+        return false;
+    }
+    const threadId = obj['thread_id'];
+    if (typeof threadId !== 'string') {
+        return false;
+    }
+    // Strict validation: non-empty and bounded length (prevent DoS)
+    if (threadId.length === 0 || threadId.length > 256) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Type guard for distributed error format
+ */
+export function isDistributedError(data) {
+    if (typeof data !== 'object' || data === null) {
+        return false;
+    }
+    const obj = data;
+    return typeof obj['error'] === 'string';
+}
 /**
  * Extract text content from a MessagePayload.
  * Handles both string content and multi-modal content blocks.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ruska/cli",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"description": "CLI for Orchestra - AI Agent Orchestration Platform",
 	"license": "Apache-2.0",
 	"author": "RUSKA <reggleston@ruska.ai>",
@@ -47,7 +47,7 @@
 		"dev": "tsc --watch",
 		"build": "tsc",
 		"build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && npm run build",
-		"format": "prettier --write \"**/*.{ts,tsx,json,md}\" && xo --fix",
+		"format": "xo --fix && prettier --write \"**/*.{ts,tsx,json,md}\"",
 		"format:check": "prettier --check .",
 		"lint": "xo",
 		"test": "npm run lint && npm run build && ava",
@@ -87,7 +87,7 @@
 		"ts-node": "^10.9.1",
 		"tsx": "^4.21.0",
 		"typescript": "^5.0.3",
-		"xo": "^0.53.1"
+		"xo": "^0.60.0"
 	},
 	"ava": {
 		"files": [
@@ -103,7 +103,16 @@
 		"rules": {
 			"react/prop-types": "off",
 			"unicorn/expiring-todo-comments": "off",
-			"ava/no-ignored-test-files": "off"
+			"ava/no-ignored-test-files": "off",
+			"unicorn/prevent-abbreviations": "off",
+			"@typescript-eslint/switch-exhaustiveness-check": "off",
+			"@typescript-eslint/no-unsafe-assignment": "off",
+			"@typescript-eslint/no-unsafe-call": "off",
+			"@typescript-eslint/restrict-plus-operands": "off",
+			"promise/prefer-await-to-then": "off",
+			"complexity": "off",
+			"unicorn/prefer-at": "off",
+			"prettier/prettier": "off"
 		}
 	},
 	"prettier": "@vdemedes/prettier-config"