agentxchain 2.116.0 → 2.117.0

package/src/lib/intake.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
 import { join, basename, resolve as pathResolve } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import { safeWriteJson } from './safe-write.js';
@@ -18,7 +18,7 @@ import { loadCoordinatorConfig } from './coordinator-config.js';
 import { loadCoordinatorState, readBarriers } from './coordinator-state.js';
 import { writeCoordinatorHandoff } from './intake-handoff.js';
 
-const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule'];
+const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan'];
 const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
 const EVENT_ID_RE = /^evt_\d+_[0-9a-f]{4}$/;
 const INTENT_ID_RE = /^intent_\d+_[0-9a-f]{4}$/;
@@ -680,6 +680,18 @@ export function startIntent(root, intentId, options = {}) {
     return { ok: false, error: 'Failed to parse governed state.json', exitCode: 2 };
   }
 
+  const allowCompletedRestart = options.allowTerminalRestart === true
+    && state.status === 'completed'
+    && getActiveTurnCount(state) === 0;
+
+  const startProvenance = {
+    trigger: 'intake',
+    intake_intent_id: intent.intent_id,
+    trigger_reason: intent.charter || null,
+    created_by: 'operator',
+    ...(options.provenance && typeof options.provenance === 'object' ? options.provenance : {}),
+  };
+
   // Check busy-run conditions
   const activeTurns = getActiveTurns(state);
   const activeCount = getActiveTurnCount(state);
@@ -698,7 +710,7 @@ export function startIntent(root, intentId, options = {}) {
     return { ok: false, error: `cannot start: run is blocked (${reason})`, exitCode: 1 };
   }
 
-  if (state.status === 'completed') {
+  if (state.status === 'completed' && !allowCompletedRestart) {
     return {
       ok: false,
       error: 'cannot start: governed run is already completed. S3 does not reopen completed runs.',
@@ -719,14 +731,10 @@ export function startIntent(root, intentId, options = {}) {
   }
 
   // Bootstrap: idle with no run → initialize
-  if (state.status === 'idle' && !state.run_id) {
+  if ((state.status === 'idle' && !state.run_id) || allowCompletedRestart) {
     const initResult = initializeGovernedRun(root, config, {
-      provenance: {
-        trigger: 'intake',
-        intake_intent_id: intent.intent_id,
-        trigger_reason: intent.charter || null,
-        created_by: 'operator',
-      },
+      provenance: startProvenance,
+      allow_terminal_restart: allowCompletedRestart,
     });
     if (!initResult.ok) {
       return { ok: false, error: `run initialization failed: ${initResult.error}`, exitCode: 1 };
@@ -1370,8 +1378,232 @@ export function scanSource(root, source, snapshot) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Inject — composed record + triage + approve in one operation
+// ---------------------------------------------------------------------------
+
+const PREEMPTION_MARKER_PATH = '.agentxchain/intake/injected-priority.json';
+
+function preemptionMarkerPath(root) {
+  return join(root, PREEMPTION_MARKER_PATH);
+}
+
+export function readPreemptionMarker(root) {
+  const p = preemptionMarkerPath(root);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function clearPreemptionMarker(root) {
+  const p = preemptionMarkerPath(root);
+  if (existsSync(p)) {
+    try {
+      unlinkSync(p);
+    } catch {
+      // best-effort
+    }
+  }
+}
+
+export function consumePreemptionMarker(root, options = {}) {
+  const marker = readPreemptionMarker(root);
+  if (!marker?.intent_id) {
+    return { ok: false, error: 'no preemption marker found', exitCode: 1 };
+  }
+
+  const loadedIntent = readIntent(root, marker.intent_id);
+  if (!loadedIntent.ok) {
+    return {
+      ok: false,
+      error: `preemption marker references missing intent ${marker.intent_id}`,
+      marker,
+      exitCode: 1,
+    };
+  }
+
+  const startingStatus = loadedIntent.intent.status;
+  let intent = loadedIntent.intent;
+  let planned = false;
+  let started = false;
+
+  if (intent.status === 'approved') {
+    const plannedResult = planIntent(root, intent.intent_id, {
+      projectName: options.projectName,
+      force: options.forcePlan === true,
+    });
+    if (!plannedResult.ok) {
+      return {
+        ok: false,
+        error: `failed to plan injected intent ${intent.intent_id}: ${plannedResult.error}`,
+        marker,
+        intent_status: intent.status,
+        exitCode: plannedResult.exitCode || 1,
+      };
+    }
+    intent = plannedResult.intent;
+    planned = true;
+  }
+
+  if (intent.status === 'planned') {
+    const startResult = startIntent(root, intent.intent_id, {
+      role: options.role || undefined,
+    });
+    if (!startResult.ok) {
+      return {
+        ok: false,
+        error: `failed to start injected intent ${intent.intent_id}: ${startResult.error}`,
+        marker,
+        intent_status: intent.status,
+        exitCode: startResult.exitCode || 1,
+      };
+    }
+    clearPreemptionMarker(root);
+    return {
+      ok: true,
+      marker,
+      intent_id: intent.intent_id,
+      starting_status: startingStatus,
+      final_status: startResult.intent.status,
+      planned,
+      started: true,
+      run_id: startResult.run_id,
+      turn_id: startResult.turn_id,
+      role: startResult.role,
+      intent: startResult.intent,
+      exitCode: 0,
+    };
+  }
+
+  if (intent.status === 'executing') {
+    clearPreemptionMarker(root);
+    return {
+      ok: true,
+      marker,
+      intent_id: intent.intent_id,
+      starting_status: startingStatus,
+      final_status: intent.status,
+      planned,
+      started: false,
+      run_id: intent.target_run || null,
+      turn_id: intent.target_turn || null,
+      role: options.role || null,
+      intent,
+      exitCode: 0,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `cannot consume preemption marker from intent status "${intent.status}"`,
+    marker,
+    intent_id: intent.intent_id,
+    intent_status: intent.status,
+    exitCode: 1,
+  };
+}
+
+export function injectIntent(root, description, options = {}) {
+  if (!description || typeof description !== 'string' || !description.trim()) {
+    return { ok: false, error: 'description is required', exitCode: 1 };
+  }
+
+  const priority = options.priority || 'p0';
+  if (!VALID_PRIORITIES.includes(priority)) {
+    return { ok: false, error: `priority must be one of: ${VALID_PRIORITIES.join(', ')}`, exitCode: 1 };
+  }
+
+  const template = options.template || 'generic';
+  if (!VALID_GOVERNED_TEMPLATE_IDS.includes(template)) {
+    return { ok: false, error: `template must be one of: ${VALID_GOVERNED_TEMPLATE_IDS.join(', ')}`, exitCode: 1 };
+  }
+
+  const charter = options.charter || description.trim();
+  const acceptance_contract = options.acceptance
+    ? options.acceptance.split(',').map(s => s.trim()).filter(Boolean)
+    : [description.trim()];
+  const approver = options.approver || 'human';
+  const noApprove = options.noApprove === true;
+
+  // Step 1: Record event
+  const recordResult = recordEvent(root, {
+    source: 'manual',
+    category: 'operator_injection',
+    signal: { description: description.trim(), injected: true, priority },
+    evidence: [{ type: 'text', value: description.trim() }],
+  });
+
+  if (!recordResult.ok) {
+    return recordResult;
+  }
+
+  // If deduplicated, return existing intent
+  if (recordResult.deduplicated) {
+    return {
+      ok: true,
+      intent: recordResult.intent,
+      event: recordResult.event,
+      deduplicated: true,
+      preemption_marker: false,
+      exitCode: 0,
+    };
+  }
+
+  const intentId = recordResult.intent.intent_id;
+
+  // Step 2: Triage
+  const triageResult = triageIntent(root, intentId, {
+    priority,
+    template,
+    charter,
+    acceptance_contract,
+  });
+
+  if (!triageResult.ok) {
+    return { ok: false, error: `triage failed: ${triageResult.error}`, exitCode: 1 };
+  }
+
+  // Step 3: Approve (unless --no-approve)
+  if (!noApprove) {
+    const approveResult = approveIntent(root, intentId, { approver, reason: 'operator injection' });
+    if (!approveResult.ok) {
+      return { ok: false, error: `approve failed: ${approveResult.error}`, exitCode: 1 };
+    }
+  }
+
+  // Step 4: Write preemption marker for p0
+  let preemptionMarker = false;
+  if (priority === 'p0' && !noApprove) {
+    const marker = {
+      intent_id: intentId,
+      priority,
+      description: description.trim(),
+      injected_at: nowISO(),
+    };
+    ensureIntakeDirs(root);
+    safeWriteJson(preemptionMarkerPath(root), marker);
+    preemptionMarker = true;
+  }
+
+  // Re-read final intent state
+  const finalRead = readIntent(root, intentId);
+  const finalIntent = finalRead.ok ? finalRead.intent : triageResult.intent;
+
+  return {
+    ok: true,
+    intent: finalIntent,
+    event: recordResult.event,
+    deduplicated: false,
+    preemption_marker: preemptionMarker,
+    exitCode: 0,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Exports for testing
 // ---------------------------------------------------------------------------
 
-export { VALID_SOURCES, VALID_PRIORITIES, VALID_TRANSITIONS, S1_STATES, TERMINAL_STATES, SCAN_SOURCES };
+export { VALID_SOURCES, VALID_PRIORITIES, VALID_TRANSITIONS, S1_STATES, TERMINAL_STATES, SCAN_SOURCES, PREEMPTION_MARKER_PATH };

package/src/lib/notification-runner.js

@@ -10,6 +10,8 @@ export const VALID_NOTIFICATION_EVENTS = [
   'run_blocked',
   'operator_escalation_raised',
   'escalation_resolved',
+  'human_escalation_raised',
+  'human_escalation_resolved',
   'phase_transition_pending',
   'run_completion_pending',
   'run_completed',
@@ -170,7 +172,7 @@ export function validateNotificationsConfig(notifications) {
     return { ok: false, errors, warnings: [] };
   }
 
-  const allowedKeys = new Set(['webhooks', 'approval_sla']);
+  const allowedKeys = new Set(['webhooks', 'approval_sla', 'local']);
   for (const key of Object.keys(notifications)) {
     if (!allowedKeys.has(key)) {
       errors.push(`notifications contains unknown field "${key}"`);

package/src/lib/run-events.js

@@ -26,6 +26,8 @@ export const VALID_RUN_EVENTS = [
   'gate_approved',
   'gate_failed',
   'budget_exceeded_warn',
+  'human_escalation_raised',
+  'human_escalation_resolved',
 ];
 
 /**

package/src/lib/run-loop.js

@@ -36,6 +36,7 @@ import { runAdmissionControl } from './admission-control.js';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { evaluateApprovalSlaReminders } from './notification-runner.js';
+import { readPreemptionMarker } from './intake.js';
 
 const DEFAULT_MAX_TURNS = 50;
 
@@ -128,6 +129,22 @@ export async function runLoop(root, config, callbacks, options = {}) {
       return makeResult(false, 'max_turns_reached', state, turnsExecuted, turnHistory, gatesApproved, errors);
     }
 
+    // ── Priority preemption check ────────────────────────────────────────
+    // If a p0 intent was injected via `agentxchain inject`, yield the run
+    // so the scheduler/continuous loop can pick up the injected work.
+    // Only preempt when no turns are currently active (avoid mid-dispatch
+    // interruption).
+    const activeTurnCount = getActiveTurnCount(state);
+    if (activeTurnCount === 0) {
+      const marker = readPreemptionMarker(root);
+      if (marker && marker.priority === 'p0') {
+        emit({ type: 'priority_injected', intent_id: marker.intent_id, priority: marker.priority });
+        const result = makeResult(false, 'priority_preempted', state, turnsExecuted, turnHistory, gatesApproved, errors);
+        result.preempted_by = marker.intent_id;
+        return result;
+      }
+    }
+
     // ── Determine concurrency mode ────────────────────────────────────────
     const maxConcurrent = getMaxConcurrentTurns(config, state.phase);
 

package/src/lib/run-provenance.js

@@ -3,12 +3,14 @@ const VALID_TRIGGERS = new Set([
   'continuation',
   'recovery',
   'intake',
+  'vision_scan',
   'schedule',
   'coordinator',
 ]);
 
 const VALID_CREATORS = new Set([
   'operator',
+  'continuous_loop',
   'coordinator',
 ]);
 
@@ -71,6 +73,8 @@ export function summarizeRunProvenance(provenance) {
     : normalized.trigger;
   const creatorSuffix = normalized.created_by === 'coordinator'
     ? ' (created by coordinator)'
+    : normalized.created_by === 'continuous_loop'
+      ? ' (created by continuous loop)'
     : '';
   const reasonSuffix = normalized.trigger_reason
     ? ` ("${normalized.trigger_reason}")`

package/src/lib/run-schedule.js

@@ -161,6 +161,49 @@ export function evaluateScheduleLaunchEligibility(root, config) {
   return { ok: false, status, reason: `run_${status}` };
 }
 
+function resolveScheduleTriggerReason(scheduleId, schedule) {
+  return schedule?.trigger_reason || `schedule:${scheduleId}`;
+}
+
+export function findContinuableScheduleRun(root, config, { scheduleId = null } = {}) {
+  const projectState = loadProjectState(root, config);
+  if (!projectState || projectState.status !== 'active' || !projectState.run_id) {
+    return { ok: false, reason: 'not_active' };
+  }
+
+  if (projectState.provenance?.trigger !== 'schedule') {
+    return { ok: false, reason: 'not_schedule_run' };
+  }
+
+  const scheduleState = readScheduleState(root, config);
+  const matches = Object.entries(config?.schedules || {}).filter(([candidateId, schedule]) => {
+    if (scheduleId && candidateId !== scheduleId) return false;
+
+    const record = scheduleState.schedules[candidateId];
+    if (record?.last_run_id === projectState.run_id) {
+      return true;
+    }
+
+    return projectState.provenance?.trigger_reason === resolveScheduleTriggerReason(candidateId, schedule);
+  });
+
+  if (matches.length === 0) {
+    return { ok: false, reason: 'no_matching_schedule' };
+  }
+
+  if (matches.length > 1) {
+    return { ok: false, reason: 'ambiguous_schedule_run' };
+  }
+
+  const [matchedId, matchedSchedule] = matches[0];
+  return {
+    ok: true,
+    schedule_id: matchedId,
+    schedule: matchedSchedule,
+    state: projectState,
+  };
+}
+
 // ── Daemon Health State ─────────────────────────────────────────────────────
 
 export function readDaemonState(root) {

package/src/lib/vision-reader.js

@@ -0,0 +1,229 @@
+/**
+ * Vision Reader — parse VISION.md and derive candidate intents.
+ *
+ * Reads a project-relative VISION.md, extracts sections and goals,
+ * compares against existing intake state (completed intents, run history),
+ * and produces ranked candidate intents for the continuous loop.
+ *
+ * IMPORTANT: The vision path is project-relative, never hardcoded to
+ * the agentxchain.dev repo. Each governed project has its own VISION.md.
+ *
+ * Spec: .planning/VISION_DRIVEN_CONTINUOUS_SPEC.md
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve as pathResolve, isAbsolute } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a VISION.md file into structured sections with goals.
+ *
+ * @param {string} content - Raw markdown content
+ * @returns {{ sections: Array<{ heading: string, level: number, goals: string[], raw: string }> }}
+ */
+export function parseVisionDocument(content) {
+  if (!content || typeof content !== 'string') {
+    return { sections: [] };
+  }
+
+  const lines = content.split('\n');
+  const sections = [];
+  let current = null;
+
+  for (const line of lines) {
+    // Match H2 or H3 headings (## or ###)
+    const headingMatch = line.match(/^(#{2,3})\s+(.+)$/);
+    if (headingMatch) {
+      if (current) sections.push(current);
+      current = {
+        heading: headingMatch[2].trim(),
+        level: headingMatch[1].length,
+        goals: [],
+        raw: '',
+      };
+      continue;
+    }
+
+    if (current) {
+      current.raw += line + '\n';
+
+      // Extract bullet points as goals
+      const bulletMatch = line.match(/^[-*]\s+\*{0,2}(.+?)\*{0,2}\s*$/);
+      if (bulletMatch) {
+        const goal = bulletMatch[1].trim();
+        if (goal.length > 5) { // skip trivially short bullets
+          current.goals.push(goal);
+        }
+      }
+    }
+  }
+
+  if (current) sections.push(current);
+
+  return { sections };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Load completed intent descriptions from the intake directory.
+ *
+ * @param {string} root - Project root
+ * @returns {string[]} Array of completed intent charters/descriptions
+ */
+export function loadCompletedIntentSignals(root) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  if (!existsSync(intentsDir)) return [];
+
+  const signals = [];
+  for (const file of readdirSync(intentsDir)) {
+    if (!file.endsWith('.json') || file.startsWith('.tmp-')) continue;
+    try {
+      const intent = JSON.parse(readFileSync(join(intentsDir, file), 'utf8'));
+      if (intent.status === 'completed' || intent.status === 'executing') {
+        const desc = intent.charter || intent.signal?.description || '';
+        if (desc) signals.push(desc.toLowerCase());
+      }
+    } catch {
+      // skip corrupt files
+    }
+  }
+  return signals;
+}
+
+/**
+ * Load existing intent signals (all statuses except suppressed/rejected) for dedup.
+ *
+ * @param {string} root - Project root
+ * @returns {string[]} Array of active intent charters/descriptions
+ */
+export function loadActiveIntentSignals(root) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  if (!existsSync(intentsDir)) return [];
+
+  const signals = [];
+  const skip = new Set(['suppressed', 'rejected']);
+  for (const file of readdirSync(intentsDir)) {
+    if (!file.endsWith('.json') || file.startsWith('.tmp-')) continue;
+    try {
+      const intent = JSON.parse(readFileSync(join(intentsDir, file), 'utf8'));
+      if (!skip.has(intent.status)) {
+        const desc = intent.charter || '';
+        if (desc) signals.push(desc.toLowerCase());
+      }
+    } catch {
+      // skip corrupt files
+    }
+  }
+  return signals;
+}
+
+/**
+ * Check whether a vision goal appears to be addressed by existing work.
+ *
+ * Uses keyword overlap: if >= 60% of significant words in the goal
+ * appear in any completed intent description, the goal is considered addressed.
+ *
+ * @param {string} goal - The vision goal text
+ * @param {string[]} completedSignals - Lowercased completed intent descriptions
+ * @returns {boolean}
+ */
+export function isGoalAddressed(goal, completedSignals) {
+  const words = extractSignificantWords(goal);
+  if (words.length === 0) return false;
+
+  for (const signal of completedSignals) {
+    const matchCount = words.filter(w => signal.includes(w)).length;
+    if (matchCount / words.length >= 0.6) return true;
+  }
+  return false;
+}
+
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+  'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+  'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+  'could', 'should', 'may', 'might', 'must', 'shall', 'can', 'that',
+  'this', 'these', 'those', 'it', 'its', 'they', 'them', 'their',
+  'not', 'no', 'nor', 'only', 'also', 'just', 'than', 'then',
+  'each', 'every', 'all', 'any', 'both', 'such', 'as', 'more',
+]);
+
+function extractSignificantWords(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+}
+
+// ---------------------------------------------------------------------------
+// Candidate derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive candidate intents from a VISION.md file.
+ *
+ * @param {string} root - Project root
+ * @param {string} visionPath - Absolute path to VISION.md
+ * @returns {{ ok: boolean, candidates: Array<{ section: string, goal: string, priority: string }>, error?: string }}
+ */
+export function deriveVisionCandidates(root, visionPath) {
+  if (!existsSync(visionPath)) {
+    return {
+      ok: false,
+      candidates: [],
+      error: `VISION.md not found at ${visionPath}. Create a .planning/VISION.md for your project to enable vision-driven operation.`,
+    };
+  }
+
+  let content;
+  try {
+    content = readFileSync(visionPath, 'utf8');
+  } catch (err) {
+    return { ok: false, candidates: [], error: `Cannot read VISION.md: ${err.message}` };
+  }
+
+  const { sections } = parseVisionDocument(content);
+  if (sections.length === 0) {
+    return { ok: false, candidates: [], error: 'VISION.md has no extractable sections.' };
+  }
+
+  const completedSignals = loadCompletedIntentSignals(root);
+  const activeSignals = loadActiveIntentSignals(root);
+  const allSignals = [...completedSignals, ...activeSignals];
+
+  const candidates = [];
+
+  for (const section of sections) {
+    for (const goal of section.goals) {
+      // Skip if this goal is already addressed
+      if (isGoalAddressed(goal, allSignals)) continue;
+
+      candidates.push({
+        section: section.heading,
+        goal,
+        priority: 'p2', // default; operators can override via triage_approval: "human"
+      });
+    }
+  }
+
+  return { ok: true, candidates };
+}
+
+/**
+ * Resolve a vision path relative to the project root.
+ *
+ * @param {string} root - Project root
+ * @param {string} visionPath - Path (absolute or project-relative)
+ * @returns {string} Absolute path
+ */
+export function resolveVisionPath(root, visionPath) {
+  if (isAbsolute(visionPath)) return visionPath;
+  return pathResolve(root, visionPath);
+}