agentxchain 2.56.0 → 2.58.0

package/dashboard/components/run-history.js

@@ -68,6 +68,13 @@ function truncateId(id, len = 12) {
   return id.length > len ? id.slice(0, len) + '…' : id;
 }
 
+function truncateHeadline(headline, len = 40) {
+  if (!headline) return '—';
+  const normalized = String(headline).replace(/\s+/g, ' ').trim();
+  if (normalized.length <= len) return normalized;
+  return normalized.slice(0, len - 1) + '…';
+}
+
 function isInheritable(entry) {
   const snap = entry?.inheritance_snapshot;
   if (!snap) return false;
@@ -105,6 +112,7 @@ function renderRow(entry, index) {
     <td>${formatCost(entry.total_cost_usd)}</td>
     <td>${formatDuration(entry.duration_ms)}</td>
     <td>${formatDate(entry.recorded_at || entry.completed_at)}</td>
+    <td title="${esc(entry.retrospective?.headline || '')}">${esc(truncateHeadline(entry.retrospective?.headline))}</td>
   </tr>`;
 }
 
@@ -144,6 +152,7 @@ export function render({ runHistory }) {
           <th>Cost</th>
           <th>Duration</th>
           <th>Date</th>
+          <th>Headline</th>
         </tr>
       </thead>
       <tbody>`;

package/package.json

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

package/src/commands/history.js

@@ -50,8 +50,11 @@ export async function historyCommand(opts) {
       const parentNote = entry.provenance?.parent_run_id
         ? ` from ${entry.provenance.parent_run_id.slice(0, 12)}`
         : '';
+      const headline = entry.retrospective?.headline
+        ? `  ${formatHeadline(entry.retrospective.headline)}`
+        : '';
       const prefix = i === 0 ? '  ' : '  └─ ';
-      console.log(`${prefix}${runId}  ${status}  ${pad(phases, 20)}  ${pad(turns, 10)}  ${pad(cost, 8)}  (${trigger}${parentNote})${ctxMarker}`);
+      console.log(`${prefix}${runId}  ${status}  ${pad(phases, 20)}  ${pad(turns, 10)}  ${pad(cost, 8)}  (${trigger}${parentNote})${ctxMarker}${headline}`);
     });
     return;
   }
@@ -89,6 +92,7 @@ export async function historyCommand(opts) {
     pad('Cost', 10),
     pad('Duration', 10),
     pad('Date', 20),
+    pad('Headline', 42),
   ].join(' ');
 
   console.log(chalk.bold(header));
@@ -111,6 +115,7 @@ export async function historyCommand(opts) {
     const date = entry.recorded_at
       ? new Date(entry.recorded_at).toLocaleString()
       : '—';
+    const headline = formatHeadline(entry.retrospective?.headline);
 
     console.log([
       pad(idx, 4),
@@ -123,6 +128,7 @@ export async function historyCommand(opts) {
       pad(cost, 10),
       pad(duration, 10),
       pad(date, 20),
+      pad(headline, 42),
     ].join(' '));
   });
 
@@ -163,3 +169,10 @@ function formatDuration(ms) {
   const remainMins = mins % 60;
   return `${hrs}h ${remainMins}m`;
 }
+
+function formatHeadline(headline) {
+  if (!headline) return '—';
+  const normalized = String(headline).replace(/\s+/g, ' ').trim();
+  if (normalized.length <= 40) return normalized;
+  return `${normalized.slice(0, 39)}…`;
+}

package/src/commands/init.js

@@ -976,6 +976,11 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');
+  if (!config?.project?.goal) {
+    console.log(`  ${chalk.dim('Tip:')} Add a project goal to guide agent context:`);
+    console.log(`    ${chalk.bold('agentxchain init --governed --goal "Build a ..."')} ${chalk.dim('# or set project.goal in agentxchain.json')}`);
+    console.log('');
+  }
   console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);
   console.log('');
 }

package/src/lib/run-context-inheritance.js

@@ -57,6 +57,7 @@ export function buildInheritedContext(root, parentRunId) {
     parent_phases_completed: parentEntry.phases_completed || [],
     parent_roles_used: parentEntry.roles_used || [],
     parent_blocked_reason: parentEntry.blocked_reason || null,
+    parent_retrospective: parentEntry.retrospective || null,
     recent_decisions: recentDecisions,
     recent_accepted_turns: acceptedTurns,
     inherited_at: new Date().toISOString(),
@@ -93,6 +94,20 @@ export function renderInheritedContextMarkdown(inheritedContext, compact = false
   }
   lines.push('');
 
+  if (!compact && inheritedContext.parent_retrospective) {
+    lines.push('### Parent Retrospective');
+    lines.push('');
+    lines.push(`- **Headline:** ${inheritedContext.parent_retrospective.headline || 'n/a'}`);
+    lines.push(`- **Terminal reason:** ${inheritedContext.parent_retrospective.terminal_reason || 'unknown'}`);
+    if (inheritedContext.parent_retrospective.next_operator_action) {
+      lines.push(`- **Next operator action:** ${inheritedContext.parent_retrospective.next_operator_action}`);
+    }
+    if (inheritedContext.parent_retrospective.follow_on_hint) {
+      lines.push(`- **Follow-on hint:** ${inheritedContext.parent_retrospective.follow_on_hint}`);
+    }
+    lines.push('');
+  }
+
   if (!compact && inheritedContext.recent_decisions?.length) {
     lines.push('### Recent Decisions');
     lines.push('');
@@ -153,6 +168,7 @@ function buildPartialContext(parentRunId, parentEntry, decisions, turns, warning
     parent_phases_completed: parentEntry?.phases_completed || [],
     parent_roles_used: parentEntry?.roles_used || [],
     parent_blocked_reason: parentEntry?.blocked_reason || null,
+    parent_retrospective: parentEntry?.retrospective || null,
     recent_decisions: decisions,
     recent_accepted_turns: turns,
     inherited_at: new Date().toISOString(),

package/src/lib/run-history.js

@@ -10,6 +10,7 @@
 import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { normalizeRunProvenance } from './run-provenance.js';
+import { deriveRecoveryDescriptor } from './blocked-state.js';
 
 const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
 const HISTORY_PATH = '.agentxchain/history.jsonl';
@@ -83,6 +84,12 @@ export function recordRunHistory(root, state, config, status) {
       connector_used: connectorUsed,
       model_used: modelUsed,
       provenance: normalizeRunProvenance(state?.provenance),
+      retrospective: buildRunRetrospective({
+        state,
+        config,
+        status,
+        historyEntries,
+      }),
       inheritance_snapshot: {
         recent_decisions: buildRecentDecisionSnapshot(ledgerEntries),
         recent_accepted_turns: buildRecentAcceptedTurnSnapshot(historyEntries),
@@ -300,7 +307,7 @@ function buildRecentDecisionSnapshot(entries) {
 
 function buildRecentAcceptedTurnSnapshot(entries) {
   return entries
-    .filter((entry) => entry.status === 'accepted')
+    .filter((entry) => entry?.status !== 'rejected' && typeof entry?.turn_id === 'string' && typeof entry?.role === 'string')
     .slice(-MAX_INHERITANCE_TURNS)
     .map((entry) => ({
       turn_id: entry.turn_id || null,
@@ -309,3 +316,57 @@ function buildRecentAcceptedTurnSnapshot(entries) {
       phase: entry.phase || null,
     }));
 }
+
+function buildRunRetrospective({ state, config, status, historyEntries }) {
+  const acceptedTurns = historyEntries.filter((entry) => entry && typeof entry === 'object');
+  const lastAcceptedTurn = acceptedTurns[acceptedTurns.length - 1] || null;
+  const recovery = status === 'blocked'
+    ? deriveRecoveryDescriptor(state, config)
+    : null;
+
+  return {
+    headline: buildRetrospectiveHeadline({ status, lastAcceptedTurn, recovery, acceptedTurns }),
+    terminal_reason: status === 'completed'
+      ? 'completed'
+      : recovery?.typed_reason || 'blocked',
+    next_operator_action: status === 'blocked'
+      ? recovery?.recovery_action || null
+      : null,
+    follow_on_hint: status === 'completed'
+      ? buildFollowOnHint(state, lastAcceptedTurn)
+      : null,
+  };
+}
+
+function buildRetrospectiveHeadline({ status, lastAcceptedTurn, recovery, acceptedTurns }) {
+  if (status === 'blocked') {
+    if (typeof recovery?.detail === 'string' && recovery.detail.trim()) {
+      return recovery.detail.trim();
+    }
+    if (typeof lastAcceptedTurn?.summary === 'string' && lastAcceptedTurn.summary.trim()) {
+      return `Run blocked after: ${lastAcceptedTurn.summary.trim()}`;
+    }
+    return 'Run blocked.';
+  }
+
+  if (typeof lastAcceptedTurn?.summary === 'string' && lastAcceptedTurn.summary.trim()) {
+    return lastAcceptedTurn.summary.trim();
+  }
+
+  return `Run completed after ${acceptedTurns.length} accepted turn(s).`;
+}
+
+function buildFollowOnHint(state, lastAcceptedTurn) {
+  const runId = state?.run_id;
+  if (typeof runId !== 'string' || !runId.trim()) {
+    return null;
+  }
+
+  const base = `If more scope remains, start a child run with \`agentxchain run --continue-from ${runId} --inherit-context\`.`;
+  const suggestedRole = lastAcceptedTurn?.proposed_next_role;
+  if (typeof suggestedRole === 'string' && suggestedRole.trim() && suggestedRole !== 'human') {
+    return `${base} The last accepted turn suggested \`${suggestedRole}\` next.`;
+  }
+
+  return base;
+}