connectonion 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ConnectOnion Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# 🚀 ConnectOnion TypeScript SDK
+
+> **Build AI agents that actually DO things** - Zero boilerplate, maximum power
+
+[![npm version](https://img.shields.io/npm/v/connectonion.svg)](https://www.npmjs.com/package/connectonion)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ What is ConnectOnion?
+
+ConnectOnion is a TypeScript SDK that makes building AI agents ridiculously simple. Your functions become tools. Your classes become toolsets. Your agents just work.
+
+```typescript
+// This is all you need for a working AI agent
+import { Agent } from 'connectonion';
+
+function calculateTip(bill: number, percentage: number): number {
+  return bill * (percentage / 100);
+}
+
+const agent = new Agent({
+  name: 'assistant',
+  tools: [calculateTip]  // Your function is now an AI tool!
+});
+
+const response = await agent.input('What\'s a 20% tip on $85?');
+// "A 20% tip on $85 would be $17.00"
+```
+
+**That's it.** No schemas. No configurations. No boilerplate.
+
+## 🆕 Python-Parity Highlights
+
+- Default LLM: Anthropic Claude Sonnet 3.5 (`claude-3-5-sonnet-20241022`)
+- LLM factory: routes `claude-*`, `gpt-*`/`o*`, `gemini-*`, and `co/*` (OpenOnion)
+- Structured output: `llm.structuredComplete(messages, schema)` returns validated JSON
+- Multi‑turn: agent now keeps conversation state until `resetConversation()`
+- Console logging: progress printed and logged to `./.co/logs/{name}.log` by default
+- Env override: set `CONNECTONION_LOG` to choose a custom log file
+
+## 🎯 Why CO?
+
+### 🧠 **Smart by Default**
+- Agents automatically understand when and how to use tools
+- Built-in conversation memory and context management
+- Parallel tool execution for maximum efficiency
+
+### 🛠️ **Any Function is a Tool**
+```typescript
+// These all become tools automatically
+function sendEmail(to: string, subject: string) { }
+async function fetchWeather(city: string) { }
+const calculate = (x: number, y: number) => x + y;
+
+// Even class methods!
+class Database {
+  query(sql: string) { }
+  insert(table: string, data: any) { }
+}
+```
+
+### 📝 **TypeScript Superpowers**
+- Full type safety and IntelliSense support
+- Compile-time parameter validation
+- Auto-completion for all APIs
+- JSDoc comments become tool descriptions
+
+### 💾 **Session & Trace**
+Agents keep an in-memory session (messages + tool execution trace). Inspect it with `agent.getSession()` and reset with `agent.resetConversation()`.
+
+## 🚀 Quick Start (60 seconds)
+
+### 1. Install
+```bash
+npm install connectonion
+# or
+yarn add connectonion
+# or
+pnpm add connectonion
+```
+
+### 2. Set API Key
+```bash
+export OPENAI_API_KEY=sk-...
+# or use .env file
+
+# Anthropic (default)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Gemini (optional)
+export GEMINI_API_KEY=sk-gem-...  # or GOOGLE_API_KEY
+
+# OpenOnion managed keys (optional, for co/* models)
+export OPENONION_API_KEY=oo-...
+export OPENONION_BASE_URL=https://oo.openonion.ai/v1
+# Dev mode: uses http://localhost:8000/v1
+export OPENONION_DEV=1
+
+# Console log override (otherwise ./.co/logs/{name}.log)
+export CONNECTONION_LOG=./my-agent.log
+```
+
+### 3. Create Your First Agent
+```typescript
+import { Agent } from 'connectonion';
+
+// Define what your agent can do
+function searchWeb(query: string): string {
+  // Your search logic here
+  return `Results for ${query}...`;
+}
+
+function sendMessage(to: string, message: string): string {
+  // Your messaging logic here
+  return `Message sent to ${to}`;
+}
+
+// Create the agent
+const agent = new Agent({
+  name: 'personal-assistant',
+  tools: [searchWeb, sendMessage],
+  systemPrompt: 'You are a helpful personal assistant.'
+});
+
+// Use it!
+const response = await agent.input(
+  'Search for TypeScript tutorials and send the link to John'
+);
+```
+
+## 🎨 Real-World Examples
+
+### Example 1: Customer Service Bot
+```typescript
+class CustomerService {
+  // Each method becomes a tool automatically
+  async lookupOrder(orderId: string): Promise<Order> {
+    return await db.orders.findOne({ id: orderId });
+  }
+
+  async processRefund(orderId: string, reason: string): Promise<RefundResult> {
+    const order = await this.lookupOrder(orderId);
+    return await payments.refund(order, reason);
+  }
+
+  async sendEmail(to: string, subject: string, body: string): Promise<void> {
+    await emailService.send({ to, subject, body });
+  }
+}
+
+// Create an agent with all methods as tools
+const agent = new Agent({
+  name: 'customer-service',
+  tools: [new CustomerService()],  // All methods become tools!
+  systemPrompt: 'You are a helpful customer service representative.'
+});
+
+// Handle customer requests naturally
+const response = await agent.input(
+  'Order #12345 arrived damaged, I want a refund'
+);
+// Agent will: lookup order → process refund → send confirmation email
+```
+
+### Example 2: Data Analysis Agent
+```typescript
+import { Agent } from 'connectonion';
+import * as fs from 'fs';
+import * as csv from 'csv-parse';
+
+// Tools for data analysis
+function readCSV(filepath: string): any[] {
+  const data = fs.readFileSync(filepath, 'utf-8');
+  return csv.parse(data, { columns: true });
+}
+
+function analyzeData(data: any[], column: string): Statistics {
+  // Statistical analysis logic
+  return {
+    mean: calculateMean(data, column),
+    median: calculateMedian(data, column),
+    stdDev: calculateStdDev(data, column)
+  };
+}
+
+function createChart(data: any[], type: string): string {
+  // Chart generation logic
+  return `chart_${Date.now()}.png`;
+}
+
+// Create the analyst
+const analyst = new Agent({
+  name: 'data-analyst',
+  tools: [readCSV, analyzeData, createChart],
+  model: 'gpt-4', // Use GPT-4 for complex analysis
+  systemPrompt: 'You are an expert data analyst. Provide insights and visualizations.'
+});
+
+// Analyze data with natural language
+const report = await analyst.input(
+  'Analyze sales.csv, focus on Q4 performance, and create a bar chart'
+);
+```
+
+### Example 3: DevOps Automation
+```typescript
+class DevOpsTools {
+  async deployToProduction(service: string, version: string) {
+    // Kubernetes deployment logic
+    return `Deployed ${service}:${version} to production`;
+  }
+
+  async checkSystemHealth(service: string) {
+    // Health check logic
+    return { status: 'healthy', uptime: '99.9%' };
+  }
+
+  async rollback(service: string) {
+    // Rollback logic
+    return `Rolled back ${service} to previous version`;
+  }
+
+  async queryLogs(service: string, timeRange: string, filter?: string) {
+    // Log querying logic
+    return [`[ERROR] Connection timeout`, `[WARN] High memory usage`];
+  }
+}
+
+const devops = new Agent({
+  name: 'devops-assistant',
+  tools: [new DevOpsTools()],
+  maxIterations: 20, // Complex operations might need more iterations
+  systemPrompt: 'You are a DevOps expert. Be cautious with production changes.'
+});
+
+// Natural language DevOps
+await devops.input(
+  'Check if api-service is healthy, if not check logs and consider rollback'
+);
+```
+
+## 🔧 Advanced Features
+
+### Dynamic Tool Management
+```typescript
+// Add tools at runtime
+agent.addTool(newFunction);
+
+// Remove tools
+agent.removeTool('oldToolName');
+
+// List available tools
+const tools = agent.getTools();
+console.log(tools.map(t => `${t.name}: ${t.description}`));
+```
+
+### Custom LLM Providers
+```typescript
+import { LLM, Agent } from 'connectonion';
+
+class CustomLLM implements LLM {
+  async complete(messages, tools) {
+    // Your LLM implementation
+    return { content: '...', toolCalls: [], rawResponse: {} };
+  }
+}
+
+const agent = new Agent({
+  name: 'custom-agent',
+  llm: new CustomLLM()
+});
+```
+
+### Session & Trace
+```typescript
+const { messages, trace } = agent.getSession();
+console.log(messages.length, trace.length);
+agent.clearHistory(); // clear in-memory trace
+```
+
+### Override Iterations for Complex Tasks
+```typescript
+// Simple task - use default
+await agent.input('What is 2+2?');
+
+// Complex multi-step task - allow more iterations
+await agent.input(
+  'Analyze all CSV files, generate reports, and email summaries',
+  30 // Allow up to 30 iterations
+);
+```
+
+## 📚 Documentation
+
+- **[Getting Started Guide](docs/getting-started.md)** - Complete setup walkthrough
+- **[API Reference](docs/api.md)** - Full API documentation
+- **[Examples](docs/examples.md)** - More real-world examples
+- **[Tool System](docs/tools.md)** - Deep dive into tools
+- **[Troubleshooting](docs/troubleshooting.md)** - Common issues & solutions
+
+## 🏗️ Project Structure
+
+```
+your-project/
+├── src/
+│   ├── agents/        # Your agent definitions
+│   ├── tools/         # Custom tool implementations
+│   └── index.ts       # Main entry point
+├── .env               # API keys (never commit!)
+├── package.json
+└── tsconfig.json
+```
+
+## 🤝 Contributing
+
+We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Setup
+```bash
+# Clone the repo
+git clone https://github.com/connectonion/connectonion-ts
+cd connectonion-ts
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## 📄 License
+
+MIT © [CO Team](https://github.com/connectonion)
+
+## 🔗 Links
+
+- **[Python Version](https://github.com/connectonion/connectonion)** - Original Python SDK
+- **[Discord Community](https://discord.gg/connectonion)** - Get help & share ideas
+- **[Blog](https://connectonion.com/blog)** - Tutorials and updates
+
+## 🌟 Why TypeScript?
+
+While our Python SDK is great, TypeScript offers unique advantages:
+
+- **Type Safety**: Catch errors at compile time
+- **IDE Support**: Unmatched IntelliSense and auto-completion
+- **Modern Async**: Native async/await and Promise handling
+- **NPM Ecosystem**: Access to millions of packages
+- **Browser Ready**: Build agents that run in browsers (coming soon!)
+
+---
+
+<p align="center">
+  Built with ❤️ by developers, for developers
+</p>
+
+<p align="center">
+  <a href="https://github.com/connectonion/connectonion-ts">⭐ Star us on GitHub</a>
+</p>

package/dist/connect.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Connect to remote agents via the relay network.
+ *
+ * Mirrors Python SDK connect(): returns a RemoteAgent proxy with input().
+ */
+type WebSocketLike = {
+    onopen: ((ev?: any) => any) | null;
+    onmessage: ((ev: {
+        data: any;
+    }) => any) | null;
+    onerror: ((ev: any) => any) | null;
+    onclose: ((ev: any) => any) | null;
+    send(data: any): void;
+    close(): void;
+};
+type WebSocketCtor = new (url: string) => WebSocketLike;
+/** Proxy to a remote agent reachable via the relay */
+export declare class RemoteAgent {
+    private address;
+    private relayUrl;
+    private WS;
+    constructor(address: string, relayUrl: string, wsCtor?: WebSocketCtor);
+    /** Send task to remote agent and await result */
+    input(prompt: string, timeoutMs?: number): Promise<string>;
+    toString(): string;
+}
+/**
+ * Connect to a remote agent.
+ *
+ * @param address Agent public key (0x...)
+ * @param relayUrl Relay announce URL (default production)
+ */
+export declare function connect(address: string, relayUrl?: string, wsCtor?: WebSocketCtor): RemoteAgent;
+export {};
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,KAAK,aAAa,GAAG;IACnB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IACnC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF,KAAK,aAAa,GAAG,KAAK,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;AAmBxD,sDAAsD;AACtD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,EAAE,CAAgB;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa;IAMrE,iDAAiD;IAC3C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAiF/D,QAAQ;CAIT;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAqE,EAC/E,MAAM,CAAC,EAAE,aAAa,GACrB,WAAW,CAEb"}

package/dist/connect.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Connect to remote agents via the relay network.
+ *
+ * Mirrors Python SDK connect(): returns a RemoteAgent proxy with input().
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteAgent = void 0;
+exports.connect = connect;
+const crypto_1 = __importDefault(require("crypto"));
+function defaultWebSocketCtor() {
+    // Prefer global WebSocket (browser), else require('ws') in Node
+    const g = globalThis;
+    if (typeof g.WebSocket === 'function') {
+        return g.WebSocket;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const WS = require('ws');
+        return WS;
+    }
+    catch {
+        throw new Error("No WebSocket implementation found. Install 'ws' (npm i ws) or provide a custom WebSocket factory.");
+    }
+}
+/** Proxy to a remote agent reachable via the relay */
+class RemoteAgent {
+    constructor(address, relayUrl, wsCtor) {
+        this.address = address;
+        this.relayUrl = relayUrl;
+        this.WS = wsCtor || defaultWebSocketCtor();
+    }
+    /** Send task to remote agent and await result */
+    async input(prompt, timeoutMs = 30000) {
+        const inputId = crypto_1.default.randomUUID();
+        const relayInputUrl = this.relayUrl.replace('/ws/announce', '/ws/input');
+        const ws = new this.WS(relayInputUrl);
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    try {
+                        ws.close();
+                    }
+                    catch { }
+                    reject(new Error('Connection timed out'));
+                }
+            }, timeoutMs);
+            ws.onopen = () => {
+                // Send INPUT message
+                const msg = {
+                    type: 'INPUT',
+                    input_id: inputId,
+                    to: this.address,
+                    prompt,
+                };
+                try {
+                    ws.send(JSON.stringify(msg));
+                }
+                catch (e) {
+                    clearTimeout(timer);
+                    if (!settled) {
+                        settled = true;
+                        try {
+                            ws.close();
+                        }
+                        catch { }
+                        reject(e);
+                    }
+                }
+            };
+            ws.onmessage = (evt) => {
+                if (settled)
+                    return;
+                try {
+                    const raw = typeof evt.data === 'string' ? evt.data : evt.data?.toString?.() ?? '';
+                    const data = JSON.parse(raw);
+                    if (data?.type === 'OUTPUT' && data?.input_id === inputId) {
+                        settled = true;
+                        clearTimeout(timer);
+                        try {
+                            ws.close();
+                        }
+                        catch { }
+                        resolve(data?.result ?? '');
+                    }
+                    else if (data?.type === 'ERROR') {
+                        settled = true;
+                        clearTimeout(timer);
+                        try {
+                            ws.close();
+                        }
+                        catch { }
+                        reject(new Error(String(data?.error || 'Agent error')));
+                    }
+                    else {
+                        // Ignore unrelated message; keep waiting
+                    }
+                }
+                catch (e) {
+                    settled = true;
+                    clearTimeout(timer);
+                    try {
+                        ws.close();
+                    }
+                    catch { }
+                    reject(e);
+                }
+            };
+            ws.onerror = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                try {
+                    ws.close();
+                }
+                catch { }
+                reject(new Error(`WebSocket error: ${String(err?.message || err)}`));
+            };
+            ws.onclose = () => {
+                // If closed without settling, treat as error
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    reject(new Error('Connection closed before response'));
+                }
+            };
+        });
+    }
+    toString() {
+        const short = this.address.length > 12 ? this.address.slice(0, 12) + '...' : this.address;
+        return `RemoteAgent(${short})`;
+    }
+}
+exports.RemoteAgent = RemoteAgent;
+/**
+ * Connect to a remote agent.
+ *
+ * @param address Agent public key (0x...)
+ * @param relayUrl Relay announce URL (default production)
+ */
+function connect(address, relayUrl = process.env.RELAY_URL || 'wss://oo.openonion.ai/ws/announce', wsCtor) {
+    return new RemoteAgent(address, relayUrl, wsCtor);
+}

package/dist/console.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @purpose Dual-output logging system (terminal + optional file) that mirrors Python SDK UX with colored terminal output and @xray tool tracing
+ * @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)
+ *   State/Effects: writes to stderr via console.error | appends to logFile if configured | creates log directories with fs.mkdirSync
+ *   Integration: exposes print(message), printXray(toolName, args, result, timing, context) | used by Agent for all output | ANSI color support via isTTY detection
+ */
+export declare class Console {
+    private logPath?;
+    private colorEnabled;
+    constructor(logFile?: string);
+    private initLogFile;
+    print(message: string): void;
+    printXray(toolName: string, toolArgs: Record<string, any>, result: any, timingMs: number, context?: {
+        agent?: string;
+        iteration?: number;
+        userPrompt?: string;
+    }): void;
+    private toPlain;
+    private stylize;
+    private code;
+    private green;
+    private red;
+    private yellow;
+    private cyan;
+    private dim;
+    private bold;
+}
+//# sourceMappingURL=console.d.ts.map

package/dist/console.d.ts.map

@@ -0,0 +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"}