dual-brain 0.2.30 → 0.3.0

package/dist/src/models.js

@@ -0,0 +1,327 @@
+/**
+ * models.ts — Static model intelligence registry for the Dual-Brain Orchestrator.
+ *
+ * Pure in-memory registry of AI model capabilities used by routing modules.
+ * No file I/O, no API calls. Updated with each package release.
+ */
+export const REGISTRY_VERSION = '2026-05-15';
+export const REGISTRY_UPDATED = '2026-05-15';
+export const MODEL_REGISTRY = Object.freeze({
+    'claude-opus-4-6': {
+        provider: 'anthropic',
+        name: 'Claude Opus 4.6',
+        tier: 'frontier',
+        contextWindow: 200000,
+        maxOutput: 32000,
+        strengths: ['complex reasoning', 'architecture', 'code review', 'long context', 'multi-step planning'],
+        weaknesses: ['speed', 'cost'],
+        costTier: 'high',
+        bestFor: ['think', 'review', 'architecture', 'complex debugging'],
+        speed: 'slow',
+        reasoning: true,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'claude-sonnet-4-6': {
+        provider: 'anthropic',
+        name: 'Claude Sonnet 4.6',
+        tier: 'workhorse',
+        contextWindow: 200000,
+        maxOutput: 16000,
+        strengths: ['balanced speed/quality', 'code generation', 'editing', 'testing'],
+        weaknesses: ['less depth on architecture decisions'],
+        costTier: 'medium',
+        bestFor: ['execute', 'implement', 'test', 'fix'],
+        speed: 'medium',
+        reasoning: true,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'claude-haiku-4-5-20251001': {
+        provider: 'anthropic',
+        name: 'Claude Haiku 4.5',
+        tier: 'fast',
+        contextWindow: 200000,
+        maxOutput: 8192,
+        strengths: ['speed', 'low cost', 'simple tasks', 'search', 'classification'],
+        weaknesses: ['complex reasoning', 'multi-step tasks'],
+        costTier: 'low',
+        bestFor: ['search', 'classify', 'simple edits', 'grep'],
+        speed: 'fast',
+        reasoning: false,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'gpt-5.5': {
+        provider: 'openai',
+        name: 'GPT-5.5',
+        tier: 'frontier',
+        contextWindow: 1050000,
+        maxOutput: 128000,
+        strengths: ['massive context', 'complex professional work', 'reasoning', 'web search', 'code interpreter'],
+        weaknesses: ['cost', 'latency on complex reasoning'],
+        costTier: 'premium',
+        bestFor: ['think', 'review', 'research', 'long-context analysis'],
+        speed: 'medium',
+        reasoning: true,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'o3': {
+        provider: 'openai',
+        name: 'o3',
+        tier: 'reasoning',
+        contextWindow: 200000,
+        maxOutput: 100000,
+        strengths: ['deep reasoning', 'math', 'code', 'science', 'multi-step logic'],
+        weaknesses: ['speed', 'cost', 'simple tasks overkill'],
+        costTier: 'premium',
+        bestFor: ['think', 'complex debugging', 'algorithm design', 'security analysis'],
+        speed: 'slow',
+        reasoning: true,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'gpt-4o': {
+        provider: 'openai',
+        name: 'GPT-4o',
+        tier: 'workhorse',
+        contextWindow: 128000,
+        maxOutput: 16384,
+        strengths: ['balanced', 'fast', 'multimodal', 'tool use'],
+        weaknesses: ['less depth than frontier models'],
+        costTier: 'medium',
+        bestFor: ['execute', 'implement', 'chat', 'multimodal'],
+        speed: 'fast',
+        reasoning: false,
+        vision: true,
+        tools: true,
+        agentCapable: true,
+    },
+    'gpt-4o-mini': {
+        provider: 'openai',
+        name: 'GPT-4o Mini',
+        tier: 'fast',
+        contextWindow: 128000,
+        maxOutput: 16384,
+        strengths: ['very fast', 'very cheap', 'good enough for simple tasks'],
+        weaknesses: ['complex reasoning', 'nuanced code review'],
+        costTier: 'low',
+        bestFor: ['search', 'classify', 'simple tasks', 'formatting'],
+        speed: 'fast',
+        reasoning: false,
+        vision: true,
+        tools: true,
+        agentCapable: false,
+    },
+});
+const COST_TIER_ORDER = ['low', 'medium', 'high', 'premium'];
+const SPEED_ORDER = ['fast', 'medium', 'slow'];
+const TIER_ORDER = ['fast', 'workhorse', 'reasoning', 'frontier'];
+const MODEL_QUIRKS = {
+    'claude-opus-4-6': [
+        'Best for architecture decisions',
+        'Use for code review when quality matters',
+        'Expensive — reserve for high-value tasks',
+    ],
+    'claude-sonnet-4-6': [
+        'Best general-purpose worker',
+        'Good balance of speed and quality',
+        'Use Agent(model: "sonnet") for work dispatch',
+    ],
+    'claude-haiku-4-5-20251001': [
+        'Best for fast search and classification',
+        'Not reliable for multi-step edits',
+        'Use for disposable search agents',
+    ],
+    'gpt-5.5': [
+        'Massive 1M+ context window',
+        'Good challenger for dual-brain think',
+        'Web search and code interpreter available',
+    ],
+    'o3': [
+        'Purpose-built for deep reasoning chains',
+        'Strong challenger for security analysis',
+        'Slow — avoid for quick tasks',
+    ],
+    'gpt-4o': [
+        'Fast and multimodal',
+        'Solid fallback for execute-tier GPT work',
+        'Native tool use support',
+    ],
+    'gpt-4o-mini': [
+        'Cheapest GPT option for simple tasks',
+        'Not agent-capable — single-shot only',
+        'Good for classification and formatting',
+    ],
+};
+export function getModel(modelId) {
+    return MODEL_REGISTRY[modelId] ?? null;
+}
+export function getModelsForTask(taskType, provider = null) {
+    const entries = Object.entries(MODEL_REGISTRY);
+    const filtered = entries.filter(([, m]) => {
+        if (provider && m.provider !== provider)
+            return false;
+        return true;
+    });
+    filtered.sort(([, a], [, b]) => {
+        const aMatch = a.bestFor.includes(taskType) ? 1 : 0;
+        const bMatch = b.bestFor.includes(taskType) ? 1 : 0;
+        if (bMatch !== aMatch)
+            return bMatch - aMatch;
+        const aTier = TIER_ORDER.indexOf(a.tier);
+        const bTier = TIER_ORDER.indexOf(b.tier);
+        if (bTier !== aTier)
+            return bTier - aTier;
+        return SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed);
+    });
+    return filtered.map(([id, m]) => ({ id, ...m }));
+}
+export function getBestModel(taskType, constraints = {}) {
+    const { provider = null, maxCost = null, preferSpeed = false, requireReasoning = false, minContext = 0 } = constraints;
+    let candidates = getModelsForTask(taskType, provider);
+    if (requireReasoning) {
+        candidates = candidates.filter(m => m.reasoning);
+    }
+    if (minContext > 0) {
+        candidates = candidates.filter(m => m.contextWindow >= minContext);
+    }
+    if (maxCost) {
+        const maxIdx = COST_TIER_ORDER.indexOf(maxCost);
+        if (maxIdx !== -1) {
+            candidates = candidates.filter(m => COST_TIER_ORDER.indexOf(m.costTier) <= maxIdx);
+        }
+    }
+    if (preferSpeed) {
+        candidates.sort((a, b) => SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed));
+    }
+    return candidates[0] ?? null;
+}
+export function compareModels(modelA, modelB) {
+    const a = MODEL_REGISTRY[modelA];
+    const b = MODEL_REGISTRY[modelB];
+    if (!a || !b) {
+        return {
+            contextAdvantage: 'tie',
+            speedAdvantage: 'tie',
+            costAdvantage: 'tie',
+            reasoningAdvantage: 'tie',
+            recommendation: 'One or both model IDs are unknown.',
+        };
+    }
+    const ctxAdv = a.contextWindow > b.contextWindow ? 'a'
+        : b.contextWindow > a.contextWindow ? 'b'
+            : 'tie';
+    const spdA = SPEED_ORDER.indexOf(a.speed);
+    const spdB = SPEED_ORDER.indexOf(b.speed);
+    const spdAdv = spdA < spdB ? 'a' : spdB < spdA ? 'b' : 'tie';
+    const costA = COST_TIER_ORDER.indexOf(a.costTier);
+    const costB = COST_TIER_ORDER.indexOf(b.costTier);
+    const costAdv = costA < costB ? 'a' : costB < costA ? 'b' : 'tie';
+    const rsnAdv = (a.reasoning && !b.reasoning) ? 'a'
+        : (b.reasoning && !a.reasoning) ? 'b'
+            : 'tie';
+    const aAdvantages = [ctxAdv, spdAdv, costAdv, rsnAdv].filter(v => v === 'a').length;
+    const bAdvantages = [ctxAdv, spdAdv, costAdv, rsnAdv].filter(v => v === 'b').length;
+    let recommendation;
+    if (aAdvantages > bAdvantages) {
+        recommendation = `Use ${a.name} for ${a.bestFor.slice(0, 2).join('/')}; ${b.name} as a lighter alternative.`;
+    }
+    else if (bAdvantages > aAdvantages) {
+        recommendation = `Use ${b.name} for ${b.bestFor.slice(0, 2).join('/')}; ${a.name} as a lighter alternative.`;
+    }
+    else {
+        recommendation = `${a.name} and ${b.name} are comparable — choose based on provider availability.`;
+    }
+    return { contextAdvantage: ctxAdv, speedAdvantage: spdAdv, costAdvantage: costAdv, reasoningAdvantage: rsnAdv, recommendation };
+}
+export function getRegistryAge() {
+    const updated = new Date(REGISTRY_UPDATED);
+    const now = new Date();
+    return Math.floor((now.getTime() - updated.getTime()) / (1000 * 60 * 60 * 24));
+}
+const COST_SYMBOL = { low: '$', medium: '$$', high: '$$$', premium: '$$$$' };
+function fmtCtx(n) {
+    if (n >= 1000000)
+        return `${(n / 1000000).toFixed(2)}M ctx`;
+    return `${Math.round(n / 1000)}K ctx`;
+}
+export function formatModelTable(provider = null) {
+    const groups = {};
+    for (const [id, m] of Object.entries(MODEL_REGISTRY)) {
+        if (provider && m.provider !== provider)
+            continue;
+        if (!groups[m.provider])
+            groups[m.provider] = [];
+        groups[m.provider].push({ id, ...m });
+    }
+    const lines = [];
+    const providerLabels = { anthropic: 'Claude Models', openai: 'OpenAI Models' };
+    const providerOrder = ['anthropic', 'openai'];
+    for (const prov of providerOrder) {
+        if (!groups[prov])
+            continue;
+        lines.push(`${providerLabels[prov] ?? prov}:`);
+        for (const m of groups[prov]) {
+            const displayName = m.provider === 'anthropic' ? m.name.replace(/^Claude /, '') : m.name;
+            const name = displayName.padEnd(12);
+            const tier = m.tier.padEnd(10);
+            const ctx = fmtCtx(m.contextWindow).padEnd(10);
+            const speed = m.speed.padEnd(8);
+            const cost = (COST_SYMBOL[m.costTier] ?? '?').padEnd(6);
+            const tasks = m.bestFor.slice(0, 2).join('/');
+            lines.push(`  ${name}${tier}${ctx}${speed}${cost}${tasks}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+export function getModelQuirks(modelId) {
+    return MODEL_QUIRKS[modelId] ?? [];
+}
+export function suggestModel(intent, risk, complexity, availableProviders = ['anthropic', 'openai']) {
+    const intentLower = (intent || '').toLowerCase();
+    const TASK_MAP = {
+        think: ['architect', 'design', 'plan', 'review', 'security', 'audit', 'analysis', 'analyze'],
+        execute: ['implement', 'edit', 'fix', 'refactor', 'test', 'build', 'write', 'update', 'create'],
+        search: ['search', 'find', 'grep', 'look', 'explore', 'classify', 'format', 'list'],
+    };
+    let taskType = 'execute';
+    for (const [type, keywords] of Object.entries(TASK_MAP)) {
+        if (keywords.some(kw => intentLower.includes(kw))) {
+            taskType = type;
+            break;
+        }
+    }
+    if ((risk === 'critical' || risk === 'high') && taskType !== 'think') {
+        taskType = 'think';
+    }
+    const requireReasoning = complexity === 'complex' || risk === 'critical';
+    const preferSpeed = risk === 'low' && complexity === 'simple';
+    const maxCost = risk === 'low' && complexity !== 'complex' ? 'medium' : null;
+    const candidates = getModelsForTask(taskType)
+        .filter(m => availableProviders.includes(m.provider))
+        .filter(m => !requireReasoning || m.reasoning)
+        .filter(m => !maxCost || COST_TIER_ORDER.indexOf(m.costTier) <= COST_TIER_ORDER.indexOf(maxCost));
+    if (preferSpeed) {
+        candidates.sort((a, b) => SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed));
+    }
+    const best = candidates[0] ?? null;
+    if (!best) {
+        return { model: null, reason: 'No suitable model found for the given constraints.', alternatives: [] };
+    }
+    const reason = [
+        `Selected ${best.name} for ${taskType}-tier work`,
+        risk !== 'low' ? `(${risk} risk)` : null,
+        requireReasoning ? '— reasoning required' : null,
+    ].filter(Boolean).join(' ');
+    const alternatives = candidates.slice(1, 3).map(m => ({ id: m.id, name: m.name }));
+    return { model: best.id, reason, alternatives };
+}
+//# sourceMappingURL=models.js.map

package/dist/src/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/models.ts"],"names":[],"mappings":"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"}

package/dist/src/narrative.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Load the current running narrative. Returns empty string if none exists.
+ * This is meant to be injected at the top of HEAD's context each turn.
+ */
+export declare function load(): string;
+/**
+ * Write a new narrative, replacing the old one.
+ * The old narrative is archived to history before overwrite.
+ *
+ * @param {string} prose - HEAD's current understanding in prose form.
+ *   Should answer: Where are we? What just happened? What's brewing?
+ *   What did the user care about? What should I not forget?
+ */
+export declare function write(prose: string): void;
+/**
+ * Evolve the narrative — append new observations without replacing everything.
+ * Used after dispatches return, after user says something illuminating,
+ * or after a wave completes.
+ *
+ * @param {string} addition - New prose to weave into the narrative.
+ * @param {object} opts
+ * @param {boolean} opts.replace - If true, replace entirely instead of appending.
+ */
+export declare function evolve(addition: string, { replace }?: {
+    replace?: boolean;
+}): void;
+/**
+ * Generate a narrative excerpt suitable for a dispatch envelope.
+ * Shorter than the full narrative — just enough context for a worker
+ * to understand the "why" without the full stream of consciousness.
+ *
+ * @param {number} maxLength - Max chars for the excerpt (default 500)
+ * @returns {string}
+ */
+export declare function excerpt(maxLength?: number): string;
+/**
+ * Get recent narrative history entries (for warm memory tier).
+ * @param {number} n - Number of recent entries to retrieve
+ * @returns {Array<{ts: number, text: string}>}
+ */
+export declare function recentHistory(n?: number): Array<{
+    ts: number;
+    text: string;
+}>;
+/**
+ * Persist the current narrative for precompact survival.
+ * Called by the precompact hook before context compression.
+ * Returns the narrative that was persisted (for confirmation).
+ */
+export declare function persist(): string;
+/**
+ * Clear the narrative (used in testing or session reset).
+ */
+export declare function clear(): void;

package/dist/src/narrative.js

@@ -0,0 +1,163 @@
+// narrative.ts — HEAD's running narrative: prose it writes to itself between turns.
+// Not structured data. A paragraph or two that captures where we are, what just
+// happened, what's brewing. Loaded at the top of each turn so HEAD is immediately
+// "in the song" without reconstructing from scattered JSON.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+const STATE_DIR = join(process.cwd(), '.dualbrain');
+const NARRATIVE_FILE = join(STATE_DIR, 'narrative.md');
+const NARRATIVE_HISTORY = join(STATE_DIR, 'narrative-history.jsonl');
+const MAX_NARRATIVE_LENGTH = 2000;
+const MAX_HISTORY_ENTRIES = 20;
+/**
+ * Load the current running narrative. Returns empty string if none exists.
+ * This is meant to be injected at the top of HEAD's context each turn.
+ */
+export function load() {
+    try {
+        if (existsSync(NARRATIVE_FILE)) {
+            return readFileSync(NARRATIVE_FILE, 'utf8').trim();
+        }
+    }
+    catch { }
+    return '';
+}
+/**
+ * Write a new narrative, replacing the old one.
+ * The old narrative is archived to history before overwrite.
+ *
+ * @param {string} prose - HEAD's current understanding in prose form.
+ *   Should answer: Where are we? What just happened? What's brewing?
+ *   What did the user care about? What should I not forget?
+ */
+export function write(prose) {
+    if (!prose || typeof prose !== 'string')
+        return;
+    const trimmed = prose.slice(0, MAX_NARRATIVE_LENGTH).trim();
+    if (!trimmed)
+        return;
+    mkdirSync(STATE_DIR, { recursive: true });
+    // Archive current before overwriting
+    const current = load();
+    if (current) {
+        _appendHistory(current);
+    }
+    writeFileSync(NARRATIVE_FILE, trimmed + '\n');
+}
+/**
+ * Evolve the narrative — append new observations without replacing everything.
+ * Used after dispatches return, after user says something illuminating,
+ * or after a wave completes.
+ *
+ * @param {string} addition - New prose to weave into the narrative.
+ * @param {object} opts
+ * @param {boolean} opts.replace - If true, replace entirely instead of appending.
+ */
+export function evolve(addition, { replace = false } = {}) {
+    if (!addition || typeof addition !== 'string')
+        return;
+    if (replace) {
+        write(addition);
+        return;
+    }
+    const current = load();
+    const combined = current
+        ? current + '\n\n' + addition.trim()
+        : addition.trim();
+    // If too long, keep the newest portion (recency bias for immersion)
+    const final = combined.length > MAX_NARRATIVE_LENGTH
+        ? combined.slice(-MAX_NARRATIVE_LENGTH)
+        : combined;
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(NARRATIVE_FILE, final.trim() + '\n');
+}
+/**
+ * Generate a narrative excerpt suitable for a dispatch envelope.
+ * Shorter than the full narrative — just enough context for a worker
+ * to understand the "why" without the full stream of consciousness.
+ *
+ * @param {number} maxLength - Max chars for the excerpt (default 500)
+ * @returns {string}
+ */
+export function excerpt(maxLength = 500) {
+    const full = load();
+    if (!full)
+        return '';
+    if (full.length <= maxLength)
+        return full;
+    // Take the last N chars — most recent context is most relevant for workers
+    const trimmed = full.slice(-maxLength);
+    // Find the first sentence boundary to avoid mid-thought cuts
+    const firstPeriod = trimmed.indexOf('. ');
+    if (firstPeriod > 0 && firstPeriod < maxLength * 0.4) {
+        return trimmed.slice(firstPeriod + 2);
+    }
+    return trimmed;
+}
+/**
+ * Get recent narrative history entries (for warm memory tier).
+ * @param {number} n - Number of recent entries to retrieve
+ * @returns {Array<{ts: number, text: string}>}
+ */
+export function recentHistory(n = 5) {
+    try {
+        if (!existsSync(NARRATIVE_HISTORY))
+            return [];
+        const lines = readFileSync(NARRATIVE_HISTORY, 'utf8').trim().split('\n').filter(Boolean);
+        return lines.slice(-n).map(line => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        }).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Persist the current narrative for precompact survival.
+ * Called by the precompact hook before context compression.
+ * Returns the narrative that was persisted (for confirmation).
+ */
+export function persist() {
+    const current = load();
+    if (!current)
+        return '';
+    // Narrative is already on disk — this just ensures it's fresh
+    // and archives a snapshot with explicit "precompact" marker
+    _appendHistory(current, { reason: 'precompact' });
+    return current;
+}
+/**
+ * Clear the narrative (used in testing or session reset).
+ */
+export function clear() {
+    try {
+        if (existsSync(NARRATIVE_FILE)) {
+            writeFileSync(NARRATIVE_FILE, '');
+        }
+    }
+    catch { }
+}
+// ── Internal ──────────────────────────────────────────────────────────────────
+function _appendHistory(text, meta = {}) {
+    try {
+        const entry = JSON.stringify({ ts: Date.now(), text: text.slice(0, 800), ...meta });
+        mkdirSync(STATE_DIR, { recursive: true });
+        // Cap history file
+        let existing = '';
+        if (existsSync(NARRATIVE_HISTORY)) {
+            existing = readFileSync(NARRATIVE_HISTORY, 'utf8');
+            const lines = existing.trim().split('\n').filter(Boolean);
+            if (lines.length >= MAX_HISTORY_ENTRIES) {
+                existing = lines.slice(-MAX_HISTORY_ENTRIES + 1).join('\n') + '\n';
+            }
+        }
+        writeFileSync(NARRATIVE_HISTORY, existing + entry + '\n');
+    }
+    catch { }
+}
+//# sourceMappingURL=narrative.js.map

package/dist/src/narrative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrative.js","sourceRoot":"","sources":["../../src/narrative.ts"],"names":[],"mappings":"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"}

package/dist/src/nextstep.d.ts

@@ -0,0 +1,16 @@
+export declare function suggestNextSteps(completedTask?: Record<string, unknown>, outcome?: Record<string, unknown>, cwd?: string): Promise<{
+    steps: {
+        priority: number;
+        type: string;
+        message: string;
+        command: string | null;
+        reason: string;
+    }[];
+    topSuggestion: string;
+}>;
+export declare function formatNextSteps(steps: Array<{
+    message: string;
+}> | undefined, limit?: number): string;
+export declare function getTopSuggestion(steps: Array<{
+    message: string;
+}> | undefined): string;