@siftd/connect-agent 0.1.0 → 0.2.2

package/README.md

@@ -0,0 +1,106 @@
+# @siftd/connect-agent
+
+Master orchestrator agent that connects to [Connect](https://connect.siftd.app) - control Claude Code remotely from any browser.
+
+## What is this?
+
+Connect Agent runs on your machine and bridges the Connect web app to Claude Code CLI. It's not just a relay - it's a **master orchestrator** with:
+
+- **Persistent Memory** - Remembers your preferences, projects, and context across sessions
+- **Worker Delegation** - Delegates complex tasks to Claude Code CLI workers
+- **Task Scheduling** - Schedule tasks for future execution
+- **Semantic Search** - Finds relevant memories by meaning, not just keywords
+
+## Quick Start
+
+```bash
+# 1. Go to https://connect.siftd.app and get a pairing code
+
+# 2. Pair your machine (with API key for full orchestrator mode)
+npx @siftd/connect-agent pair <CODE> --api-key <YOUR_ANTHROPIC_API_KEY>
+
+# 3. Start the agent
+npx @siftd/connect-agent start
+```
+
+## Modes
+
+### Orchestrator Mode (Recommended)
+When you provide an Anthropic API key, the agent runs as a **master orchestrator**:
+- Uses Claude API directly for the orchestration layer
+- Maintains persistent memory about you and your projects
+- Delegates file/code work to Claude Code CLI workers
+- Schedules future tasks
+
+### Simple Relay Mode
+Without an API key, the agent acts as a simple relay to `claude -p --continue`.
+
+## Commands
+
+```bash
+# Pair with the web app
+connect-agent pair <CODE> [--api-key <KEY>]
+
+# Start processing messages
+connect-agent start [--interval <ms>]
+
+# Check status
+connect-agent status
+
+# Set API key (without re-pairing)
+connect-agent set-key <KEY>
+
+# Clear configuration
+connect-agent logout
+```
+
+## Special Commands (via web chat)
+
+- `/reset` or `/clear` - Clear conversation history
+- `/mode` - Check current mode (orchestrator vs simple)
+- `/memory` - Show memory statistics
+
+## How It Works
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Browser        │────▶│  Connect Server  │◀────│  Connect Agent  │
+│  (any device)   │     │  (connect.siftd) │     │  (your machine) │
+└─────────────────┘     └──────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+                                                 ┌─────────────────┐
+                                                 │ Master          │
+                                                 │ Orchestrator    │
+                                                 │ (memory, sched) │
+                                                 └────────┬────────┘
+                                                          │ delegates
+                                                          ▼
+                                                 ┌─────────────────┐
+                                                 │ Claude Code CLI │
+                                                 │ (file ops, code)│
+                                                 └─────────────────┘
+```
+
+The orchestrator understands it's the **master**, not a worker. It:
+1. Receives your message from the web
+2. Searches memory for relevant context
+3. Decides what needs to be done
+4. Delegates actual work to Claude Code CLI
+5. Synthesizes results into a clear response
+6. Remembers important things for next time
+
+## Environment Variables
+
+- `ANTHROPIC_API_KEY` - Alternative to `--api-key` flag
+- `VOYAGE_API_KEY` - (Optional) For better semantic search embeddings
+
+## Requirements
+
+- Node.js 18+
+- [Claude Code CLI](https://claude.ai/code) installed and authenticated
+- Anthropic API key (for orchestrator mode)
+
+## License
+
+MIT

package/dist/agent.js

@@ -1,17 +1,47 @@
 import { spawn } from 'child_process';
 import { pollMessages, sendResponse } from './api.js';
+import { getUserId, getAnthropicApiKey, isCloudMode, getDeploymentInfo } from './config.js';
+import { MasterOrchestrator } from './orchestrator.js';
+import { AgentWebSocket } from './websocket.js';
+import { startHeartbeat, stopHeartbeat, getHeartbeatState } from './heartbeat.js';
 // Strip ANSI escape codes for clean output
 function stripAnsi(str) {
     return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
 }
+// Conversation history for orchestrator mode
+let conversationHistory = [];
+let orchestrator = null;
+let wsClient = null;
 /**
- * Send a message to Claude Code and get the response
- * Uses --continue to maintain conversation context
+ * Initialize the orchestrator if API key is available
  */
-async function sendToClaude(input) {
-    return new Promise((resolve, reject) => {
+function initOrchestrator() {
+    // Check env first, then stored config
+    const apiKey = process.env.ANTHROPIC_API_KEY || getAnthropicApiKey();
+    const userId = getUserId();
+    if (!apiKey) {
+        console.log('[AGENT] No API key - using simple relay mode');
+        console.log('[AGENT] To enable orchestrator: pair with --api-key flag');
+        return null;
+    }
+    if (!userId) {
+        console.log('[AGENT] No userId configured - using simple relay mode');
+        return null;
+    }
+    console.log('[AGENT] Initializing Master Orchestrator...');
+    return new MasterOrchestrator({
+        apiKey,
+        userId,
+        workspaceDir: process.env.HOME || '/tmp',
+        voyageApiKey: process.env.VOYAGE_API_KEY
+    });
+}
+/**
+ * Simple relay mode - just pipes to Claude Code CLI
+ */
+async function sendToClaudeSimple(input) {
+    return new Promise((resolve) => {
         console.log(`\n[CLAUDE] Sending: ${input.substring(0, 80)}...`);
-        // Use -p (print mode) with --continue to maintain context
         const claude = spawn('claude', ['-p', '--continue'], {
             cwd: process.env.HOME,
             env: process.env,
@@ -27,7 +57,6 @@ async function sendToClaude(input) {
         claude.stderr?.on('data', (data) => {
             const text = data.toString();
             errorOutput += text;
-            // Only print stderr if it's not just status info
             if (!text.includes('Checking') && !text.includes('Connected')) {
                 process.stderr.write(text);
             }
@@ -48,43 +77,193 @@ async function sendToClaude(input) {
             console.error(`\n[CLAUDE] Failed to start: ${err.message}`);
             resolve(`Error: Failed to start Claude - ${err.message}`);
         });
-        // Send the input to claude's stdin
         if (claude.stdin) {
             claude.stdin.write(input);
             claude.stdin.end();
         }
     });
 }
+/**
+ * Orchestrator mode - uses the master orchestrator with memory
+ * Supports WebSocket streaming for real-time progress updates
+ * @param apiKey Optional per-request API key from user
+ */
+async function sendToOrchestrator(input, orch, messageId, apiKey) {
+    console.log(`\n[ORCHESTRATOR] Processing: ${input.substring(0, 80)}...`);
+    // Send typing indicator via WebSocket
+    if (wsClient?.connected()) {
+        wsClient.sendTyping(true);
+    }
+    try {
+        const response = await orch.processMessage(input, conversationHistory, async (msg) => {
+            // Progress callback - log to console and send via WebSocket
+            console.log(`[ORCHESTRATOR] ${msg}`);
+            if (wsClient?.connected() && messageId) {
+                wsClient.sendProgress(messageId, msg);
+            }
+        }, apiKey // Pass per-request API key
+        );
+        // Update conversation history (only if response is non-empty)
+        if (response && response.trim()) {
+            conversationHistory.push({ role: 'user', content: input });
+            conversationHistory.push({ role: 'assistant', content: response });
+            // Keep history manageable (last 20 exchanges)
+            if (conversationHistory.length > 40) {
+                conversationHistory = conversationHistory.slice(-40);
+            }
+        }
+        else {
+            console.log('[ORCHESTRATOR] Empty response - not adding to conversation history');
+        }
+        console.log(`\n[ORCHESTRATOR] Response: ${response.substring(0, 80)}...`);
+        // Stop typing indicator
+        if (wsClient?.connected()) {
+            wsClient.sendTyping(false);
+        }
+        return response;
+    }
+    catch (error) {
+        console.error('[ORCHESTRATOR] Error:', error);
+        if (wsClient?.connected()) {
+            wsClient.sendTyping(false);
+        }
+        return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+}
 export async function processMessage(message) {
     console.log(`\n[WEB] >>> ${message.content}`);
-    try {
-        const response = await sendToClaude(message.content);
+    // Handle special commands
+    const content = message.content.trim().toLowerCase();
+    if (content === '/reset' || content === '/clear') {
+        conversationHistory = [];
+        return 'Conversation history cleared.';
+    }
+    if (content === '/mode') {
+        const wsStatus = wsClient?.connected() ? 'WebSocket' : 'Polling';
+        const hbState = getHeartbeatState();
+        const runnerInfo = hbState.runnerId ? ` [${hbState.runnerId}]` : '';
+        return orchestrator
+            ? `Running in ORCHESTRATOR mode (${wsStatus})${runnerInfo} with memory and delegation`
+            : `Running in SIMPLE mode (${wsStatus})${runnerInfo} - direct Claude Code relay`;
+    }
+    if (content === '/memory' && orchestrator) {
+        // Trigger memory stats
+        const response = await orchestrator.processMessage('Show me my memory stats', [], undefined, message.apiKey // Use per-message API key if provided
+        );
         return response;
     }
+    try {
+        if (orchestrator) {
+            return await sendToOrchestrator(message.content, orchestrator, message.id, message.apiKey);
+        }
+        else {
+            return await sendToClaudeSimple(message.content);
+        }
+    }
     catch (error) {
         console.error('Error:', error);
         return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`;
     }
 }
 export async function runAgent(pollInterval = 2000) {
-    console.log('╔══════════════════════════════════════════╗');
-    console.log('║  Connect Agent - Claude Code Relay       ║');
-    console.log('╚══════════════════════════════════════════╝\n');
-    console.log('[AGENT] Polling for web messages...\n');
-    while (true) {
-        try {
-            const { messages } = await pollMessages();
-            for (const msg of messages) {
-                const response = await processMessage(msg);
-                await sendResponse(msg.id, response);
-                console.log(`[AGENT] Response sent (${response.length} chars)`);
+    // Initialize orchestrator
+    orchestrator = initOrchestrator();
+    const mode = orchestrator ? 'ORCHESTRATOR' : 'SIMPLE RELAY';
+    const deployment = getDeploymentInfo();
+    console.log('╔══════════════════════════════════════════════════╗');
+    console.log('║  Connect Agent - Master Orchestrator              ║');
+    console.log(`║  Mode: ${mode.padEnd(41)}║`);
+    console.log(`║  Deployment: ${deployment.mode.toUpperCase().padEnd(35)}║`);
+    console.log('╚══════════════════════════════════════════════════╝\n');
+    if (isCloudMode()) {
+        console.log(`[AGENT] Running in CLOUD mode`);
+        console.log(`[AGENT] Server: ${deployment.server}`);
+    }
+    if (orchestrator) {
+        console.log('[AGENT] Features: Memory, Scheduling, Worker Delegation');
+        // Initialize orchestrator (indexes filesystem into memory)
+        await orchestrator.initialize();
+    }
+    // Start heartbeat to maintain presence in runner registry
+    const runnerType = isCloudMode() ? 'vm' : 'local';
+    startHeartbeat({
+        runnerType,
+        capabilities: orchestrator ? ['orchestrator', 'memory'] : [],
+        onError: (error) => {
+            // Log only significant errors
+            if (error.message.includes('401') || error.message.includes('403')) {
+                console.error('[AGENT] Heartbeat auth failed - may need to re-pair');
             }
+        },
+    });
+    // Graceful shutdown
+    process.on('SIGINT', () => {
+        console.log('\n[AGENT] Shutting down...');
+        stopHeartbeat();
+        if (wsClient) {
+            wsClient.close();
+        }
+        if (orchestrator) {
+            orchestrator.shutdown();
         }
-        catch (error) {
-            if (error instanceof Error && !error.message.includes('ECONNREFUSED')) {
+        process.exit(0);
+    });
+    // Try WebSocket first
+    wsClient = new AgentWebSocket();
+    const wsConnected = await wsClient.connect();
+    if (wsConnected) {
+        console.log('[AGENT] Using WebSocket for real-time communication\n');
+        // Handle messages via WebSocket
+        wsClient.onMessage(async (wsMsg) => {
+            if (wsMsg.type === 'message' && wsMsg.content && wsMsg.id) {
+                const message = {
+                    id: wsMsg.id,
+                    content: wsMsg.content,
+                    timestamp: wsMsg.timestamp || Date.now(),
+                    apiKey: wsMsg.apiKey // Pass through per-request API key
+                };
+                const response = await processMessage(message);
+                // Send response via WebSocket
+                wsClient.sendResponse(wsMsg.id, response);
+                console.log(`[AGENT] Response sent via WebSocket (${response.length} chars)`);
+            }
+        });
+        // Keep process alive - WebSocket handles messages
+        console.log('[AGENT] Listening for WebSocket messages...\n');
+        // Always poll for messages (socket-store.ts stores messages that WebSocket doesn't see)
+        while (true) {
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+            try {
+                const { messages } = await pollMessages();
+                for (const msg of messages) {
+                    const response = await processMessage(msg);
+                    await sendResponse(msg.id, response);
+                    console.log(`[AGENT] Response sent (${response.length} chars)`);
+                }
+            }
+            catch (error) {
                 console.error('[AGENT] Poll error:', error.message);
             }
         }
-        await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
+    else {
+        // Fall back to polling
+        console.log('[AGENT] WebSocket unavailable, using HTTP polling\n');
+        while (true) {
+            try {
+                const { messages } = await pollMessages();
+                for (const msg of messages) {
+                    const response = await processMessage(msg);
+                    await sendResponse(msg.id, response);
+                    console.log(`[AGENT] Response sent (${response.length} chars)`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && !error.message.includes('ECONNREFUSED')) {
+                    console.error('[AGENT] Poll error:', error.message);
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
     }
 }

package/dist/api.d.ts

@@ -2,6 +2,7 @@ export interface Message {
     id: string;
     content: string;
     timestamp: number;
+    apiKey?: string;
 }
 export interface ConnectResponse {
     success: boolean;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import ora from 'ora';
-import { getServerUrl, setServerUrl, setAgentToken, setUserId, isConfigured, clearConfig, getConfigPath, } from './config.js';
+import { getServerUrl, setServerUrl, setAgentToken, setUserId, setAnthropicApiKey, getAnthropicApiKey, isConfigured, clearConfig, getConfigPath, } from './config.js';
 import { connectWithPairingCode, checkConnection } from './api.js';
 import { runAgent } from './agent.js';
 program
@@ -13,6 +13,7 @@ program
     .description('Pair with Connect web app using a pairing code')
     .argument('<code>', 'The 6-character pairing code from the web app')
     .option('-s, --server <url>', 'Server URL', getServerUrl())
+    .option('-k, --api-key <key>', 'Anthropic API key for orchestrator mode')
     .action(async (code, options) => {
     const spinner = ora('Connecting to server...').start();
     try {
@@ -26,9 +27,18 @@ program
         }
         setAgentToken(result.agentToken);
         setUserId(result.userId);
+        // Store API key if provided
+        if (options.apiKey) {
+            setAnthropicApiKey(options.apiKey);
+        }
         spinner.succeed('Paired successfully!');
         console.log(`\nAgent is now connected to ${getServerUrl()}`);
-        console.log('Run "connect-agent start" to begin processing messages.');
+        if (options.apiKey) {
+            console.log('Orchestrator mode enabled (API key saved)');
+        }
+        console.log('\nTo start the agent, run one of:');
+        console.log('  npx @siftd/connect-agent start');
+        console.log('  (or install globally: npm install -g @siftd/connect-agent)');
     }
     catch (error) {
         spinner.fail(`Connection failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -64,6 +74,7 @@ program
     console.log(`Config file: ${getConfigPath()}`);
     console.log(`Server URL: ${getServerUrl()}`);
     console.log(`Configured: ${isConfigured() ? 'Yes' : 'No'}`);
+    console.log(`Orchestrator mode: ${getAnthropicApiKey() ? 'Yes (API key saved)' : 'No (simple relay)'}`);
     if (isConfigured()) {
         const spinner = ora('Checking connection...').start();
         const connected = await checkConnection();
@@ -90,4 +101,12 @@ program
     setServerUrl(url);
     console.log(`Server URL set to: ${url}`);
 });
+program
+    .command('set-key')
+    .description('Set Anthropic API key for orchestrator mode')
+    .argument('<key>', 'Your Anthropic API key')
+    .action((key) => {
+    setAnthropicApiKey(key);
+    console.log('API key saved. Orchestrator mode will be enabled on next start.');
+});
 program.parse();

package/dist/config.d.ts

@@ -1,9 +1,23 @@
+/**
+ * Check if running in cloud mode (environment variables take precedence)
+ */
+export declare function isCloudMode(): boolean;
 export declare function getServerUrl(): string;
 export declare function setServerUrl(url: string): void;
 export declare function getAgentToken(): string | null;
 export declare function setAgentToken(token: string | null): void;
 export declare function getUserId(): string | null;
 export declare function setUserId(id: string | null): void;
+export declare function getAnthropicApiKey(): string | null;
+export declare function setAnthropicApiKey(key: string | null): void;
 export declare function isConfigured(): boolean;
 export declare function clearConfig(): void;
 export declare function getConfigPath(): string;
+/**
+ * Get deployment mode info for logging
+ */
+export declare function getDeploymentInfo(): {
+    mode: string;
+    server: string;
+    userId: string | null;
+};

package/dist/config.js

@@ -5,14 +5,22 @@ const config = new Conf({
         serverUrl: 'https://connect.siftd.app',
     },
 });
+/**
+ * Check if running in cloud mode (environment variables take precedence)
+ */
+export function isCloudMode() {
+    return !!(process.env.CONNECT_SERVER_URL && process.env.CONNECT_AGENT_TOKEN && process.env.CONNECT_USER_ID);
+}
 export function getServerUrl() {
-    return config.get('serverUrl');
+    // Environment variable takes precedence (cloud mode)
+    return process.env.CONNECT_SERVER_URL || config.get('serverUrl');
 }
 export function setServerUrl(url) {
     config.set('serverUrl', url);
 }
 export function getAgentToken() {
-    return config.get('agentToken') ?? null;
+    // Environment variable takes precedence (cloud mode)
+    return process.env.CONNECT_AGENT_TOKEN || config.get('agentToken') || null;
 }
 export function setAgentToken(token) {
     if (token === null) {
@@ -23,7 +31,8 @@ export function setAgentToken(token) {
     }
 }
 export function getUserId() {
-    return config.get('userId') ?? null;
+    // Environment variable takes precedence (cloud mode)
+    return process.env.CONNECT_USER_ID || config.get('userId') || null;
 }
 export function setUserId(id) {
     if (id === null) {
@@ -33,13 +42,37 @@ export function setUserId(id) {
         config.set('userId', id);
     }
 }
+export function getAnthropicApiKey() {
+    // Environment variable takes precedence (cloud mode)
+    // Note: ANTHROPIC_API_KEY is also checked in orchestrator.ts
+    return process.env.ANTHROPIC_API_KEY || config.get('anthropicApiKey') || null;
+}
+export function setAnthropicApiKey(key) {
+    if (key === null) {
+        config.delete('anthropicApiKey');
+    }
+    else {
+        config.set('anthropicApiKey', key);
+    }
+}
 export function isConfigured() {
     return !!getAgentToken() && !!getUserId();
 }
 export function clearConfig() {
     config.delete('agentToken');
     config.delete('userId');
+    config.delete('anthropicApiKey');
 }
 export function getConfigPath() {
     return config.path;
 }
+/**
+ * Get deployment mode info for logging
+ */
+export function getDeploymentInfo() {
+    return {
+        mode: isCloudMode() ? 'cloud' : 'local',
+        server: getServerUrl(),
+        userId: getUserId(),
+    };
+}

package/dist/core/memory-advanced.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Advanced Memory System
+ *
+ * Features:
+ * - Hierarchical memory types (episodic, semantic, procedural)
+ * - Vector embeddings for semantic search
+ * - Importance scoring with temporal decay
+ * - Memory associations/links
+ * - Reflection and consolidation
+ */
+export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'working';
+export interface Memory {
+    id: string;
+    type: MemoryType;
+    content: string;
+    summary?: string;
+    source: string;
+    timestamp: string;
+    lastAccessed: string;
+    importance: number;
+    accessCount: number;
+    decayRate: number;
+    associations: string[];
+    tags: string[];
+    hasEmbedding: boolean;
+}
+export declare class AdvancedMemoryStore {
+    private db;
+    private vectorIndex;
+    private vectorPath;
+    private embedder;
+    private config;
+    constructor(options?: {
+        dbPath?: string;
+        vectorPath?: string;
+        voyageApiKey?: string;
+        maxMemories?: number;
+    });
+    private init;
+    private initVectorIndex;
+    remember(content: string, options?: {
+        type?: MemoryType;
+        source?: string;
+        importance?: number;
+        tags?: string[];
+        associations?: string[];
+        summary?: string;
+    }): Promise<string>;
+    search(query: string, options?: {
+        limit?: number;
+        type?: MemoryType;
+        minImportance?: number;
+        includeAssociations?: boolean;
+    }): Promise<Memory[]>;
+    private textSearch;
+    getById(id: string): Memory | null;
+    getByType(type: MemoryType, limit?: number): Memory[];
+    recall(id: string): Memory | null;
+    forget(id: string): Promise<boolean>;
+    updateImportance(id: string, importance: number): void;
+    associate(id1: string, id2: string): void;
+    applyDecay(): number;
+    reflect(): Promise<{
+        insights: string[];
+        consolidations: number;
+        memoriesProcessed: number;
+    }>;
+    stats(): {
+        total: number;
+        byType: Record<MemoryType, number>;
+        avgImportance: number;
+        totalAssociations: number;
+        oldestMemory: string | null;
+        newestMemory: string | null;
+    };
+    list(limit?: number): Memory[];
+    getRecent(limit?: number): Memory[];
+    private addEmbedding;
+    private createAssociations;
+    private removeAssociations;
+    private recordAccess;
+    private inferMemoryType;
+    private calculateInitialImportance;
+    private getDecayRateForType;
+    private extractTags;
+    private consolidateMemories;
+    private findCommonWords;
+    private pruneIfNeeded;
+    private rowToMemory;
+    close(): void;
+}