agentxchain 2.86.0 → 2.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.86.0",
+  "version": "2.88.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/lib/dispatch-bundle.js

@@ -124,6 +124,12 @@ export function writeDispatchBundle(root, state, config, opts = {}) {
   if (turn.conflict_context) {
     assignment.conflict_context = turn.conflict_context;
   }
+  if (turn.delegation_context) {
+    assignment.delegation_context = turn.delegation_context;
+  }
+  if (turn.delegation_review) {
+    assignment.delegation_review = turn.delegation_review;
+  }
   if (warnings.length > 0) {
     assignment.advisory_warnings = warnings.map((message) => ({ code: 'advisory_scope_overlap', message }));
   }
@@ -547,6 +553,52 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
+  // Delegation context (when this turn is a delegated sub-task)
+  if (turn.delegation_context) {
+    const dc = turn.delegation_context;
+    lines.push('## Delegation Context');
+    lines.push('');
+    lines.push('You are executing a delegated sub-task.');
+    lines.push('');
+    lines.push(`- **Delegated by:** ${dc.parent_role} (turn ${dc.parent_turn_id})`);
+    lines.push(`- **Charter:** ${dc.charter}`);
+    if (Array.isArray(dc.acceptance_contract) && dc.acceptance_contract.length > 0) {
+      lines.push('- **Acceptance contract:**');
+      for (const req of dc.acceptance_contract) {
+        lines.push(`  - ${req}`);
+      }
+    }
+    lines.push('');
+    lines.push('Focus exclusively on the charter above. Do not expand scope beyond the delegation.');
+    lines.push('');
+  }
+
+  // Delegation review context (when this turn reviews completed delegations)
+  if (turn.delegation_review) {
+    const dr = turn.delegation_review;
+    lines.push('## Delegation Review');
+    lines.push('');
+    lines.push('Your delegated sub-tasks have been completed. Review the results below.');
+    lines.push('');
+    for (const result of dr.results || []) {
+      lines.push(`### ${result.delegation_id} → ${result.to_role}`);
+      lines.push('');
+      lines.push(`- **Charter:** ${result.charter}`);
+      lines.push(`- **Status:** ${result.status}`);
+      lines.push(`- **Summary:** ${result.summary}`);
+      if (result.files_changed?.length > 0) {
+        lines.push(`- **Files changed:** ${result.files_changed.join(', ')}`);
+      }
+      if (result.verification?.status) {
+        lines.push(`- **Verification:** ${result.verification.status}`);
+      }
+      lines.push('');
+    }
+    lines.push('Evaluate whether each delegation met its acceptance contract.');
+    lines.push('Your turn result should assess the delegation outcomes and decide next steps.');
+    lines.push('');
+  }
+
   // Inherited context from parent run (when --inherit-context was used)
   if (state.inherited_context) {
     // First turn gets the full rendering; subsequent turns get compact

package/src/lib/governed-state.js

@@ -2065,24 +2065,53 @@ export function assignGovernedTurn(root, config, roleId) {
   // Record which turns are concurrent siblings (for conflict detection context)
   const concurrentWith = Object.keys(activeTurns);
 
+  // Build the new turn object
+  const newTurn = {
+    turn_id: turnId,
+    assigned_role: roleId,
+    status: 'running',
+    attempt: 1,
+    started_at: now,
+    deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
+    runtime_id: runtimeId,
+    baseline,
+    assigned_sequence: nextSequence,
+    concurrent_with: concurrentWith,
+  };
+
+  // Attach delegation context if this turn fulfills a pending delegation
+  const delegationQueue = state.delegation_queue || [];
+  const pendingDelegation = delegationQueue.find(d => d.status === 'pending' && d.to_role === roleId);
+  if (pendingDelegation) {
+    newTurn.delegation_context = {
+      delegation_id: pendingDelegation.delegation_id,
+      parent_turn_id: pendingDelegation.parent_turn_id,
+      parent_role: pendingDelegation.parent_role,
+      charter: pendingDelegation.charter,
+      acceptance_contract: pendingDelegation.acceptance_contract,
+    };
+    // Mark the delegation as active
+    pendingDelegation.status = 'active';
+    pendingDelegation.child_turn_id = turnId;
+  }
+
+  // Attach delegation review context if a review is pending for this role
+  const pendingReview = state.pending_delegation_review;
+  if (pendingReview && pendingReview.parent_role === roleId && !pendingDelegation) {
+    newTurn.delegation_review = {
+      parent_turn_id: pendingReview.parent_turn_id,
+      results: pendingReview.delegation_results,
+    };
+  }
+
   const updatedState = {
     ...state,
     turn_sequence: nextSequence,
     budget_reservations: reservations,
+    delegation_queue: delegationQueue,
     active_turns: {
       ...activeTurns,
-      [turnId]: {
-        turn_id: turnId,
-        assigned_role: roleId,
-        status: 'running',
-        attempt: 1,
-        started_at: now,
-        deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
-        runtime_id: runtimeId,
-        baseline,
-        assigned_sequence: nextSequence,
-        concurrent_with: concurrentWith,
-      },
+      [turnId]: newTurn,
     },
   };
 
@@ -2649,6 +2678,97 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     },
   };
 
+  // ── Delegation queue management ──────────────────────────────────────────
+  // Initialize delegation queue if not present
+  if (!updatedState.delegation_queue) {
+    updatedState.delegation_queue = [];
+  }
+  if (!updatedState.pending_delegation_review) {
+    updatedState.pending_delegation_review = null;
+  }
+
+  // If this turn has delegations, enqueue them
+  if (Array.isArray(turnResult.delegations) && turnResult.delegations.length > 0) {
+    for (const del of turnResult.delegations) {
+      updatedState.delegation_queue.push({
+        delegation_id: del.id,
+        parent_turn_id: turnResult.turn_id,
+        parent_role: turnResult.role,
+        to_role: del.to_role,
+        charter: del.charter,
+        acceptance_contract: del.acceptance_contract,
+        status: 'pending',
+        child_turn_id: null,
+        created_at: now,
+      });
+    }
+    // Override next_recommended_role to first pending delegation
+    updatedState.next_recommended_role = turnResult.delegations[0].to_role;
+  }
+
+  // If this turn was a delegated sub-task, update the delegation queue entry
+  if (currentTurn.delegation_context) {
+    const delId = currentTurn.delegation_context.delegation_id;
+    const queueEntry = updatedState.delegation_queue.find(d => d.delegation_id === delId);
+    if (queueEntry) {
+      queueEntry.status = turnResult.status === 'completed' ? 'completed' : 'failed';
+      queueEntry.child_turn_id = currentTurn.turn_id;
+
+      // Check if all delegations from the same parent are now complete
+      const parentTurnId = queueEntry.parent_turn_id;
+      const parentDelegations = updatedState.delegation_queue.filter(d => d.parent_turn_id === parentTurnId);
+      const allDone = parentDelegations.every(d => d.status === 'completed' || d.status === 'failed');
+
+      if (allDone) {
+        // Build delegation review context
+        const delegationResults = parentDelegations.map(d => {
+          const childHistory = nextHistoryEntries.find(h => h.turn_id === d.child_turn_id);
+          return {
+            delegation_id: d.delegation_id,
+            child_turn_id: d.child_turn_id,
+            to_role: d.to_role,
+            charter: d.charter,
+            acceptance_contract: d.acceptance_contract,
+            summary: childHistory?.summary || '(no summary)',
+            status: d.status,
+            files_changed: childHistory?.files_changed || [],
+            verification: childHistory?.verification || { status: 'skipped' },
+          };
+        });
+
+        updatedState.pending_delegation_review = {
+          parent_turn_id: parentTurnId,
+          parent_role: queueEntry.parent_role,
+          delegation_results: delegationResults,
+        };
+
+        // Recommend the parent role for the review turn
+        updatedState.next_recommended_role = queueEntry.parent_role;
+
+        // Clear completed delegation queue entries for this parent
+        updatedState.delegation_queue = updatedState.delegation_queue.filter(
+          d => d.parent_turn_id !== parentTurnId
+        );
+      } else {
+        // More pending delegations — route to the next one
+        const nextPending = updatedState.delegation_queue.find(
+          d => d.parent_turn_id === parentTurnId && d.status === 'pending'
+        );
+        if (nextPending) {
+          updatedState.next_recommended_role = nextPending.to_role;
+        }
+      }
+    }
+  }
+
+  // If a delegation review was pending and this turn was the review, clear it
+  if (updatedState.pending_delegation_review &&
+      turnResult.role === updatedState.pending_delegation_review.parent_role &&
+      !currentTurn.delegation_context) {
+    // The parent role just completed their review turn
+    updatedState.pending_delegation_review = null;
+  }
+
   if (updatedState.status === 'blocked' && !hasBlockingActiveTurn(remainingTurns)) {
     updatedState.status = 'active';
     updatedState.blocked_on = null;

package/src/lib/role-resolution.js

@@ -30,6 +30,15 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
   const routing = phase ? config?.routing?.[phase] : null;
   const warnings = [];
 
+  // ── Delegation queue priority ───────────────────────────────────────────
+  // If there are pending delegations, the next role is the delegation target
+  const pendingDelegation = Array.isArray(state?.delegation_queue)
+    ? state.delegation_queue.find(d => d.status === 'pending')
+    : null;
+
+  // If a delegation review is pending, the parent role takes priority
+  const pendingReview = state?.pending_delegation_review || null;
+
   if (override) {
     if (!config?.roles?.[override]) {
       return {
@@ -45,6 +54,14 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
       warnings.push(`role "${override}" is not in allowed_next_roles for phase "${phase}"`);
     }
 
+    // Warn if override skips a pending delegation
+    if (pendingDelegation && override !== pendingDelegation.to_role) {
+      warnings.push(`Override skips pending delegation ${pendingDelegation.delegation_id} to role "${pendingDelegation.to_role}"`);
+    }
+    if (pendingReview && override !== pendingReview.parent_role) {
+      warnings.push(`Override skips pending delegation review for role "${pendingReview.parent_role}"`);
+    }
+
     return {
       roleId: override,
       warnings,
@@ -54,6 +71,30 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
     };
   }
 
+  // Delegation review takes priority over pending delegations
+  if (pendingReview && config?.roles?.[pendingReview.parent_role]) {
+    return {
+      roleId: pendingReview.parent_role,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+      delegation_review: true,
+    };
+  }
+
+  // Pending delegation takes priority over normal resolution
+  if (pendingDelegation && config?.roles?.[pendingDelegation.to_role]) {
+    return {
+      roleId: pendingDelegation.to_role,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+      delegation: pendingDelegation,
+    };
+  }
+
   if (state?.next_recommended_role && config?.roles?.[state.next_recommended_role]) {
     const recommended = state.next_recommended_role;
     const isLegal = !routing?.allowed_next_roles || routing.allowed_next_roles.includes(recommended);

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

@@ -228,6 +228,39 @@
         "output_tokens": { "type": "integer", "minimum": 0 },
         "usd": { "type": "number", "minimum": 0 }
       }
+    },
+    "delegations": {
+      "type": "array",
+      "description": "Sub-tasks delegated to other roles. The delegating role defines the charter; delegates execute it; the delegating role reviews results.",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["id", "to_role", "charter", "acceptance_contract"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^del-\\d{3}$",
+            "description": "Delegation ID, e.g. del-001"
+          },
+          "to_role": {
+            "type": "string",
+            "pattern": "^[a-z0-9_-]+$",
+            "description": "Role that should execute this sub-task. Must be a defined role and routing-legal."
+          },
+          "charter": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Scope of the delegated work."
+          },
+          "acceptance_contract": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "description": "What the delegate must achieve for this delegation to be considered complete."
+          }
+        }
+      }
     }
   }
 }

package/src/lib/turn-result-validator.js

@@ -602,6 +602,54 @@ function validateProtocol(tr, state, config) {
     warnings.push('status is "needs_human" but needs_human_reason is empty.');
   }
 
+  // ── Delegation validation ───────────────────────────────────────────────
+  if (Array.isArray(tr.delegations) && tr.delegations.length > 0) {
+    // Maximum 5 delegations per turn
+    if (tr.delegations.length > 5) {
+      errors.push(`Maximum 5 delegations per turn (got ${tr.delegations.length}).`);
+    }
+
+    // Delegations are mutually exclusive with run_completion_request
+    if (tr.run_completion_request) {
+      errors.push('delegations are mutually exclusive with run_completion_request — a turn cannot delegate and complete the run.');
+    }
+
+    // No recursive delegation: if this turn is a delegation review, it cannot delegate further
+    const activeTurn = state?.active_turns ? Object.values(state.active_turns)[0] : null;
+    if (activeTurn?.delegation_context) {
+      errors.push('Delegation review turns cannot contain further delegations.');
+    }
+
+    const seenIds = new Set();
+    for (const del of tr.delegations) {
+      // Duplicate IDs
+      if (seenIds.has(del.id)) {
+        errors.push(`Duplicate delegation id "${del.id}".`);
+      }
+      seenIds.add(del.id);
+
+      // Self-delegation
+      if (del.to_role === tr.role) {
+        errors.push(`Role "${tr.role}" cannot delegate to itself (delegation ${del.id}).`);
+      }
+
+      // to_role must be a defined role
+      if (!config.roles?.[del.to_role]) {
+        errors.push(`Delegation to_role "${del.to_role}" is not a defined role (delegation ${del.id}).`);
+      }
+
+      // to_role must be routing-legal for current phase
+      if (routing && del.to_role) {
+        const allowed = routing.allowed_next_roles || [];
+        if (allowed.length > 0 && !allowed.includes(del.to_role)) {
+          errors.push(
+            `Delegation to_role "${del.to_role}" is not in allowed_next_roles for phase "${phase}": [${allowed.join(', ')}] (delegation ${del.id}).`
+          );
+        }
+      }
+    }
+  }
+
   return { errors, warnings };
 }