agentxchain 0.8.8 → 2.1.1

package/src/lib/schema.js

@@ -29,6 +29,127 @@ export function validateStateSchema(data) {
   return { ok: errors.length === 0, errors };
 }
 
+export function validateGovernedStateSchema(data) {
+  const errors = [];
+  const VALID_RUN_STATUSES = ['idle', 'active', 'paused', 'blocked', 'completed', 'failed'];
+  const isV1_1 = data?.schema_version === '1.1';
+  const hasLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(data || {}, 'current_turn');
+
+  function validateTurn(turn, label) {
+    if (typeof turn !== 'object' || Array.isArray(turn)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+
+    if (typeof turn.turn_id !== 'string' || !turn.turn_id.trim()) errors.push(`${label}.turn_id must be a non-empty string`);
+    if (typeof turn.assigned_role !== 'string' || !turn.assigned_role.trim()) errors.push(`${label}.assigned_role must be a non-empty string`);
+    if (typeof turn.status !== 'string' || !turn.status.trim()) errors.push(`${label}.status must be a non-empty string`);
+    if (typeof turn.runtime_id !== 'string' || !turn.runtime_id.trim()) errors.push(`${label}.runtime_id must be a non-empty string`);
+    if (typeof turn.attempt !== 'number' || !Number.isInteger(turn.attempt)) errors.push(`${label}.attempt must be an integer`);
+    if (isV1_1 && (!Number.isInteger(turn.assigned_sequence) || turn.assigned_sequence < 1)) {
+      errors.push(`${label}.assigned_sequence must be an integer >= 1`);
+    }
+  }
+
+  if (data === null || typeof data !== 'object') {
+    return { ok: false, errors: ['governed state must be a JSON object'] };
+  }
+
+  const hasRunId = typeof data.run_id === 'string' && data.run_id.trim();
+  const hasNoActiveTurn = isV1_1
+    ? data.active_turns && typeof data.active_turns === 'object' && !Array.isArray(data.active_turns)
+      ? Object.keys(data.active_turns).length === 0
+      : false
+    : data.current_turn === null;
+  const isUninitializedIdle = data.run_id === null && data.status === 'idle' && hasNoActiveTurn;
+  if (!hasRunId && !isUninitializedIdle) {
+    errors.push('run_id must be a non-empty string, or null only for an idle state with no active turn');
+  }
+  if (typeof data.project_id !== 'string' || !data.project_id.trim()) errors.push('project_id must be a non-empty string');
+  if (typeof data.status !== 'string' || !data.status.trim()) {
+    errors.push('status must be a non-empty string');
+  } else if (!VALID_RUN_STATUSES.includes(data.status)) {
+    errors.push(`status must be one of: ${VALID_RUN_STATUSES.join(', ')}`);
+  }
+  if (typeof data.phase !== 'string' || !data.phase.trim()) errors.push('phase must be a non-empty string');
+
+  if (isV1_1) {
+    if (hasLegacyCurrentTurn) {
+      errors.push('current_turn is not allowed when schema_version is "1.1"; use active_turns');
+    }
+    if (!data.active_turns || typeof data.active_turns !== 'object' || Array.isArray(data.active_turns)) {
+      errors.push('active_turns must be an object when schema_version is "1.1"');
+    } else {
+      for (const [turnId, turn] of Object.entries(data.active_turns)) {
+        validateTurn(turn, `active_turns.${turnId}`);
+      }
+    }
+    if (!Number.isInteger(data.turn_sequence) || data.turn_sequence < 0) {
+      errors.push('turn_sequence must be an integer >= 0 when schema_version is "1.1"');
+    }
+  } else if ('current_turn' in data && data.current_turn !== null) {
+    validateTurn(data.current_turn, 'current_turn');
+  }
+
+  if ('phase_gate_status' in data && data.phase_gate_status !== null && typeof data.phase_gate_status !== 'object') {
+    errors.push('phase_gate_status must be an object');
+  }
+  if ('budget_status' in data && data.budget_status !== null && typeof data.budget_status !== 'object') {
+    errors.push('budget_status must be an object');
+  }
+  if (isV1_1 && 'budget_reservations' in data && data.budget_reservations !== null && typeof data.budget_reservations !== 'object') {
+    errors.push('budget_reservations must be an object when provided');
+  }
+
+  if (data.status === 'blocked') {
+    if (typeof data.blocked_on !== 'string' || !data.blocked_on.trim()) {
+      errors.push('blocked_on must be a non-empty string when status is "blocked"');
+    }
+    if (!data.blocked_reason || typeof data.blocked_reason !== 'object') {
+      errors.push('blocked_reason must be an object when status is "blocked"');
+    } else {
+      if (typeof data.blocked_reason.category !== 'string' || !data.blocked_reason.category.trim()) {
+        errors.push('blocked_reason.category must be a non-empty string');
+      }
+      if (typeof data.blocked_reason.blocked_at !== 'string' || !data.blocked_reason.blocked_at.trim()) {
+        errors.push('blocked_reason.blocked_at must be a non-empty string');
+      }
+      if (!('turn_id' in data.blocked_reason) || (data.blocked_reason.turn_id !== null && typeof data.blocked_reason.turn_id !== 'string')) {
+        errors.push('blocked_reason.turn_id must be a string or null');
+      }
+      const recovery = data.blocked_reason.recovery;
+      if (!recovery || typeof recovery !== 'object') {
+        errors.push('blocked_reason.recovery must be an object');
+      } else {
+        if (typeof recovery.typed_reason !== 'string' || !recovery.typed_reason.trim()) errors.push('blocked_reason.recovery.typed_reason must be a non-empty string');
+        if (typeof recovery.owner !== 'string' || !recovery.owner.trim()) errors.push('blocked_reason.recovery.owner must be a non-empty string');
+        if (typeof recovery.recovery_action !== 'string' || !recovery.recovery_action.trim()) errors.push('blocked_reason.recovery.recovery_action must be a non-empty string');
+        if (typeof recovery.turn_retained !== 'boolean') errors.push('blocked_reason.recovery.turn_retained must be a boolean');
+        if ('detail' in recovery && recovery.detail !== null && typeof recovery.detail !== 'string') {
+          errors.push('blocked_reason.recovery.detail must be a string or null');
+        }
+      }
+    }
+  }
+
+  if (data.status === 'paused' && !data.pending_phase_transition && !data.pending_run_completion) {
+    errors.push('paused state must include pending_phase_transition or pending_run_completion');
+  }
+
+  if (data.status === 'active' && data.blocked_on != null) {
+    errors.push('active state must not include blocked_on');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateProjectStateSchema(data) {
+  if (data && typeof data === 'object' && ('run_id' in data || 'current_turn' in data || 'active_turns' in data || 'phase_gate_status' in data)) {
+    return validateGovernedStateSchema(data);
+  }
+  return validateStateSchema(data);
+}
+
 export function validateConfigSchema(data) {
   const errors = [];
   if (data === null || typeof data !== 'object') {

package/src/lib/schemas/turn-result.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentxchain.dev/schemas/turn-result/v1",
+  "title": "AgentXchain Turn Result v1",
+  "description": "Structured output produced by every agent turn. The orchestrator validates and accepts/rejects based on this contract.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "run_id",
+    "turn_id",
+    "role",
+    "runtime_id",
+    "status",
+    "summary",
+    "decisions",
+    "objections",
+    "files_changed",
+    "verification",
+    "artifact",
+    "proposed_next_role"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": "1.0",
+      "description": "Must be '1.0' for v1 turn results."
+    },
+    "run_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Must match the current run. Format: run_XXXX..."
+    },
+    "turn_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Must match the current turn assignment. Format: turn-NNNN"
+    },
+    "role": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+$",
+      "description": "Must match the role assigned for this turn."
+    },
+    "runtime_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The runtime that executed this turn."
+    },
+    "status": {
+      "enum": ["completed", "blocked", "needs_human", "failed"],
+      "description": "Outcome of this turn."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable summary of what happened."
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "category", "statement", "rationale"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^DEC-\\d+$",
+            "description": "Decision ID, e.g. DEC-014"
+          },
+          "category": {
+            "enum": ["implementation", "architecture", "scope", "process", "quality", "release"]
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "objections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "statement"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^OBJ-\\d+$",
+            "description": "Objection ID, e.g. OBJ-007"
+          },
+          "severity": {
+            "enum": ["low", "medium", "high", "blocking"]
+          },
+          "against_turn_id": {
+            "type": "string",
+            "description": "Turn that this objection challenges."
+          },
+          "against_decision_id": {
+            "type": "string",
+            "description": "Decision ID being challenged."
+          },
+          "statement": {
+            "type": "string",
+            "minLength": 1
+          },
+          "proposed_resolution": {
+            "type": "string"
+          },
+          "status": {
+            "enum": ["raised", "acknowledged", "resolved", "escalated", "resolved_by_human", "resolved_by_director"],
+            "default": "raised"
+          }
+        }
+      }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths of files modified during this turn. Must match observed diff for authoritative runtimes."
+    },
+    "artifacts_created": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths of planning/review artifacts created (under .planning/ or .agentxchain/)."
+    },
+    "verification": {
+      "type": "object",
+      "required": ["status"],
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "enum": ["pass", "fail", "skipped"],
+          "description": "Raw status from agent. Orchestrator may normalize to attested_pass or not_reproducible."
+        },
+        "commands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Verification commands that were run."
+        },
+        "evidence_summary": {
+          "type": "string",
+          "description": "Human-readable description of verification evidence."
+        },
+        "machine_evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["command", "exit_code"],
+            "properties": {
+              "command": { "type": "string" },
+              "exit_code": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": ["workspace", "patch", "commit", "review"],
+          "description": "workspace = direct local changes, patch = unified diff, commit = git commit, review = no code changes"
+        },
+        "ref": {
+          "type": ["string", "null"],
+          "description": "Git SHA, patch path, or null for review-only."
+        },
+        "diff_summary": {
+          "type": "string"
+        }
+      }
+    },
+    "proposed_next_role": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+$|^human$",
+      "description": "Role that should work next. Must be in routing allowlist or 'human'."
+    },
+    "phase_transition_request": {
+      "type": ["string", "null"],
+      "description": "If the agent believes the phase should advance, name the target phase."
+    },
+    "run_completion_request": {
+      "type": ["boolean", "null"],
+      "description": "Set to true only in the final phase when the run should complete. Mutually exclusive with phase_transition_request."
+    },
+    "needs_human_reason": {
+      "type": ["string", "null"],
+      "description": "If status is needs_human, explain why."
+    },
+    "cost": {
+      "type": "object",
+      "properties": {
+        "input_tokens": { "type": "integer", "minimum": 0 },
+        "output_tokens": { "type": "integer", "minimum": 0 },
+        "usd": { "type": "number", "minimum": 0 }
+      }
+    }
+  }
+}

package/src/lib/token-budget.js

@@ -0,0 +1,206 @@
+/**
+ * Token budget evaluator for preflight tokenization.
+ *
+ * Combines the context section parser, context compressor, and token counter
+ * to produce a TokenBudgetReport and effective context for api_proxy dispatch.
+ *
+ * This is a pure computation helper — it does not perform network dispatch,
+ * write audit artifacts, or mutate state.
+ */
+
+import { countTokens } from './token-counter.js';
+import { parseContextSections, renderContextSections } from './context-section-parser.js';
+import { compressContextSections } from './context-compressor.js';
+import { getDispatchEffectiveContextPath } from './turn-paths.js';
+
+const SEPARATOR = '\n\n---\n\n';
+
+const SYSTEM_PROMPT = [
+  'You are acting as a governed agent in an AgentXchain protocol run.',
+  'Your task and rules are described in the user message.',
+  'You MUST respond with a valid JSON object matching the turn result schema provided in the prompt.',
+  'Do NOT wrap the JSON in markdown code fences. Respond with raw JSON only.',
+].join('\n');
+
+/**
+ * Evaluate the token budget for a preflight tokenization check.
+ *
+ * @param {object} params
+ * @param {string} params.promptMd - Full PROMPT.md text
+ * @param {string} params.contextMd - Full CONTEXT.md text (may be empty)
+ * @param {string} params.provider - Provider name (e.g. "anthropic")
+ * @param {string} params.model - Model identifier
+ * @param {string} params.runtimeId - Runtime identifier for the report
+ * @param {string} params.runId - Run identifier for the report
+ * @param {string} params.turnId - Turn identifier for the report
+ * @param {number} params.contextWindowTokens - Total context window size
+ * @param {number} params.maxOutputTokens - Reserved output tokens
+ * @param {number} params.safetyMarginTokens - Safety margin tokens
+ * @returns {TokenBudgetResult}
+ */
+export function evaluateTokenBudget({
+  promptMd,
+  contextMd,
+  provider,
+  model,
+  runtimeId,
+  runId,
+  turnId,
+  contextWindowTokens,
+  maxOutputTokens,
+  safetyMarginTokens,
+}) {
+  const reservedOutputTokens = maxOutputTokens || 4096;
+  const safetyMargin = safetyMarginTokens ?? 2048;
+  const availableInputTokens = contextWindowTokens - reservedOutputTokens - safetyMargin;
+
+  // Count immutable parts
+  const systemPromptTokens = countTokens(SYSTEM_PROMPT, provider);
+  const promptTokens = countTokens(promptMd || '', provider);
+  const hasSeparator = !!(contextMd && contextMd.trim());
+  const separatorTokens = hasSeparator ? countTokens(SEPARATOR, provider) : 0;
+  const immutableTokens = systemPromptTokens + promptTokens + separatorTokens;
+
+  // Build base report fields
+  const baseReport = {
+    provider,
+    model,
+    runtime_id: runtimeId,
+    run_id: runId,
+    turn_id: turnId,
+    tokenizer: 'provider_local',
+    context_window_tokens: contextWindowTokens,
+    reserved_output_tokens: reservedOutputTokens,
+    safety_margin_tokens: safetyMargin,
+    available_input_tokens: availableInputTokens,
+    system_prompt_tokens: systemPromptTokens,
+    prompt_tokens: promptTokens,
+    separator_tokens: separatorTokens,
+  };
+
+  // Prompt-only overflow: if immutable parts alone exceed budget, fail immediately
+  if (immutableTokens > availableInputTokens) {
+    const originalContextTokens = hasSeparator
+      ? countTokens(contextMd, provider)
+      : 0;
+
+    return {
+      sent_to_provider: false,
+      effective_context: hasSeparator ? contextMd : '',
+      report: {
+        ...baseReport,
+        original_context_tokens: originalContextTokens,
+        final_context_tokens: originalContextTokens,
+        estimated_input_tokens: immutableTokens + originalContextTokens,
+        truncated: false,
+        sent_to_provider: false,
+        effective_context_path: getDispatchEffectiveContextPath(turnId),
+        sections: [],
+      },
+    };
+  }
+
+  // No context case
+  if (!hasSeparator) {
+    return {
+      sent_to_provider: true,
+      effective_context: '',
+      report: {
+        ...baseReport,
+        original_context_tokens: 0,
+        final_context_tokens: 0,
+        estimated_input_tokens: immutableTokens,
+        truncated: false,
+        sent_to_provider: true,
+        effective_context_path: getDispatchEffectiveContextPath(turnId),
+        sections: [],
+      },
+    };
+  }
+
+  // Parse context into sections and count original tokens per section
+  const sections = parseContextSections(contextMd);
+  const originalTokensById = new Map();
+  for (const section of sections) {
+    originalTokensById.set(section.id, countTokens(section.content, provider));
+  }
+
+  const originalContextTokens = countTokens(contextMd, provider);
+
+  // Budget callback for the compressor: check if the full outbound request fits
+  function fitsInBudget(effectiveContext) {
+    const contextTokens = countTokens(effectiveContext, provider);
+    return immutableTokens + contextTokens <= availableInputTokens;
+  }
+
+  // Check if it fits without compression
+  if (fitsInBudget(contextMd)) {
+    const sectionActions = sections.map((s) => ({
+      id: s.id,
+      required: s.required,
+      original_tokens: originalTokensById.get(s.id),
+      final_tokens: originalTokensById.get(s.id),
+      action: 'kept',
+    }));
+
+    return {
+      sent_to_provider: true,
+      effective_context: contextMd,
+      report: {
+        ...baseReport,
+        original_context_tokens: originalContextTokens,
+        final_context_tokens: originalContextTokens,
+        estimated_input_tokens: immutableTokens + originalContextTokens,
+        truncated: false,
+        sent_to_provider: true,
+        effective_context_path: getDispatchEffectiveContextPath(turnId),
+        sections: sectionActions,
+      },
+    };
+  }
+
+  // Run compression
+  const compressionResult = compressContextSections(sections, fitsInBudget);
+  const effectiveContext = compressionResult.effective_context;
+  const finalContextTokens = countTokens(effectiveContext, provider);
+  const estimatedInputTokens = immutableTokens + finalContextTokens;
+  const sentToProvider = !compressionResult.exhausted;
+
+  // Build per-section actions with token counts
+  const sectionActions = compressionResult.actions.map((a) => {
+    let finalTokens;
+    if (a.action === 'dropped') {
+      finalTokens = 0;
+    } else if (a.action === 'truncated') {
+      const remaining = compressionResult.sections.find((s) => s.id === a.id);
+      finalTokens = remaining ? countTokens(remaining.content, provider) : 0;
+    } else {
+      finalTokens = originalTokensById.get(a.id) ?? 0;
+    }
+
+    return {
+      id: a.id,
+      required: a.required,
+      original_tokens: originalTokensById.get(a.id) ?? 0,
+      final_tokens: finalTokens,
+      action: a.action,
+    };
+  });
+
+  return {
+    sent_to_provider: sentToProvider,
+    effective_context: effectiveContext,
+    report: {
+      ...baseReport,
+      original_context_tokens: originalContextTokens,
+      final_context_tokens: finalContextTokens,
+      estimated_input_tokens: estimatedInputTokens,
+      truncated: compressionResult.steps_applied > 0,
+      sent_to_provider: sentToProvider,
+      effective_context_path: getDispatchEffectiveContextPath(turnId),
+      sections: sectionActions,
+    },
+  };
+}
+
+export { SYSTEM_PROMPT, SEPARATOR };

package/src/lib/token-counter.js

@@ -0,0 +1,27 @@
+import { countTokens as countAnthropicTokens } from '@anthropic-ai/tokenizer';
+
+const SUPPORTED_TOKEN_COUNTER_PROVIDERS = ['anthropic'];
+
+export { SUPPORTED_TOKEN_COUNTER_PROVIDERS };
+
+export function countTokens(text, provider = 'anthropic') {
+  const normalizedProvider = String(provider || '').trim().toLowerCase();
+
+  if (!SUPPORTED_TOKEN_COUNTER_PROVIDERS.includes(normalizedProvider)) {
+    throw new Error(
+      `Unsupported token counter provider "${provider}". Supported: ${SUPPORTED_TOKEN_COUNTER_PROVIDERS.join(', ')}`
+    );
+  }
+
+  const normalizedText = String(text ?? '');
+  if (!normalizedText) {
+    return 0;
+  }
+
+  const tokens = countAnthropicTokens(normalizedText);
+  if (!Number.isInteger(tokens) || tokens < 0) {
+    throw new Error(`Anthropic tokenizer returned invalid token count: ${tokens}`);
+  }
+
+  return tokens;
+}

package/src/lib/turn-paths.js

@@ -0,0 +1,67 @@
+const DISPATCH_ROOT = '.agentxchain/dispatch';
+const DISPATCH_INDEX_PATH = `${DISPATCH_ROOT}/index.json`;
+const DISPATCH_TURNS_DIR = `${DISPATCH_ROOT}/turns`;
+const STAGING_ROOT = '.agentxchain/staging';
+
+export function getDispatchTurnDir(turnId) {
+  return `${DISPATCH_TURNS_DIR}/${turnId}`;
+}
+
+export function getDispatchPromptPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/PROMPT.md`;
+}
+
+export function getDispatchContextPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/CONTEXT.md`;
+}
+
+export function getDispatchAssignmentPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/ASSIGNMENT.json`;
+}
+
+export function getDispatchApiRequestPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/API_REQUEST.json`;
+}
+
+export function getDispatchTokenBudgetPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/TOKEN_BUDGET.json`;
+}
+
+export function getDispatchEffectiveContextPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/CONTEXT.effective.md`;
+}
+
+export function getDispatchManifestPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/MANIFEST.json`;
+}
+
+export function getDispatchLogPath(turnId) {
+  return `${getDispatchTurnDir(turnId)}/stdout.log`;
+}
+
+export function getTurnStagingDir(turnId) {
+  return `${STAGING_ROOT}/${turnId}`;
+}
+
+export function getTurnStagingResultPath(turnId) {
+  return `${getTurnStagingDir(turnId)}/turn-result.json`;
+}
+
+export function getTurnProviderResponsePath(turnId) {
+  return `${getTurnStagingDir(turnId)}/provider-response.json`;
+}
+
+export function getTurnApiErrorPath(turnId) {
+  return `${getTurnStagingDir(turnId)}/api-error.json`;
+}
+
+export function getTurnRetryTracePath(turnId) {
+  return `${getTurnStagingDir(turnId)}/retry-trace.json`;
+}
+
+export {
+  DISPATCH_ROOT,
+  DISPATCH_INDEX_PATH,
+  DISPATCH_TURNS_DIR,
+  STAGING_ROOT,
+};