@ruska/cli 0.1.5 → 0.1.6

package/dist/commands/chat.js

@@ -116,7 +116,7 @@ function ChatCommandTui({ message, assistantId, threadId, tools, truncateOptions
         : 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
@@ -161,16 +161,17 @@ function ChatCommandTui({ message, assistantId, threadId, tools, 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

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,6 +13,7 @@ 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 handleReference = useRef();
@@ -29,6 +30,7 @@ export function useStream(config, request) {
             setEvents([]);
             setMessages([]);
             setFinalResponse(undefined);
+            setStreamMetadata(undefined);
             setError(undefined);
             setErrorCode(undefined);
             try {
@@ -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);
                     }
@@ -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/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.5",
+	"version": "0.1.6",
 	"description": "CLI for Orchestra - AI Agent Orchestration Platform",
 	"license": "Apache-2.0",
 	"author": "RUSKA <reggleston@ruska.ai>",