connectonion 0.0.1

package/dist/console.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * @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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Console = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class Console {
+    constructor(logFile) {
+        this.logPath = logFile;
+        this.colorEnabled = !!process.stderr.isTTY || process.env.FORCE_COLOR === '1';
+        if (this.logPath)
+            this.initLogFile();
+    }
+    initLogFile() {
+        const dir = path.dirname(this.logPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const header = `\n============================================================\n` +
+            `Session started: ${new Date().toISOString()}\n` +
+            `============================================================\n\n`;
+        fs.appendFileSync(this.logPath, header, 'utf-8');
+    }
+    print(message) {
+        const timestamp = new Date().toTimeString().split(' ')[0];
+        const line = `${this.dim(timestamp)} ${this.stylize(message)}`;
+        // stderr-like behavior
+        console.error(line);
+        if (this.logPath) {
+            fs.appendFileSync(this.logPath, `[${timestamp}] ${this.toPlain(message)}\n`, 'utf-8');
+        }
+    }
+    printXray(toolName, toolArgs, result, timingMs, context) {
+        // Simple tabular block
+        this.print(`@xray: ${toolName}`);
+        if (context?.agent)
+            this.print(`  agent: ${context.agent}`);
+        if (context?.userPrompt)
+            this.print(`  task: ${context.userPrompt.slice(0, 80)}`);
+        if (context?.iteration != null)
+            this.print(`  iteration: ${context.iteration}`);
+        for (const [k, v] of Object.entries(toolArgs || {})) {
+            const s = String(v);
+            this.print(`  ${k}: ${s.length > 120 ? s.slice(0, 120) + '...' : s}`);
+        }
+        const rs = String(result);
+        this.print(`  result: ${rs.length > 120 ? rs.slice(0, 120) + '...' : rs}`);
+        this.print(`  timing: ${timingMs.toFixed(1)}ms`);
+    }
+    toPlain(message) {
+        return message
+            .replace(/\[[^\]]+\]/g, '')
+            .replace('→', '->')
+            .replace('←', '<-')
+            .replace('✓', '[OK]')
+            .replace('✗', '[ERROR]');
+    }
+    stylize(msg) {
+        // Simple heuristic coloring similar to Python Rich output
+        if (!this.colorEnabled)
+            return msg;
+        if (msg.startsWith('→'))
+            return this.yellow(msg);
+        if (msg.startsWith('←'))
+            return this.green(msg);
+        if (msg.startsWith('✓'))
+            return this.green(msg);
+        if (msg.startsWith('✗'))
+            return this.red(msg);
+        if (msg.startsWith('@xray'))
+            return this.cyan(msg);
+        if (msg.startsWith('INPUT:'))
+            return this.bold(msg);
+        return msg;
+    }
+    // Color helpers
+    code(s, c) { return this.colorEnabled ? `\x1b[${c}m${s}\x1b[0m` : s; }
+    green(s) { return this.code(s, 32); }
+    red(s) { return this.code(s, 31); }
+    yellow(s) { return this.code(s, 33); }
+    cyan(s) { return this.code(s, 36); }
+    dim(s) { return this.code(s, 2); }
+    bold(s) { return this.code(s, 1); }
+}
+exports.Console = Console;

package/dist/core/agent.d.ts

@@ -0,0 +1,233 @@
+/**
+ * @purpose Main Agent orchestrator that combines LLM reasoning with parallel tool execution, multi-turn conversations, and interactive debugging
+ * @llm-note
+ *   Dependencies: imports from [src/types, src/llm/index, src/console, src/tools/tool-utils, src/trust/index, node:fs, node:dotenv, node:readline] | imported by [src/index.ts] | tested by [tests/agent.test.ts, tests/e2e/*.test.ts]
+ *   Data flow: receives user prompt → lazy-init messages array (system + user) → LLM loop (max 10 iterations) → parallel tool execution via Promise.all → adds tool results to messages → repeats until no tool calls → returns final text response
+ *   State/Effects: mutates this.messages (persistent conversation state) | writes to Console (stderr + optional file) | reads systemPrompt from file if path provided | reads env for API keys/config
+ *   Integration: exposes input(prompt, maxIterations?), resetConversation(), addTool(), removeTool(), getTools(), executeTool(), autoDebug(), getSession(), getTrust() | uses createLLM() factory | tool execution at line 285-302 (parallel) | main loop at line 221-267
+ *   Performance: parallel tool execution via Promise.all | no caching | tool map for O(1) lookup | max 10 iterations default (configurable)
+ *   ⚠️ messages persist across input() calls until resetConversation() | @xray tools pause execution in debug mode | tool errors returned to LLM for retry
+ */
+import { AgentConfig, Tool, Message, ToolResult } from '../types';
+/**
+ * Agent class - The core of ConnectOnion
+ *
+ * An Agent combines:
+ * - LLM for intelligence and reasoning
+ * - Tools for taking actions
+ * - In-memory session (messages + trace)
+ * - System prompts for personality
+ *
+ * @example
+ * ```typescript
+ * // Create a simple agent with a calculator tool
+ * function add(a: number, b: number): number {
+ *   return a + b;
+ * }
+ *
+ * const agent = new Agent({
+ *   name: 'calculator',
+ *   tools: [add],
+ *   systemPrompt: 'You are a helpful math assistant.'
+ * });
+ *
+ * const response = await agent.input('What is 5 plus 3?');
+ * console.log(response); // "5 plus 3 equals 8"
+ * ```
+ */
+export declare class Agent {
+    /** Unique identifier for this agent */
+    private name;
+    /** System prompt that defines the agent's behavior and personality */
+    private systemPrompt;
+    /** Maximum number of iterations for tool calling loops */
+    private maxIterations;
+    /** Array of tools available to this agent */
+    private tools;
+    /** Quick lookup map for tools by name */
+    private toolMap;
+    /** LLM instance for generating responses */
+    private llm;
+    /** Session interface aligned with Python: messages + trace */
+    /** Persistent conversation messages for multi-turn interactions */
+    private messages;
+    /** Console for terminal + optional file logging */
+    private console;
+    /** Current iteration counter for logging */
+    private currentIteration;
+    /** Debug flag to pause at @xray tools */
+    private debugEnabled;
+    /** Trust configuration object */
+    private _trust;
+    /** In-memory trace entries for xray-style introspection */
+    private trace;
+    /** Last user prompt, for xray context */
+    private lastUserPrompt;
+    /**
+     * Creates a new Agent instance
+     *
+     * @param config - Configuration object for the agent
+     * @param config.name - Unique name for the agent (used for behavior tracking)
+     * @param config.llm - Optional custom LLM instance
+     * @param config.tools - Array of tools (functions, class instances, or Tool objects)
+     * @param config.systemPrompt - System prompt defining agent behavior
+     * @param config.apiKey - API key for LLM provider (uses env var if not provided)
+     * @param config.model - Model to use (default: 'gpt-4o-mini')
+     * @param config.maxIterations - Max iterations for tool calling (default: 10)
+     *
+     * @example
+     * ```typescript
+     * // With environment variable for API key
+     * const agent = new Agent({
+     *   name: 'my-agent',
+     *   tools: [myTool1, myTool2]
+     * });
+     *
+     * // With explicit API key
+     * const agent = new Agent({
+     *   name: 'my-agent',
+     *   apiKey: 'sk-...',
+     *   model: 'gpt-4',
+     *   tools: [myTool]
+     * });
+     * ```
+     */
+    constructor(config: AgentConfig);
+    /**
+     * Process user input and generate a response
+     *
+     * This is the main entry point for interacting with the agent.
+     * The agent will:
+     * 1. Process the input prompt
+     * 2. Decide whether to use tools
+     * 3. Execute any necessary tool calls
+     * 4. Generate a final response
+     *
+     * @param prompt - The user's input prompt
+     * @param maxIterations - Override the default max iterations for this request
+     * @returns The agent's response as a string
+     *
+     * @example
+     * ```typescript
+     * const response = await agent.input('What is the weather in NYC?');
+     * console.log(response);
+     *
+     * // With custom iteration limit for complex tasks
+     * const response = await agent.input(
+     *   'Analyze this data and create a report',
+     *   20 // Allow more iterations for complex task
+     * );
+     * ```
+     */
+    input(prompt: string, maxIterations?: number): Promise<string>;
+    /**
+     * Execute multiple tool calls in parallel
+     *
+     * @param toolCalls - Array of tool calls to execute
+     * @returns Array of results with their corresponding call IDs
+     *
+     * @private
+     */
+    private executeToolCalls;
+    /**
+     * Execute a single tool call
+     *
+     * @param name - Name of the tool to execute
+     * @param args - Arguments to pass to the tool
+     * @param callId - Unique identifier for this tool call
+     * @returns The result of the tool execution
+     *
+     * @private
+     */
+    private executeToolCall;
+    /** Pause at @xray breakpoint with basic interactive menu */
+    private pauseAtBreakpoint;
+    /** Start a debugging session. If prompt provided, runs single session. */
+    autoDebug(prompt?: string): Promise<string | void>;
+    /** Get trust configuration */
+    getTrust(): any;
+    /**
+     * Get the current in-memory session (messages + tool execution trace)
+     */
+    getSession(): {
+        messages: Message[];
+        trace: {
+            tool_name: string;
+            timing: number;
+            status: string;
+            args?: any;
+            result?: any;
+            iteration?: number;
+        }[];
+        iteration: number;
+        user_prompt: string;
+    };
+    /**
+     * Clear the in-memory tool execution trace for this session
+     */
+    clearHistory(): void;
+    /**
+     * Get all available tools for this agent
+     *
+     * @returns Array of Tool objects
+     *
+     * @example
+     * ```typescript
+     * const tools = agent.getTools();
+     * console.log('Available tools:');
+     * tools.forEach(tool => {
+     *   console.log(`- ${tool.name}: ${tool.description}`);
+     * });
+     * ```
+     */
+    getTools(): Tool[];
+    /**
+     * List tool names for quick inspection
+     */
+    listTools(): string[];
+    /**
+     * Dynamically add a new tool to the agent
+     *
+     * @param tool - Tool to add (function, class instance, or Tool object)
+     *
+     * @example
+     * ```typescript
+     * // Add a function as a tool
+     * function newTool(param: string): string {
+     *   return `Processed: ${param}`;
+     * }
+     * agent.addTool(newTool);
+     *
+     * // Add a class instance
+     * class MyService {
+     *   getData(): string { return 'data'; }
+     * }
+     * agent.addTool(new MyService());
+     * ```
+     */
+    addTool(tool: Tool | Function | any): void;
+    /**
+     * Remove a tool by name
+     *
+     * @param name - Name of the tool to remove
+     * @returns true if the tool was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const removed = agent.removeTool('oldTool');
+     * if (removed) {
+     *   console.log('Tool removed successfully');
+     * }
+     * ```
+     */
+    removeTool(name: string): boolean;
+    /**
+     * Execute a single tool by name with arguments (manual invocation)
+     */
+    executeTool(name: string, args?: Record<string, any>): Promise<ToolResult>;
+    /**
+     * Reset the conversation, keeping tools and configuration intact
+     */
+    resetConversation(): void;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,WAAW,EACX,IAAI,EAEJ,OAAO,EACP,UAAU,EACX,MAAM,UAAU,CAAC;AAalB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,KAAK;IAChB,uCAAuC;IACvC,OAAO,CAAC,IAAI,CAAS;IAErB,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAS;IAE7B,0DAA0D;IAC1D,OAAO,CAAC,aAAa,CAAS;IAE9B,6CAA6C;IAC7C,OAAO,CAAC,KAAK,CAAS;IAEtB,yCAAyC;IACzC,OAAO,CAAC,OAAO,CAAoB;IAEnC,4CAA4C;IAC5C,OAAO,CAAC,GAAG,CAAM;IAEjB,8DAA8D;IAG9D,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAA0B;IAE1C,mDAAmD;IACnD,OAAO,CAAC,OAAO,CAAU;IAEzB,4CAA4C;IAC5C,OAAO,CAAC,gBAAgB,CAAa;IACrC,yCAAyC;IACzC,OAAO,CAAC,YAAY,CAAS;IAC7B,iCAAiC;IACjC,OAAO,CAAC,MAAM,CAAa;IAC3B,2DAA2D;IAC3D,OAAO,CAAC,KAAK,CAAkH;IAC/H,yCAAyC;IACzC,OAAO,CAAC,cAAc,CAAuB;IAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBACS,MAAM,EAAE,WAAW;IAsD/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0EpE;;;;;;;OAOG;YACW,gBAAgB;IAmB9B;;;;;;;;;OASG;YACW,eAAe;IAyD7B,4DAA4D;YAC9C,iBAAiB;IAyB/B,0EAA0E;IACpE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAqBxD,8BAA8B;IAC9B,QAAQ;IAER;;OAEG;IACH,UAAU;;;uBA/UwB,MAAM;oBAAU,MAAM;oBAAU,MAAM;mBAAS,GAAG;qBAAW,GAAG;wBAAc,MAAM;;;;;IAwVtH;;OAEG;IACH,YAAY;IAKZ;;;;;;;;;;;;;OAaG;IACH,QAAQ,IAAI,IAAI,EAAE;IAIlB;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,GAAG,GAAG,IAAI;IAQ1C;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAUjC;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAKpF;;OAEG;IACH,iBAAiB,IAAI,IAAI;CAI1B"}