@intella/sdk 0.0.1

package/README.md

@@ -0,0 +1,492 @@
+# Intella SDK
+
+An agent orchestrator SDK for managing tasks across multiple AI agents using AI SDK v6 as a consistent interface.
+
+## Features
+
+- **Unified Interface**: Consistent API for interacting with multiple AI providers
+- **Agent Management**: Easy selection and configuration of different agents
+- **Multi-Agent Orchestration**: Coordinate multiple agents working on a single task
+- **Framework Agnostic**: Works in Node.js, React, and other TypeScript/JavaScript environments
+- **Type Safe**: Full TypeScript support with comprehensive type definitions
+
+## Supported Agents
+
+- **Intella Lite**: Default lightweight agent (OpenAI-compatible)
+- **Claude Agent**: Powered by Claude Code provider
+- **Codex Agent**: Powered by Codex CLI provider
+- **OpenCode Agent**: Powered by OpenCode SDK provider
+
+## Installation
+
+```bash
+npm install @intella/sdk ai
+```
+
+### Peer Dependencies
+
+The SDK requires the following peer dependencies for specific agents:
+
+```bash
+# For Claude Agent
+npm install ai-sdk-provider-claude-code
+
+# For Codex Agent
+npm install ai-sdk-provider-codex-cli
+
+# For OpenCode Agent
+npm install ai-sdk-provider-opencode-sdk
+
+# For Intella Lite Agent
+npm install @ai-sdk/openai
+```
+
+**Note**: These providers use CLI authentication. Make sure you have the respective CLI tools installed and authenticated:
+- Claude Code: `npm install -g @anthropic-ai/claude-code && claude login`
+- Codex CLI: Ensure Codex CLI is installed and authenticated
+- OpenCode: `npm install -g opencode && opencode login`
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { IntellaSDK } from '@intella/sdk';
+
+const sdk = new IntellaSDK();
+
+// Configure an agent (Claude Code uses CLI authentication)
+sdk.configureAgent('claude', {
+  model: 'sonnet', // Shortcuts: 'opus', 'sonnet', 'haiku'
+  // Optional: allowedTools, disallowedTools, mcpServers, permissionMode, etc.
+});
+
+// Execute a task
+const response = await sdk.executeTask('Write a summary of AI SDK v6');
+console.log(response.text);
+```
+
+### Streaming Responses
+
+```typescript
+// Stream a task execution
+for await (const chunk of sdk.streamTask('Explain quantum computing')) {
+  process.stdout.write(chunk.text);
+  if (chunk.isDone) {
+    console.log('\nDone!');
+  }
+}
+```
+
+### Multi-Agent Orchestration
+
+```typescript
+// Sequential orchestration: agents work in sequence
+const result = await sdk.orchestrateTask(
+  'Analyze this code and generate tests',
+  ['claude', 'codex'],
+  'sequential',
+  {
+    passResults: true, // Pass previous results to next agent
+  }
+);
+
+console.log(result.result);
+console.log('Agent responses:', result.agentResponses);
+
+// Parallel orchestration: agents work simultaneously
+const parallelResult = await sdk.orchestrateTask(
+  'Write a blog post about AI',
+  ['claude', 'opencode'],
+  'parallel',
+  {
+    combineStrategy: 'merge', // Combine all responses
+  }
+);
+
+// Conditional orchestration: route based on task
+const conditionalResult = await sdk.orchestrateTask(
+  'Fix this bug',
+  ['claude', 'codex'],
+  'conditional',
+  {
+    router: (task) => {
+      // Custom routing logic
+      return task.prompt.includes('code') ? 'codex' : 'claude';
+    },
+  }
+);
+```
+
+## API Reference
+
+### IntellaSDK
+
+Main SDK class for orchestrating agents.
+
+#### Methods
+
+##### `configureAgent(agentType, config)`
+
+Configure an agent with model settings and provider-specific options.
+
+```typescript
+// Claude Code agent (uses CLI authentication)
+sdk.configureAgent('claude', {
+  model: 'sonnet', // or 'opus', 'haiku', or full model ID
+  allowedTools: ['Read', 'Write', 'Edit'],
+  permissionMode: 'default',
+});
+
+// Codex CLI agent (uses CLI auth or OPENAI_API_KEY env var)
+sdk.configureAgent('codex', {
+  model: 'gpt-5.2-codex',
+  reasoningEffort: 'high',
+  approvalMode: 'on-failure',
+  sandboxMode: 'workspace-write',
+});
+
+// OpenCode agent (uses CLI authentication)
+sdk.configureAgent('opencode', {
+  model: 'anthropic/claude-sonnet-4-5-20250929',
+});
+
+// Intella Lite agent (uses OpenAI API key)
+sdk.configureAgent('intella-lite', {
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini',
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+```
+
+##### `selectAgent(agentType, config?)`
+
+Select and configure an agent as the default.
+
+```typescript
+sdk.selectAgent('claude', { apiKey: 'your-api-key' });
+```
+
+##### `executeTask(task, agentType?)`
+
+Execute a task with the specified agent (or default).
+
+```typescript
+// Simple string prompt
+const response = await sdk.executeTask('Hello, world!');
+
+// Full task request
+const response = await sdk.executeTask({
+  prompt: 'Write a function',
+  systemPrompt: 'You are a helpful coding assistant',
+  temperature: 0.8,
+}, 'codex');
+```
+
+##### `streamTask(task, agentType?)`
+
+Stream a task execution.
+
+```typescript
+for await (const chunk of sdk.streamTask('Explain recursion')) {
+  console.log(chunk.text);
+}
+```
+
+##### `orchestrateTask(task, agents, strategy, options?)`
+
+Orchestrate a task across multiple agents.
+
+**Strategies:**
+- `sequential`: Agents work in sequence, optionally passing results
+- `parallel`: Agents work simultaneously, results combined
+- `conditional`: Route to agents based on task characteristics
+
+```typescript
+const result = await sdk.orchestrateTask(
+  'Complex task',
+  ['claude', 'codex'],
+  'sequential',
+  { passResults: true }
+);
+```
+
+##### `listAgents()`
+
+List all available agent types.
+
+```typescript
+const agents = sdk.listAgents();
+// ['intella-lite', 'claude', 'codex', 'opencode']
+```
+
+##### `getAgentConfig(agentType)`
+
+Get the current configuration for an agent.
+
+```typescript
+const config = sdk.getAgentConfig('claude');
+```
+
+##### `setDefaultAgent(agentType)`
+
+Set the default agent type.
+
+```typescript
+sdk.setDefaultAgent('intella-lite');
+```
+
+## Agent Configuration
+
+Each agent supports the following configuration options:
+
+```typescript
+interface AgentConfig {
+  apiKey?: string;           // Provider API key (for Intella Lite)
+  model?: string;            // Model identifier
+  temperature?: number;      // Generation temperature (0-2)
+  maxTokens?: number;       // Maximum tokens to generate
+  headers?: Record<string, string>; // Custom headers
+  baseURL?: string;         // Custom base URL
+  [key: string]: unknown;    // Provider-specific options
+}
+```
+
+### Provider-Specific Options
+
+#### Claude Code Agent
+- `model`: Model shortcut ('opus', 'sonnet', 'haiku') or full model ID
+- `allowedTools`: Array of allowed tool names
+- `disallowedTools`: Array of disallowed tool names
+- `mcpServers`: MCP server configurations
+- `permissionMode`: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
+- `maxTurns`: Maximum conversation turns
+- `cwd`: Working directory
+- `verbose`: Enable debug logging
+
+See [Claude Code Provider docs](https://ai-sdk.dev/providers/community-providers/claude-code)
+
+#### Codex CLI Agent
+- `model`: Model ID ('gpt-5.2-codex', 'gpt-5.2', 'gpt-5.1-codex-max', etc.)
+- `reasoningEffort`: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+- `approvalMode`: 'untrusted' | 'on-failure' | 'on-request' | 'never'
+- `sandboxMode`: 'read-only' | 'workspace-write' | 'danger-full-access'
+- `mcpServers`: MCP server configurations
+- `verbose`: Enable verbose logging
+- `logger`: Custom logger instance
+
+See [Codex CLI Provider docs](https://ai-sdk.dev/providers/community-providers/codex-cli)
+
+#### OpenCode Agent
+- `model`: Model ID in format 'provider/model-id' (e.g., 'anthropic/claude-sonnet-4-5-20250929')
+
+See [OpenCode Provider docs](https://ai-sdk.dev/providers/community-providers/opencode-sdk)
+
+### Environment Variables
+
+- `OPENAI_API_KEY` - For Intella Lite (OpenAI-compatible) and Codex CLI (optional)
+
+**Note**: Claude Code, Codex CLI, and OpenCode providers primarily use CLI authentication. Make sure you're logged in via their respective CLI tools:
+- Claude Code: `npm install -g @anthropic-ai/claude-code && claude login`
+- Codex CLI: `npm install -g @openai/codex && codex` (follow interactive setup)
+- OpenCode: `npm install -g opencode && opencode login`
+
+## Advanced Usage
+
+### Direct Agent Access
+
+```typescript
+import { AgentManager, ClaudeAgent } from '@intella/sdk';
+
+const manager = new AgentManager();
+const claudeAgent = new ClaudeAgent({
+  apiKey: 'your-key',
+  model: 'claude-sonnet-4-5-20250929',
+});
+
+manager.registerAgent('claude', claudeAgent);
+const agent = manager.getAgent('claude');
+const response = await agent.execute({ prompt: 'Hello!' });
+```
+
+### Custom Orchestration
+
+```typescript
+import { Orchestrator, AgentManager } from '@intella/sdk';
+
+const manager = new AgentManager();
+const orchestrator = new Orchestrator(manager);
+
+const result = await orchestrator.orchestrate({
+  task: { prompt: 'Complex task' },
+  agents: ['claude', 'codex'],
+  strategy: 'parallel',
+  options: {
+    combineStrategy: 'merge',
+  },
+});
+```
+
+## Sandbox Support
+
+The SDK supports multiple sandbox providers for executing code in isolated environments.
+
+### Supported Sandbox Providers
+
+- **E2B**: Cloud sandbox environment for code execution
+- **Daytona**: Development environment sandboxes
+- **Modal**: Serverless sandbox execution
+
+### Basic Sandbox Usage
+
+```typescript
+// Initialize a sandbox
+await sdk.initializeSandbox('e2b', {
+  templateId: 'base',
+  env: {
+    NODE_ENV: 'development',
+  },
+});
+
+// Execute a command
+const result = await sdk.executeInSandbox('echo "Hello, World!"');
+console.log(result.result.stdout);
+
+// Get active sandbox and use directly
+const sandbox = sdk.getActiveSandbox();
+if (sandbox) {
+  await sandbox.writeFile('/tmp/test.txt', 'Hello!');
+  const content = await sandbox.readFile('/tmp/test.txt');
+}
+
+// Close sandbox
+await sdk.closeSandbox();
+```
+
+### Connecting to Existing Sandboxes
+
+You can connect to an existing sandbox using the `fromSandboxId` config option or by calling `fromSandbox` directly:
+
+```typescript
+// Option 1: Using fromSandboxId in config (recommended)
+await sdk.initializeSandbox('modal', {
+  fromSandboxId: 'existing-sandbox-id',
+});
+
+// Option 2: Direct fromSandbox call
+const sandbox = sdk.getActiveSandbox();
+if (sandbox) {
+  const sandboxInstance = await sandbox.fromSandbox('existing-sandbox-id');
+}
+```
+
+### Getting Sandbox Information
+
+The `getInfo` method provides detailed information about a sandbox:
+
+```typescript
+const sandbox = sdk.getActiveSandbox();
+if (sandbox) {
+  // Get info for active sandbox
+  const info = await sandbox.getInfo();
+  console.log(info);
+  // {
+  //   sandboxId: 'sb-123',
+  //   provider: 'e2b',
+  //   isRunning: true,
+  //   isInitialized: true,
+  //   createdAt: Date,
+  //   metadata: { ... },
+  //   info: { ... } // Raw provider-specific info
+  // }
+
+  // Get info for a specific sandbox by ID
+  const otherInfo = await sandbox.getInfo('another-sandbox-id');
+}
+```
+
+### Sandbox Configuration
+
+```typescript
+interface SandboxConfig {
+  fromSandboxId?: string;      // Connect to existing sandbox
+  provider?: SandboxProviderType;
+  apiKey?: string;             // Provider API key
+  templateId?: string;         // Template/workspace ID
+  baseURL?: string;            // Provider base URL
+  env?: Record<string, string>; // Environment variables
+  timeout?: number;            // Timeout in milliseconds
+  [key: string]: unknown;      // Provider-specific options
+}
+```
+
+### Provider-Specific Configuration
+
+#### E2B
+- Requires `E2B_API_KEY` environment variable or `apiKey` in config
+- Supports `templateId` for selecting sandbox templates
+- Use `fromSandboxId` to reconnect to existing sandboxes
+
+#### Daytona
+- Requires `DAYTONA_API_KEY` or `DAYTONA_API_TOKEN` environment variable
+- Supports `templateId` for workspace templates
+- Optional `baseURL` for custom Daytona server
+
+#### Modal
+- Requires `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` environment variables
+- Supports `appName` and `imageName` for custom app/image configuration
+- Use `fromSandboxId` to connect to existing sandboxes
+
+### Sandbox Operations
+
+All sandbox providers support:
+
+- **Command Execution**: `executeCommand(command, options?)`
+- **Code Execution**: `runCode(code, options?)`
+- **File Operations**: `readFile`, `writeFile`, `uploadFile`, `downloadFile`, `listFiles`, `fileExists`, `deleteFile`
+- **Status & Info**: `getStatus()`, `getInfo(sandboxId?)`
+- **Management**: `close()`, `getSandboxId()`, `isInitialized()`
+
+## Type Definitions
+
+The SDK exports comprehensive TypeScript types:
+
+```typescript
+import type {
+  AgentType,
+  AgentConfig,
+  TaskRequest,
+  TaskResponse,
+  OrchestrationRequest,
+  OrchestrationResponse,
+  IAgent,
+  SandboxProviderType,
+  SandboxConfig,
+  SandboxInfo,
+  ISandboxProvider,
+} from '@intella/sdk';
+```
+
+## Error Handling
+
+The SDK throws descriptive errors for common issues:
+
+```typescript
+try {
+  const response = await sdk.executeTask('Hello', 'unknown-agent');
+} catch (error) {
+  if (error.message.includes('not registered')) {
+    console.error('Agent not found');
+  }
+}
+```
+
+## Examples
+
+See the `/examples` directory for more detailed usage examples.
+
+## License
+
+ISC
+

package/examples/claude-code/README.md

@@ -0,0 +1,178 @@
+# Claude Code Agent Examples
+
+This folder contains examples demonstrating how to use the Claude Code agent through the Intella SDK.
+
+## Prerequisites
+
+1. **Install dependencies:**
+   ```bash
+   npm install @intella/sdk ai ai-sdk-provider-claude-code
+   ```
+
+2. **Install Claude Code CLI:**
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   ```
+
+3. **Authenticate:**
+   ```bash
+   claude login
+   ```
+   This will open a browser window for authentication. You need a Claude Pro or Max subscription.
+
+## Examples
+
+### 1. Basic Usage (`basic-usage.ts`)
+
+Demonstrates the simplest way to use the Claude Code agent:
+
+```bash
+npx tsx examples/claude-code/basic-usage.ts
+```
+
+**Features:**
+- Basic agent configuration
+- Simple task execution
+- Response handling
+
+### 2. Advanced Configuration (`advanced-config.ts`)
+
+Shows how to configure the Claude Code agent with advanced options:
+
+```bash
+npx tsx examples/claude-code/advanced-config.ts
+```
+
+**Features:**
+- Tool permissions (allowedTools, disallowedTools)
+- Permission modes
+- MCP server configuration
+- Custom working directory
+- Verbose logging
+
+### 3. Streaming (`streaming.ts`)
+
+Demonstrates streaming responses from the Claude Code agent:
+
+```bash
+npx tsx examples/claude-code/streaming.ts
+```
+
+**Features:**
+- Real-time response streaming
+- Chunk-by-chunk output
+- Completion detection
+
+### 4. Orchestration (`orchestration.ts`)
+
+Shows how to orchestrate multiple agents including Claude Code:
+
+```bash
+npx tsx examples/claude-code/orchestration.ts
+```
+
+**Features:**
+- Sequential orchestration (agents work in sequence)
+- Parallel orchestration (agents work simultaneously)
+- Result combination strategies
+
+### 5. Model Comparison (`model-comparison.ts`)
+
+Compares different Claude models (Opus, Sonnet, Haiku) on the same task:
+
+```bash
+npx tsx examples/claude-code/model-comparison.ts
+```
+
+**Features:**
+- Model performance comparison
+- Response time analysis
+- Token usage tracking
+
+## Claude Code Models
+
+The Claude Code provider supports three model shortcuts:
+
+- **`opus`**: Claude Opus - Most capable model, best for complex reasoning
+- **`sonnet`**: Claude Sonnet - Balanced performance and capability (default)
+- **`haiku`**: Claude Haiku - Fastest model, good for simple tasks
+
+You can also use full model identifiers:
+- `claude-opus-4-5`
+- `claude-sonnet-4-5-20250929`
+- `claude-haiku-4-5`
+
+## Configuration Options
+
+### Basic Configuration
+
+```typescript
+sdk.configureAgent('claude', {
+  model: 'sonnet', // Model shortcut or full ID
+});
+```
+
+### Advanced Configuration
+
+```typescript
+sdk.configureAgent('claude', {
+  model: 'opus',
+  allowedTools: ['Read', 'Write', 'Edit'],
+  disallowedTools: ['Bash'],
+  permissionMode: 'default',
+  maxTurns: 10,
+  cwd: process.cwd(),
+  verbose: true,
+});
+```
+
+## Tool Permissions
+
+Claude Code has built-in tools (Bash, Edit, Read, Write, etc.) that execute autonomously. You can control which tools are available:
+
+- **`allowedTools`**: Array of tool names to allow (whitelist)
+- **`disallowedTools`**: Array of tool names to disallow (blacklist)
+- **`permissionMode`**: How to handle tool permissions
+  - `'default'`: Standard permission handling
+  - `'acceptEdits'`: Automatically accept file edits
+  - `'bypassPermissions'`: Skip permission prompts
+  - `'plan'`: Show plan before execution
+
+## MCP Servers
+
+You can configure Model Context Protocol (MCP) servers for extended functionality:
+
+```typescript
+sdk.configureAgent('claude', {
+  mcpServers: {
+    'my-server': {
+      command: 'node',
+      args: ['server.js'],
+    },
+  },
+});
+```
+
+## Authentication
+
+Claude Code uses CLI authentication. After running `claude login`, your Claude Pro or Max subscription is automatically used. No API keys are needed in your code.
+
+## More Information
+
+- [Claude Code Provider Documentation](https://ai-sdk.dev/providers/community-providers/claude-code)
+- [Intella SDK Documentation](../../README.md)
+- [Claude Code CLI Documentation](https://github.com/anthropics/claude-code)
+
+## Running Examples
+
+Make sure you have TypeScript execution support. You can use:
+
+- `tsx` (recommended): `npm install -g tsx`
+- `ts-node`: `npm install -g ts-node`
+- Or compile first: `tsc` then `node dist/example.js`
+
+Example:
+```bash
+npx tsx examples/claude-code/basic-usage.ts
+```
+