connectonion 0.0.8 → 0.0.10

package/README.md

@@ -205,7 +205,98 @@ While we recommend building agents in Python, you can also build simple agents d
 
 If you encounter bugs building agents in TypeScript, please [report them on GitHub](https://github.com/openonion/connectonion-ts/issues).
 
-## 🏗️ Project Structure
+## 🏗️ Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    ConnectOnion TypeScript SDK                    │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
+│  │    Agent      │  │   connect()  │  │      llmDo()           │ │
+│  │  (local AI)   │  │  (remote)    │  │  (one-shot LLM call)   │ │
+│  └──────┬───────┘  └──────┬───────┘  └────────────┬───────────┘ │
+│         │                 │                        │             │
+│         ▼                 ▼                        │             │
+│  ┌─────────────────────────────┐                   │             │
+│  │        LLM Factory          │◀──────────────────┘             │
+│  │      createLLM(model)       │                                 │
+│  └──────────┬──────────────────┘                                 │
+│     ┌───────┼──────────┬────────────┐                            │
+│     ▼       ▼          ▼            ▼                            │
+│  Anthropic  OpenAI   Gemini    OpenOnion                         │
+│  (claude-*) (gpt-*)  (gemini-*) (co/*)                          │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────┐  ┌───────────┐  ┌───────────┐  │
+│  │  Tool System  │  │  Trust   │  │  Console  │  │   Xray    │  │
+│  │  func→schema  │  │  Levels  │  │  Logging  │  │  Debugger │  │
+│  └──────────────┘  └──────────┘  └───────────┘  └───────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Agent Execution Flow
+
+```
+  agent.input("What is 2+2?")
+       │
+       ▼
+  ┌─────────────────┐
+  │  Init messages   │  [system prompt] + [user message]
+  └────────┬────────┘
+           │
+           ▼
+  ┌─────────────────────────────────────┐
+  │        Main Loop (max 10 iter)       │
+  │                                      │
+  │  LLM.complete(messages, tools)       │
+  │       │                              │
+  │       ├── No tool calls ──▶ EXIT     │
+  │       │                              │
+  │       └── Tool calls found:          │
+  │            Promise.all(              │
+  │              tool_1.run(args),       │
+  │              tool_2.run(args)        │
+  │            )                         │
+  │            │                         │
+  │            ▼                         │
+  │       Append results → LOOP          │
+  └─────────────────────────────────────┘
+       │
+       ▼
+  Return final text response
+```
+
+### Tool Conversion
+
+```
+  Your code                        SDK internals
+
+  function add(a: number,          Tool {
+    b: number): number {    ──▶      name: "add",
+    return a + b;                    description: "...",
+  }                                  run(args) → add(a, b),
+                                     toFunctionSchema() → {
+  class API {                          type: "object",
+    search(q: string) {}   ──▶        properties: {a: {type: "number"}, ...}
+    fetch(id: number) {}             }
+  }                                }
+```
+
+### LLM Provider Routing
+
+```
+  createLLM(model)
+       │
+       ├── "co/*"     ──▶ OpenAI LLM + OpenOnion baseURL
+       ├── "claude-*"  ──▶ Anthropic LLM (default)
+       ├── "gpt-*"     ──▶ OpenAI LLM
+       ├── "o*"        ──▶ OpenAI LLM
+       ├── "gemini-*"  ──▶ Gemini LLM
+       └── (unknown)   ──▶ Anthropic (fallback) or NoopLLM
+```
+
+### Project Structure
 
 ```
 your-project/
@@ -218,6 +309,34 @@ your-project/
 └── tsconfig.json
 ```
 
+### SDK Internal Structure
+
+```
+src/
+├── core/
+│   └── agent.ts            # Main Agent class (orchestrator)
+├── llm/
+│   ├── index.ts            # LLM factory (routes model names)
+│   ├── anthropic.ts        # Anthropic Claude provider (default)
+│   ├── openai.ts           # OpenAI GPT/O-series provider
+│   ├── gemini.ts           # Google Gemini provider
+│   ├── noop.ts             # Fallback for missing config
+│   └── llm-do.ts           # One-shot llmDo() helper
+├── tools/
+│   ├── tool-utils.ts       # Function → Tool conversion
+│   ├── tool-executor.ts    # Execution + trace recording
+│   ├── xray.ts             # Debug context injection (@xray)
+│   ├── replay.ts           # Replay decorator for debugging
+│   └── email.ts            # Mock email tools for demos/tests
+├── trust/
+│   ├── index.ts            # Trust levels (open/careful/strict)
+│   └── tools.ts            # Whitelist checks & verification
+├── connect.ts              # Remote agent connection via relay
+├── console.ts              # Dual logging (stderr + file)
+├── types.ts                # Core TypeScript interfaces
+└── index.ts                # Public API exports
+```
+
 ---
 
 ## 💬 Join the Community

package/dist/connect.d.ts

@@ -1,30 +1,56 @@
 /**
  * @purpose Client for connecting to remote agents via WebSocket with automatic keep-alive, session recovery, and polling fallback
- * @llm-note
- *   Dependencies: imports from [src/address.ts (AddressData, generate, load, sign, etc.), src/types.ts (SessionStatus)] | imported by [src/index.ts, src/react/index.ts, examples/connect-example.ts, tests/connect.test.ts] | tested by [tests/connect.test.ts]
- *   Data flow: connect(address, options) → creates RemoteAgent → agent.input(prompt) → generates session_id (UUID) → saves to localStorage → opens WebSocket → sends INPUT{type, input_id, to, prompt, session{session_id}, signature?} → receives PING every 30s, responds with PONG → receives stream events (tool_call, tool_result, thinking, assistant) → receives OUTPUT{result, session_id, session} → clears localStorage → returns Response{text, done} | On disconnect/timeout: polls GET /sessions/{session_id} every 10s until result ready
- *   State/Effects: opens WebSocket connections | sends signed/unsigned messages | updates internal UI events array | syncs session from server | generates/loads Ed25519 keys | saves keys to localStorage (browser) or .co/keys/ (Node.js) | saves active session_id to localStorage for recovery | polls server via HTTP fetch on connection failure | health check interval detects dead connections
- *   Integration: exposes connect(address, options), RemoteAgent class, Response, ChatItem types, AgentStatus, ConnectOptions{enablePolling, pollIntervalMs, maxPollAttempts} | supports relay mode (wss://oo.openonion.ai) and direct mode (deployed agent URL) | Ed25519 signing for authentication | session persistence across calls | automatic recovery from network failures, timeouts, page refreshes
- *   Performance: 600s timeout default (10 min, up from 180s) | real-time WebSocket streaming | parallel tool execution on agent side | no client-side caching | auto-generates keys if missing | PING/PONG keep-alive every 30s | health check every 10s | polling fallback on failures | results persist 24h server-side
- *   Errors: throws on timeout (600s default) after polling exhausted | throws on WebSocket errors after polling attempt | throws on connection close after polling attempt | throws on ERROR messages from server | throws if session expired (404) during polling | includes error context in messages | graceful fallback to polling prevents data loss
  *
- * Architecture:
- *   Normal Flow:
- *     Client → /ws/input → Relay → Agent → OUTPUT → Relay → Client
+ * @graph Connection Modes
+ *
+ *   connect('0xAddr', options?)
+ *        │
+ *        ├── directUrl set? ──yes──▶ Direct: wss://{directUrl}/ws
+ *        │
+ *        ├── resolveEndpoint()? ──found──▶ Direct: resolved wsUrl
+ *        │
+ *        └── fallback ──▶ Relay: {relayUrl}/ws/input
  *
- *   Keep-Alive:
- *     Server sends PING every 30s → Client responds PONG → Health check every 10s
+ * @graph Remote Agent Communication Flow
  *
- *   Recovery Flow (on disconnect/timeout):
- *     WebSocket fails → Poll GET /sessions/{session_id} every 10s → Status="done" → Return result
+ *   Client (TS)                       Relay / Agent
+ *        │                                │
+ *        │  connect('0xAddr')             │
+ *        │  ──▶ RemoteAgent               │
+ *        │  (lazy-load Ed25519 keys)      │
+ *        │                                │
+ *        │  agent.input("prompt")         │
+ *        │  ──▶ WebSocket open ─────────▶ │
+ *        │      INPUT{prompt, sig, to}    │  ──▶ agent processes
+ *        │                                │
+ *        │  ◀── PING ◀───────────────── │  (every 30s keep-alive)
+ *        │  ──▶ PONG ──────────────────▶ │
+ *        │                                │
+ *        │  ◀── stream events ◀──────── │  (thinking, tool_call,
+ *        │      (update agent.ui[])       │   tool_result, assistant)
+ *        │                                │
+ *        │  ◀── OUTPUT{result, session} ◀ │
+ *        │  ws.close()                    │
+ *        ▼                                ▼
  *
- * Related Files:
- *   - oo-api/relay/routes.py: Relay server WebSocket endpoints
- *   - connectonion/network/connect.py: Python equivalent of this file
- *   - connectonion/network/asgi/websocket.py: Server-side PING sender
- *   - connectonion/network/host/session.py: SessionStorage for 24h TTL
- *   - src/react/index.ts: useAgent hook built on RemoteAgent
- *   - src/types.ts: SessionStatus, PollResult interfaces
+ * @graph Recovery Flow (on disconnect/timeout)
+ *
+ *   WebSocket fails
+ *        │
+ *        ▼
+ *   Poll GET /sessions/{session_id} (every 10s)
+ *        │
+ *        ├── status: "running" ──▶ retry poll
+ *        ├── status: "done"    ──▶ return result
+ *        └── 404 / max attempts ──▶ throw Error
+ *
+ * @llm-note
+ *   Dependencies: imports from [src/address.ts (AddressData, generate, load, sign, etc.), src/types.ts (SessionStatus)] | imported by [src/index.ts, src/react/index.ts, examples/connect-example.ts, tests/connect.test.ts] | tested by [tests/connect.test.ts]
+ *   Data flow: connect(address, options) → creates RemoteAgent → agent.input(prompt) → generates session_id (UUID) → opens WebSocket → sends INPUT{type, input_id, to, prompt, session{session_id, messages}, signature?} → receives PING every 30s, responds with PONG → receives stream events (tool_call, tool_result, thinking, assistant) with session state → receives OUTPUT{result, session_id, session} → returns Response{text, done} | On disconnect/timeout: polls GET /sessions/{session_id} every 10s until result ready
+ *   State/Effects: opens WebSocket connections | sends signed/unsigned messages | updates internal UI events array | syncs session from server events (in-memory) | generates/loads Ed25519 keys | saves keys to localStorage (browser) or .co/keys/ (Node.js) | polls server via HTTP fetch on connection failure | health check interval detects dead connections
+ *   Integration: exposes connect(address, options), RemoteAgent class, Response, ChatItem types, AgentStatus, ConnectOptions{enablePolling, pollIntervalMs, maxPollAttempts} | supports relay mode (wss://oo.openonion.ai) and direct mode (deployed agent URL) | Ed25519 signing for authentication | session persistence across calls | automatic recovery from network failures, timeouts, page refreshes
+ *   Performance: 600s timeout default (10 min) | real-time WebSocket streaming | PING/PONG keep-alive every 30s | health check every 10s | polling fallback on failures | results persist 24h server-side
+ *   Errors: throws on timeout (600s default) after polling exhausted | throws on WebSocket errors after polling attempt | throws on connection close after polling attempt | throws on ERROR messages from server | throws if session expired (404) during polling | graceful fallback to polling prevents data loss
  */
 import * as address from './address';
 export type { AddressData } from './address';
@@ -45,6 +71,7 @@ export type ChatItem = {
     id: string;
     type: 'user';
     content: string;
+    images?: string[];
 } | {
     id: string;
     type: 'agent';
@@ -279,14 +306,20 @@ export declare class RemoteAgent {
      * Returns Response with text and done flag.
      *
      * @param prompt - User's input
-     * @param timeoutMs - Timeout in milliseconds (default: 600000 / 10 minutes)
+     * @param options - Optional settings: images (base64 data URLs), timeoutMs
      * @returns Response with text and done flag
      */
-    input(prompt: string, timeoutMs?: number): Promise<Response>;
+    input(prompt: string, options?: {
+        images?: string[];
+        timeoutMs?: number;
+    }): Promise<Response>;
     /**
      * Async version of input (same as input, for API consistency with Python).
      */
-    inputAsync(prompt: string, timeoutMs?: number): Promise<Response>;
+    inputAsync(prompt: string, options?: {
+        images?: string[];
+        timeoutMs?: number;
+    }): Promise<Response>;
     /**
      * Respond to ask_user event.
      * Only valid when status === 'waiting' after an ask_user event.
@@ -324,14 +357,6 @@ export declare class RemoteAgent {
      * Repeatedly checks GET /sessions/{session_id} until result is ready.
      */
     private _pollForResult;
-    /**
-     * Save session ID to localStorage (browser only).
-     */
-    private _saveSessionId;
-    /**
-     * Clear session ID from localStorage (browser only).
-     */
-    private _clearSessionId;
     /**
      * Start health check interval to detect dead connections.
      * Checks if PING received within 60 seconds, attempts reconnect if not.

package/dist/connect.d.ts.map

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

package/dist/connect.js

@@ -1,31 +1,57 @@
 "use strict";
 /**
  * @purpose Client for connecting to remote agents via WebSocket with automatic keep-alive, session recovery, and polling fallback
- * @llm-note
- *   Dependencies: imports from [src/address.ts (AddressData, generate, load, sign, etc.), src/types.ts (SessionStatus)] | imported by [src/index.ts, src/react/index.ts, examples/connect-example.ts, tests/connect.test.ts] | tested by [tests/connect.test.ts]
- *   Data flow: connect(address, options) → creates RemoteAgent → agent.input(prompt) → generates session_id (UUID) → saves to localStorage → opens WebSocket → sends INPUT{type, input_id, to, prompt, session{session_id}, signature?} → receives PING every 30s, responds with PONG → receives stream events (tool_call, tool_result, thinking, assistant) → receives OUTPUT{result, session_id, session} → clears localStorage → returns Response{text, done} | On disconnect/timeout: polls GET /sessions/{session_id} every 10s until result ready
- *   State/Effects: opens WebSocket connections | sends signed/unsigned messages | updates internal UI events array | syncs session from server | generates/loads Ed25519 keys | saves keys to localStorage (browser) or .co/keys/ (Node.js) | saves active session_id to localStorage for recovery | polls server via HTTP fetch on connection failure | health check interval detects dead connections
- *   Integration: exposes connect(address, options), RemoteAgent class, Response, ChatItem types, AgentStatus, ConnectOptions{enablePolling, pollIntervalMs, maxPollAttempts} | supports relay mode (wss://oo.openonion.ai) and direct mode (deployed agent URL) | Ed25519 signing for authentication | session persistence across calls | automatic recovery from network failures, timeouts, page refreshes
- *   Performance: 600s timeout default (10 min, up from 180s) | real-time WebSocket streaming | parallel tool execution on agent side | no client-side caching | auto-generates keys if missing | PING/PONG keep-alive every 30s | health check every 10s | polling fallback on failures | results persist 24h server-side
- *   Errors: throws on timeout (600s default) after polling exhausted | throws on WebSocket errors after polling attempt | throws on connection close after polling attempt | throws on ERROR messages from server | throws if session expired (404) during polling | includes error context in messages | graceful fallback to polling prevents data loss
  *
- * Architecture:
- *   Normal Flow:
- *     Client → /ws/input → Relay → Agent → OUTPUT → Relay → Client
+ * @graph Connection Modes
+ *
+ *   connect('0xAddr', options?)
+ *        │
+ *        ├── directUrl set? ──yes──▶ Direct: wss://{directUrl}/ws
+ *        │
+ *        ├── resolveEndpoint()? ──found──▶ Direct: resolved wsUrl
+ *        │
+ *        └── fallback ──▶ Relay: {relayUrl}/ws/input
  *
- *   Keep-Alive:
- *     Server sends PING every 30s → Client responds PONG → Health check every 10s
+ * @graph Remote Agent Communication Flow
  *
- *   Recovery Flow (on disconnect/timeout):
- *     WebSocket fails → Poll GET /sessions/{session_id} every 10s → Status="done" → Return result
+ *   Client (TS)                       Relay / Agent
+ *        │                                │
+ *        │  connect('0xAddr')             │
+ *        │  ──▶ RemoteAgent               │
+ *        │  (lazy-load Ed25519 keys)      │
+ *        │                                │
+ *        │  agent.input("prompt")         │
+ *        │  ──▶ WebSocket open ─────────▶ │
+ *        │      INPUT{prompt, sig, to}    │  ──▶ agent processes
+ *        │                                │
+ *        │  ◀── PING ◀───────────────── │  (every 30s keep-alive)
+ *        │  ──▶ PONG ──────────────────▶ │
+ *        │                                │
+ *        │  ◀── stream events ◀──────── │  (thinking, tool_call,
+ *        │      (update agent.ui[])       │   tool_result, assistant)
+ *        │                                │
+ *        │  ◀── OUTPUT{result, session} ◀ │
+ *        │  ws.close()                    │
+ *        ▼                                ▼
  *
- * Related Files:
- *   - oo-api/relay/routes.py: Relay server WebSocket endpoints
- *   - connectonion/network/connect.py: Python equivalent of this file
- *   - connectonion/network/asgi/websocket.py: Server-side PING sender
- *   - connectonion/network/host/session.py: SessionStorage for 24h TTL
- *   - src/react/index.ts: useAgent hook built on RemoteAgent
- *   - src/types.ts: SessionStatus, PollResult interfaces
+ * @graph Recovery Flow (on disconnect/timeout)
+ *
+ *   WebSocket fails
+ *        │
+ *        ▼
+ *   Poll GET /sessions/{session_id} (every 10s)
+ *        │
+ *        ├── status: "running" ──▶ retry poll
+ *        ├── status: "done"    ──▶ return result
+ *        └── 404 / max attempts ──▶ throw Error
+ *
+ * @llm-note
+ *   Dependencies: imports from [src/address.ts (AddressData, generate, load, sign, etc.), src/types.ts (SessionStatus)] | imported by [src/index.ts, src/react/index.ts, examples/connect-example.ts, tests/connect.test.ts] | tested by [tests/connect.test.ts]
+ *   Data flow: connect(address, options) → creates RemoteAgent → agent.input(prompt) → generates session_id (UUID) → opens WebSocket → sends INPUT{type, input_id, to, prompt, session{session_id, messages}, signature?} → receives PING every 30s, responds with PONG → receives stream events (tool_call, tool_result, thinking, assistant) with session state → receives OUTPUT{result, session_id, session} → returns Response{text, done} | On disconnect/timeout: polls GET /sessions/{session_id} every 10s until result ready
+ *   State/Effects: opens WebSocket connections | sends signed/unsigned messages | updates internal UI events array | syncs session from server events (in-memory) | generates/loads Ed25519 keys | saves keys to localStorage (browser) or .co/keys/ (Node.js) | polls server via HTTP fetch on connection failure | health check interval detects dead connections
+ *   Integration: exposes connect(address, options), RemoteAgent class, Response, ChatItem types, AgentStatus, ConnectOptions{enablePolling, pollIntervalMs, maxPollAttempts} | supports relay mode (wss://oo.openonion.ai) and direct mode (deployed agent URL) | Ed25519 signing for authentication | session persistence across calls | automatic recovery from network failures, timeouts, page refreshes
+ *   Performance: 600s timeout default (10 min) | real-time WebSocket streaming | PING/PONG keep-alive every 30s | health check every 10s | polling fallback on failures | results persist 24h server-side
+ *   Errors: throws on timeout (600s default) after polling exhausted | throws on WebSocket errors after polling attempt | throws on connection close after polling attempt | throws on ERROR messages from server | throws if session expired (404) during polling | graceful fallback to polling prevents data loss
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -360,17 +386,19 @@ class RemoteAgent {
      * Returns Response with text and done flag.
      *
      * @param prompt - User's input
-     * @param timeoutMs - Timeout in milliseconds (default: 600000 / 10 minutes)
+     * @param options - Optional settings: images (base64 data URLs), timeoutMs
      * @returns Response with text and done flag
      */
-    async input(prompt, timeoutMs = 600000) {
-        return this._streamInput(prompt, timeoutMs);
+    async input(prompt, options) {
+        const timeoutMs = options?.timeoutMs ?? 600000;
+        const images = options?.images;
+        return this._streamInput(prompt, timeoutMs, images);
     }
     /**
      * Async version of input (same as input, for API consistency with Python).
      */
-    async inputAsync(prompt, timeoutMs = 600000) {
-        return this.input(prompt, timeoutMs);
+    async inputAsync(prompt, options) {
+        return this.input(prompt, options);
     }
     /**
      * Respond to ask_user event.
@@ -493,32 +521,6 @@ class RemoteAgent {
         }
         throw new Error('Polling timeout: Result not ready after maximum attempts');
     }
-    /**
-     * Save session ID to localStorage (browser only).
-     */
-    _saveSessionId(sessionId) {
-        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
-            try {
-                globalThis.localStorage.setItem('connectonion_active_session', sessionId);
-            }
-            catch {
-                // Ignore localStorage errors
-            }
-        }
-    }
-    /**
-     * Clear session ID from localStorage (browser only).
-     */
-    _clearSessionId() {
-        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
-            try {
-                globalThis.localStorage.removeItem('connectonion_active_session');
-            }
-            catch {
-                // Ignore localStorage errors
-            }
-        }
-    }
     /**
      * Start health check interval to detect dead connections.
      * Checks if PING received within 60 seconds, attempts reconnect if not.
@@ -538,16 +540,13 @@ class RemoteAgent {
                 if (this._enablePolling) {
                     this._pollForResult(sessionId)
                         .then((result) => {
-                        this._clearSessionId();
                         resolve({ text: result, done: true });
                     })
                         .catch((pollError) => {
-                        this._clearSessionId();
                         reject(new Error(`Connection health check failed and polling failed: ${pollError}`));
                     });
                 }
                 else {
-                    this._clearSessionId();
                     reject(new Error('Connection health check failed: No PING received for 60 seconds'));
                 }
             }
@@ -584,21 +583,20 @@ class RemoteAgent {
      * Stream input to agent with real-time UI events.
      * Uses directUrl if provided, otherwise tries auto-discovery, then falls back to relay.
      */
-    async _streamInput(prompt, timeoutMs) {
+    async _streamInput(prompt, timeoutMs, images) {
         // Lazy-load keys on first use
         this._ensureKeys();
         // Try endpoint resolution (once, cached)
         await this._tryResolveEndpoint();
         // Add user event to UI
-        this._addChatItem({ type: 'user', content: prompt });
+        this._addChatItem({ type: 'user', content: prompt, images });
         // Add optimistic thinking (shows immediately, removed when real events arrive)
         this._addChatItem({ type: 'thinking', id: '__optimistic__', status: 'running' });
         // Set status to working
         this._status = 'working';
         const inputId = generateUUID();
-        // Generate or reuse session_id for tracking and polling fallback
+        // Reuse existing session_id or generate new one for tracking and polling fallback
         const sessionId = this._currentSession?.session_id || generateUUID();
-        this._saveSessionId(sessionId);
         // Choose connection mode: direct (explicit or resolved) or via relay
         let wsUrl;
         let isDirect = false;
@@ -634,16 +632,16 @@ class RemoteAgent {
                     if (this._enablePolling) {
                         try {
                             const result = await this._pollForResult(sessionId);
-                            this._clearSessionId();
+                            // Don't clear session - keep for next message
                             resolve({ text: result, done: true });
                         }
                         catch (pollError) {
-                            this._clearSessionId();
+                            // Don't clear session - keep for retry with context
                             reject(new Error(`Connection timed out and polling failed: ${pollError}`));
                         }
                     }
                     else {
-                        this._clearSessionId();
+                        // Don't clear session - keep for retry with context
                         reject(new Error('Connection timed out'));
                     }
                 }
@@ -667,6 +665,10 @@ class RemoteAgent {
                     prompt,
                     ...signed,
                 };
+                // Add images if provided
+                if (images && images.length > 0) {
+                    inputMessage.images = images;
+                }
                 // Only include 'to' for relay mode
                 if (!isDirect) {
                     inputMessage.to = this.address;
@@ -720,6 +722,10 @@ class RemoteAgent {
                         data?.type === 'intent' || data?.type === 'eval' || data?.type === 'compact' ||
                         data?.type === 'tool_blocked') {
                         this._handleStreamEvent(data);
+                        // Sync session state from each event (client is source of truth)
+                        if (data.session) {
+                            this._currentSession = data.session;
+                        }
                     }
                     // Handle ask_user event (agent needs more input)
                     // Keep WebSocket OPEN - user will respond via respond() method
@@ -807,6 +813,7 @@ class RemoteAgent {
                         settled = true;
                         clearTimeout(timer);
                         this._stopHealthCheck();
+                        this._removeOptimisticThinking();
                         this._status = 'idle';
                         // Sync session from server
                         if (data.session) {
@@ -821,7 +828,7 @@ class RemoteAgent {
                             }
                         }
                         this._activeWs = null; // Clear before close
-                        this._clearSessionId(); // Clear session_id on success
+                        // Don't clear session - keep for next message in conversation
                         try {
                             ws.close();
                         }
@@ -835,7 +842,7 @@ class RemoteAgent {
                         this._stopHealthCheck();
                         this._status = 'idle';
                         this._activeWs = null; // Clear before close
-                        this._clearSessionId(); // Clear session_id on error
+                        // Don't clear session - keep for retry with context
                         try {
                             ws.close();
                         }
@@ -848,7 +855,7 @@ class RemoteAgent {
                     clearTimeout(timer);
                     this._stopHealthCheck();
                     this._status = 'idle';
-                    this._clearSessionId(); // Clear session_id on error
+                    // Don't clear session - keep for retry with context
                     try {
                         ws.close();
                     }
@@ -871,7 +878,7 @@ class RemoteAgent {
                 if (this._enablePolling) {
                     try {
                         const result = await this._pollForResult(sessionId);
-                        this._clearSessionId();
+                        // Don't clear session - keep for next message
                         resolve({ text: result, done: true });
                         return;
                     }
@@ -879,7 +886,7 @@ class RemoteAgent {
                         // Polling failed, fall through to original error
                     }
                 }
-                this._clearSessionId();
+                // Don't clear session - keep for retry with context
                 reject(new Error(`WebSocket error: ${String(err)}`));
             };
             ws.onclose = async () => {
@@ -893,7 +900,7 @@ class RemoteAgent {
                     if (this._enablePolling) {
                         try {
                             const result = await this._pollForResult(sessionId);
-                            this._clearSessionId();
+                            // Don't clear session - keep for next message
                             resolve({ text: result, done: true });
                             return;
                         }
@@ -901,7 +908,7 @@ class RemoteAgent {
                             // Polling failed, fall through to original error
                         }
                     }
-                    this._clearSessionId();
+                    // Don't clear session - keep for retry with context
                     reject(new Error('Connection closed before response'));
                 }
             };

package/dist/console.d.ts

@@ -1,5 +1,36 @@
 /**
  * @purpose Dual-output logging system (terminal + optional file) that mirrors Python SDK UX with colored terminal output and @xray tool tracing
+ *
+ * @graph Dual Output Flow
+ *
+ *   Agent / Tool Executor
+ *        │
+ *        ▼
+ *   console.print(message)
+ *        │
+ *        ├──────────────────────────────┐
+ *        ▼                              ▼
+ *   ┌──────────────────┐     ┌───────────────────────┐
+ *   │  stderr (TTY)    │     │  Log File (optional)  │
+ *   │                  │     │                       │
+ *   │  [HH:MM:SS]     │     │  .co/logs/{name}.log  │
+ *   │  + ANSI colors   │     │  plain text, no ANSI  │
+ *   │  + dim timestamp │     │  + [timestamp] prefix │
+ *   └──────────────────┘     └───────────────────────┘
+ *
+ * @graph @xray Output Block
+ *
+ *   printXray(toolName, args, result, timing, context)
+ *        │
+ *        ▼
+ *   ┌───────────────────────────────────────┐
+ *   │  @xray: toolName                      │
+ *   │    agent: myAgent  iter: 3            │
+ *   │    args: { query: "hello" }           │
+ *   │    result: "world"                    │
+ *   │    timing: 42ms                       │
+ *   └───────────────────────────────────────┘
+ *
  * @llm-note
  *   Dependencies: imports from [node:fs, node:path] | imported by [src/core/agent.ts, src/tools/tool-executor.ts] | tested by agent tests
  *   Data flow: receives log messages/xray traces → formats with timestamps/colors → writes to stderr + optional file (.co/logs/{name}.log)

package/dist/console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../src/console.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,YAAY,CAAU;gBAElB,OAAO,CAAC,EAAE,MAAM;IAM5B,OAAO,CAAC,WAAW;IASnB,KAAK,CAAC,OAAO,EAAE,MAAM;IAUrB,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAgBvE,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;CACb"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../src/console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,YAAY,CAAU;gBAElB,OAAO,CAAC,EAAE,MAAM;IAM5B,OAAO,CAAC,WAAW;IASnB,KAAK,CAAC,OAAO,EAAE,MAAM;IAUrB,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAgBvE,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,IAAI;CACb"}