@mindrian_os/install 1.13.0-beta.11

package/lib/core/dispatch-optimizer.cjs

@@ -0,0 +1,354 @@
+/**
+ * MindrianOS Plugin - Agent Dispatch Optimizer
+ * Budget-aware swarm sizing, cost estimation, and model downgrade logic.
+ * Pure Node.js built-ins only. No npm dependencies.
+ *
+ * Requirements: AGENT-01, AGENT-02, AGENT-04
+ */
+
+'use strict';
+
+const path = require('path');
+const { safeReadFile } = require('./index.cjs');
+const { resolveModel } = require('./model-profiles.cjs');
+
+// ─── Token Cost Constants ──────────────────────────────────────────
+// Approximate token costs per agent invocation by model tier.
+// Based on Claude API pricing (input + output per typical methodology session).
+// These are estimates -- actual cost varies by session depth.
+
+const TOKEN_COSTS = {
+  opus:   { input: 30000, output: 20000, total: 50000 },
+  sonnet: { input: 15000, output: 10000, total: 25000 },
+  haiku:  { input:  5000, output:  3000, total:  8000 },
+};
+
+// Default context window sizes by model
+const CONTEXT_WINDOWS = {
+  opus:   200000,
+  sonnet: 200000,
+  haiku:  200000,
+};
+
+// Safety margin -- never use more than this fraction of remaining context
+const BUDGET_SAFETY_MARGIN = 0.85;
+
+// Downgrade threshold -- if total cost exceeds this fraction of remaining context, downgrade
+const DOWNGRADE_THRESHOLD = 0.6;
+
+// ─── Cost Estimation ───────────────────────────────────────────────
+
+/**
+ * Estimate token cost for dispatching N agents at a given model tier.
+ * @param {number} agentCount - Number of agents to dispatch
+ * @param {string} model - Model alias (opus, sonnet, haiku)
+ * @returns {{ perAgent: number, total: number, model: string, breakdown: { input: number, output: number } }}
+ */
+function estimateTokenCost(agentCount, model) {
+  const tier = TOKEN_COSTS[model] || TOKEN_COSTS.sonnet;
+  return {
+    perAgent: tier.total,
+    total: tier.total * agentCount,
+    model,
+    breakdown: {
+      input: tier.input * agentCount,
+      output: tier.output * agentCount,
+    },
+  };
+}
+
+/**
+ * Format a cost estimate as a human-readable string for display.
+ * @param {{ total: number, model: string, perAgent: number }} estimate
+ * @param {number} agentCount
+ * @returns {string} e.g. "This will use ~150K tokens (3 agents x Opus)"
+ */
+function formatCostEstimate(estimate, agentCount) {
+  const totalK = Math.round(estimate.total / 1000);
+  const modelName = estimate.model.charAt(0).toUpperCase() + estimate.model.slice(1);
+  return `This will use ~${totalK}K tokens (${agentCount} agent${agentCount !== 1 ? 's' : ''} x ${modelName})`;
+}
+
+// ─── Dynamic Swarm Sizing ──────────────────────────────────────────
+
+/**
+ * Identify weak sections from room STATE.md.
+ * Weak = fewer than 5 entries.
+ * @param {string} roomDir - Path to room directory
+ * @returns {Array<{ section: string, entries: number }>} Sorted ascending by entry count
+ */
+function findWeakSections(roomDir) {
+  const statePath = path.join(roomDir, 'STATE.md');
+  const content = safeReadFile(statePath);
+  if (!content) return [];
+
+  const sections = [];
+  // Parse section fill levels from STATE.md
+  // Format varies but typically: "section-name: N entries" or "| section-name | N |"
+  const tablePattern = /\|\s*([a-z][a-z0-9-]+)\s*\|\s*(\d+)\s*\|/gi;
+  const linePattern = /^\s*[-*]\s+([a-z][a-z0-9-]+)(?:\/?):\s*(\d+)\s*entr/gmi;
+
+  let match;
+  while ((match = tablePattern.exec(content)) !== null) {
+    const name = match[1].trim();
+    const count = parseInt(match[2], 10);
+    if (count < 5) {
+      sections.push({ section: name, entries: count });
+    }
+  }
+
+  // Also try line-based format
+  while ((match = linePattern.exec(content)) !== null) {
+    const name = match[1].trim();
+    const count = parseInt(match[2], 10);
+    // Avoid duplicates
+    if (count < 5 && !sections.find(s => s.section === name)) {
+      sections.push({ section: name, entries: count });
+    }
+  }
+
+  // Sort ascending by entry count (weakest first)
+  sections.sort((a, b) => a.entries - b.entries);
+  return sections;
+}
+
+/**
+ * Calculate optimal swarm size based on weak sections and context budget.
+ * Formula: N = min(weakSections.length, floor(contextBudget / agentCost))
+ *
+ * @param {Array<{ section: string, entries: number }>} weakSections - Weak sections from findWeakSections()
+ * @param {number} contextBudget - Remaining context tokens available
+ * @param {number} agentCost - Token cost per agent (from estimateTokenCost)
+ * @returns {{ count: number, sections: Array<{ section: string, entries: number }>, reason: string }}
+ */
+function scaleSwarm(weakSections, contextBudget, agentCost) {
+  if (!weakSections || weakSections.length === 0) {
+    return {
+      count: 0,
+      sections: [],
+      reason: 'No weak sections found -- room is well-developed',
+    };
+  }
+
+  const usableBudget = Math.floor(contextBudget * BUDGET_SAFETY_MARGIN);
+  const maxByBudget = Math.max(1, Math.floor(usableBudget / agentCost));
+  const maxBySections = weakSections.length;
+  const count = Math.min(maxByBudget, maxBySections);
+  const selectedSections = weakSections.slice(0, count);
+
+  let reason;
+  if (maxByBudget < maxBySections) {
+    reason = `Budget-limited: ${maxByBudget} agents fit in ${Math.round(usableBudget / 1000)}K budget (${maxBySections} weak sections available)`;
+  } else {
+    reason = `Section-limited: ${maxBySections} weak section${maxBySections !== 1 ? 's' : ''} found (budget allows ${maxByBudget})`;
+  }
+
+  return { count, sections: selectedSections, reason };
+}
+
+// ─── Budget-Aware Model Selection ──────────────────────────────────
+
+/**
+ * Select optimal model tier based on total dispatch cost vs remaining context.
+ * If total cost at current model exceeds DOWNGRADE_THRESHOLD of remaining context,
+ * downgrade from opus -> sonnet -> haiku.
+ *
+ * @param {number} agentCount - Number of agents to dispatch
+ * @param {string} preferredModel - The model resolved by model-profiles.cjs
+ * @param {number} remainingContext - Remaining context tokens
+ * @returns {{ model: string, downgraded: boolean, originalModel: string, reason: string }}
+ */
+function selectModel(agentCount, preferredModel, remainingContext) {
+  const downgradeChain = ['opus', 'sonnet', 'haiku'];
+  const startIdx = downgradeChain.indexOf(preferredModel);
+
+  // If preferred model not in chain, use as-is (could be 'inherit' or 'skip')
+  if (startIdx === -1) {
+    return {
+      model: preferredModel,
+      downgraded: false,
+      originalModel: preferredModel,
+      reason: `Model "${preferredModel}" is not in downgrade chain -- using as-is`,
+    };
+  }
+
+  for (let i = startIdx; i < downgradeChain.length; i++) {
+    const candidate = downgradeChain[i];
+    const cost = estimateTokenCost(agentCount, candidate);
+
+    if (cost.total <= remainingContext * DOWNGRADE_THRESHOLD) {
+      const downgraded = i > startIdx;
+      return {
+        model: candidate,
+        downgraded,
+        originalModel: preferredModel,
+        reason: downgraded
+          ? `Downgraded ${preferredModel} -> ${candidate}: ${Math.round(cost.total / 1000)}K tokens fits within ${Math.round(remainingContext * DOWNGRADE_THRESHOLD / 1000)}K budget (60% of ${Math.round(remainingContext / 1000)}K remaining)`
+          : `${candidate} fits within budget: ${Math.round(cost.total / 1000)}K of ${Math.round(remainingContext * DOWNGRADE_THRESHOLD / 1000)}K allowed`,
+      };
+    }
+  }
+
+  // Even haiku exceeds budget -- dispatch minimum with haiku
+  return {
+    model: 'haiku',
+    downgraded: true,
+    originalModel: preferredModel,
+    reason: `All models exceed 60% budget -- using haiku as minimum (${Math.round(estimateTokenCost(agentCount, 'haiku').total / 1000)}K tokens)`,
+  };
+}
+
+// ─── Full Dispatch Plan ────────────────────────────────────────────
+
+/**
+ * Generate a complete dispatch plan for swarm mode.
+ * Combines weak section detection, swarm sizing, model selection, and cost estimation.
+ *
+ * @param {string} roomDir - Path to room directory
+ * @param {Object} options
+ * @param {number} [options.remainingContext=200000] - Remaining context tokens
+ * @param {number} [options.maxBudget] - User-specified max token budget (--budget flag)
+ * @param {string} [options.preferredModel] - Override model (otherwise resolved from room config)
+ * @returns {Object} Full dispatch plan with agents, costs, and reasoning
+ */
+function planDispatch(roomDir, options = {}) {
+  const remainingContext = options.remainingContext || 200000;
+  const maxBudget = options.maxBudget || remainingContext;
+  const effectiveBudget = Math.min(remainingContext, maxBudget);
+
+  // Resolve preferred model from room config
+  const preferredModel = options.preferredModel || resolveModel(roomDir, 'framework-runner');
+
+  // Find weak sections
+  const weakSections = findWeakSections(roomDir);
+
+  // Model selection with budget awareness
+  const modelResult = selectModel(
+    weakSections.length || 1,
+    preferredModel === 'skip' ? 'sonnet' : preferredModel,
+    effectiveBudget
+  );
+
+  // Cost per agent at selected model
+  const perAgentCost = estimateTokenCost(1, modelResult.model).total;
+
+  // Scale swarm to budget
+  const swarmResult = scaleSwarm(weakSections, effectiveBudget, perAgentCost);
+
+  // Total cost estimate
+  const totalEstimate = estimateTokenCost(swarmResult.count, modelResult.model);
+
+  return {
+    agents: swarmResult.count,
+    model: modelResult.model,
+    sections: swarmResult.sections,
+    cost: {
+      perAgent: perAgentCost,
+      total: totalEstimate.total,
+      display: formatCostEstimate(totalEstimate, swarmResult.count),
+    },
+    budget: {
+      remaining: remainingContext,
+      maxBudget: maxBudget !== remainingContext ? maxBudget : null,
+      effective: effectiveBudget,
+    },
+    downgrade: modelResult.downgraded ? {
+      from: modelResult.originalModel,
+      to: modelResult.model,
+      reason: modelResult.reason,
+    } : null,
+    reasoning: {
+      swarm: swarmResult.reason,
+      model: modelResult.reason,
+    },
+  };
+}
+
+// ─── Chain Checkpoint Support ──────────────────────────────────────
+
+/**
+ * Generate a chain checkpoint prompt for the user.
+ * Used between pipeline steps in --chain mode.
+ *
+ * @param {number} currentStep - 1-indexed current step number
+ * @param {number} totalSteps - Total steps in chain
+ * @param {string} completedFramework - Name of just-completed framework
+ * @param {string} nextFramework - Name of next framework to run
+ * @param {Object} [stats] - Optional stats from completed step
+ * @param {number} [stats.artifactsAdded] - Artifacts filed
+ * @param {string} [stats.section] - Target section
+ * @returns {{ prompt: string, metadata: Object }}
+ */
+function chainCheckpoint(currentStep, totalSteps, completedFramework, nextFramework, stats = {}) {
+  const prompt = [
+    `[CHAIN] Step ${currentStep}/${totalSteps} complete: ${completedFramework}`,
+    stats.artifactsAdded ? `        Filed: ${stats.artifactsAdded} artifact${stats.artifactsAdded !== 1 ? 's' : ''} to room/${stats.section || 'unknown'}/` : null,
+    '',
+    `Continue to step ${currentStep + 1}? (${nextFramework})`,
+    '(yes / skip / stop)',
+  ].filter(Boolean).join('\n');
+
+  return {
+    prompt,
+    metadata: {
+      step: currentStep,
+      total: totalSteps,
+      completed: completedFramework,
+      next: nextFramework,
+      canSkip: true,
+      canStop: true,
+    },
+  };
+}
+
+// ─── CLI Interface ─────────────────────────────────────────────────
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const subcmd = args[0];
+
+  if (subcmd === 'estimate' && args.length >= 3) {
+    // estimate <agentCount> <model>
+    const result = estimateTokenCost(parseInt(args[1], 10), args[2]);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (subcmd === 'plan' && args.length >= 2) {
+    // plan <roomDir> [--budget <N>] [--context <N>]
+    const roomDir = args[1];
+    const opts = {};
+    for (let i = 2; i < args.length; i += 2) {
+      if (args[i] === '--budget' && args[i + 1]) opts.maxBudget = parseInt(args[i + 1], 10);
+      if (args[i] === '--context' && args[i + 1]) opts.remainingContext = parseInt(args[i + 1], 10);
+    }
+    const result = planDispatch(roomDir, opts);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (subcmd === 'weak-sections' && args.length >= 2) {
+    // weak-sections <roomDir>
+    const result = findWeakSections(args[1]);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (subcmd === 'select-model' && args.length >= 4) {
+    // select-model <agentCount> <preferredModel> <remainingContext>
+    const result = selectModel(parseInt(args[1], 10), args[2], parseInt(args[3], 10));
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    process.stderr.write('Usage: node dispatch-optimizer.cjs <estimate|plan|weak-sections|select-model> [args...]\n');
+    process.stderr.write('  estimate <agentCount> <model>\n');
+    process.stderr.write('  plan <roomDir> [--budget <N>] [--context <N>]\n');
+    process.stderr.write('  weak-sections <roomDir>\n');
+    process.stderr.write('  select-model <agentCount> <preferredModel> <remainingContext>\n');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  TOKEN_COSTS,
+  CONTEXT_WINDOWS,
+  DOWNGRADE_THRESHOLD,
+  BUDGET_SAFETY_MARGIN,
+  estimateTokenCost,
+  formatCostEstimate,
+  findWeakSections,
+  scaleSwarm,
+  selectModel,
+  planDispatch,
+  chainCheckpoint,
+};

package/lib/core/dual-path-detector.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+/*
+ * Phase 115-02 -- Dual-path detector (DISCRETION-03 resolution)
+ *
+ * 5-feature additive score classifier for turn-1 intake.
+ *
+ *   F1 word_count: < 80 -> -2; > 300 -> +2; 80..300 -> 0
+ *   F2 newline_density (newlines/words): > 0.10 -> +2; < 0.05 -> -1; 0.05..0.10 -> 0
+ *   F3 SECTION_HEADER match -> +3
+ *   F4 DOMAIN_MARKER match -> +2
+ *   F5 STUCK_LANGUAGE match -> -3 (NEGATIVE WEIGHT, Pitfall 3 safety net)
+ *
+ * Decision rule:
+ *   score >= +3 -> 'upload'
+ *   score <= -3 -> 'type'
+ *   else        -> 'ambiguous'
+ *
+ * Canon Part 8: pure string classification; output is enum + int + booleans
+ * (NO matched substrings in features). Safe for Phase 121 trajectory telemetry
+ * which carries the features payload as scalars only.
+ *
+ * Pitfall 3 mitigation: STUCK_LANGUAGE carries -3 NEGATIVE WEIGHT so a thoughtful
+ * 250-word stuck-decision answer cannot be misclassified as upload even when a
+ * single domain marker (e.g. "$5M") is present in the prose.
+ */
+
+const SECTION_HEADER = /^(Education|Experience|Summary|Methodology|Background|Problem Statement|Abstract|Hypothesis|Goal|Objective|Approach|Team|Founder|CEO|CTO|Advisor|Skills|Publications|Patents|Funding|Market|Solution|Pitch)\b/im;
+const DOMAIN_MARKER = /(IRB#?\s*\d|NCT\d{8}|NIH\b|IND\b|FDA\b|HIPAA\b|\$[\d.]+[MBK]\b|ARR|MRR|Series\s*[A-Z]\b|runway|burn rate|LP\b|GP\b|fund size|check size|portfolio)/i;
+const STUCK_LANGUAGE = /(I'?m stuck|I can'?t|I don'?t know|I'?m trying to|help me think|I keep|I keep coming back to)/i;
+
+function classify(text) {
+  if (!text || typeof text !== 'string') {
+    return { path: 'ambiguous', score: 0, features: {} };
+  }
+  const trimmed = text.trim();
+  const words = trimmed.split(/\s+/).filter(Boolean);
+  const wc = words.length;
+  const newlines = (text.match(/\n/g) || []).length;
+  const density = wc > 0 ? newlines / wc : 0;
+
+  let score = 0;
+  const features = {
+    word_count: wc,
+    newline_density: density,
+    section_header: false,
+    domain_marker: false,
+    stuck_language: false,
+  };
+
+  // F1 word count
+  if (wc < 80) score -= 2;
+  else if (wc > 300) score += 2;
+
+  // F2 newline density
+  if (density > 0.10) score += 2;
+  else if (density < 0.05) score -= 1;
+
+  // F3 section headers
+  features.section_header = SECTION_HEADER.test(text);
+  if (features.section_header) score += 3;
+
+  // F4 domain markers
+  features.domain_marker = DOMAIN_MARKER.test(text);
+  if (features.domain_marker) score += 2;
+
+  // F5 first-person stuck-language (negative weight: Pitfall 3 safety net)
+  features.stuck_language = STUCK_LANGUAGE.test(text);
+  if (features.stuck_language) score -= 3;
+
+  let path;
+  if (score >= 3) path = 'upload';
+  else if (score <= -3) path = 'type';
+  else path = 'ambiguous';
+
+  return { path, score, features };
+}
+
+module.exports = {
+  classify,
+  SECTION_HEADER,
+  DOMAIN_MARKER,
+  STUCK_LANGUAGE,
+};