magi-ai 0.1.0

package/dist/src/adapters/base.js

@@ -0,0 +1,149 @@
+import { AdapterError } from '../types/adapter.js';
+import { spawnProcess, isBinaryAvailable } from '../utils/process.js';
+import { withRetry } from '../utils/retry.js';
+import { logger } from '../utils/logger.js';
+import { BinaryNotFoundError } from '../utils/errors.js';
+import { assertNoUnsafeFlags } from '../utils/flag-validator.js';
+import { extractJson } from '../parsers/json-extractor.js';
+export class AbstractCliAdapter {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** All adapters use stdin for prompt delivery (security: no shell injection via args). */
+    usesStdinInput() { return true; }
+    /**
+     * Build stdin data with JSON output instructions and optional system context.
+     *
+     * Default implementation embeds CRITICAL INSTRUCTION and few-shot examples
+     * for CLIs that don't support structured output natively (Codex, Gemini).
+     * Subclasses with native structured output (Claude) should override this.
+     */
+    getStdinData(request) {
+        const systemContext = request.systemPrompt
+            ? `Context: ${request.systemPrompt}\n\n`
+            : '';
+        const fileAccessHint = request.fileAccessEnabled
+            ? 'You have access to the project directory. Read relevant files to enrich your analysis before responding.\n\n'
+            : '';
+        return `${systemContext}${request.prompt}
+
+${fileAccessHint}CRITICAL INSTRUCTION: You MUST respond with ONLY a valid JSON object and absolutely nothing else. No markdown, no explanation, no code blocks. Just pure JSON:
+{"vote":"APPROVE or REJECT or ABSTAIN","confidence":"<0.0-1.0>","reasoning":"your reasoning","keyPoints":["point1","point2"],"suggestions":["suggestion1"]}
+
+Here are examples of well-structured responses:
+
+Example 1 (APPROVE with moderate confidence):
+{"vote":"APPROVE","confidence":0.78,"reasoning":"The implementation correctly handles edge cases including null inputs and concurrent access. Error messages are specific and actionable.","keyPoints":["Null safety verified","Concurrency handled via mutex","Clear error messages"],"suggestions":["Consider adding retry logic for transient failures"]}
+
+Example 2 (REJECT with specific concerns):
+{"vote":"REJECT","confidence":0.65,"reasoning":"The authentication flow skips token expiry validation, allowing expired sessions to persist indefinitely.","keyPoints":["Token expiry not checked","Session cleanup missing","Security risk identified"],"suggestions":["Add token expiry check in middleware","Implement session timeout cleanup"]}`;
+    }
+    async healthCheck() {
+        const binary = this.config.binaryPath ?? this.tool;
+        const available = await isBinaryAvailable(binary);
+        if (!available) {
+            throw new BinaryNotFoundError(this.tool);
+        }
+        try {
+            const result = await spawnProcess({
+                command: binary,
+                args: ['--version'],
+                timeoutMs: 10_000,
+            });
+            return result.stdout.trim() || result.stderr.trim() || 'unknown version';
+        }
+        catch (err) {
+            logger.debug('Adapter: version check failed', { tool: this.tool, error: String(err) });
+            return 'available (version unknown)';
+        }
+    }
+    async execute(request) {
+        const timeoutMs = request.timeoutMs ?? this.config.timeoutMs;
+        const { result: response, attempts } = await withRetry(async () => this.executeOnce(request, timeoutMs), {
+            maxRetries: this.config.maxRetries,
+            shouldRetry: (error) => this.isRetryable(error),
+        });
+        response.meta.retryCount = attempts - 1;
+        return response;
+    }
+    async executeOnce(request, timeoutMs) {
+        const args = this.buildCommand(request);
+        const binary = args[0];
+        const cliArgs = args.slice(1);
+        // Validate no unsafe flags in the command
+        assertNoUnsafeFlags(cliArgs, this.tool);
+        const stdinData = this.getStdinData(request);
+        logger.debug(`${this.displayName} executing`, { binary, args: cliArgs.length });
+        const result = await spawnProcess({
+            command: binary,
+            args: cliArgs,
+            stdin: stdinData,
+            timeoutMs,
+            cwd: request.cwd ?? this.config.cwd,
+            env: this.config.env,
+            onStdoutChunk: request.onStdoutChunk,
+            onStderrChunk: request.onStderrChunk,
+            signal: request.signal,
+        });
+        if (result.timedOut) {
+            throw new AdapterError({
+                unit: this.unit,
+                tool: this.tool,
+                code: 'TIMEOUT',
+                message: `${this.displayName} timed out after ${timeoutMs}ms`,
+                partialOutput: result.stdout,
+            });
+        }
+        if (result.exitCode !== 0) {
+            throw new AdapterError({
+                unit: this.unit,
+                tool: this.tool,
+                code: 'CRASH',
+                message: `${this.displayName} exited with code ${result.exitCode}`,
+                stderr: result.stderr,
+                exitCode: result.exitCode,
+                partialOutput: result.stdout,
+            });
+        }
+        try {
+            const parsed = this.parseResponse(result.stdout);
+            return {
+                ...parsed,
+                meta: {
+                    durationMs: result.durationMs,
+                    exitCode: result.exitCode,
+                    retryCount: 0,
+                    structuredOutput: parsed.parsed,
+                },
+            };
+        }
+        catch (err) {
+            logger.debug('Adapter: output parse failed', { unit: this.unit, error: String(err) });
+            throw new AdapterError({
+                unit: this.unit,
+                tool: this.tool,
+                code: 'PARSE_ERROR',
+                message: `Failed to parse ${this.displayName} output`,
+                partialOutput: result.stdout,
+            });
+        }
+    }
+    /**
+     * Parse the CLI's raw output into structured form.
+     *
+     * Default implementation uses extractJson for heuristic JSON extraction.
+     * All three adapters (Claude, Codex, Gemini) share this same logic.
+     */
+    parseResponse(raw) {
+        const result = extractJson(raw);
+        return {
+            structured: result.data,
+            raw: result.effectiveRaw,
+            parsed: result.success,
+        };
+    }
+    isRetryable(error) {
+        return error.code === 'TIMEOUT' || error.code === 'CRASH';
+    }
+}

package/dist/src/adapters/claude.d.ts

@@ -0,0 +1,29 @@
+import { AbstractCliAdapter } from './base.js';
+import type { AdapterRequest } from '../types/adapter.js';
+import type { MagiUnit, CliTool } from '../types/core.js';
+/**
+ * MELCHIOR - Claude Code CLI Adapter
+ *
+ * The most feature-rich adapter:
+ * - Supports --json-schema for structured output
+ * - Supports --system-prompt for persona injection
+ * - Supports --output-format json for envelope parsing
+ * - Supports --max-budget-usd for cost control
+ * - Prompt delivered via stdin (never in CLI args)
+ */
+export declare class ClaudeAdapter extends AbstractCliAdapter {
+    readonly unit: MagiUnit;
+    readonly tool: CliTool;
+    readonly displayName = "MELCHIOR (Claude)";
+    supportsStructuredOutput(): boolean;
+    supportsSystemPrompt(): boolean;
+    buildCommand(request: AdapterRequest): string[];
+    /**
+     * Override: systemPrompt is prepended via <system> tags to handle multi-line
+     * prompts safely (CLI --system-prompt flag breaks on newlines in BERSERK mode).
+     *
+     * Although --json-schema is passed, the model may ignore it and return Markdown.
+     * Belt-and-suspenders: include explicit JSON instructions in the prompt as well.
+     */
+    protected getStdinData(request: AdapterRequest): string;
+}

package/dist/src/adapters/claude.js

@@ -0,0 +1,65 @@
+import { AbstractCliAdapter } from './base.js';
+/** Hardcoded safety flags that MUST always be present. */
+const CLAUDE_SAFETY_FLAGS = [
+    '--output-format', 'json',
+    '--no-session-persistence',
+];
+/**
+ * MELCHIOR - Claude Code CLI Adapter
+ *
+ * The most feature-rich adapter:
+ * - Supports --json-schema for structured output
+ * - Supports --system-prompt for persona injection
+ * - Supports --output-format json for envelope parsing
+ * - Supports --max-budget-usd for cost control
+ * - Prompt delivered via stdin (never in CLI args)
+ */
+export class ClaudeAdapter extends AbstractCliAdapter {
+    unit = 'MELCHIOR';
+    tool = 'claude';
+    displayName = 'MELCHIOR (Claude)';
+    supportsStructuredOutput() { return true; }
+    supportsSystemPrompt() { return true; }
+    buildCommand(request) {
+        const cmd = [
+            this.config.binaryPath ?? 'claude',
+            // NOTE: -p is removed. Prompt is delivered via stdin.
+            ...CLAUDE_SAFETY_FLAGS,
+        ];
+        // NOTE: systemPrompt is delivered via stdin (getStdinData), not CLI args.
+        // This handles multi-line BERSERK prompts safely.
+        if (request.fileAccessEnabled) {
+            cmd.push('--allowedTools', 'Read Glob Grep');
+        }
+        if (request.jsonSchema) {
+            cmd.push('--json-schema', JSON.stringify(request.jsonSchema));
+        }
+        if (request.maxBudgetUsd) {
+            cmd.push('--max-budget-usd', String(request.maxBudgetUsd));
+        }
+        if (this.config.model) {
+            cmd.push('--model', this.config.model);
+        }
+        // parseResponse() inherited from AbstractCliAdapter.
+        return cmd;
+    }
+    /**
+     * Override: systemPrompt is prepended via <system> tags to handle multi-line
+     * prompts safely (CLI --system-prompt flag breaks on newlines in BERSERK mode).
+     *
+     * Although --json-schema is passed, the model may ignore it and return Markdown.
+     * Belt-and-suspenders: include explicit JSON instructions in the prompt as well.
+     */
+    getStdinData(request) {
+        const systemContext = request.systemPrompt
+            ? `<system>\n${request.systemPrompt}\n</system>\n\n`
+            : '';
+        const fileAccessHint = request.fileAccessEnabled
+            ? 'You have access to project files via Read, Glob, and Grep tools. Explore the codebase as needed to form a well-informed opinion, then respond with your final answer.\n\n'
+            : '';
+        return `${systemContext}${request.prompt}
+
+${fileAccessHint}CRITICAL INSTRUCTION: You MUST respond with ONLY a valid JSON object and absolutely nothing else. No markdown, no explanation, no code blocks. Just pure JSON:
+{"vote":"APPROVE or REJECT or ABSTAIN","confidence":0.75,"reasoning":"your reasoning","keyPoints":["point1","point2"],"suggestions":["suggestion1"]}`;
+    }
+}

package/dist/src/adapters/codex.d.ts

@@ -0,0 +1,21 @@
+import { AbstractCliAdapter } from './base.js';
+import type { AdapterRequest } from '../types/adapter.js';
+import type { MagiUnit, CliTool } from '../types/core.js';
+/**
+ * BALTHASAR - Codex CLI Adapter
+ *
+ * The trickiest adapter:
+ * - No --json-schema support -> embeds JSON instructions in stdin
+ * - No --output-format json -> heuristic regex extraction
+ * - Uses `codex exec` for non-interactive execution
+ * - Always runs with --sandbox read-only for safety
+ * - Prompt delivered via stdin (never in CLI args)
+ */
+export declare class CodexAdapter extends AbstractCliAdapter {
+    readonly unit: MagiUnit;
+    readonly tool: CliTool;
+    readonly displayName = "BALTHASAR (Codex)";
+    supportsStructuredOutput(): boolean;
+    supportsSystemPrompt(): boolean;
+    buildCommand(request: AdapterRequest): string[];
+}

package/dist/src/adapters/codex.js

@@ -0,0 +1,41 @@
+import { AbstractCliAdapter } from './base.js';
+/** Hardcoded safety flags that MUST always be present. */
+const CODEX_SAFETY_FLAGS = [
+    'exec',
+    '--full-auto',
+    '--sandbox', 'read-only',
+    '--skip-git-repo-check',
+];
+/**
+ * BALTHASAR - Codex CLI Adapter
+ *
+ * The trickiest adapter:
+ * - No --json-schema support -> embeds JSON instructions in stdin
+ * - No --output-format json -> heuristic regex extraction
+ * - Uses `codex exec` for non-interactive execution
+ * - Always runs with --sandbox read-only for safety
+ * - Prompt delivered via stdin (never in CLI args)
+ */
+export class CodexAdapter extends AbstractCliAdapter {
+    unit = 'BALTHASAR';
+    tool = 'codex';
+    displayName = 'BALTHASAR (Codex)';
+    supportsStructuredOutput() { return false; }
+    supportsSystemPrompt() { return false; }
+    buildCommand(request) {
+        const cmd = [
+            this.config.binaryPath ?? 'codex',
+            ...CODEX_SAFETY_FLAGS,
+        ];
+        if (this.config.model) {
+            cmd.push('-m', this.config.model);
+        }
+        const cwd = request.cwd ?? (request.fileAccessEnabled ? process.cwd() : undefined);
+        if (cwd) {
+            cmd.push('-C', cwd);
+        }
+        // NOTE: prompt is no longer appended to args. Delivered via stdin.
+        // getStdinData() and parseResponse() inherited from AbstractCliAdapter.
+        return cmd;
+    }
+}

package/dist/src/adapters/gemini.d.ts

@@ -0,0 +1,18 @@
+import { AbstractCliAdapter } from './base.js';
+import type { AdapterRequest } from '../types/adapter.js';
+import type { MagiUnit, CliTool } from '../types/core.js';
+/**
+ * CASPER - Gemini CLI Adapter
+ *
+ * Always runs in plan (read-only) mode for safety (5-layer defense).
+ * - Prompt delivered via stdin (never in CLI args)
+ * - JSON instructions embedded in stdin data
+ */
+export declare class GeminiAdapter extends AbstractCliAdapter {
+    readonly unit: MagiUnit;
+    readonly tool: CliTool;
+    readonly displayName = "CASPER (Gemini)";
+    supportsStructuredOutput(): boolean;
+    supportsSystemPrompt(): boolean;
+    buildCommand(_request: AdapterRequest): string[];
+}

package/dist/src/adapters/gemini.js

@@ -0,0 +1,31 @@
+import { AbstractCliAdapter } from './base.js';
+/** Hardcoded safety flags that MUST always be present. */
+const GEMINI_SAFETY_FLAGS = [
+    '--approval-mode', 'plan', // Always read-only (5-layer defense)
+];
+/**
+ * CASPER - Gemini CLI Adapter
+ *
+ * Always runs in plan (read-only) mode for safety (5-layer defense).
+ * - Prompt delivered via stdin (never in CLI args)
+ * - JSON instructions embedded in stdin data
+ */
+export class GeminiAdapter extends AbstractCliAdapter {
+    unit = 'CASPER';
+    tool = 'gemini';
+    displayName = 'CASPER (Gemini)';
+    supportsStructuredOutput() { return false; }
+    supportsSystemPrompt() { return false; }
+    buildCommand(_request) {
+        const cmd = [
+            this.config.binaryPath ?? 'gemini',
+            // NOTE: -p is removed. Prompt is delivered via stdin.
+            ...GEMINI_SAFETY_FLAGS,
+        ];
+        if (this.config.model) {
+            cmd.push('-m', this.config.model);
+        }
+        // getStdinData() and parseResponse() inherited from AbstractCliAdapter.
+        return cmd;
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { ICliAdapter } from '../types/adapter.js';
+import type { MagiUnitDefinition } from '../types/core.js';
+/**
+ * Registry for CLI adapters.
+ * Supports dynamic registration for N-body configurations (2-7 units).
+ */
+export declare class AdapterRegistry {
+    private adapters;
+    private definitions;
+    register(adapter: ICliAdapter, definition?: MagiUnitDefinition): void;
+    get(unit: string): ICliAdapter;
+    has(unit: string): boolean;
+    getAll(): ICliAdapter[];
+    getAllUnits(): string[];
+    getDefinition(unit: string): MagiUnitDefinition | undefined;
+    get size(): number;
+    validateQuorum(minQuorum?: number): void;
+    healthCheckAll(): Promise<Map<string, string | Error>>;
+}

package/dist/src/adapters/registry.js

@@ -0,0 +1,59 @@
+import { logger } from '../utils/logger.js';
+/**
+ * Registry for CLI adapters.
+ * Supports dynamic registration for N-body configurations (2-7 units).
+ */
+export class AdapterRegistry {
+    adapters = new Map();
+    definitions = new Map();
+    register(adapter, definition) {
+        this.adapters.set(adapter.unit, adapter);
+        if (definition) {
+            this.definitions.set(adapter.unit, definition);
+        }
+        if (this.adapters.size > 7) {
+            logger.warn('More than 7 MAGI units registered — performance may degrade');
+        }
+        logger.debug(`Registered adapter: ${adapter.displayName}`);
+    }
+    get(unit) {
+        const adapter = this.adapters.get(unit);
+        if (!adapter) {
+            throw new Error(`No adapter registered for MAGI unit: ${unit}`);
+        }
+        return adapter;
+    }
+    has(unit) {
+        return this.adapters.has(unit);
+    }
+    getAll() {
+        return Array.from(this.adapters.values());
+    }
+    getAllUnits() {
+        return Array.from(this.adapters.keys());
+    }
+    getDefinition(unit) {
+        return this.definitions.get(unit);
+    }
+    get size() {
+        return this.adapters.size;
+    }
+    validateQuorum(minQuorum = 2) {
+        if (this.adapters.size < minQuorum) {
+            throw new Error(`Quorum not met: ${this.adapters.size} adapters registered, minimum ${minQuorum} required`);
+        }
+    }
+    async healthCheckAll() {
+        const results = new Map();
+        await Promise.allSettled(this.getAll().map(async (adapter) => {
+            try {
+                const version = await adapter.healthCheck();
+                results.set(adapter.unit, version);
+            }
+            catch (error) {
+                results.set(adapter.unit, error instanceof Error ? error : new Error(String(error)));
+            }
+        }));
+        return results;
+    }
+}

package/dist/src/audit/hash-chain.d.ts

@@ -0,0 +1,21 @@
+import type { AuditLogEntry } from './types.js';
+export interface VerifyResult {
+    valid: boolean;
+    brokenAt?: number;
+    error?: string;
+}
+/**
+ * Compute a deterministic SHA-256 hash for an audit log entry.
+ *
+ * The canonical string is: timestamp + event + deliberationId + JSON.stringify(data, sortedKeys) + prevHash
+ */
+export declare function computeEntryHash(entry: Omit<AuditLogEntry, 'hash'>): string;
+/**
+ * Verify the integrity of a hash chain of audit log entries.
+ *
+ * Checks:
+ * 1. Each entry's hash matches recomputation from its fields.
+ * 2. Each entry's prevHash matches the previous entry's hash.
+ * 3. The first entry's prevHash is the empty string.
+ */
+export declare function verifyChain(entries: AuditLogEntry[]): VerifyResult;

package/dist/src/audit/hash-chain.js

@@ -0,0 +1,70 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * Compute a deterministic SHA-256 hash for an audit log entry.
+ *
+ * The canonical string is: timestamp + event + deliberationId + JSON.stringify(data, sortedKeys) + prevHash
+ */
+export function computeEntryHash(entry) {
+    const sortedKeys = Object.keys(entry.data).sort();
+    const canonicalData = JSON.stringify(entry.data, sortedKeys);
+    const canonical = entry.timestamp +
+        entry.event +
+        entry.deliberationId +
+        canonicalData +
+        entry.prevHash;
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Verify the integrity of a hash chain of audit log entries.
+ *
+ * Checks:
+ * 1. Each entry's hash matches recomputation from its fields.
+ * 2. Each entry's prevHash matches the previous entry's hash.
+ * 3. The first entry's prevHash is the empty string.
+ */
+export function verifyChain(entries) {
+    if (entries.length === 0) {
+        return { valid: true };
+    }
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        // Verify the hash matches recomputation
+        const expectedHash = computeEntryHash({
+            timestamp: entry.timestamp,
+            event: entry.event,
+            deliberationId: entry.deliberationId,
+            data: entry.data,
+            prevHash: entry.prevHash,
+        });
+        const hashBuf = Buffer.from(entry.hash, 'hex');
+        const expectedBuf = Buffer.from(expectedHash, 'hex');
+        if (hashBuf.length !== expectedBuf.length || !timingSafeEqual(hashBuf, expectedBuf)) {
+            return {
+                valid: false,
+                brokenAt: i,
+                error: `Entry ${i}: hash mismatch (expected ${expectedHash}, got ${entry.hash})`,
+            };
+        }
+        // Verify prevHash chain
+        if (i === 0) {
+            if (entry.prevHash !== '') {
+                return {
+                    valid: false,
+                    brokenAt: i,
+                    error: `Entry 0: prevHash should be empty string, got "${entry.prevHash}"`,
+                };
+            }
+        }
+        else {
+            const prevEntry = entries[i - 1];
+            if (entry.prevHash !== prevEntry.hash) {
+                return {
+                    valid: false,
+                    brokenAt: i,
+                    error: `Entry ${i}: prevHash does not match previous entry's hash`,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}

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

@@ -0,0 +1,25 @@
+/** Audit event types for MAGI deliberation lifecycle */
+export type AuditEvent = 'deliberation.start' | 'deliberation.complete' | 'deliberation.cache_hit' | 'phase.start' | 'phase.complete' | 'phase.timeout' | 'adapter.success' | 'adapter.failure' | 'validation.clamp' | 'validation.failure' | 'objective.complete' | 'human.resolve' | 'syncrate.update' | 'bias.detected' | 'gospel.milestone' | 'umbilical.status_change' | 'dummyplug.activate' | 'dummyplug.recovery' | 'cipher.discovered' | 'berserk.activated' | 'berserk.deactivated' | 'berserk.adapter_failure' | 'instrumentality.resolve' | 'engram.record' | 'drift.warning' | 'lcl.contamination' | 'nebuchadnezzar.override' | 'angel.detected' | 'scrolls.prophecy' | 'scrolls.fulfilled' | 'selfdestruct.motion' | 'selfdestruct.executed' | 'selfdestruct.aborted' | 'firewall.scan' | 'firewall.blocked' | 'firewall.scan_berserk' | 'firewall.blocked_berserk';
+/** A single audit log entry */
+export interface AuditLogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Event type */
+    event: AuditEvent;
+    /** Deliberation ID */
+    deliberationId: string;
+    /** Event-specific data */
+    data: Record<string, unknown>;
+    /** SHA-256 hash of this entry (computed from timestamp + event + deliberationId + data + prevHash) */
+    hash: string;
+    /** Hash of the previous entry in the chain (empty string for first entry) */
+    prevHash: string;
+}
+export interface AuditLogConfig {
+    /** Directory for audit log files */
+    logDir: string;
+    /** Max file size before rotation (bytes). Default: 10MB */
+    maxFileSize?: number;
+    /** Max number of rotated files to keep. Default: 5 */
+    maxFiles?: number;
+}

package/dist/src/audit/types.js

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

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

@@ -0,0 +1,18 @@
+import type { AuditEvent, AuditLogConfig, AuditLogEntry } from './types.js';
+export declare class AuditLogWriter {
+    private readonly config;
+    private lastHash;
+    private currentFile;
+    private currentSize;
+    private writeQueue;
+    constructor(config: AuditLogConfig);
+    /** Initialize: create log directory with 0o700, set current file, recover lastHash from existing log */
+    initialize(): Promise<void>;
+    /** Write a single entry, auto-rotate if needed. Serializes concurrent calls. */
+    write(event: AuditEvent, deliberationId: string, data: Record<string, unknown>): Promise<AuditLogEntry>;
+    /** Get the current log file path */
+    get logFile(): string;
+    private writeEntry;
+    /** Rotate: rename current to timestamped, clean old files beyond maxFiles */
+    private rotate;
+}