dual-brain 0.2.30 → 0.3.0

package/dist/src/strategy.js

@@ -0,0 +1,95 @@
+// strategy.ts — Dispatch strategy library + selection
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const STRATEGIES = {
+    direct: { id: 'direct', label: 'Direct dispatch', description: 'Single agent, single task. Best for clear, focused work.', applicability: { maxFiles: 3, maxComplexity: 'moderate', maxRisk: 'medium' }, cost: 1.0 },
+    cascade: { id: 'cascade', label: 'Think → Execute cascade', description: 'Cheap thinker refines spec, then worker executes. Best for routine-but-multi-step tasks.', applicability: { minFiles: 1, minComplexity: 'moderate', maxRisk: 'high' }, cost: 1.3 },
+    split: { id: 'split', label: 'Decompose → parallel dispatch', description: 'Break into sub-tasks, dispatch each at optimal tier. Best for large multi-file changes.', applicability: { minFiles: 4, minComplexity: 'complex' }, cost: 2.0 },
+    'dual-review': { id: 'dual-review', label: 'Execute → adversarial review', description: 'Worker implements, second model reviews. Best for high-risk/security code.', applicability: { minRisk: 'high' }, cost: 1.5 },
+    'architect-editor': { id: 'architect-editor', label: 'Architect reasons → editor implements', description: 'Opus/o3 reasons freely, sonnet/haiku formats the edits. Best for complex architecture + implementation.', applicability: { minComplexity: 'complex', minFiles: 3 }, cost: 1.8 },
+};
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+const COMPLEXITY_RANK = { trivial: 0, simple: 1, moderate: 2, complex: 3 };
+const RISK_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+const COST_CAPS = {
+    frugal: 1.0, 'cost-saver': 1.3, balanced: 2.0, 'quality-first': 3.0, maximum: Infinity, aggressive: Infinity, fullpower: Infinity, fast: 1.3,
+};
+const SECURITY_KEYWORDS = /\b(auth|security|billing|payment|credential|secret|token|encrypt|permission|oauth|jwt)\b/i;
+function costCap(workStyle) { return COST_CAPS[workStyle] ?? 2.0; }
+function fileCount(detection) { return detection?.fileCount ?? detection?.files ?? 0; }
+function complexityRank(detection) { return COMPLEXITY_RANK[detection?.complexity ?? ''] ?? 1; }
+function riskRank(detection) { return RISK_RANK[detection?.risk ?? ''] ?? 0; }
+function prompt(detection) { return detection?.prompt ?? detection?.description ?? ''; }
+// ─── Scoring ───────────────────────────────────────────────────────────────────
+function scoreStrategies(detection, workStyle) {
+    const files = fileCount(detection);
+    const cRank = complexityRank(detection);
+    const rRank = riskRank(detection);
+    const text = prompt(detection);
+    const frugal = workStyle === 'frugal';
+    const saver = workStyle === 'cost-saver' || workStyle === 'fast';
+    return {
+        direct: 0.5,
+        cascade: 0 + (cRank >= COMPLEXITY_RANK.moderate ? 0.3 : 0) + (files >= 2 ? 0.2 : 0) - (frugal ? 0.5 : 0),
+        split: 0 + (files >= 4 ? 0.4 : 0) + (cRank >= COMPLEXITY_RANK.complex ? 0.3 : 0) - (frugal || saver ? 0.5 : 0),
+        'dual-review': 0 + (rRank >= RISK_RANK.high ? 0.5 : 0) + (SECURITY_KEYWORDS.test(text) ? 0.3 : 0) - (frugal ? 0.3 : 0),
+        'architect-editor': 0 + (cRank >= COMPLEXITY_RANK.complex && files >= 3 ? 0.4 : 0) - (saver ? 0.3 : 0),
+    };
+}
+export function selectStrategy(detection, decision, profile) {
+    try {
+        const workStyle = profile?.workStyle ?? profile?.bias ?? 'balanced';
+        const cap = costCap(workStyle);
+        const scores = scoreStrategies(detection, workStyle);
+        const ranked = Object.entries(scores).filter(([id]) => STRATEGIES[id].cost <= cap).sort(([, a], [, b]) => b - a);
+        if (!ranked.length)
+            return { strategy: 'direct', reason: 'Cost cap allows only direct dispatch.', alternatives: [] };
+        const [bestId] = ranked[0];
+        const alternatives = ranked.slice(1).map(([id]) => id);
+        const reasons = {
+            direct: 'Clear, focused task within single-agent scope.',
+            cascade: 'Multi-step task benefits from spec refinement before execution.',
+            split: 'Large file count warrants decomposition into parallel sub-tasks.',
+            'dual-review': 'High-risk or security-sensitive work requires adversarial review.',
+            'architect-editor': 'Complex architecture + implementation benefits from dual-model reasoning.',
+        };
+        return { strategy: bestId, reason: reasons[bestId] ?? 'Best match for task profile.', alternatives };
+    }
+    catch {
+        return { strategy: 'direct', reason: 'Fallback to direct dispatch.', alternatives: [] };
+    }
+}
+export function describeStrategy(strategyId) {
+    const s = STRATEGIES[strategyId];
+    if (!s)
+        return `Unknown strategy: ${strategyId}`;
+    return `${s.label} (cost ×${s.cost})\n${s.description}`;
+}
+export function getStrategyForTask(detection, cwd) {
+    const dir = cwd ?? process.cwd();
+    let profile = {};
+    try {
+        const p = join(dir, '.dualbrain', 'config.json');
+        if (existsSync(p))
+            profile = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch { }
+    const decision = { model: profile?.models?.execute ?? 'sonnet' };
+    const selected = selectStrategy(detection, decision, profile);
+    return { ...selected, plan: buildPlan(selected.strategy, decision) };
+}
+function buildPlan(strategyId, decision) {
+    const m = decision?.model ?? 'sonnet';
+    const plans = {
+        direct: [{ role: 'worker', model: m, description: 'Execute task' }],
+        cascade: [{ role: 'thinker', model: 'sonnet', description: 'Refine spec' }, { role: 'worker', model: 'from-think', description: 'Execute refined spec' }],
+        split: [{ role: 'thinker', model: 'sonnet', description: 'Decompose into sub-tasks' }, { role: 'worker', model: 'varies', description: 'Execute each sub-task' }],
+        'dual-review': [{ role: 'worker', model: m, description: 'Implement' }, { role: 'reviewer', model: 'sonnet', description: 'Adversarial review' }],
+        'architect-editor': [{ role: 'thinker', model: 'opus', description: 'Architect solution' }, { role: 'worker', model: 'haiku', description: 'Format edits' }],
+    };
+    return { steps: plans[strategyId] ?? plans.direct };
+}
+export function listStrategies() {
+    return Object.values(STRATEGIES).map(({ id, label, description, cost }) => ({ id, label, description, cost }));
+}
+//# sourceMappingURL=strategy.js.map

package/dist/src/strategy.js.map

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

package/dist/src/subscription.d.ts

@@ -0,0 +1,40 @@
+interface SubscriptionConfig {
+    label: string;
+    provider: string;
+    tokenBudget: string;
+    recommendedProfile: string;
+    modelWeights: Record<string, number>;
+    notes: string;
+}
+export declare const SUBSCRIPTIONS: Record<string, SubscriptionConfig>;
+interface DefaultWeights {
+    modelWeights: Record<string, number>;
+    profile: string;
+    notes: string;
+}
+/** Returns the subscription config object or null. */
+export declare function getSubscription(subType: string): SubscriptionConfig | null;
+/** Returns { modelWeights, profile, notes } for the subscription. Falls back to balanced defaults. */
+export declare function getRecommendedWeights(subType: string): DefaultWeights;
+/** Writes { subscription, configuredAt } to .dualbrain/subscription.json. */
+export declare function saveUserSubscription(subType: string, cwd: string | undefined): void;
+/** Reads the saved subscription. Returns subType string or null. */
+export declare function loadUserSubscription(cwd: string | undefined): string | null;
+interface RoutingStatsInput {
+    cells?: Record<string, Record<string, {
+        observations?: number;
+    }>>;
+}
+/**
+ * Generates a text recommendation based on subscription + current routing stats.
+ * routingStats: return value of getRoutingStats() from routing-advisor.mjs
+ */
+export declare function generateRecommendation(subType: string, routingStats: RoutingStatsInput | null | undefined): string;
+interface SubscriptionListEntry {
+    key: string;
+    label: string;
+    provider: string;
+}
+/** Returns array of { key, label, provider } for display in UX. */
+export declare function listSubscriptions(): SubscriptionListEntry[];
+export {};

package/dist/src/subscription.js

@@ -0,0 +1,189 @@
+// subscription.ts — Subscription-aware routing defaults
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const SUBSCRIPTIONS = {
+    // Claude subscriptions
+    'claude-pro': {
+        label: 'Claude Pro ($20/mo)',
+        provider: 'claude',
+        tokenBudget: 'moderate', // 5-hr rolling window, weekly cap
+        recommendedProfile: 'balanced',
+        modelWeights: { haiku: 0.4, sonnet: 0.5, opus: 0.1 },
+        notes: 'One extended Opus session can use 20% of your allocation. Prefer sonnet for routine work.',
+    },
+    'claude-max-5x': {
+        label: 'Claude Max 5x ($100/mo)',
+        provider: 'claude',
+        tokenBudget: 'generous',
+        recommendedProfile: 'quality-first',
+        modelWeights: { haiku: 0.2, sonnet: 0.5, opus: 0.3 },
+        notes: '5x Pro capacity. Opus is available for complex/creative work without worry.',
+    },
+    'claude-max-20x': {
+        label: 'Claude Max 20x ($200/mo)',
+        provider: 'claude',
+        tokenBudget: 'unlimited',
+        recommendedProfile: 'quality-first',
+        modelWeights: { haiku: 0.1, sonnet: 0.4, opus: 0.5 },
+        notes: 'Effectively unlimited. Use the best model for every task.',
+    },
+    'claude-team': {
+        label: 'Claude Team ($30/seat/mo)',
+        provider: 'claude',
+        tokenBudget: 'moderate',
+        recommendedProfile: 'balanced',
+        modelWeights: { haiku: 0.3, sonnet: 0.5, opus: 0.2 },
+        notes: 'Team tier with admin controls. Collaboration triggers recommended.',
+    },
+    // ChatGPT subscriptions
+    'chatgpt-plus': {
+        label: 'ChatGPT Plus ($20/mo)',
+        provider: 'openai',
+        tokenBudget: 'limited', // 50 o3/day on Plus
+        recommendedProfile: 'cost-saver',
+        modelWeights: { 'o4-mini': 0.6, 'gpt-4.1': 0.3, 'o3': 0.1 },
+        notes: '50 o3 messages/day limit. Heavy on o4-mini for routine, save o3 for critical decisions.',
+    },
+    'chatgpt-pro': {
+        label: 'ChatGPT Pro ($200/mo)',
+        provider: 'openai',
+        tokenBudget: 'generous',
+        recommendedProfile: 'quality-first',
+        modelWeights: { 'o4-mini': 0.3, 'gpt-4.1': 0.4, 'o3': 0.3 },
+        notes: 'Unlimited access to all models. Use o3 freely for complex reasoning.',
+    },
+    // Dual subscription (both providers)
+    'dual-pro': {
+        label: 'Both Pro tiers',
+        provider: 'both',
+        tokenBudget: 'moderate',
+        recommendedProfile: 'balanced',
+        modelWeights: { haiku: 0.2, sonnet: 0.3, 'gpt-4.1': 0.3, 'o4-mini': 0.2 },
+        notes: 'Split load across providers. Route by model strength: Claude for code, GPT for reasoning.',
+    },
+    'dual-max': {
+        label: 'Max + Pro (or both Max)',
+        provider: 'both',
+        tokenBudget: 'unlimited',
+        recommendedProfile: 'quality-first',
+        modelWeights: { sonnet: 0.3, opus: 0.2, 'gpt-4.1': 0.2, 'o3': 0.3 },
+        notes: 'Full power from both providers. Route by task fit, not by cost.',
+    },
+};
+const DEFAULT_WEIGHTS = {
+    modelWeights: { haiku: 0.3, sonnet: 0.5, opus: 0.2 },
+    profile: 'balanced',
+    notes: 'No subscription configured. Using balanced defaults.',
+};
+function subFile(cwd) {
+    return join(cwd || process.cwd(), '.dualbrain', 'subscription.json');
+}
+/** Returns the subscription config object or null. */
+export function getSubscription(subType) {
+    return SUBSCRIPTIONS[subType] ?? null;
+}
+/** Returns { modelWeights, profile, notes } for the subscription. Falls back to balanced defaults. */
+export function getRecommendedWeights(subType) {
+    const sub = SUBSCRIPTIONS[subType];
+    if (!sub)
+        return DEFAULT_WEIGHTS;
+    return {
+        modelWeights: sub.modelWeights,
+        profile: sub.recommendedProfile,
+        notes: sub.notes,
+    };
+}
+/** Writes { subscription, configuredAt } to .dualbrain/subscription.json. */
+export function saveUserSubscription(subType, cwd) {
+    const dir = join(cwd || process.cwd(), '.dualbrain');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(subFile(cwd), JSON.stringify({ subscription: subType, configuredAt: new Date().toISOString() }, null, 2), 'utf8');
+}
+/** Reads the saved subscription. Returns subType string or null. */
+export function loadUserSubscription(cwd) {
+    try {
+        const p = subFile(cwd);
+        if (!existsSync(p))
+            return null;
+        const data = JSON.parse(readFileSync(p, 'utf8'));
+        return data.subscription ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generates a text recommendation based on subscription + current routing stats.
+ * routingStats: return value of getRoutingStats() from routing-advisor.mjs
+ */
+export function generateRecommendation(subType, routingStats) {
+    const sub = SUBSCRIPTIONS[subType];
+    if (!sub)
+        return 'No subscription configured. Run `dual-brain subscription set <type>` to enable smart routing defaults.';
+    // Tally actual model usage from routing stats cells
+    const actualUsage = {};
+    let totalObs = 0;
+    for (const models of Object.values(routingStats?.cells ?? {})) {
+        for (const [model, entry] of Object.entries(models)) {
+            actualUsage[model] = (actualUsage[model] ?? 0) + (entry.observations ?? 0);
+            totalObs += entry.observations ?? 0;
+        }
+    }
+    if (totalObs === 0) {
+        return `You're on ${sub.label}. No routing history yet — recommended profile is ${sub.recommendedProfile}. ${sub.notes}`;
+    }
+    // Compute actual share per model
+    const actualShare = {};
+    for (const [model, count] of Object.entries(actualUsage)) {
+        actualShare[model] = count / totalObs;
+    }
+    const rec = sub.modelWeights;
+    const budget = sub.tokenBudget;
+    const lines = [];
+    // Check expensive model utilization vs. recommended
+    const expensiveModels = ['opus', 'o3'];
+    for (const model of expensiveModels) {
+        const recW = rec[model] ?? 0;
+        const actW = actualShare[model] ?? 0;
+        if (recW > 0 && budget === 'unlimited' && actW < recW * 0.5) {
+            lines.push(`You're on ${sub.label} but only using ${model} ${Math.round(actW * 100)}% of the time` +
+                ` (recommended: ${Math.round(recW * 100)}%). You're paying for capacity you're not using.` +
+                ` Consider switching to ${sub.recommendedProfile} mode.`);
+        }
+        else if (recW < 0.2 && budget === 'limited' && actW > recW * 2 && actW > 0.1) {
+            lines.push(`Your ${sub.label} subscription is token-limited. ${model} usage at ${Math.round(actW * 100)}%` +
+                ` may exhaust daily limits — recommended cap is ~${Math.round(recW * 100)}%.`);
+        }
+    }
+    // Cheap model suggestions on budget-constrained plans
+    const cheapModels = ['haiku', 'o4-mini'];
+    if (budget === 'moderate' || budget === 'limited') {
+        for (const model of cheapModels) {
+            const recW = rec[model] ?? 0;
+            const actW = actualShare[model] ?? 0;
+            if (recW > 0 && actW < recW * 0.5) {
+                lines.push(`Your ${sub.label} subscription has a ${budget} budget. Increasing ${model} usage` +
+                    ` (currently ${Math.round(actW * 100)}%, recommended ${Math.round(recW * 100)}%)` +
+                    ` for search and routine tasks would preserve your allocation.`);
+                break; // one cheap-model tip is enough
+            }
+        }
+    }
+    // Dominant model confirmation — find the most-used model
+    const topModel = Object.entries(actualShare).sort((a, b) => b[1] - a[1])[0];
+    if (lines.length === 0 && topModel) {
+        lines.push(`Your ${sub.label} subscription is well-matched. ${Math.round(topModel[1] * 100)}% of dispatches` +
+            ` use ${topModel[0]} — a good fit for your ${budget} budget. ${sub.notes}`);
+    }
+    return lines.slice(0, 3).join(' ');
+}
+/** Returns array of { key, label, provider } for display in UX. */
+export function listSubscriptions() {
+    return Object.entries(SUBSCRIPTIONS).map(([key, sub]) => ({
+        key,
+        label: sub.label,
+        provider: sub.provider,
+    }));
+}
+//# sourceMappingURL=subscription.js.map

package/dist/src/subscription.js.map

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

package/dist/src/templates.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Task contract — every dispatch must have one.
+ * @typedef {{
+ *   id: string,
+ *   objective: string,
+ *   scope: string[],
+ *   nonGoals?: string[],
+ *   risk: 'low'|'medium'|'high'|'critical',
+ *   acceptanceCriteria: string[],
+ *   allowedOperations?: string[],
+ *   context?: string,
+ *   files?: string[],
+ *   timeoutMs?: number,
+ * }} TaskContract
+ */
+interface TaskContract {
+    id?: string;
+    objective?: string;
+    scope?: string[];
+    nonGoals?: string[];
+    risk?: string;
+    acceptanceCriteria?: string[];
+    allowedOperations?: string[];
+    context?: string;
+    files?: string[];
+    timeoutMs?: number;
+    [key: string]: unknown;
+}
+type TemplateTier = 'search' | 'execute' | 'think' | 'review';
+interface QuickRenderOpts {
+    scope?: string[];
+    files?: string[];
+    risk?: string;
+    criteria?: string[];
+    nonGoals?: string[];
+    context?: string;
+}
+/**
+ * Validate a task contract has all required fields.
+ * Returns { valid, missing }
+ */
+export declare function validateContract(contract: TaskContract): {
+    valid: boolean;
+    missing: string[];
+    contract: {
+        id: string;
+        objective?: string;
+        scope?: string[];
+        nonGoals?: string[];
+        risk?: string;
+        acceptanceCriteria?: string[];
+        allowedOperations?: string[];
+        context?: string;
+        files?: string[];
+        timeoutMs?: number;
+    } | null;
+};
+/**
+ * Get the structured output schema for a tier.
+ */
+export declare function getOutputSchema(tier: TemplateTier): string | null;
+/**
+ * Get the preferred prompt rendering format for a given model ID.
+ */
+export declare function getRenderHint(modelId: string | undefined): string;
+/**
+ * Get a template by tier name.
+ */
+export declare function getTemplate(tier: TemplateTier): {
+    id: string;
+    version: string;
+    tier: string;
+    description: string;
+    requiredFields: string[];
+    render(contract: TaskContract, context?: Record<string, unknown>): string;
+} | {
+    id: string;
+    version: string;
+    tier: string;
+    description: string;
+    requiredFields: string[];
+    render(contract: TaskContract, context?: Record<string, unknown>): string;
+} | {
+    id: string;
+    version: string;
+    tier: string;
+    description: string;
+    requiredFields: string[];
+    render(contract: TaskContract, context?: Record<string, unknown>): string;
+} | {
+    id: string;
+    version: string;
+    tier: string;
+    description: string;
+    requiredFields: string[];
+    render(contract: TaskContract, context?: Record<string, unknown>): string;
+};
+/**
+ * List all available templates.
+ */
+export declare function listTemplates(): {
+    id: string;
+    version: string;
+    tier: string;
+    description: string;
+    requiredFields: string[];
+}[];
+/**
+ * Render a prompt from a template and task contract.
+ * Validates contract first. Returns { prompt, template, contract, valid, errors }
+ */
+export declare function renderPrompt(tier: TemplateTier, contract: TaskContract, context?: Record<string, unknown>): {
+    prompt: null;
+    valid: boolean;
+    errors: string[];
+    template?: undefined;
+    contract?: undefined;
+    outputSchema?: undefined;
+    stats?: undefined;
+} | {
+    prompt: null;
+    valid: boolean;
+    errors: string[];
+    template: {
+        id: string;
+        version: string;
+    };
+    contract?: undefined;
+    outputSchema?: undefined;
+    stats?: undefined;
+} | {
+    prompt: string;
+    valid: boolean;
+    errors: never[];
+    template: {
+        id: string;
+        version: string;
+    };
+    contract: {
+        id: string;
+        objective?: string;
+        scope?: string[];
+        nonGoals?: string[];
+        risk?: string;
+        acceptanceCriteria?: string[];
+        allowedOperations?: string[];
+        context?: string;
+        files?: string[];
+        timeoutMs?: number;
+    };
+    outputSchema: string | null;
+    stats: {
+        words: number;
+        chars: number;
+        estimatedTokens: number;
+    };
+};
+/**
+ * Quick render: build a contract from minimal inputs and render.
+ * For when HEAD knows the tier and objective but hasn't built a full contract.
+ */
+export declare function quickRender(tier: TemplateTier, objective: string, opts?: QuickRenderOpts): {
+    prompt: null;
+    valid: boolean;
+    errors: string[];
+    template?: undefined;
+    contract?: undefined;
+    outputSchema?: undefined;
+    stats?: undefined;
+} | {
+    prompt: null;
+    valid: boolean;
+    errors: string[];
+    template: {
+        id: string;
+        version: string;
+    };
+    contract?: undefined;
+    outputSchema?: undefined;
+    stats?: undefined;
+} | {
+    prompt: string;
+    valid: boolean;
+    errors: never[];
+    template: {
+        id: string;
+        version: string;
+    };
+    contract: {
+        id: string;
+        objective?: string;
+        scope?: string[];
+        nonGoals?: string[];
+        risk?: string;
+        acceptanceCriteria?: string[];
+        allowedOperations?: string[];
+        context?: string;
+        files?: string[];
+        timeoutMs?: number;
+    };
+    outputSchema: string | null;
+    stats: {
+        words: number;
+        chars: number;
+        estimatedTokens: number;
+    };
+};
+export {};