ai-maestro 1.0.0

package/src/orchestration/budget-manager.mjs

@@ -0,0 +1,121 @@
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { readJsonSafe } from '../files.mjs';
+import { validateBudget } from '../schema.mjs';
+import { DEFAULT_HOST_VALIDATION_POLICY, normalizeHostValidationPolicy } from './host-validation.mjs';
+
+const budgetPath = path.join(CONFIG.maestroPath, 'budget.json');
+
+export const DEFAULT_BUDGET = {
+  schemaVersion: 1,
+  currencyBudget: 0,
+  estimatedTokenBudget: 100000,
+  maxRunsPerTask: 3,
+  maxSubagentsPerTask: 4,
+  maxDepth: 2,
+  preferFree: true,
+  allowPaid: false,
+  allowClaudeReview: false,
+  allowDirectOpenAI: false,
+  ...DEFAULT_HOST_VALIDATION_POLICY
+};
+
+export function getBudgetPath() {
+  return budgetPath;
+}
+
+export async function loadBudget() {
+  const budget = await readJsonSafe(budgetPath, DEFAULT_BUDGET);
+  const result = validateBudget(budget);
+  if (!result.ok) {
+    console.warn('.maestro/budget.json failed schema validation (' + result.errors.join(', ') + '); missing/invalid fields fall back to safe defaults.');
+    return { ...DEFAULT_BUDGET, ...budget };
+  }
+  return budget;
+}
+
+export function getHostValidationPolicy(budget = {}) {
+  return normalizeHostValidationPolicy({ ...DEFAULT_HOST_VALIDATION_POLICY, ...(budget || {}) });
+}
+
+export function checkRunLimit(budget, runsSoFar) {
+  if (runsSoFar >= budget.maxRunsPerTask) {
+    return { allowed: false, reason: 'maxRunsPerTask (' + budget.maxRunsPerTask + ') reached for this task (runsSoFar=' + runsSoFar + ').' };
+  }
+  return { allowed: true };
+}
+
+export function checkSubagentLimit(budget, subagentsSoFar) {
+  if (subagentsSoFar >= budget.maxSubagentsPerTask) {
+    return { allowed: false, reason: 'maxSubagentsPerTask (' + budget.maxSubagentsPerTask + ') reached (subagentsSoFar=' + subagentsSoFar + ').' };
+  }
+  return { allowed: true };
+}
+
+export function checkDepthLimit(budget, depth) {
+  if (depth >= budget.maxDepth) {
+    return { allowed: false, reason: 'maxDepth (' + budget.maxDepth + ') reached at depth=' + depth + '.' };
+  }
+  return { allowed: true };
+}
+
+export function checkTokenBudget(budget, estimatedTokensUsedSoFar, estimatedTokensForThisRun = 0) {
+  const projected = estimatedTokensUsedSoFar + estimatedTokensForThisRun;
+  if (budget.estimatedTokenBudget > 0 && projected > budget.estimatedTokenBudget) {
+    return {
+      allowed: false,
+      reason: 'estimatedTokenBudget (' + budget.estimatedTokenBudget + ') would be exceeded: ' +
+        estimatedTokensUsedSoFar + ' already used + ' + estimatedTokensForThisRun + ' projected = ' + projected + '.'
+    };
+  }
+  return { allowed: true };
+}
+
+// Env vars are an ADDITIONAL way to satisfy a gate already open in
+// budget.json, never a way to bypass one that's closed there — this mirrors
+// the spec's "OpenAI direto bloqueado sem MAESTRO_ALLOW_DIRECT_OPENAI=1" /
+// "Claude review somente com MAESTRO_ALLOW_CLAUDE_REVIEW=1" language, which
+// names env vars as the opt-in mechanism operators actually use day to day,
+// while budget.json remains the durable, inspectable source of policy.
+function envAllows(name) {
+  return process.env[name] === '1';
+}
+
+export function checkEnginePolicy(budget, engineRecord, { isClaudeReview = false, isDirectOpenAI = false } = {}) {
+  const costClass = engineRecord && engineRecord.cost ? engineRecord.cost.class : 'unknown';
+  if (costClass === 'paid' && budget.allowPaid !== true) {
+    return { allowed: false, reason: 'Engine cost class is "paid" and allowPaid is false in .maestro/budget.json.' };
+  }
+  if (isClaudeReview && budget.allowClaudeReview !== true && !envAllows('MAESTRO_ALLOW_CLAUDE_REVIEW')) {
+    return { allowed: false, reason: 'Claude/premium review requires budget.allowClaudeReview=true or MAESTRO_ALLOW_CLAUDE_REVIEW=1.' };
+  }
+  if (isDirectOpenAI && budget.allowDirectOpenAI !== true && !envAllows('MAESTRO_ALLOW_DIRECT_OPENAI')) {
+    return { allowed: false, reason: 'Direct OpenAI requires budget.allowDirectOpenAI=true or MAESTRO_ALLOW_DIRECT_OPENAI=1.' };
+  }
+  return { allowed: true };
+}
+
+export async function evaluateBudget({
+  runsSoFar = 0,
+  subagentsSoFar = 0,
+  depth = 0,
+  estimatedTokensUsedSoFar = 0,
+  estimatedTokensForThisRun = 0,
+  engineRecord = null,
+  isClaudeReview = false,
+  isDirectOpenAI = false
+} = {}) {
+  const budget = await loadBudget();
+  const checks = [
+    checkRunLimit(budget, runsSoFar),
+    checkSubagentLimit(budget, subagentsSoFar),
+    checkDepthLimit(budget, depth),
+    checkTokenBudget(budget, estimatedTokensUsedSoFar, estimatedTokensForThisRun),
+    checkEnginePolicy(budget, engineRecord, { isClaudeReview, isDirectOpenAI })
+  ];
+  const failed = checks.find(check => check.allowed === false);
+  if (failed) {
+    return { allowed: false, reason: failed.reason, budget };
+  }
+  return { allowed: true, reason: 'Within budget.', budget };
+}

package/src/orchestration/capability-registry.mjs

@@ -0,0 +1,108 @@
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { readJsonSafe } from '../files.mjs';
+
+const enginesFilePath = path.join(CONFIG.maestroPath, 'engines.json');
+
+const EMPTY_REGISTRY = { schemaVersion: 1, generatedBy: 'none', note: '', engines: [] };
+
+const TRUTHY_UNKNOWN = new Set(['unknown', null, undefined]);
+
+export function getEnginesFilePath() {
+  return enginesFilePath;
+}
+
+export async function loadEngineRegistry() {
+  return readJsonSafe(enginesFilePath, EMPTY_REGISTRY);
+}
+
+export async function listEngineRecords({ enabledOnly = false } = {}) {
+  const registry = await loadEngineRegistry();
+  const engines = registry.engines || [];
+  return enabledOnly ? engines.filter(engine => engine.enabled === true) : engines;
+}
+
+export async function getEngineRecord(id) {
+  const engines = await listEngineRecords();
+  return engines.find(engine => engine.id === id) || null;
+}
+
+// `field` is unknown if it's the literal string 'unknown', null, or undefined.
+// Booleans (true/false) are treated as known even when false — a declared
+// `false` is a real, confirmed answer ("this engine cannot do X"), not a gap.
+export function isUnknownField(value) {
+  return TRUTHY_UNKNOWN.has(value);
+}
+
+export function hasTool(engineRecord, toolName) {
+  if (!engineRecord || !engineRecord.tools) {
+    return false;
+  }
+  const value = engineRecord.tools[toolName];
+  return value === true;
+}
+
+export function hasCapabilityAtLeast(engineRecord, capabilityName, minLevel) {
+  if (!engineRecord || !engineRecord.capabilities) {
+    return false;
+  }
+  const value = engineRecord.capabilities[capabilityName];
+  if (isUnknownField(value) || typeof value !== 'number') {
+    return false;
+  }
+  return value >= minLevel;
+}
+
+// 'paid' is the only class that hard-requires the allowPaid opt-in (project
+// rule: never call a paid engine without explicit opt-in). 'unknown' is
+// deliberately NOT treated as equivalent to 'paid': this project's only real
+// worker (codex9, via 9Router's own documented subscription->cheap->free
+// auto-fallback) has honestly unknown per-call cost, and hard-blocking every
+// unknown-cost engine by default would make the orchestrator unable to
+// select the one engine that actually works. Unknown-cost engines remain
+// selectable by default but score worse than confirmed free/local/free-tier
+// ones (see engine-selector.mjs), and callers that want strict "confirmed
+// non-paid only" behavior can pass allowUnknownCost:false explicitly.
+export function isCostAcceptable(engineRecord, { allowPaid = false, allowUnknownCost = true } = {}) {
+  const costClass = engineRecord && engineRecord.cost ? engineRecord.cost.class : 'unknown';
+  if (costClass === 'free' || costClass === 'free-tier' || costClass === 'local') {
+    return true;
+  }
+  if (costClass === 'paid') {
+    return allowPaid === true;
+  }
+  return allowUnknownCost === true;
+}
+
+export function summarizeConfidence(engineRecord) {
+  const confidence = (engineRecord && engineRecord.confidence) || {};
+  const values = Object.values(confidence);
+  if (values.length === 0) {
+    return 'unknown';
+  }
+  if (values.every(value => value === 'confirmed')) {
+    return 'confirmed';
+  }
+  if (values.some(value => value === 'unknown')) {
+    return 'unknown';
+  }
+  return 'probable';
+}
+
+export async function describeEngine(id) {
+  const engineRecord = await getEngineRecord(id);
+  if (!engineRecord) {
+    return { id, found: false };
+  }
+  return {
+    id: engineRecord.id,
+    found: true,
+    displayName: engineRecord.displayName,
+    enabled: engineRecord.enabled === true,
+    validated: engineRecord.validated === true,
+    costClass: engineRecord.cost ? engineRecord.cost.class : 'unknown',
+    overallConfidence: summarizeConfidence(engineRecord),
+    roles: engineRecord.roles || [],
+    engineRecord
+  };
+}