agentxchain 2.62.0 → 2.63.0

package/bin/agentxchain.js

@@ -86,6 +86,8 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { roleCommand } from '../src/commands/role.js';
+import { turnShowCommand } from '../src/commands/turn.js';
 import { templateValidateCommand } from '../src/commands/template-validate.js';
 import {
   multiInitCommand,
@@ -485,6 +487,33 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateValidateCommand);
 
+const roleCmd = program
+  .command('role')
+  .description('Inspect governed role definitions');
+
+roleCmd
+  .command('list')
+  .description('List all defined roles with title, authority, and runtime')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => roleCommand('list', null, opts));
+
+roleCmd
+  .command('show <role_id>')
+  .description('Show detailed information for a single role')
+  .option('-j, --json', 'Output as JSON')
+  .action((roleId, opts) => roleCommand('show', roleId, opts));
+
+const turnCmd = program
+  .command('turn')
+  .description('Inspect active governed turn dispatch bundles');
+
+turnCmd
+  .command('show [turn_id]')
+  .description('Show a selected active turn and its dispatch artifacts')
+  .option('--artifact <name>', 'Print one artifact: assignment, prompt, context, or manifest')
+  .option('-j, --json', 'Output as JSON')
+  .action(turnShowCommand);
+
 const multiCmd = program
   .command('multi')
   .description('Multi-repo coordinator orchestration');

package/package.json

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

package/scripts/release-bump.sh

@@ -198,21 +198,53 @@ echo "  OK: all 9 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.
-# The SHA256 is carried from the previous version — it is inherently a
+# The SHA256 is carried from the previous committed formula — it is inherently a
 # post-publish artifact (npm registry tarballs are not byte-identical to
-# local npm-pack output). sync-homebrew.sh corrects the SHA after publish.
+# local npm-pack output). Any working-tree SHA edit is overwritten here.
+# sync-homebrew.sh corrects the SHA after publish.
 echo "[5/9] Auto-aligning Homebrew mirror to ${TARGET_VERSION}..."
 HOMEBREW_MIRROR="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
 HOMEBREW_MIRROR_README="${REPO_ROOT}/cli/homebrew/README.md"
 TARBALL_URL="https://registry.npmjs.org/agentxchain/-/agentxchain-${TARGET_VERSION}.tgz"
 HOMEBREW_ALIGNED=false
+COMMITTED_HOMEBREW_SHA=""
+
+extract_formula_sha() {
+  sed -nE 's|^[[:space:]]*sha256 "([a-f0-9]{64})".*|\1|p' "$1" | head -n 1
+}
 
 if [[ -f "$HOMEBREW_MIRROR" ]]; then
+  COMMITTED_FORMULA_TMP="$(mktemp "${TMPDIR:-/tmp}/agentxchain-homebrew-head.XXXXXX")"
+  if ! git -C "$REPO_ROOT" show "HEAD:cli/homebrew/agentxchain.rb" >"$COMMITTED_FORMULA_TMP" 2>/dev/null; then
+    rm -f "$COMMITTED_FORMULA_TMP"
+    echo "FAIL: could not load HEAD:cli/homebrew/agentxchain.rb to carry the pre-publish SHA" >&2
+    exit 1
+  fi
+  COMMITTED_HOMEBREW_SHA="$(extract_formula_sha "$COMMITTED_FORMULA_TMP")"
+  rm -f "$COMMITTED_FORMULA_TMP"
+  if [[ -z "$COMMITTED_HOMEBREW_SHA" ]]; then
+    echo "FAIL: HEAD:cli/homebrew/agentxchain.rb does not contain a parseable sha256" >&2
+    exit 1
+  fi
+
+  WORKTREE_HOMEBREW_SHA="$(extract_formula_sha "$HOMEBREW_MIRROR")"
+  if [[ -z "$WORKTREE_HOMEBREW_SHA" ]]; then
+    echo "FAIL: cli/homebrew/agentxchain.rb does not contain a parseable sha256" >&2
+    exit 1
+  fi
+
   ESCAPED_URL="$(printf '%s' "$TARBALL_URL" | sed 's/[&/\]/\\&/g')"
+  ESCAPED_SHA="$(printf '%s' "$COMMITTED_HOMEBREW_SHA" | sed 's/[&/\]/\\&/g')"
   sed -i.bak -E "s|^([[:space:]]*url \").*(\")|\1${ESCAPED_URL}\2|" "$HOMEBREW_MIRROR"
+  sed -i.bak -E "s|^([[:space:]]*sha256 \").*(\")|\1${ESCAPED_SHA}\2|" "$HOMEBREW_MIRROR"
   rm -f "${HOMEBREW_MIRROR}.bak"
   HOMEBREW_ALIGNED=true
   echo "  OK: formula URL -> ${TARBALL_URL}"
+  if [[ "$WORKTREE_HOMEBREW_SHA" != "$COMMITTED_HOMEBREW_SHA" ]]; then
+    echo "  OK: formula SHA normalized back to committed pre-publish SHA ${COMMITTED_HOMEBREW_SHA}"
+  else
+    echo "  OK: formula SHA carried from committed pre-publish SHA ${COMMITTED_HOMEBREW_SHA}"
+  fi
 fi
 
 if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
@@ -223,7 +255,7 @@ if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
 fi
 
 if $HOMEBREW_ALIGNED; then
-  echo "  Note: SHA carried from previous version; sync-homebrew.sh will set the real registry SHA post-publish"
+  echo "  Note: local npm pack output is not canonical release truth; sync-homebrew.sh will set the real registry SHA post-publish"
 else
   echo "  Skipped: no Homebrew mirror files found"
 fi
@@ -346,4 +378,7 @@ if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
   echo "  npm run preflight:release:strict -- --target-version ${TARGET_VERSION}"
 fi
 echo ""
+echo "Homebrew mirror is in Phase 1 (stale SHA from previous version)."
+echo "After npm publish completes, run sync-homebrew.sh to reach Phase 3."
+echo ""
 echo "Next: git push origin main --follow-tags"

package/src/commands/role.js

@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+
+export function roleCommand(subcommand, roleId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { rawConfig, version } = context;
+
+  if (version !== 4) {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const roles = rawConfig.roles || {};
+  const roleIds = Object.keys(roles);
+
+  if (subcommand === 'show') {
+    return showRole(roleId, roles, roleIds, opts);
+  }
+
+  // Default: list
+  return listRoles(roles, roleIds, opts);
+}
+
+function listRoles(roles, roleIds, opts) {
+  if (roleIds.length === 0) {
+    if (opts.json) {
+      console.log('[]');
+    } else {
+      console.log('  No roles defined.');
+    }
+    return;
+  }
+
+  if (opts.json) {
+    const output = roleIds.map((id) => ({
+      id,
+      title: roles[id].title,
+      mandate: roles[id].mandate,
+      write_authority: roles[id].write_authority,
+      runtime: roles[id].runtime,
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Roles (${roleIds.length}):\n`));
+  for (const id of roleIds) {
+    const r = roles[id];
+    const authority = r.write_authority === 'authoritative'
+      ? chalk.green(r.write_authority)
+      : r.write_authority === 'proposed'
+        ? chalk.yellow(r.write_authority)
+        : chalk.dim(r.write_authority);
+    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}] → ${chalk.dim(r.runtime)}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain role show <role_id>\n'));
+}
+
+function showRole(roleId, roles, roleIds, opts) {
+  if (!roleId) {
+    console.log(chalk.red('  Missing role ID.'));
+    console.log(chalk.dim(`  Usage: agentxchain role show <role_id>`));
+    if (roleIds.length > 0) {
+      console.log(chalk.dim(`  Available: ${roleIds.join(', ')}`));
+    }
+    process.exit(1);
+  }
+
+  if (!roles[roleId]) {
+    console.log(chalk.red(`  Unknown role: ${roleId}`));
+    console.log(chalk.dim(`  Available: ${roleIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const r = roles[roleId];
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      id: roleId,
+      title: r.title,
+      mandate: r.mandate,
+      write_authority: r.write_authority,
+      runtime: r.runtime,
+    }, null, 2));
+    return;
+  }
+
+  const authority = r.write_authority === 'authoritative'
+    ? chalk.green(r.write_authority)
+    : r.write_authority === 'proposed'
+      ? chalk.yellow(r.write_authority)
+      : chalk.dim(r.write_authority);
+
+  console.log(chalk.bold(`\n  Role: ${chalk.cyan(roleId)}\n`));
+  console.log(`  Title:      ${r.title}`);
+  console.log(`  Mandate:    ${r.mandate}`);
+  console.log(`  Authority:  ${authority}`);
+  console.log(`  Runtime:    ${chalk.dim(r.runtime)}`);
+  console.log('');
+}

package/src/commands/turn.js

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
+import {
+  getDispatchAssignmentPath,
+  getDispatchContextPath,
+  getDispatchManifestPath,
+  getDispatchPromptPath,
+  getDispatchTurnDir,
+} from '../lib/turn-paths.js';
+
+const ARTIFACTS = {
+  assignment: {
+    label: 'Assignment',
+    pathFor: getDispatchAssignmentPath,
+    parse: 'json',
+  },
+  prompt: {
+    label: 'Prompt',
+    pathFor: getDispatchPromptPath,
+    parse: 'text',
+  },
+  context: {
+    label: 'Context',
+    pathFor: getDispatchContextPath,
+    parse: 'text',
+  },
+  manifest: {
+    label: 'Manifest',
+    pathFor: getDispatchManifestPath,
+    parse: 'json',
+  },
+};
+
+export function turnShowCommand(turnId, opts) {
+  const context = requireGovernedContext();
+  const state = loadProjectState(context.root, context.config);
+
+  if (!state) {
+    console.log(chalk.red('  Governed state is missing or invalid.'));
+    process.exit(1);
+  }
+
+  const activeTurns = getActiveTurns(state);
+  const selectedTurnId = resolveTurnId(turnId, activeTurns);
+  const turn = activeTurns[selectedTurnId];
+  const artifacts = buildArtifactIndex(context.root, selectedTurnId);
+  const assignment = readJsonArtifact(artifacts.assignment.absPath);
+
+  if (opts.artifact) {
+    return printArtifact(selectedTurnId, turn, artifacts, opts.artifact, opts.json);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(buildTurnPayload(selectedTurnId, turn, state, artifacts, assignment), null, 2));
+    return;
+  }
+
+  printTurnSummary(selectedTurnId, turn, state, artifacts, assignment);
+}
+
+function requireGovernedContext() {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+  if (context.config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  The turn command is only available for governed projects.'));
+    process.exit(1);
+  }
+  return context;
+}
+
+function resolveTurnId(requestedTurnId, activeTurns) {
+  const turnIds = Object.keys(activeTurns);
+  if (requestedTurnId) {
+    if (!activeTurns[requestedTurnId]) {
+      console.log(chalk.red(`  Unknown active turn: ${requestedTurnId}`));
+      if (turnIds.length > 0) {
+        console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+      }
+      process.exit(1);
+    }
+    return requestedTurnId;
+  }
+
+  if (turnIds.length === 0) {
+    console.log(chalk.red('  No active turn found.'));
+    process.exit(1);
+  }
+
+  if (turnIds.length > 1) {
+    console.log(chalk.red('  Multiple active turns are present. Re-run with `agentxchain turn show <turn_id>`.'));
+    console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  return turnIds[0];
+}
+
+function buildArtifactIndex(root, turnId) {
+  return Object.fromEntries(
+    Object.entries(ARTIFACTS).map(([id, artifact]) => {
+      const relPath = artifact.pathFor(turnId);
+      const absPath = join(root, relPath);
+      return [id, {
+        id,
+        label: artifact.label,
+        relPath,
+        absPath,
+        exists: existsSync(absPath),
+        parse: artifact.parse,
+      }];
+    }),
+  );
+}
+
+function buildTurnPayload(turnId, turn, state, artifacts, assignment) {
+  return {
+    turn_id: turnId,
+    run_id: state.run_id || assignment?.run_id || null,
+    phase: state.phase || assignment?.phase || null,
+    role: turn.assigned_role,
+    runtime: turn.runtime_id,
+    status: turn.status,
+    attempt: turn.attempt,
+    dispatch_dir: getDispatchTurnDir(turnId),
+    staging_result_path: assignment?.staging_result_path || null,
+    active_turn_count: getActiveTurnCount(state),
+    artifacts: Object.fromEntries(
+      Object.entries(artifacts).map(([id, artifact]) => [id, {
+        path: artifact.relPath,
+        exists: artifact.exists,
+      }]),
+    ),
+  };
+}
+
+function printTurnSummary(turnId, turn, state, artifacts, assignment) {
+  console.log('');
+  console.log(chalk.bold(`  Turn: ${chalk.cyan(turnId)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Run:')}      ${state.run_id || assignment?.run_id || chalk.dim('unknown')}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state.phase || assignment?.phase || chalk.dim('unknown')}`);
+  console.log(`  ${chalk.dim('Role:')}     ${chalk.bold(turn.assigned_role)}`);
+  console.log(`  ${chalk.dim('Runtime:')}  ${turn.runtime_id}`);
+  console.log(`  ${chalk.dim('Status:')}   ${turn.status}`);
+  console.log(`  ${chalk.dim('Attempt:')}  ${turn.attempt}`);
+  console.log(`  ${chalk.dim('Dispatch:')} ${getDispatchTurnDir(turnId)}`);
+  if (assignment?.staging_result_path) {
+    console.log(`  ${chalk.dim('Staging:')}  ${assignment.staging_result_path}`);
+  }
+  console.log('');
+  console.log(`  ${chalk.dim('Artifacts:')}`);
+  for (const artifact of Object.values(artifacts)) {
+    const marker = artifact.exists ? chalk.green('exists') : chalk.red('missing');
+    console.log(`    ${artifact.label.padEnd(10)} ${marker}  ${artifact.relPath}`);
+  }
+  console.log('');
+  console.log(chalk.dim(`  View one: agentxchain turn show ${turnId} --artifact prompt`));
+  console.log('');
+}
+
+function printArtifact(turnId, turn, artifacts, artifactId, jsonMode) {
+  const artifact = artifacts[artifactId];
+  if (!artifact) {
+    console.log(chalk.red(`  Unknown artifact: ${artifactId}`));
+    console.log(chalk.dim(`  Allowed: ${Object.keys(ARTIFACTS).join(', ')}`));
+    process.exit(1);
+  }
+  if (!artifact.exists) {
+    console.log(chalk.red(`  Missing artifact: ${artifact.relPath}`));
+    process.exit(1);
+  }
+
+  const raw = readFileSync(artifact.absPath, 'utf8');
+  if (!jsonMode) {
+    process.stdout.write(raw.endsWith('\n') ? raw : `${raw}\n`);
+    return;
+  }
+
+  const content = artifact.parse === 'json'
+    ? JSON.parse(raw)
+    : raw;
+
+  console.log(JSON.stringify({
+    turn_id: turnId,
+    role: turn.assigned_role,
+    runtime: turn.runtime_id,
+    artifact: {
+      id: artifact.id,
+      path: artifact.relPath,
+      content,
+    },
+  }, null, 2));
+}
+
+function readJsonArtifact(absPath) {
+  if (!existsSync(absPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}