connectonion 0.0.8 → 0.0.9

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
+ *
+ * @graph Connection Modes
+ *
+ *   connect('0xAddr', options?)
+ *        │
+ *        ├── directUrl set? ──yes──▶ Direct: wss://{directUrl}/ws
+ *        │
+ *        ├── resolveEndpoint()? ──found──▶ Direct: resolved wsUrl
+ *        │
+ *        └── fallback ──▶ Relay: {relayUrl}/ws/input
+ *
+ * @graph Remote Agent Communication Flow
+ *
+ *   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()                    │
+ *        ▼                                ▼
+ *
+ * @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) → 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
- *
- *   Keep-Alive:
- *     Server sends PING every 30s → Client responds PONG → Health check every 10s
- *
- *   Recovery Flow (on disconnect/timeout):
- *     WebSocket fails → Poll GET /sessions/{session_id} every 10s → Status="done" → Return result
- *
- * 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
+ *   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';
@@ -205,6 +231,7 @@ export interface SessionState {
     }>;
     trace?: unknown[];
     turn?: number;
+    _savedAt?: number;
 }
 /** Agent status */
 export type AgentStatus = 'idle' | 'working' | 'waiting';
@@ -330,8 +357,27 @@ export declare class RemoteAgent {
     private _saveSessionId;
     /**
      * Clear session ID from localStorage (browser only).
+     * Also clears the full session data.
      */
     private _clearSessionId;
+    /**
+     * Save full session state to localStorage (browser only).
+     * Enables conversation recovery after browser refresh.
+     */
+    private _saveSession;
+    /**
+     * Load session state from localStorage (browser only).
+     * Returns null if session doesn't exist.
+     */
+    private _loadSession;
+    /**
+     * Load active session ID from localStorage (browser only).
+     */
+    private _loadActiveSessionId;
+    /**
+     * Clear specific session from localStorage (browser only).
+     */
+    private _clearSession;
     /**
      * 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
+ *
+ * @graph Connection Modes
+ *
+ *   connect('0xAddr', options?)
+ *        │
+ *        ├── directUrl set? ──yes──▶ Direct: wss://{directUrl}/ws
+ *        │
+ *        ├── resolveEndpoint()? ──found──▶ Direct: resolved wsUrl
+ *        │
+ *        └── fallback ──▶ Relay: {relayUrl}/ws/input
+ *
+ * @graph Remote Agent Communication Flow
+ *
+ *   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()                    │
+ *        ▼                                ▼
+ *
+ * @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) → 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
- *
- *   Keep-Alive:
- *     Server sends PING every 30s → Client responds PONG → Health check every 10s
- *
- *   Recovery Flow (on disconnect/timeout):
- *     WebSocket fails → Poll GET /sessions/{session_id} every 10s → Status="done" → Return result
- *
- * 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
+ *   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;
@@ -346,6 +372,11 @@ class RemoteAgent {
             catch { /* ignore */ }
             this._activeWs = null;
         }
+        // Clear session from localStorage
+        if (this._currentSession?.session_id) {
+            this._clearSession(this._currentSession.session_id);
+        }
+        this._clearSessionId();
         this._currentSession = null;
         this._chatItems = [];
         this._status = 'idle';
@@ -508,10 +539,16 @@ class RemoteAgent {
     }
     /**
      * Clear session ID from localStorage (browser only).
+     * Also clears the full session data.
      */
     _clearSessionId() {
         if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
             try {
+                // Get active session_id and clear its data
+                const activeId = globalThis.localStorage.getItem('connectonion_active_session');
+                if (activeId) {
+                    this._clearSession(activeId);
+                }
                 globalThis.localStorage.removeItem('connectonion_active_session');
             }
             catch {
@@ -519,6 +556,75 @@ class RemoteAgent {
             }
         }
     }
+    /**
+     * Save full session state to localStorage (browser only).
+     * Enables conversation recovery after browser refresh.
+     */
+    _saveSession(session) {
+        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis && session.session_id) {
+            try {
+                const sessionWithTimestamp = {
+                    ...session,
+                    _savedAt: Date.now()
+                };
+                const key = `connectonion_session_${session.session_id}`;
+                globalThis.localStorage.setItem(key, JSON.stringify(sessionWithTimestamp));
+            }
+            catch {
+                // Ignore localStorage errors (quota exceeded, etc.)
+            }
+        }
+    }
+    /**
+     * Load session state from localStorage (browser only).
+     * Returns null if session doesn't exist.
+     */
+    _loadSession(sessionId) {
+        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
+            try {
+                const key = `connectonion_session_${sessionId}`;
+                const stored = globalThis.localStorage.getItem(key);
+                if (stored) {
+                    const data = JSON.parse(stored);
+                    // Remove timestamp before returning
+                    delete data._savedAt;
+                    return data;
+                }
+            }
+            catch {
+                // Ignore localStorage errors
+            }
+        }
+        return null;
+    }
+    /**
+     * Load active session ID from localStorage (browser only).
+     */
+    _loadActiveSessionId() {
+        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
+            try {
+                return globalThis.localStorage.getItem('connectonion_active_session');
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Clear specific session from localStorage (browser only).
+     */
+    _clearSession(sessionId) {
+        if (isBrowserEnv() && typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
+            try {
+                const key = `connectonion_session_${sessionId}`;
+                globalThis.localStorage.removeItem(key);
+            }
+            catch {
+                // Ignore localStorage errors
+            }
+        }
+    }
     /**
      * Start health check interval to detect dead connections.
      * Checks if PING received within 60 seconds, attempts reconnect if not.
@@ -596,6 +702,14 @@ class RemoteAgent {
         // Set status to working
         this._status = 'working';
         const inputId = generateUUID();
+        // Try to restore session from localStorage if not in memory
+        const activeSessionId = this._loadActiveSessionId();
+        if (activeSessionId && !this._currentSession) {
+            const loaded = this._loadSession(activeSessionId);
+            if (loaded) {
+                this._currentSession = loaded;
+            }
+        }
         // Generate or reuse session_id for tracking and polling fallback
         const sessionId = this._currentSession?.session_id || generateUUID();
         this._saveSessionId(sessionId);
@@ -634,16 +748,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'));
                     }
                 }
@@ -808,9 +922,10 @@ class RemoteAgent {
                         clearTimeout(timer);
                         this._stopHealthCheck();
                         this._status = 'idle';
-                        // Sync session from server
+                        // Sync session from server and persist to localStorage
                         if (data.session) {
                             this._currentSession = data.session;
+                            this._saveSession(data.session); // Save for next message
                         }
                         // Add agent response to UI (skip if already added via 'assistant' event)
                         const result = data.result || '';
@@ -821,7 +936,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 +950,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 +963,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 +986,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 +994,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 +1008,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 +1016,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"}

package/dist/console.js

@@ -1,6 +1,37 @@
 "use strict";
 /**
  * @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)