overarch-linux-arm64 0.8.0

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

@@ -0,0 +1,24 @@
+import { Message } from './types.js';
+export interface ValidatedMessagePayload {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+/**
+ * Pre-flight message validator and healer for LLM APIs (especially OpenAI / OpenRouter).
+ * Guarantees that every assistant tool call is paired with a corresponding tool result message,
+ * and fixes orphaned calls or results that would cause provider 400 Bad Request errors.
+ */
+export declare function validateAndHealMessages(messages: Message[]): Message[];
+/**
+ * Serializes Message array into strict OpenAI / OpenRouter Chat Completion format.
+ */
+export declare function formatForOpenAI(messages: Message[]): ValidatedMessagePayload[];

package/dist/src/providers/validator.js

@@ -0,0 +1,161 @@
+/**
+ * Pre-flight message validator and healer for LLM APIs (especially OpenAI / OpenRouter).
+ * Guarantees that every assistant tool call is paired with a corresponding tool result message,
+ * and fixes orphaned calls or results that would cause provider 400 Bad Request errors.
+ */
+export function validateAndHealMessages(messages) {
+    if (!messages || messages.length === 0) {
+        return [];
+    }
+    const healed = [];
+    const pendingToolCalls = new Map(); // id -> toolName
+    for (let i = 0; i < messages.length; i++) {
+        const rawMsg = messages[i];
+        const role = rawMsg.role;
+        const content = rawMsg.content || '';
+        const toolCallId = rawMsg.toolCallId || rawMsg.tool_call_id;
+        const toolCalls = rawMsg.toolCalls || rawMsg.tool_calls;
+        if (role === 'assistant') {
+            // If we had pending tool calls from a previous assistant message that were never answered,
+            // heal them by inserting synthesized tool result messages before continuing
+            if (pendingToolCalls.size > 0) {
+                for (const [orphanId, orphanName] of pendingToolCalls.entries()) {
+                    healed.push({
+                        role: 'tool',
+                        toolCallId: orphanId,
+                        content: JSON.stringify({ success: false, error: `Tool call '${orphanName}' (${orphanId}) had no returned result.` })
+                    });
+                }
+                pendingToolCalls.clear();
+            }
+            if (toolCalls && Array.isArray(toolCalls) && toolCalls.length > 0) {
+                const normalizedToolCalls = toolCalls.map((tc, idx) => {
+                    const id = tc.id || `call_${Date.now()}_${idx}`;
+                    const name = tc.name || tc.function?.name || 'unknown_tool';
+                    let args = tc.arguments;
+                    if (typeof args === 'string') {
+                        try {
+                            args = JSON.parse(args);
+                        }
+                        catch {
+                            args = {};
+                        }
+                    }
+                    pendingToolCalls.set(id, name);
+                    return { id, name, arguments: args || {} };
+                });
+                healed.push({
+                    role: 'assistant',
+                    content,
+                    toolCalls: normalizedToolCalls
+                });
+            }
+            else {
+                healed.push({
+                    role: 'assistant',
+                    content
+                });
+            }
+        }
+        else if (role === 'tool') {
+            const validId = toolCallId || `call_unpaired_${Date.now()}`;
+            if (pendingToolCalls.has(validId)) {
+                pendingToolCalls.delete(validId);
+                healed.push({
+                    role: 'tool',
+                    toolCallId: validId,
+                    content
+                });
+            }
+            else if (pendingToolCalls.size > 0) {
+                // Match first available pending tool call if ID mismatched due to corruption
+                const firstPendingId = pendingToolCalls.keys().next().value;
+                if (firstPendingId) {
+                    pendingToolCalls.delete(firstPendingId);
+                    healed.push({
+                        role: 'tool',
+                        toolCallId: firstPendingId,
+                        content
+                    });
+                }
+            }
+            else {
+                // Orphaned tool response with no preceding tool call.
+                // Convert to a system/user observation so providers don't reject it with missing tool_call_id
+                healed.push({
+                    role: 'user',
+                    content: `[Previous Tool Observation]: ${content}`
+                });
+            }
+        }
+        else {
+            // System or User message.
+            // If there are pending tool calls, heal them first!
+            if (pendingToolCalls.size > 0) {
+                for (const [orphanId, orphanName] of pendingToolCalls.entries()) {
+                    healed.push({
+                        role: 'tool',
+                        toolCallId: orphanId,
+                        content: JSON.stringify({ success: false, error: `Tool call '${orphanName}' (${orphanId}) was interrupted.` })
+                    });
+                }
+                pendingToolCalls.clear();
+            }
+            healed.push({
+                role: role,
+                content
+            });
+        }
+    }
+    // Trailing check: if the very last message was an assistant tool call, synthesize results
+    if (pendingToolCalls.size > 0) {
+        for (const [orphanId, orphanName] of pendingToolCalls.entries()) {
+            healed.push({
+                role: 'tool',
+                toolCallId: orphanId,
+                content: JSON.stringify({ success: false, error: `Tool call '${orphanName}' (${orphanId}) awaiting completion.` })
+            });
+        }
+        pendingToolCalls.clear();
+    }
+    return healed;
+}
+/**
+ * Serializes Message array into strict OpenAI / OpenRouter Chat Completion format.
+ */
+export function formatForOpenAI(messages) {
+    const healed = validateAndHealMessages(messages);
+    return healed.map((m) => {
+        if (m.role === 'tool') {
+            return {
+                role: 'tool',
+                tool_call_id: m.toolCallId || 'call_fallback',
+                content: m.content
+            };
+        }
+        if (m.role === 'assistant') {
+            if (m.toolCalls && m.toolCalls.length > 0) {
+                return {
+                    role: 'assistant',
+                    content: m.content || null,
+                    tool_calls: m.toolCalls.map((tc) => ({
+                        id: tc.id,
+                        type: 'function',
+                        function: {
+                            name: tc.name,
+                            arguments: JSON.stringify(tc.arguments || {})
+                        }
+                    }))
+                };
+            }
+            return {
+                role: 'assistant',
+                content: m.content || ''
+            };
+        }
+        return {
+            role: m.role,
+            content: m.content || ''
+        };
+    });
+}

package/dist/src/security/audit.d.ts

@@ -0,0 +1,56 @@
+import { Capability, RiskLevel } from './policy.js';
+export interface AuditRecord {
+    id: string;
+    timestamp: string;
+    action: string;
+    capability: Capability;
+    riskLevel: RiskLevel;
+    decision: 'ALLOWED' | 'DENIED' | 'APPROVED' | 'ESCALATED' | 'STOPPED';
+    outcome: 'SUCCESS' | 'FAILED' | 'BLOCKED' | 'PENDING';
+    reason?: string;
+    params?: Record<string, any>;
+    durationMs?: number;
+}
+export interface AuditFilterOptions {
+    limit?: number;
+    riskLevel?: RiskLevel;
+    decision?: string;
+    action?: string;
+    capability?: Capability;
+    since?: string;
+}
+export declare class AuditLogger {
+    private logPath;
+    private static instance;
+    constructor(customPath?: string);
+    static getInstance(customPath?: string): AuditLogger;
+    getLogPath(): string;
+    setLogPath(newPath: string): void;
+    /**
+     * Append an entry to the append-only JSONL audit log.
+     */
+    log(entry: {
+        action: string;
+        capability: Capability;
+        riskLevel: RiskLevel;
+        decision: 'ALLOWED' | 'DENIED' | 'APPROVED' | 'ESCALATED' | 'STOPPED';
+        outcome: 'SUCCESS' | 'FAILED' | 'BLOCKED' | 'PENDING';
+        reason?: string;
+        params?: Record<string, any>;
+        durationMs?: number;
+    }): AuditRecord;
+    /**
+     * Read and filter entries from the audit log.
+     */
+    readEntries(options?: AuditFilterOptions): AuditRecord[];
+    /**
+     * Export audit log to a target file in JSON, JSONL, or CSV format.
+     */
+    exportEntries(destinationPath: string, format?: 'json' | 'jsonl' | 'csv'): string;
+    /**
+     * Clear audit log (primarily for testing).
+     */
+    clear(): void;
+    private sanitizeParams;
+}
+export declare const auditLogger: AuditLogger;

package/dist/src/security/audit.js

@@ -0,0 +1,154 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+export class AuditLogger {
+    logPath;
+    static instance = null;
+    constructor(customPath) {
+        if (customPath) {
+            this.logPath = customPath;
+        }
+        else {
+            const workspaceDir = path.join(process.cwd(), '.overarch');
+            if (fs.existsSync(workspaceDir)) {
+                this.logPath = path.join(workspaceDir, 'audit.jsonl');
+            }
+            else {
+                const globalDir = path.join(os.homedir(), '.overarch');
+                if (!fs.existsSync(globalDir)) {
+                    try {
+                        fs.mkdirSync(globalDir, { recursive: true });
+                    }
+                    catch { }
+                }
+                this.logPath = path.join(globalDir, 'audit.jsonl');
+            }
+        }
+    }
+    static getInstance(customPath) {
+        if (!AuditLogger.instance || customPath) {
+            AuditLogger.instance = new AuditLogger(customPath);
+        }
+        return AuditLogger.instance;
+    }
+    getLogPath() {
+        return this.logPath;
+    }
+    setLogPath(newPath) {
+        this.logPath = newPath;
+    }
+    /**
+     * Append an entry to the append-only JSONL audit log.
+     */
+    log(entry) {
+        const record = {
+            id: crypto.randomBytes(8).toString('hex'),
+            timestamp: new Date().toISOString(),
+            action: entry.action,
+            capability: entry.capability,
+            riskLevel: entry.riskLevel,
+            decision: entry.decision,
+            outcome: entry.outcome,
+            reason: entry.reason,
+            params: entry.params ? this.sanitizeParams(entry.params) : undefined,
+            durationMs: entry.durationMs,
+        };
+        try {
+            const dir = path.dirname(this.logPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.appendFileSync(this.logPath, JSON.stringify(record) + '\n', 'utf8');
+        }
+        catch (err) {
+            // Append-only logging fails closed without crashing runtime
+            console.error(`[Overarch Audit] Failed to append audit log: ${err}`);
+        }
+        return record;
+    }
+    /**
+     * Read and filter entries from the audit log.
+     */
+    readEntries(options = {}) {
+        if (!fs.existsSync(this.logPath)) {
+            return [];
+        }
+        try {
+            const content = fs.readFileSync(this.logPath, 'utf8');
+            const lines = content.split('\n').filter(line => line.trim().length > 0);
+            const records = [];
+            for (const line of lines) {
+                try {
+                    const rec = JSON.parse(line);
+                    if (options.riskLevel && rec.riskLevel !== options.riskLevel)
+                        continue;
+                    if (options.decision && rec.decision.toLowerCase() !== options.decision.toLowerCase())
+                        continue;
+                    if (options.action && !rec.action.toLowerCase().includes(options.action.toLowerCase()))
+                        continue;
+                    if (options.capability && rec.capability !== options.capability)
+                        continue;
+                    if (options.since && new Date(rec.timestamp) < new Date(options.since))
+                        continue;
+                    records.push(rec);
+                }
+                catch { }
+            }
+            if (options.limit && options.limit > 0) {
+                return records.slice(-options.limit);
+            }
+            return records;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Export audit log to a target file in JSON, JSONL, or CSV format.
+     */
+    exportEntries(destinationPath, format = 'jsonl') {
+        const entries = this.readEntries();
+        const destDir = path.dirname(destinationPath);
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+        if (format === 'json') {
+            fs.writeFileSync(destinationPath, JSON.stringify(entries, null, 2), 'utf8');
+        }
+        else if (format === 'csv') {
+            const header = 'id,timestamp,action,capability,riskLevel,decision,outcome,reason\n';
+            const rows = entries.map(e => `"${e.id}","${e.timestamp}","${e.action}","${e.capability}","${e.riskLevel}","${e.decision}","${e.outcome}","${(e.reason || '').replace(/"/g, '""')}"`).join('\n');
+            fs.writeFileSync(destinationPath, header + rows + '\n', 'utf8');
+        }
+        else {
+            const content = entries.map(e => JSON.stringify(e)).join('\n') + (entries.length ? '\n' : '');
+            fs.writeFileSync(destinationPath, content, 'utf8');
+        }
+        return destinationPath;
+    }
+    /**
+     * Clear audit log (primarily for testing).
+     */
+    clear() {
+        if (fs.existsSync(this.logPath)) {
+            fs.writeFileSync(this.logPath, '', 'utf8');
+        }
+    }
+    sanitizeParams(params) {
+        const sanitized = {};
+        for (const [key, val] of Object.entries(params)) {
+            if (/key|secret|token|password|auth/i.test(key)) {
+                sanitized[key] = '[REDACTED]';
+            }
+            else if (typeof val === 'string' && val.length > 200) {
+                sanitized[key] = val.slice(0, 197) + '...';
+            }
+            else {
+                sanitized[key] = val;
+            }
+        }
+        return sanitized;
+    }
+}
+export const auditLogger = AuditLogger.getInstance();

package/dist/src/security/guardrails.d.ts

@@ -0,0 +1,9 @@
+export declare function validatePath(filepath: string, basePath: string): boolean;
+export declare const DANGEROUS_COMMANDS: string[];
+export declare function isCommandDangerous(command: string): {
+    dangerous: boolean;
+    reason?: string;
+};
+export declare function abort(): void;
+export declare function isAborted(): boolean;
+export declare function resetAbort(): void;

package/dist/src/security/guardrails.js

@@ -0,0 +1,32 @@
+import * as path from 'node:path';
+export function validatePath(filepath, basePath) {
+    const resolvedPath = path.resolve(basePath, filepath);
+    const resolvedBase = path.resolve(basePath);
+    return resolvedPath.startsWith(resolvedBase);
+}
+export const DANGEROUS_COMMANDS = [
+    'rm -rf /',
+    'format',
+    ':(){:|:&};:',
+    'dd if=',
+    'mkfs',
+    '> /dev/sda'
+];
+export function isCommandDangerous(command) {
+    for (const pattern of DANGEROUS_COMMANDS) {
+        if (command.includes(pattern)) {
+            return { dangerous: true, reason: `Matches dangerous pattern: ${pattern}` };
+        }
+    }
+    return { dangerous: false };
+}
+let aborted = false;
+export function abort() {
+    aborted = true;
+}
+export function isAborted() {
+    return aborted;
+}
+export function resetAbort() {
+    aborted = false;
+}

package/dist/src/security/permissions.d.ts

@@ -0,0 +1,12 @@
+import { PermissionTier, PermissionConfig } from '../config/types.js';
+import { ToolDefinition } from '../tools/types.js';
+import * as readline from 'node:readline/promises';
+export declare function classifyAction(tool: ToolDefinition): PermissionTier;
+export declare function checkPermission(tool: ToolDefinition, params: Record<string, unknown>, config: PermissionConfig, options?: {
+    autoApprove?: boolean;
+    rl?: readline.Interface;
+}): Promise<{
+    allowed: boolean;
+    reason?: string;
+}>;
+export declare function formatPermissionPrompt(tool: ToolDefinition, params: Record<string, unknown>): string;

package/dist/src/security/permissions.js

@@ -0,0 +1,68 @@
+import { PermissionTier } from '../config/types.js';
+import * as readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+export function classifyAction(tool) {
+    return tool.tier;
+}
+export async function checkPermission(tool, params, config, options) {
+    const tier = classifyAction(tool);
+    // Check deny list
+    if (config.deny?.includes(tool.name)) {
+        return { allowed: false, reason: `Tool '${tool.name}' is in the deny list` };
+    }
+    if (tier === PermissionTier.ReadOnly) {
+        return { allowed: true };
+    }
+    if (tier === PermissionTier.SafeMutation) {
+        return { allowed: true };
+    }
+    if (tier === PermissionTier.StateMutating) {
+        if (options?.autoApprove)
+            return { allowed: true };
+        if (config.autoApprove?.includes(PermissionTier.StateMutating))
+            return { allowed: true };
+        const prompt = formatPermissionPrompt(tool, params);
+        let answer = '';
+        if (options?.rl) {
+            answer = await options.rl.question(`\n${prompt}\nAllow? [Y/n] `);
+        }
+        else {
+            const rl = readline.createInterface({ input: stdin, output: stdout });
+            answer = await rl.question(`\n${prompt}\nAllow? [Y/n] `);
+            rl.close();
+        }
+        if (answer.trim().toLowerCase() === 'n') {
+            return { allowed: false, reason: 'User denied permission' };
+        }
+        return { allowed: true };
+    }
+    if (tier === PermissionTier.Destructive) {
+        if (options?.autoApprove) {
+            // Even with autoApprove, destructive actions need explicit confirmation
+            // unless the config specifically auto-approves destructive
+            if (!config.autoApprove?.includes(PermissionTier.Destructive)) {
+                const prompt = formatPermissionPrompt(tool, params);
+                let answer = '';
+                if (options?.rl) {
+                    answer = await options.rl.question(`\n⚠ DESTRUCTIVE ACTION\n${prompt}\nType 'yes' to confirm: `);
+                }
+                else {
+                    const rl = readline.createInterface({ input: stdin, output: stdout });
+                    answer = await rl.question(`\n⚠ DESTRUCTIVE ACTION\n${prompt}\nType 'yes' to confirm: `);
+                    rl.close();
+                }
+                if (answer.trim().toLowerCase() !== 'yes') {
+                    return { allowed: false, reason: 'User denied destructive action' };
+                }
+            }
+        }
+        return { allowed: true };
+    }
+    return { allowed: false, reason: 'Unknown permission tier' };
+}
+export function formatPermissionPrompt(tool, params) {
+    const paramStr = Object.entries(params)
+        .map(([k, v]) => `  ${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+        .join('\n');
+    return `Tool: ${tool.name}\n${paramStr}`;
+}