ai-maestro 1.0.0

package/src/orchestration/orchestration-scheduler.mjs

@@ -0,0 +1,135 @@
+function cloneData(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function subtaskId(subtask) {
+  return String(subtask && subtask.id);
+}
+
+function dependencyList(subtask) {
+  return Array.isArray(subtask && subtask.blockedBy) ? subtask.blockedBy.map(String) : [];
+}
+
+function sortedBySubtaskId(values) {
+  return [...values].sort((a, b) => subtaskId(a).localeCompare(subtaskId(b)));
+}
+
+function conflictSubtaskIds(conflict) {
+  const ids = [];
+  if (conflict && conflict.subtaskId !== undefined && conflict.subtaskId !== null) {
+    ids.push(String(conflict.subtaskId));
+  }
+  if (conflict && Array.isArray(conflict.subtaskIds)) {
+    for (const id of conflict.subtaskIds) ids.push(String(id));
+  }
+  return ids;
+}
+
+function hasBlockingWaveConflict(subtask, waveConflicts = []) {
+  const id = subtaskId(subtask);
+  return waveConflicts.some(conflict => {
+    if (!['file-write-conflict', 'sensitive-path', 'missing-expected-files'].includes(conflict && conflict.type)) {
+      return false;
+    }
+    return conflictSubtaskIds(conflict).includes(id);
+  });
+}
+
+export function computeWaves(subtasks) {
+  if (!Array.isArray(subtasks)) {
+    throw new TypeError('subtasks must be an array');
+  }
+
+  const ordered = sortedBySubtaskId(subtasks);
+  const byId = new Map();
+  for (const subtask of ordered) {
+    const id = subtaskId(subtask);
+    if (byId.has(id)) {
+      throw new Error('duplicate subtask id in orchestration plan: ' + id);
+    }
+    byId.set(id, subtask);
+  }
+
+  for (const subtask of ordered) {
+    for (const dependency of dependencyList(subtask)) {
+      if (!byId.has(dependency)) {
+        throw new Error('unresolved subtask dependency: ' + subtaskId(subtask) + ' blockedBy ' + dependency);
+      }
+    }
+  }
+
+  const remaining = new Set(ordered.map(subtaskId));
+  const completed = new Set();
+  const waves = [];
+
+  while (remaining.size > 0) {
+    const readyIds = [...remaining]
+      .filter(id => dependencyList(byId.get(id)).every(dependency => completed.has(dependency)))
+      .sort((a, b) => a.localeCompare(b));
+
+    if (readyIds.length === 0) {
+      throw new Error('dependency cycle remained after 03C planning');
+    }
+
+    const waveSubtasks = readyIds.map(id => cloneData(byId.get(id)));
+    waves.push({
+      waveIndex: waves.length,
+      subtaskIds: readyIds,
+      subtasks: waveSubtasks
+    });
+    for (const id of readyIds) {
+      remaining.delete(id);
+      completed.add(id);
+    }
+  }
+
+  return waves;
+}
+
+export function classifySubtask(subtask, waveConflicts = []) {
+  const files = Array.isArray(subtask && subtask.expectedFiles) ? subtask.expectedFiles : [];
+  const requires = subtask && subtask.requires;
+  if (!requires || requires.filesystemWrite !== false) {
+    return 'serial-required';
+  }
+  if (files.length > 0) {
+    return 'serial-required';
+  }
+  if (hasBlockingWaveConflict(subtask, waveConflicts)) {
+    return 'serial-required';
+  }
+  return 'parallel-eligible';
+}
+
+export function planWaveExecution(wave, subtasks, limits = {}) {
+  const subtasksById = new Map((Array.isArray(subtasks) ? subtasks : []).map(subtask => [subtaskId(subtask), subtask]));
+  const sourceSubtasks = Array.isArray(wave && wave.subtasks)
+    ? wave.subtasks
+    : Array.isArray(wave)
+      ? wave
+      : Array.isArray(wave && wave.subtaskIds)
+        ? wave.subtaskIds.map(id => subtasksById.get(String(id))).filter(Boolean)
+        : [];
+  const ordered = sortedBySubtaskId(sourceSubtasks);
+  const waveConflicts = Array.isArray(limits.waveConflicts)
+    ? limits.waveConflicts
+    : Array.isArray(limits.conflicts)
+      ? limits.conflicts
+      : [];
+
+  if (ordered.length <= 1) {
+    return { parallel: [], serial: ordered.map(cloneData) };
+  }
+
+  const parallel = [];
+  const serial = [];
+  for (const subtask of ordered) {
+    if (classifySubtask(subtask, waveConflicts) === 'parallel-eligible') {
+      parallel.push(cloneData(subtask));
+    } else {
+      serial.push(cloneData(subtask));
+    }
+  }
+  return { parallel, serial };
+}

package/src/orchestration/orchestration-trail.mjs

@@ -0,0 +1,192 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { pathExists } from '../files.mjs';
+import { redactObject } from '../format.mjs';
+import { stampSchemaVersion, validateOrchestrationEvent } from '../schema.mjs';
+
+const trailFilePath = path.join(CONFIG.maestroPath, 'ORCHESTRATIONS.jsonl');
+
+function cloneData(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeChild(child) {
+  return {
+    subtaskId: child && child.subtaskId !== undefined && child.subtaskId !== null ? String(child.subtaskId) : null,
+    taskId: child && child.taskId !== undefined ? child.taskId : null,
+    runId: child && child.runId ? child.runId : null,
+    status: child && child.status ? child.status : 'unknown'
+  };
+}
+
+function normalizeConsolidation(consolidation) {
+  if (!consolidation || typeof consolidation !== 'object') return null;
+  return {
+    status: consolidation.status || null,
+    consolidationCompleteness: consolidation.consolidationCompleteness || null
+  };
+}
+
+function normalizeVerification(verification) {
+  if (!verification || typeof verification !== 'object') return null;
+  return {
+    verificationOutcome: verification.verificationOutcome || verification.outcome || null
+  };
+}
+
+function normalizeStrings(values) {
+  return Array.isArray(values) ? values.map(value => String(value)) : [];
+}
+
+function normalizeTrace(values) {
+  return Array.isArray(values) ? cloneData(values) : [];
+}
+
+function normalizeConcurrency(concurrency) {
+  if (!concurrency || typeof concurrency !== 'object' || Array.isArray(concurrency)) return undefined;
+  const result = {};
+  if (concurrency.maxConcurrent !== undefined) result.maxConcurrent = Number(concurrency.maxConcurrent);
+  if (concurrency.observedMaxActive !== undefined) result.observedMaxActive = Number(concurrency.observedMaxActive);
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function normalizeWaves(waves) {
+  if (!Array.isArray(waves)) return undefined;
+  return waves.map(wave => ({
+    waveIndex: Number(wave && wave.waveIndex),
+    parallelSubtaskIds: normalizeStrings(wave && wave.parallelSubtaskIds),
+    serialSubtaskIds: normalizeStrings(wave && wave.serialSubtaskIds)
+  }));
+}
+
+function executionFields(event) {
+  const fields = {};
+  if (event && (event.strategy === 'serial' || event.strategy === 'controlled-parallel')) {
+    fields.strategy = event.strategy;
+  }
+  const concurrency = normalizeConcurrency(event && event.concurrency);
+  if (concurrency) fields.concurrency = concurrency;
+  const waves = normalizeWaves(event && event.waves);
+  if (waves) fields.waves = waves;
+  return fields;
+}
+
+function normalizeEvent(event) {
+  const eventType = event && event.eventType;
+  const timestamp = event && event.timestamp ? event.timestamp : new Date().toISOString();
+  const base = stampSchemaVersion({
+    orchestrationId: event && event.orchestrationId !== undefined && event.orchestrationId !== null ? String(event.orchestrationId) : event && event.orchestrationId,
+    parentTaskId: event && event.parentTaskId !== undefined && event.parentTaskId !== null ? String(event.parentTaskId) : event && event.parentTaskId,
+    attempt: Number(event && event.attempt),
+    mode: 'real',
+    eventType,
+    startTime: event && event.startTime ? event.startTime : timestamp,
+    timestamp
+  });
+
+  if (eventType === 'orchestration_blocked') {
+    return {
+      ...base,
+      status: event.status === 'needs_human' ? 'needs_human' : 'blocked',
+      reason: String(event.reason || ''),
+      trace: normalizeTrace(event.trace),
+      warnings: normalizeStrings(event.warnings),
+      ...executionFields(event)
+    };
+  }
+
+  if (eventType === 'orchestration_finished') {
+    return {
+      ...base,
+      endTime: event.endTime || timestamp,
+      status: event.status || 'blocked',
+      children: Array.isArray(event.children) ? event.children.map(normalizeChild) : [],
+      consolidation: normalizeConsolidation(event.consolidation),
+      verification: normalizeVerification(event.verification),
+      warnings: normalizeStrings(event.warnings),
+      reason: String(event.reason || ''),
+      trace: normalizeTrace(event.trace),
+      ...executionFields(event)
+    };
+  }
+
+  return { ...base, ...executionFields(event) };
+}
+
+export async function appendOrchestrationEvent(event) {
+  const normalized = normalizeEvent(cloneData(event || {}));
+  const stamped = cloneData(redactObject(normalized));
+  const result = validateOrchestrationEvent(stamped);
+  if (!result.ok) {
+    console.warn('Orchestration event for task #' + stamped.parentTaskId + ' failed schema validation: ' + result.errors.join(', '));
+  }
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  if (await pathExists(trailFilePath)) {
+    await fs.copyFile(trailFilePath, trailFilePath + '.bak');
+  }
+  await fs.appendFile(trailFilePath, JSON.stringify(stamped) + '\n', { encoding: 'utf8' });
+  return cloneData(stamped);
+}
+
+export async function getOrchestrationEvents(parentTaskId) {
+  try {
+    const content = await fs.readFile(trailFilePath, 'utf-8');
+    return content
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(line => {
+        try {
+          const event = JSON.parse(line);
+          const validation = validateOrchestrationEvent(event);
+          if (!validation.ok) {
+            return { ...event, parseError: 'schema validation failed: ' + validation.errors.join(', '), raw: line };
+          }
+          return event;
+        } catch (error) {
+          return { parseError: error.message, raw: line };
+        }
+      })
+      .filter(event => parentTaskId === undefined || parentTaskId === null || event.parseError || String(event.parentTaskId) === String(parentTaskId));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export async function getLatestOrchestrationForTask(parentTaskId) {
+  const events = await getOrchestrationEvents(parentTaskId);
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event && !event.parseError && (event.eventType === 'orchestration_finished' || event.eventType === 'orchestration_blocked')) {
+      return cloneData(event);
+    }
+  }
+  return null;
+}
+
+export function buildOrchestrationSummary(event) {
+  if (!event || event.parseError) return null;
+  return {
+    orchestrationId: event.orchestrationId,
+    parentTaskId: event.parentTaskId,
+    attempt: event.attempt,
+    mode: event.mode,
+    eventType: event.eventType,
+    status: event.status || null,
+    startTime: event.startTime || null,
+    endTime: event.endTime || null,
+    timestamp: event.timestamp || null,
+    children: Array.isArray(event.children) ? event.children.map(normalizeChild) : [],
+    consolidation: normalizeConsolidation(event.consolidation),
+    verification: normalizeVerification(event.verification),
+    warnings: normalizeStrings(event.warnings),
+    reason: event.reason || null,
+    ...(event.strategy ? { strategy: event.strategy } : {}),
+    ...(event.concurrency ? { concurrency: normalizeConcurrency(event.concurrency) } : {}),
+    ...(event.waves ? { waves: normalizeWaves(event.waves) } : {})
+  };
+}

package/src/orchestration/preflight.mjs

@@ -0,0 +1,212 @@
+import { hasTool, isCostAcceptable, isUnknownField, summarizeConfidence } from './capability-registry.mjs';
+
+export const PREFLIGHT_DECISIONS = [
+  'ACCEPT', 'DECLINE', 'DELEGATE', 'NEEDS_CAPABILITY', 'NEEDS_CONTEXT', 'NEEDS_HUMAN', 'UNAVAILABLE'
+];
+
+const REQUIRED_TOOL_KEYS = ['shell', 'filesystemWrite', 'browser', 'vision', 'testExecution'];
+
+// vision has no direct 'tools.vision' key in the ficha shape; it lives under
+// capabilities.vision and tools.imageInput. Map classifier requirement keys
+// to the concrete ficha field(s) that must be true.
+function toolCheck(engineRecord, requirementKey) {
+  if (requirementKey === 'vision') {
+    return engineRecord.capabilities && engineRecord.capabilities.vision === true;
+  }
+  if (requirementKey === 'browser') {
+    return hasTool(engineRecord, 'browser');
+  }
+  if (requirementKey === 'testExecution') {
+    return hasTool(engineRecord, 'testExecution');
+  }
+  if (requirementKey === 'filesystemWrite') {
+    return hasTool(engineRecord, 'filesystemWrite');
+  }
+  if (requirementKey === 'shell') {
+    return hasTool(engineRecord, 'shell');
+  }
+  return false;
+}
+
+// Only blocks on a numeric shortfall when BOTH the requirement and the
+// engine's declared capability are known numbers. An engine with an
+// unrated (null/'unknown') capability is a scoring/confidence concern for
+// engine-selector.mjs, not an automatic preflight rejection here — this
+// project never treats "we don't know" the same as "confirmed too weak".
+function findMissingNumericCapabilities(engineRecord, requires) {
+  const missing = [];
+  const caps = engineRecord.capabilities || {};
+  for (const key of ['reasoning', 'coding']) {
+    const required = requires[key];
+    const have = caps[key];
+    if (typeof required === 'number' && typeof have === 'number' && have < required) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
+
+function findMissingCapabilities(engineRecord, requires) {
+  const missing = [];
+  for (const key of REQUIRED_TOOL_KEYS) {
+    if (requires[key] === true && !toolCheck(engineRecord, key)) {
+      missing.push(key);
+    }
+  }
+  return [...missing, ...findMissingNumericCapabilities(engineRecord, requires)];
+}
+
+function confidenceToScore(level) {
+  if (level === 'confirmed') return 0.9;
+  if (level === 'probable') return 0.6;
+  return 0.3;
+}
+
+// Deterministic, ficha-only preflight. The Maestro must never trust a
+// model's self-reported capability over this — see runSelfReportedPreflight
+// below for the (optional, short, non-authoritative) model self-check.
+export function runPreflight(task, engineRecord, classification, options = {}) {
+  const allowPaid = options.allowPaid === true;
+  const allowCritical = options.allowCritical === true;
+
+  // Accept either a raw engine record or the describeEngine() wrapper shape.
+  const record = engineRecord && engineRecord.engineRecord ? engineRecord.engineRecord : engineRecord;
+
+  if (!record) {
+    return {
+      decision: 'UNAVAILABLE',
+      confidence: 0.9,
+      reason: 'Engine not found in capability registry.',
+      missingCapabilities: [],
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  if (record.enabled !== true) {
+    return {
+      decision: 'UNAVAILABLE',
+      confidence: 0.9,
+      reason: 'Engine "' + record.id + '" is disabled in .maestro/engines.json.',
+      missingCapabilities: [],
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  if (record.health && record.health.available === false) {
+    return {
+      decision: 'UNAVAILABLE',
+      confidence: 0.8,
+      reason: 'Engine "' + record.id + '" is currently marked unavailable by health tracking.',
+      missingCapabilities: [],
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  const allowUnknownCost = options.allowUnknownCost !== false;
+  if (!isCostAcceptable(record, { allowPaid, allowUnknownCost })) {
+    return {
+      decision: 'DECLINE',
+      confidence: 0.85,
+      reason: 'Engine "' + record.id + '" cost class is "' + (record.cost ? record.cost.class : 'unknown') +
+        '" and is not allowed for this run (allowPaid=' + allowPaid + ', allowUnknownCost=' + allowUnknownCost + ').',
+      missingCapabilities: [],
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  if (classification.risk === 'critical' && !allowCritical) {
+    return {
+      decision: 'NEEDS_HUMAN',
+      confidence: 0.7,
+      reason: 'Task risk is "critical" (taskKind=' + classification.taskKind + ', complexity=' + classification.complexity + '). Autonomous execution requires explicit allowCritical opt-in or human sign-off.',
+      missingCapabilities: [],
+      recommendedRole: 'human',
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  const missingCapabilities = findMissingCapabilities(record, classification.requires || {});
+  if (missingCapabilities.length > 0) {
+    return {
+      decision: 'NEEDS_CAPABILITY',
+      confidence: 0.75,
+      reason: 'Engine "' + record.id + '" is missing required capabilities: ' + missingCapabilities.join(', ') + '.',
+      missingCapabilities,
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  const requiredContext = classification.requires ? classification.requires.minimumContextTokens : null;
+  const maxContext = record.limits ? record.limits.maxContextTokens : null;
+  if (typeof requiredContext === 'number' && typeof maxContext === 'number' && maxContext < requiredContext) {
+    return {
+      decision: 'NEEDS_CONTEXT',
+      confidence: 0.8,
+      reason: 'Task needs at least ' + requiredContext + ' context tokens; engine "' + record.id + '" declares a max of ' + maxContext + '.',
+      missingCapabilities: [],
+      recommendedRole: null,
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  if (classification.canDelegate && classification.complexity >= 3 && !(record.roles || []).includes('manager') && options.skipDelegationCheck !== true) {
+    return {
+      decision: 'DELEGATE',
+      confidence: 0.55,
+      reason: 'Task complexity ' + classification.complexity + ' (taskKind=' + classification.taskKind + ') benefits from decomposition; "' + record.id + '" is a worker, not a manager. Route through a sector manager first (see src/orchestration/sector-managers.mjs).',
+      missingCapabilities: [],
+      recommendedRole: 'manager',
+      recommendedSuccessor: null,
+      suggestedSubtasks: []
+    };
+  }
+
+  const overallConfidence = confidenceToScore(summarizeConfidence(record));
+  return {
+    decision: 'ACCEPT',
+    confidence: overallConfidence,
+    reason: 'Engine "' + record.id + '" satisfies required tools, cost policy, context, and risk gates for this task.',
+    missingCapabilities: [],
+    recommendedRole: 'worker',
+    recommendedSuccessor: null,
+    suggestedSubtasks: []
+  };
+}
+
+// Optional, short, NON-AUTHORITATIVE self-report from the model itself. Per
+// project policy, this can only ever narrow a decision the deterministic
+// preflight already reached (e.g. surface a caveat), never widen it — a
+// model claiming a capability the ficha says it lacks must be ignored.
+export function reconcileSelfReport(deterministicResult, selfReport) {
+  if (!selfReport || typeof selfReport !== 'object') {
+    return deterministicResult;
+  }
+  const claims = selfReport.claims || {};
+  const contradicted = Object.entries(claims).filter(([key, value]) => {
+    return value === true && deterministicResult.missingCapabilities.includes(key);
+  });
+  if (contradicted.length > 0) {
+    return {
+      ...deterministicResult,
+      reason: deterministicResult.reason + ' (model self-report claimed ' +
+        contradicted.map(([key]) => key).join(', ') + ' despite ficha saying otherwise; ignored — ficha wins.)'
+    };
+  }
+  return deterministicResult;
+}
+
+export function isUnknownRequirement(value) {
+  return isUnknownField(value);
+}