overarch-linux-arm64 0.8.0

package/dist/src/learning/memory_manager.js

@@ -0,0 +1,211 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export class MemoryManager {
+    projectMemoryDir;
+    globalMemoryDir;
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+        this.projectMemoryDir = path.join(cwd, '.overarch', 'memory');
+        this.globalMemoryDir = path.join(os.homedir(), '.overarch');
+    }
+    async ensureDirs() {
+        await fs.mkdir(this.projectMemoryDir, { recursive: true });
+        await fs.mkdir(this.globalMemoryDir, { recursive: true });
+    }
+    // ── Project Memory ──
+    async getProjectMemory() {
+        await this.ensureDirs();
+        const filePath = path.join(this.projectMemoryDir, 'project.json');
+        try {
+            const data = await fs.readFile(filePath, 'utf8');
+            return JSON.parse(data);
+        }
+        catch {
+            return {
+                conventions: [],
+                importantFiles: [],
+                frameworks: [],
+                buildCommands: [],
+                testCommands: [],
+                deploymentPatterns: [],
+                recurringErrors: [],
+                decisions: []
+            };
+        }
+    }
+    async saveProjectMemory(memory) {
+        await this.ensureDirs();
+        const filePath = path.join(this.projectMemoryDir, 'project.json');
+        await fs.writeFile(filePath, JSON.stringify(memory, null, 2), 'utf8');
+    }
+    // ── User Memory ──
+    async getUserMemory() {
+        await this.ensureDirs();
+        const filePath = path.join(this.globalMemoryDir, 'user_memory.json');
+        try {
+            const data = await fs.readFile(filePath, 'utf8');
+            return JSON.parse(data);
+        }
+        catch {
+            return {
+                codingPreferences: [],
+                preferredWorkflows: [],
+                conventions: [],
+                frequentlyUsedCommands: [],
+                communicationPreferences: []
+            };
+        }
+    }
+    async saveUserMemory(memory) {
+        await this.ensureDirs();
+        const filePath = path.join(this.globalMemoryDir, 'user_memory.json');
+        await fs.writeFile(filePath, JSON.stringify(memory, null, 2), 'utf8');
+    }
+    // ── Lessons (Episodic Memory) ──
+    async getLessons(scope = 'all') {
+        await this.ensureDirs();
+        const lessons = [];
+        // Project lessons
+        if (scope === 'all' || scope === 'project') {
+            try {
+                const pFile = path.join(this.projectMemoryDir, 'lessons.json');
+                const data = await fs.readFile(pFile, 'utf8');
+                const list = JSON.parse(data);
+                lessons.push(...list.map(l => ({ ...l, scope: 'project' })));
+            }
+            catch { }
+        }
+        // Global lessons
+        if (scope === 'all' || scope === 'global') {
+            try {
+                const gFile = path.join(this.globalMemoryDir, 'lessons.json');
+                const data = await fs.readFile(gFile, 'utf8');
+                const list = JSON.parse(data);
+                lessons.push(...list.map(l => ({ ...l, scope: 'global' })));
+            }
+            catch { }
+        }
+        return lessons.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    }
+    async recordLesson(lesson) {
+        await this.ensureDirs();
+        const id = `les_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+        const fullLesson = {
+            id,
+            timestamp: new Date().toISOString(),
+            sourceCwd: this.cwd,
+            ...lesson
+        };
+        const targetFile = fullLesson.scope === 'global'
+            ? path.join(this.globalMemoryDir, 'lessons.json')
+            : path.join(this.projectMemoryDir, 'lessons.json');
+        let existing = [];
+        try {
+            const data = await fs.readFile(targetFile, 'utf8');
+            existing = JSON.parse(data);
+        }
+        catch { }
+        existing.unshift(fullLesson);
+        await fs.writeFile(targetFile, JSON.stringify(existing, null, 2), 'utf8');
+        return fullLesson;
+    }
+    async learnQuick(lessonText, tags = []) {
+        return this.recordLesson({
+            problem: 'Direct user guidance / insight',
+            investigation: 'User specified engineering instruction or lesson',
+            resolution: 'Saved to persistent episodic memory',
+            lesson: lessonText,
+            tags: tags.length > 0 ? tags : ['user-taught', 'best-practice'],
+            scope: 'project'
+        });
+    }
+    // ── Search & Selective Retrieval ──
+    async search(query) {
+        const q = query.toLowerCase().trim();
+        const words = q.split(/\s+/).filter(w => w.length > 2);
+        const allLessons = await this.getLessons('all');
+        const projectMem = await this.getProjectMemory();
+        const matchedLessons = allLessons.filter(l => {
+            const text = `${l.problem} ${l.investigation} ${l.resolution} ${l.lesson} ${l.tags.join(' ')}`.toLowerCase();
+            return text.includes(q) || words.some(w => text.includes(w));
+        });
+        const matchedConventions = projectMem.conventions.filter(c => c.toLowerCase().includes(q) || words.some(w => c.toLowerCase().includes(w)));
+        const matchedDecisions = projectMem.decisions.filter(d => `${d.decision} ${d.rationale}`.toLowerCase().includes(q) || words.some(w => `${d.decision} ${d.rationale}`.toLowerCase().includes(w)));
+        return {
+            lessons: matchedLessons,
+            conventions: matchedConventions,
+            decisions: matchedDecisions
+        };
+    }
+    /**
+     * Selectively retrieves relevant memory for the active task.
+     * Keeps token count bounded so full memory is never dumped blindly into prompts.
+     */
+    async retrieveRelevantContext(taskPrompt, maxItems = 3) {
+        const searchRes = await this.search(taskPrompt);
+        const projectMem = await this.getProjectMemory();
+        const userMem = await this.getUserMemory();
+        const relevantLessons = searchRes.lessons.slice(0, maxItems);
+        const relevantConventions = projectMem.conventions.slice(0, 3);
+        const relevantUserPrefs = userMem.codingPreferences.slice(0, 3);
+        const lines = [];
+        if (projectMem.architecture) {
+            lines.push(`- Architecture: ${projectMem.architecture}`);
+        }
+        if (relevantConventions.length > 0) {
+            lines.push(`- Project Conventions: ${relevantConventions.join('; ')}`);
+        }
+        if (relevantLessons.length > 0) {
+            lines.push('- Lessons from previous tasks:');
+            relevantLessons.forEach(l => {
+                lines.push(`  • ${l.lesson} (Context: ${l.problem} → ${l.resolution})`);
+            });
+        }
+        if (relevantUserPrefs.length > 0) {
+            lines.push(`- User Preferences: ${relevantUserPrefs.join('; ')}`);
+        }
+        const formattedPromptInjection = lines.length > 0
+            ? `\n<persistent_project_memory>\n${lines.join('\n')}\n</persistent_project_memory>`
+            : '';
+        const estimatedTokens = Math.ceil(formattedPromptInjection.length / 4);
+        return {
+            lessons: relevantLessons,
+            projectConventions: relevantConventions,
+            userPreferences: relevantUserPrefs,
+            architectureNotes: projectMem.architecture,
+            formattedPromptInjection,
+            estimatedTokens
+        };
+    }
+    async forget(id) {
+        await this.ensureDirs();
+        let removed = false;
+        // Check project lessons
+        try {
+            const pFile = path.join(this.projectMemoryDir, 'lessons.json');
+            const data = await fs.readFile(pFile, 'utf8');
+            const list = JSON.parse(data);
+            const filtered = list.filter(l => l.id !== id);
+            if (filtered.length !== list.length) {
+                await fs.writeFile(pFile, JSON.stringify(filtered, null, 2), 'utf8');
+                removed = true;
+            }
+        }
+        catch { }
+        // Check global lessons
+        try {
+            const gFile = path.join(this.globalMemoryDir, 'lessons.json');
+            const data = await fs.readFile(gFile, 'utf8');
+            const list = JSON.parse(data);
+            const filtered = list.filter(l => l.id !== id);
+            if (filtered.length !== list.length) {
+                await fs.writeFile(gFile, JSON.stringify(filtered, null, 2), 'utf8');
+                removed = true;
+            }
+        }
+        catch { }
+        return removed;
+    }
+}

package/dist/src/learning/types.d.ts

@@ -0,0 +1,54 @@
+export interface EpisodicLesson {
+    id: string;
+    timestamp: string;
+    problem: string;
+    investigation: string;
+    resolution: string;
+    lesson: string;
+    tags: string[];
+    scope: 'project' | 'global';
+    sourceCwd?: string;
+}
+export interface ProjectMemory {
+    architecture?: string;
+    conventions: string[];
+    importantFiles: string[];
+    frameworks: string[];
+    buildCommands: string[];
+    testCommands: string[];
+    deploymentPatterns: string[];
+    recurringErrors: string[];
+    decisions: Array<{
+        id: string;
+        decision: string;
+        date: string;
+        rationale: string;
+    }>;
+}
+export interface UserMemory {
+    codingPreferences: string[];
+    preferredWorkflows: string[];
+    conventions: string[];
+    frequentlyUsedCommands: string[];
+    communicationPreferences: string[];
+}
+export interface SessionMemoryRecord {
+    sessionId: string;
+    task: string;
+    plan: string[];
+    completedSteps: string[];
+    failedAttempts: string[];
+    discoveries: string[];
+    modifiedFiles: string[];
+    startedAt: string;
+    updatedAt: string;
+    status: 'active' | 'completed' | 'interrupted' | 'failed';
+}
+export interface RelevantMemoryContext {
+    lessons: EpisodicLesson[];
+    projectConventions: string[];
+    userPreferences: string[];
+    architectureNotes?: string;
+    formattedPromptInjection: string;
+    estimatedTokens: number;
+}

package/dist/src/learning/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/mcp/registry.d.ts

@@ -0,0 +1,17 @@
+import { Tool } from '../tools/types.js';
+import { McpServerConfig, McpToolAdapter } from './types.js';
+export declare class McpRegistry {
+    private servers;
+    private tools;
+    constructor();
+    registerServer(config: McpServerConfig): void;
+    listServers(): McpServerConfig[];
+    registerTool(adapter: McpToolAdapter): void;
+    listTools(): McpToolAdapter[];
+    toOverarchTools(): Tool[];
+    /**
+     * Register default built-in MCP tool adapters for developer services
+     */
+    private registerBuiltinAdapters;
+}
+export declare const mcpRegistry: McpRegistry;

package/dist/src/mcp/registry.js

@@ -0,0 +1,97 @@
+import { PermissionTier } from '../config/types.js';
+export class McpRegistry {
+    servers = new Map();
+    tools = new Map();
+    constructor() {
+        this.registerBuiltinAdapters();
+    }
+    registerServer(config) {
+        this.servers.set(config.name, config);
+    }
+    listServers() {
+        return Array.from(this.servers.values());
+    }
+    registerTool(adapter) {
+        this.tools.set(adapter.definition.name, adapter);
+    }
+    listTools() {
+        return Array.from(this.tools.values());
+    }
+    toOverarchTools() {
+        return Array.from(this.tools.values()).map(adapter => ({
+            definition: adapter.definition,
+            handler: adapter.handler
+        }));
+    }
+    /**
+     * Register default built-in MCP tool adapters for developer services
+     */
+    registerBuiltinAdapters() {
+        // 1. GitHub Integration Tool
+        this.registerTool({
+            serverName: 'github',
+            definition: {
+                name: 'mcp_github_query',
+                description: 'Query GitHub issues, pull requests, or commits via MCP',
+                tier: PermissionTier.ReadOnly,
+                parameters: [
+                    { name: 'action', type: 'string', description: 'Action: list_issues, list_prs, view_pr', required: true, enum: ['list_issues', 'list_prs', 'view_pr'] },
+                    { name: 'repo', type: 'string', description: 'Repository e.g. owner/repo', required: false },
+                    { name: 'id', type: 'number', description: 'Issue or PR number', required: false }
+                ]
+            },
+            handler: async (params) => {
+                const ghToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+                if (!ghToken) {
+                    return {
+                        success: true,
+                        output: `[MCP GitHub] Query simulated (Set GITHUB_TOKEN to connect live): action=${params.action} repo=${params.repo || 'local'}`
+                    };
+                }
+                return {
+                    success: true,
+                    output: `[MCP GitHub] Queried ${params.action} on ${params.repo || 'local repository'}`
+                };
+            }
+        });
+        // 2. Database Explorer Tool
+        this.registerTool({
+            serverName: 'database',
+            definition: {
+                name: 'mcp_db_inspect',
+                description: 'Inspect database tables and schema via MCP connector',
+                tier: PermissionTier.ReadOnly,
+                parameters: [
+                    { name: 'connectionString', type: 'string', description: 'Database connection or path', required: false },
+                    { name: 'table', type: 'string', description: 'Table name to inspect', required: false }
+                ]
+            },
+            handler: async (params) => {
+                return {
+                    success: true,
+                    output: `[MCP Database] Schema inspection: table=${params.table || 'all'} connected via MCP adapter.`
+                };
+            }
+        });
+        // 3. Issue Tracker Tool
+        this.registerTool({
+            serverName: 'issue_tracker',
+            definition: {
+                name: 'mcp_issue_tracker',
+                description: 'Read or update project issues and task tickets via MCP',
+                tier: PermissionTier.SafeMutation,
+                parameters: [
+                    { name: 'action', type: 'string', description: 'Action: get_ticket, list_tickets, update_ticket', required: true, enum: ['get_ticket', 'list_tickets', 'update_ticket'] },
+                    { name: 'ticketId', type: 'string', description: 'Ticket ID e.g. OVR-101', required: false }
+                ]
+            },
+            handler: async (params) => {
+                return {
+                    success: true,
+                    output: `[MCP Issue Tracker] Action ${params.action} processed for ticket ${params.ticketId || 'all'}.`
+                };
+            }
+        });
+    }
+}
+export const mcpRegistry = new McpRegistry();

package/dist/src/mcp/types.d.ts

@@ -0,0 +1,13 @@
+import { ToolDefinition, ToolHandler } from '../tools/types.js';
+export interface McpServerConfig {
+    name: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    disabled?: boolean;
+}
+export interface McpToolAdapter {
+    serverName: string;
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}

package/dist/src/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/providers/anthropic.d.ts

@@ -0,0 +1,10 @@
+import { BaseProvider } from './base.js';
+import { CompletionRequest, CompletionResponse, StreamChunk } from './types.js';
+export declare class AnthropicProvider extends BaseProvider {
+    constructor(apiKey: string, baseUrl?: string);
+    protected headers(): Record<string, string>;
+    protected getEndpoint(request: CompletionRequest): string;
+    protected buildRequestBody(request: CompletionRequest): Record<string, unknown>;
+    protected parseResponse(body: any): CompletionResponse;
+    protected parseStreamChunk(dataStr: string, buffer: Record<string, unknown>): StreamChunk | null;
+}

package/dist/src/providers/anthropic.js

@@ -0,0 +1,95 @@
+import { BaseProvider } from './base.js';
+export class AnthropicProvider extends BaseProvider {
+    constructor(apiKey, baseUrl = 'https://api.anthropic.com/v1') {
+        super('anthropic', apiKey, baseUrl);
+    }
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            'anthropic-version': '2023-06-01'
+        };
+    }
+    getEndpoint(request) {
+        return `${this.baseUrl.replace(/\/$/, '')}/messages`;
+    }
+    buildRequestBody(request) {
+        const systemMessages = request.messages.filter(m => m.role === 'system').map(m => m.content);
+        const system = systemMessages.length > 0 ? systemMessages.join('\n') : undefined;
+        const messages = request.messages
+            .filter(m => m.role !== 'system')
+            .map(m => ({
+            role: m.role === 'tool' ? 'user' : (m.role === 'assistant' ? 'assistant' : 'user'),
+            content: m.content
+        }));
+        const tools = request.tools?.map(t => ({
+            name: t.function.name,
+            description: t.function.description,
+            input_schema: t.function.parameters
+        }));
+        return {
+            model: request.model,
+            messages,
+            ...(system ? { system } : {}),
+            max_tokens: request.maxTokens || 4096,
+            ...(tools && tools.length > 0 ? { tools } : {}),
+            ...(request.temperature !== undefined ? { temperature: request.temperature } : {}),
+            stream: request.stream
+        };
+    }
+    parseResponse(body) {
+        const contentBlocks = body.content || [];
+        let content = '';
+        const toolCalls = [];
+        for (const block of contentBlocks) {
+            if (block.type === 'text') {
+                content += block.text;
+            }
+            else if (block.type === 'tool_use') {
+                toolCalls.push({
+                    id: block.id,
+                    name: block.name,
+                    arguments: block.input
+                });
+            }
+        }
+        return {
+            content,
+            toolCalls,
+            usage: body.usage ? {
+                promptTokens: body.usage.input_tokens,
+                completionTokens: body.usage.output_tokens,
+                totalTokens: body.usage.input_tokens + body.usage.output_tokens
+            } : undefined,
+            finishReason: body.stop_reason === 'tool_use' ? 'tool_calls' : (body.stop_reason === 'end_turn' ? 'stop' : 'stop')
+        };
+    }
+    parseStreamChunk(dataStr, buffer) {
+        try {
+            const data = JSON.parse(dataStr);
+            if (data.type === 'content_block_start') {
+                if (data.content_block.type === 'tool_use') {
+                    return {
+                        type: 'tool_call_start',
+                        toolCall: { id: data.content_block.id, name: data.content_block.name }
+                    };
+                }
+            }
+            else if (data.type === 'content_block_delta') {
+                if (data.delta.type === 'text_delta') {
+                    return { type: 'text', content: data.delta.text };
+                }
+                else if (data.delta.type === 'input_json_delta') {
+                    return { type: 'tool_call_args', toolCall: { arguments: data.delta.partial_json } };
+                }
+            }
+            else if (data.type === 'message_stop') {
+                return { type: 'done' };
+            }
+            return null;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+}

package/dist/src/providers/base.d.ts

@@ -0,0 +1,15 @@
+import { CompletionRequest, CompletionResponse, StreamChunk, LLMProvider } from './types.js';
+export declare abstract class BaseProvider implements LLMProvider {
+    name: string;
+    protected apiKey: string;
+    protected baseUrl: string;
+    constructor(name: string, apiKey: string, baseUrl: string);
+    protected headers(): Record<string, string>;
+    protected abstract buildRequestBody(request: CompletionRequest): Record<string, unknown>;
+    protected abstract parseResponse(body: unknown): CompletionResponse;
+    protected abstract parseStreamChunk(line: string, buffer: Record<string, unknown>): StreamChunk | null;
+    private fetchWithRetry;
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+    protected getEndpoint(request: CompletionRequest): string;
+}

package/dist/src/providers/base.js

@@ -0,0 +1,108 @@
+export class BaseProvider {
+    name;
+    apiKey;
+    baseUrl;
+    constructor(name, apiKey, baseUrl) {
+        this.name = name;
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`
+        };
+    }
+    async fetchWithRetry(url, options, maxRetries = 3) {
+        let delay = 1000;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, options);
+                if (response.ok)
+                    return response;
+                // Retryable HTTP status codes (rate limits, server errors)
+                const isRetryable = response.status === 429 || response.status >= 500;
+                if (!isRetryable || attempt === maxRetries) {
+                    const text = await response.text();
+                    let errorMessage = text;
+                    try {
+                        const parsed = JSON.parse(text);
+                        errorMessage = parsed.error?.message || parsed.message || text;
+                    }
+                    catch { }
+                    throw new Error(`[${this.name}] API Error ${response.status}: ${errorMessage}`);
+                }
+                // Wait with jitter before retrying
+                const jitter = Math.floor(Math.random() * 200);
+                await new Promise(r => setTimeout(r, delay + jitter));
+                delay *= 2;
+            }
+            catch (err) {
+                if (attempt === maxRetries || !err.message.includes('API Error')) {
+                    throw err;
+                }
+                await new Promise(r => setTimeout(r, delay));
+                delay *= 2;
+            }
+        }
+        throw new Error(`[${this.name}] Max retries (${maxRetries}) exceeded`);
+    }
+    async complete(request) {
+        const url = this.getEndpoint(request);
+        const body = this.buildRequestBody(request);
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body)
+        });
+        const data = await response.json();
+        return this.parseResponse(data);
+    }
+    async *stream(request) {
+        request.stream = true;
+        const url = this.getEndpoint(request);
+        const body = this.buildRequestBody(request);
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body)
+        });
+        if (!response.body) {
+            throw new Error(`[${this.name}] Expected a stream in the response`);
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let bufferStr = '';
+        const buffer = {};
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                bufferStr += decoder.decode(value, { stream: true });
+                const lines = bufferStr.split('\n');
+                bufferStr = lines.pop() || '';
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || !trimmed.startsWith('data: '))
+                        continue;
+                    const dataStr = trimmed.slice(6).trim();
+                    if (dataStr === '[DONE]') {
+                        yield { type: 'done' };
+                        continue;
+                    }
+                    const chunk = this.parseStreamChunk(dataStr, buffer);
+                    if (chunk) {
+                        yield chunk;
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    getEndpoint(request) {
+        return this.baseUrl;
+    }
+}

package/dist/src/providers/factory.d.ts

@@ -0,0 +1,28 @@
+import { LLMProvider, ModelInfo, CompletionRequest, CompletionResponse, StreamChunk } from './types.js';
+import { CANONICAL_MODELS, SUPPORTED_PROVIDERS, ProviderDefinition, normalizeModel } from './registry.js';
+export { CANONICAL_MODELS, SUPPORTED_PROVIDERS, ProviderDefinition, normalizeModel };
+import { ProviderConfig } from '../config/types.js';
+export declare const MODEL_REGISTRY: ModelInfo[];
+export declare class OfflineProvider implements LLMProvider {
+    name: string;
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    stream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+}
+export declare function createProvider(providerName: string, config?: ProviderConfig): LLMProvider;
+/**
+ * Resolves a raw model string, alias, or provider/model into a canonical structure.
+ */
+export declare function resolveModel(modelId: string, preferredProvider?: string): {
+    provider: string;
+    model: string;
+    displayName: string;
+} | undefined;
+export declare function listModels(providerFilter?: string): ModelInfo[];
+export declare function listProviders(): ProviderDefinition[];
+/**
+ * Validates whether an API key is structurally and functionally plausible.
+ */
+export declare function validateProviderKey(providerName: string, apiKey: string): Promise<{
+    valid: boolean;
+    error?: string;
+}>;