agentxchain 0.8.7 → 2.1.1

package/src/lib/config.js

@@ -1,36 +1,167 @@
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, parse as pathParse, resolve } from 'path';
+import { safeParseJson, validateConfigSchema, validateLockSchema, validateProjectStateSchema, validateStateSchema } from './schema.js';
+import { loadNormalizedConfig } from './normalized-config.js';
+import { safeWriteJson } from './safe-write.js';
+import { normalizeGovernedStateShape, getActiveTurn } from './governed-state.js';
+
+function attachLegacyCurrentTurnAlias(state) {
+  if (!state || typeof state !== 'object') {
+    return state;
+  }
+
+  const existing = Object.getOwnPropertyDescriptor(state, 'current_turn');
+  if (existing && existing.enumerable === false) {
+    return state;
+  }
+
+  Object.defineProperty(state, 'current_turn', {
+    configurable: true,
+    enumerable: false,
+    get() {
+      return getActiveTurn(state);
+    },
+  });
+
+  return state;
+}
 
 const CONFIG_FILE = 'agentxchain.json';
 const LOCK_FILE = 'lock.json';
 const STATE_FILE = 'state.json';
 
 export function findProjectRoot(startDir = process.cwd()) {
-  let dir = startDir;
-  while (dir !== '/') {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = pathParse(dir);
+  while (true) {
     if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    if (dir === fsRoot) return null;
     dir = join(dir, '..');
   }
-  return null;
 }
 
 export function loadConfig(dir = process.cwd()) {
   const root = findProjectRoot(dir);
   if (!root) return null;
-  const raw = readFileSync(join(root, CONFIG_FILE), 'utf8');
-  return { root, config: JSON.parse(raw) };
+  const filePath = join(root, CONFIG_FILE);
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateConfigSchema);
+  if (!result.ok) {
+    console.error(`  Warning: agentxchain.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return { root, config: result.data };
+}
+
+export function loadProjectContext(dir = process.cwd()) {
+  const root = findProjectRoot(dir);
+  if (!root) return null;
+
+  const filePath = join(root, CONFIG_FILE);
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`  Warning: agentxchain.json is invalid JSON: ${err.message}`);
+    return null;
+  }
+
+  const normalized = loadNormalizedConfig(parsed, root);
+  if (!normalized.ok) {
+    console.error(`  Warning: agentxchain.json has issues: ${normalized.errors.join(', ')}`);
+    return null;
+  }
+
+  return {
+    root,
+    rawConfig: parsed,
+    config: normalized.normalized,
+    version: normalized.version,
+  };
 }
 
 export function loadLock(root) {
-  const path = join(root, LOCK_FILE);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, 'utf8'));
+  const filePath = join(root, LOCK_FILE);
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateLockSchema);
+  if (!result.ok) {
+    console.error(`  Warning: lock.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return result.data;
 }
 
 export function loadState(root) {
-  const path = join(root, STATE_FILE);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, 'utf8'));
+  const filePath = join(root, STATE_FILE);
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const result = safeParseJson(raw, validateStateSchema);
+  if (!result.ok) {
+    console.error(`  Warning: state.json has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  return result.data;
+}
+
+export function loadProjectState(root, config) {
+  const relPath = config?.files?.state || STATE_FILE;
+  const filePath = join(root, relPath);
+  if (!existsSync(filePath)) return null;
+
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const parsed = safeParseJson(raw);
+  if (!parsed.ok) {
+    console.error(`  Warning: ${relPath} has issues: ${parsed.errors.join(', ')}`);
+    return null;
+  }
+
+  let stateData = parsed.data;
+  if (config?.protocol_mode === 'governed') {
+    const normalized = normalizeGovernedStateShape(stateData);
+    stateData = normalized.state;
+    if (normalized.changed) {
+      safeWriteJson(filePath, stateData);
+    }
+  }
+
+  const result = validateProjectStateSchema(stateData);
+  if (!result.ok) {
+    console.error(`  Warning: ${relPath} has issues: ${result.errors.join(', ')}`);
+    return null;
+  }
+  if (config?.protocol_mode === 'governed') {
+    return attachLegacyCurrentTurnAlias(stateData);
+  }
+  return stateData;
 }
 
 export { CONFIG_FILE, LOCK_FILE, STATE_FILE };

package/src/lib/context-compressor.js

@@ -0,0 +1,121 @@
+/**
+ * Bounded context compressor for preflight tokenization.
+ *
+ * Takes parsed context sections and applies the v1.1 deterministic
+ * compression order from PREEMPTIVE_TOKENIZATION_SPEC.md §4.
+ * Does not perform token counting — that is the caller's responsibility.
+ */
+
+import { renderContextSections } from './context-section-parser.js';
+
+/**
+ * The fixed compression order. Each step is tried in sequence until the
+ * caller's budget check passes or all steps are exhausted.
+ */
+const COMPRESSION_STEPS = [
+  { id: 'budget', action: 'drop' },
+  { id: 'phase_gate_status', action: 'drop' },
+  { id: 'gate_required_files', action: 'drop' },
+  { id: 'last_turn_objections', action: 'drop' },
+  { id: 'last_turn_decisions', action: 'drop' },
+  { id: 'last_turn_summary', action: 'truncate', max_chars: 240 },
+  { id: 'last_turn_summary', action: 'drop' },
+];
+
+export { COMPRESSION_STEPS };
+
+/**
+ * @typedef {Object} SectionAction
+ * @property {string} id - Section ID
+ * @property {boolean} required - Whether the section is sticky
+ * @property {number} original_tokens - Token count before compression (set by caller)
+ * @property {number} final_tokens - Token count after compression (set by caller)
+ * @property {'kept' | 'dropped' | 'truncated'} action - What happened to this section
+ */
+
+/**
+ * @typedef {Object} CompressionResult
+ * @property {Array<Object>} sections - The (possibly compressed) section array
+ * @property {Array<SectionAction>} actions - Per-section action log
+ * @property {string} effective_context - Rendered markdown of the compressed sections
+ * @property {boolean} exhausted - True if all compression steps were applied
+ * @property {number} steps_applied - Number of compression steps applied
+ */
+
+/**
+ * Compress parsed context sections using the v1.1 bounded compression order.
+ *
+ * The `fitsInBudget` callback is called after each compression step with the
+ * current effective context string. It should return true if the full outbound
+ * request (including system prompt, PROMPT.md, separator, and the provided
+ * effective context) fits within the available input token budget.
+ *
+ * @param {Array<Object>} sections - Parsed sections from parseContextSections()
+ * @param {(effectiveContext: string) => boolean} fitsInBudget - Budget check callback
+ * @returns {CompressionResult}
+ */
+export function compressContextSections(sections, fitsInBudget) {
+  // Deep copy so we don't mutate the caller's array
+  let working = sections.map((s) => ({ ...s }));
+
+  // Track actions per section
+  const actionMap = new Map(
+    sections.map((s) => [s.id, { id: s.id, required: s.required, action: 'kept' }])
+  );
+
+  // Check if it already fits before any compression
+  let effectiveContext = renderContextSections(working);
+  if (fitsInBudget(effectiveContext)) {
+    return buildResult(working, actionMap, effectiveContext, false, 0);
+  }
+
+  // Apply compression steps in order
+  let stepsApplied = 0;
+  for (const step of COMPRESSION_STEPS) {
+    const sectionIndex = working.findIndex((s) => s.id === step.id);
+    if (sectionIndex === -1) {
+      // Section not present — skip this step
+      continue;
+    }
+
+    const section = working[sectionIndex];
+
+    // Safety: never compress a required/sticky section
+    if (section.required) {
+      continue;
+    }
+
+    if (step.action === 'drop') {
+      working = working.filter((s) => s.id !== step.id);
+      actionMap.get(step.id).action = 'dropped';
+      stepsApplied += 1;
+    } else if (step.action === 'truncate') {
+      const original = section.content;
+      if (original.length > step.max_chars) {
+        section.content = original.slice(0, step.max_chars);
+        // Only count as a step if we actually truncated
+        actionMap.get(step.id).action = 'truncated';
+        stepsApplied += 1;
+      }
+    }
+
+    effectiveContext = renderContextSections(working);
+    if (fitsInBudget(effectiveContext)) {
+      return buildResult(working, actionMap, effectiveContext, false, stepsApplied);
+    }
+  }
+
+  // All compression steps exhausted and still doesn't fit
+  effectiveContext = renderContextSections(working);
+  return buildResult(working, actionMap, effectiveContext, true, stepsApplied);
+}
+
+function buildResult(sections, actionMap, effectiveContext, exhausted, stepsApplied) {
+  return {
+    sections,
+    actions: Array.from(actionMap.values()),
+    effective_context: effectiveContext,
+    exhausted,
+    steps_applied: stepsApplied,
+  };
+}

package/src/lib/context-section-parser.js

@@ -0,0 +1,220 @@
+const CONTEXT_TITLE = '# Execution Context';
+
+const SECTION_DEFINITIONS = [
+  { id: 'current_state', header: 'Current State', required: true },
+  { id: 'budget', header: null, required: false },
+  { id: 'last_turn_header', header: 'Last Accepted Turn', required: true },
+  { id: 'last_turn_summary', header: null, required: false },
+  { id: 'last_turn_decisions', header: null, required: false },
+  { id: 'last_turn_objections', header: null, required: false },
+  { id: 'blockers', header: 'Blockers', required: true },
+  { id: 'escalation', header: 'Escalation', required: true },
+  { id: 'gate_required_files', header: 'Gate Required Files', required: false },
+  { id: 'phase_gate_status', header: 'Phase Gate Status', required: false },
+];
+
+const REQUIRED_BY_ID = new Map(SECTION_DEFINITIONS.map((section) => [section.id, section.required]));
+const HEADER_TO_ID = new Map(
+  SECTION_DEFINITIONS
+    .filter((section) => section.header)
+    .map((section) => [section.header, section.id])
+);
+
+const BUDGET_LINE_PATTERN = /^- \*\*Budget (spent|remaining):\*\*/;
+const SUMMARY_LINE_PATTERN = /^- \*\*Summary:\*\*/;
+const DECISIONS_LINE_PATTERN = /^- \*\*Decisions:\*\*/;
+const OBJECTIONS_LINE_PATTERN = /^- \*\*Objections:\*\*/;
+
+export { CONTEXT_TITLE, SECTION_DEFINITIONS };
+
+export function parseContextSections(contextMd) {
+  const normalized = normalizeNewlines(contextMd);
+  const topLevelSections = splitTopLevelSections(normalized);
+  const parsedSections = [];
+
+  const currentStateBody = topLevelSections.get('Current State');
+  if (currentStateBody) {
+    const budgetLines = currentStateBody.filter((line) => BUDGET_LINE_PATTERN.test(line));
+    const stickyLines = currentStateBody.filter((line) => !BUDGET_LINE_PATTERN.test(line));
+
+    pushSection(parsedSections, 'current_state', stickyLines);
+    pushSection(parsedSections, 'budget', budgetLines);
+  }
+
+  const lastAcceptedTurnBody = topLevelSections.get('Last Accepted Turn');
+  if (lastAcceptedTurnBody) {
+    const {
+      headerLines,
+      summaryLines,
+      decisionsLines,
+      objectionsLines,
+    } = splitLastAcceptedTurn(lastAcceptedTurnBody);
+
+    pushSection(parsedSections, 'last_turn_header', headerLines);
+    pushSection(parsedSections, 'last_turn_summary', summaryLines);
+    pushSection(parsedSections, 'last_turn_decisions', decisionsLines);
+    pushSection(parsedSections, 'last_turn_objections', objectionsLines);
+  }
+
+  for (const [header, id] of HEADER_TO_ID.entries()) {
+    if (header === 'Current State' || header === 'Last Accepted Turn') continue;
+    pushSection(parsedSections, id, topLevelSections.get(header));
+  }
+
+  return SECTION_DEFINITIONS
+    .map((definition) => parsedSections.find((section) => section.id === definition.id))
+    .filter(Boolean);
+}
+
+export function renderContextSections(sections) {
+  const sectionMap = new Map((sections || []).map((section) => [section.id, section]));
+  const lines = [CONTEXT_TITLE, ''];
+
+  appendTopLevelSection(lines, 'Current State', [
+    sectionMap.get('current_state')?.content,
+    sectionMap.get('budget')?.content,
+  ]);
+
+  appendTopLevelSection(lines, 'Last Accepted Turn', [
+    sectionMap.get('last_turn_header')?.content,
+    sectionMap.get('last_turn_summary')?.content,
+    sectionMap.get('last_turn_decisions')?.content,
+    sectionMap.get('last_turn_objections')?.content,
+  ]);
+
+  appendTopLevelSection(lines, 'Blockers', [sectionMap.get('blockers')?.content]);
+  appendTopLevelSection(lines, 'Escalation', [sectionMap.get('escalation')?.content]);
+  appendTopLevelSection(lines, 'Gate Required Files', [sectionMap.get('gate_required_files')?.content]);
+  appendTopLevelSection(lines, 'Phase Gate Status', [sectionMap.get('phase_gate_status')?.content]);
+
+  return `${lines.join('\n')}\n`;
+}
+
+function appendTopLevelSection(lines, header, fragments) {
+  const content = fragments
+    .filter((fragment) => typeof fragment === 'string' && fragment.length > 0)
+    .join('\n');
+
+  if (!content) return;
+
+  lines.push(`## ${header}`);
+  lines.push('');
+  lines.push(...content.split('\n'));
+  lines.push('');
+}
+
+function splitTopLevelSections(contextMd) {
+  const lines = normalizeNewlines(contextMd).split('\n');
+  const sectionStarts = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].startsWith('## ')) {
+      sectionStarts.push(index);
+    }
+  }
+
+  const sections = new Map();
+  for (let index = 0; index < sectionStarts.length; index += 1) {
+    const start = sectionStarts[index];
+    const end = sectionStarts[index + 1] ?? lines.length;
+    const header = lines[start].slice(3).trim();
+    const bodyLines = trimBlankLines(lines.slice(start + 1, end));
+    sections.set(header, bodyLines);
+  }
+
+  return sections;
+}
+
+function splitLastAcceptedTurn(lines) {
+  const headerLines = [];
+  let summaryLines = [];
+  let decisionsLines = [];
+  let objectionsLines = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+
+    if (SUMMARY_LINE_PATTERN.test(line)) {
+      summaryLines = [line];
+      continue;
+    }
+
+    if (DECISIONS_LINE_PATTERN.test(line)) {
+      const { blockLines, nextIndex } = consumeIndentedBlock(lines, index);
+      decisionsLines = blockLines;
+      index = nextIndex - 1;
+      continue;
+    }
+
+    if (OBJECTIONS_LINE_PATTERN.test(line)) {
+      const { blockLines, nextIndex } = consumeIndentedBlock(lines, index);
+      objectionsLines = blockLines;
+      index = nextIndex - 1;
+      continue;
+    }
+
+    headerLines.push(line);
+  }
+
+  return {
+    headerLines: trimBlankLines(headerLines),
+    summaryLines: trimBlankLines(summaryLines),
+    decisionsLines: trimBlankLines(decisionsLines),
+    objectionsLines: trimBlankLines(objectionsLines),
+  };
+}
+
+function consumeIndentedBlock(lines, startIndex) {
+  const blockLines = [lines[startIndex]];
+  let index = startIndex + 1;
+
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.startsWith('  ') || line.trim() === '') {
+      blockLines.push(line);
+      index += 1;
+      continue;
+    }
+    break;
+  }
+
+  return {
+    blockLines: trimBlankLines(blockLines),
+    nextIndex: index,
+  };
+}
+
+function pushSection(target, id, lines) {
+  const normalizedLines = trimBlankLines(lines || []);
+  if (!normalizedLines.length) return;
+
+  target.push({
+    id,
+    content: normalizedLines.join('\n'),
+    required: REQUIRED_BY_ID.get(id) === true,
+  });
+}
+
+function trimBlankLines(lines) {
+  return trimTrailingBlankLines(trimLeadingBlankLines(lines));
+}
+
+function trimLeadingBlankLines(lines) {
+  let start = 0;
+  while (start < lines.length && lines[start].trim() === '') {
+    start += 1;
+  }
+  return lines.slice(start);
+}
+
+function trimTrailingBlankLines(lines) {
+  let end = lines.length;
+  while (end > 0 && lines[end - 1].trim() === '') {
+    end -= 1;
+  }
+  return lines.slice(0, end);
+}
+
+function normalizeNewlines(value) {
+  return String(value || '').replace(/\r\n/g, '\n');
+}