agentxchain 2.23.0 → 2.24.2

package/package.json

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

package/scripts/release-postflight.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Release postflight — run this after publish succeeds.
 # Verifies: release tag exists, npm registry serves the version, metadata is present,
-# the published package can execute its CLI entrypoint, and runner package exports
-# are importable in a clean consumer project.
+# the published package resolves through npx, the published package can execute its
+# CLI entrypoint from the tarball, and runner package exports are importable in a
+# clean consumer project.
 # Usage: bash scripts/release-postflight.sh --target-version <semver> [--tag vX.Y.Z]
 set -uo pipefail
 
@@ -100,6 +101,27 @@ trim_last_line() {
   printf '%s\n' "$1" | awk 'NF { line=$0 } END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line }'
 }
 
+extract_matching_line() {
+  local output="$1"
+  local expected="$2"
+  printf '%s\n' "$output" | awk -v expected="$expected" '
+    {
+      line=$0
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
+      if (line == expected) {
+        print line
+        found=1
+        exit
+      }
+    }
+    END {
+      if (!found) {
+        exit 1
+      }
+    }
+  '
+}
+
 run_install_smoke() {
   if [[ -z "$TARBALL_URL" ]]; then
     echo "registry tarball metadata unavailable for install smoke" >&2
@@ -139,6 +161,36 @@ run_install_smoke() {
   return "$version_status"
 }
 
+run_npx_smoke() {
+  local smoke_root
+  local smoke_npmrc
+  local npx_output
+  local npx_status
+
+  smoke_root="$(mktemp -d "${TMPDIR:-/tmp}/agentxchain-npx-postflight.XXXXXX")"
+  mkdir -p "${smoke_root}/home" "${smoke_root}/cache" "${smoke_root}/npm-cache" "${smoke_root}/workspace"
+
+  smoke_npmrc="${smoke_root}/.npmrc"
+  echo "registry=https://registry.npmjs.org/" > "$smoke_npmrc"
+
+  npx_output="$(
+    (
+      cd "${smoke_root}/workspace" || exit 1
+      env -u NODE_AUTH_TOKEN \
+        HOME="${smoke_root}/home" \
+        XDG_CACHE_HOME="${smoke_root}/cache" \
+        NPM_CONFIG_CACHE="${smoke_root}/npm-cache" \
+        NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
+        npx --yes -p "${PACKAGE_NAME}@${TARGET_VERSION}" -c "${PACKAGE_BIN_NAME} --version" 2>&1
+    )
+  )"
+  npx_status=$?
+
+  printf '%s\n' "$npx_output"
+  rm -rf "$smoke_root"
+  return "$npx_status"
+}
+
 run_runner_export_smoke() {
   if [[ -z "$TARBALL_URL" ]]; then
     echo "registry tarball metadata unavailable for runner export smoke" >&2
@@ -261,17 +313,17 @@ run_with_retry() {
 
 echo "AgentXchain v${TARGET_VERSION} Release Postflight"
 echo "====================================="
-echo "Checks release truth after publish: tag, registry visibility, metadata, CLI install smoke, and package export smoke."
+echo "Checks release truth after publish: tag, registry visibility, metadata, npx smoke, CLI install smoke, and package export smoke."
 echo ""
 
-echo "[1/6] Git tag"
+echo "[1/7] Git tag"
 if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null 2>&1; then
   pass "Git tag ${TAG} exists locally"
 else
   fail "Git tag ${TAG} is missing locally"
 fi
 
-echo "[2/6] Registry version"
+echo "[2/7] Registry version"
 if run_with_retry VERSION_OUTPUT "registry version" equals "${TARGET_VERSION}" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" version; then
   PUBLISHED_VERSION="$(trim_last_line "$VERSION_OUTPUT")"
   if [[ "$PUBLISHED_VERSION" == "$TARGET_VERSION" ]]; then
@@ -284,7 +336,7 @@ else
   printf '%s\n' "$VERSION_OUTPUT" | tail -20
 fi
 
-echo "[3/6] Registry tarball metadata"
+echo "[3/7] Registry tarball metadata"
 if run_with_retry TARBALL_OUTPUT "registry tarball metadata" nonempty "" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball; then
   TARBALL_URL="$(trim_last_line "$TARBALL_OUTPUT")"
   if [[ -n "$TARBALL_URL" ]]; then
@@ -297,7 +349,7 @@ else
   printf '%s\n' "$TARBALL_OUTPUT" | tail -20
 fi
 
-echo "[4/6] Registry checksum metadata"
+echo "[4/7] Registry checksum metadata"
 if run_with_retry INTEGRITY_OUTPUT "registry checksum metadata" nonempty "" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.integrity; then
   REGISTRY_CHECKSUM="$(trim_last_line "$INTEGRITY_OUTPUT")"
 fi
@@ -312,7 +364,20 @@ else
   fail "registry did not return checksum metadata"
 fi
 
-echo "[5/6] Install smoke"
+echo "[5/7] npx smoke"
+if run_with_retry NPX_OUTPUT "npx smoke" nonempty "" run_npx_smoke; then
+  NPX_VERSION="$(extract_matching_line "$NPX_OUTPUT" "$TARGET_VERSION" 2>/dev/null || trim_last_line "$NPX_OUTPUT")"
+  if [[ "$NPX_VERSION" == "$TARGET_VERSION" ]]; then
+    pass "published npx command resolves and reports ${TARGET_VERSION}"
+  else
+    fail "published npx command reported '${NPX_VERSION}', expected '${TARGET_VERSION}'"
+  fi
+else
+  fail "published npx smoke failed"
+  printf '%s\n' "$NPX_OUTPUT" | tail -20
+fi
+
+echo "[6/7] Install smoke"
 if run_with_retry EXEC_OUTPUT "install smoke" nonempty "" run_install_smoke; then
   EXEC_VERSION="$(trim_last_line "$EXEC_OUTPUT")"
   if [[ "$EXEC_VERSION" == "$TARGET_VERSION" ]]; then
@@ -325,7 +390,7 @@ else
   printf '%s\n' "$EXEC_OUTPUT" | tail -20
 fi
 
-echo "[6/6] Package export smoke"
+echo "[7/7] Package export smoke"
 if run_with_retry RUNNER_EXPORT_OUTPUT "runner export smoke" nonempty "" run_runner_export_smoke; then
   RUNNER_EXPORT_JSON="$(trim_last_line "$RUNNER_EXPORT_OUTPUT")"
   RUNNER_EXPORT_VERSION="$(printf '%s' "$RUNNER_EXPORT_JSON" | node --input-type=module -e "process.stdin.setEncoding('utf8'); let raw=''; process.stdin.on('data', (chunk) => raw += chunk); process.stdin.on('end', () => { const parsed = JSON.parse(raw); console.log(parsed.runner_interface_version || ''); });")"

package/src/commands/demo.js

@@ -605,7 +605,7 @@ All acceptance criteria met. OBJ-002 (clock skew) noted for follow-up. OBJ-003 (
       console.log(chalk.dim('  ─'.repeat(26)));
       console.log('');
       console.log(`  ${chalk.bold('Try it for real:')}  agentxchain init --governed`);
-      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/first-turn`);
+      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/getting-started`);
       console.log(`  ${chalk.bold('Read more:')}       https://agentxchain.dev/docs/quickstart`);
       console.log('');
     }

package/src/commands/init.js

@@ -105,6 +105,7 @@ const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
   'local-dev': DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
   'api-qa': { type: 'api_proxy', provider: 'anthropic', model: 'claude-sonnet-4-6', auth_env: 'ANTHROPIC_API_KEY' },
+  'manual-qa': { type: 'manual' },
   'manual-director': { type: 'manual' }
 };
 
@@ -684,6 +685,29 @@ async function initGoverned(opts) {
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
+
+  // Readiness hint: tell user which roles work immediately vs which need API keys
+  const allRuntimes = { ...GOVERNED_RUNTIMES, 'local-dev': localDevRuntime };
+  const needsKey = Object.entries(allRuntimes)
+    .filter(([, rt]) => rt.auth_env)
+    .map(([id, rt]) => ({ id, env: rt.auth_env }));
+  if (needsKey.length > 0) {
+    const envVars = [...new Set(needsKey.map(r => r.env))];
+    const roleNames = needsKey.map(r => r.id);
+    const hasKeys = envVars.every(v => process.env[v]);
+    if (hasKeys) {
+      console.log(`  ${chalk.green('Ready:')} all runtimes configured (${envVars.join(', ')} detected)`);
+    } else {
+      console.log(`  ${chalk.yellow('Mixed-mode:')} pm and eng_director work immediately (manual).`);
+      console.log(`  ${chalk.yellow('  ')}${roleNames.join(', ')} need ${chalk.bold(envVars.join(', '))} to dispatch automatically.`);
+      console.log(`  ${chalk.yellow('  ')}Without it, those turns fall back to manual input.`);
+      if (allRuntimes['manual-qa']) {
+        console.log(`  ${chalk.yellow('  ')}No-key QA path: change ${chalk.bold('roles.qa.runtime')} from ${chalk.bold('"api-qa"')} to ${chalk.bold('"manual-qa"')} in ${chalk.bold('agentxchain.json')}.`);
+      }
+    }
+    console.log('');
+  }
+
   console.log(`  ${chalk.cyan('Next:')}`);
   if (dir !== process.cwd()) {
     console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
@@ -691,6 +715,8 @@ 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('');
+  console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);
+  console.log('');
 }
 
 export async function initCommand(opts) {

package/src/commands/run.js

@@ -47,7 +47,7 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The run command is only available for governed projects.'));
@@ -112,6 +112,7 @@ export async function runCommand(opts) {
 
   // ── Track first-call for --role override ────────────────────────────────
   let firstSelectRole = true;
+  let qaMissingCredentialsFallback = null;
 
   // ── Callbacks ───────────────────────────────────────────────────────────
   const callbacks = {
@@ -134,6 +135,7 @@ export async function runCommand(opts) {
       const runtime = cfg.runtimes?.[runtimeId];
       const runtimeType = runtime?.type || role?.runtime_class || 'manual';
       const hooksConfig = cfg.hooks || {};
+      qaMissingCredentialsFallback = null;
 
       // Manual adapter is not supported in run mode
       if (runtimeType === 'manual') {
@@ -219,6 +221,18 @@ export async function runCommand(opts) {
 
       // Adapter failure
       if (!adapterResult.ok) {
+        if (shouldPrintManualQaFallback({
+          roleId,
+          runtimeId,
+          classified: adapterResult.classified,
+          rawConfig,
+        })) {
+          qaMissingCredentialsFallback = {
+            roleId,
+            runtimeId,
+            errorClass: adapterResult.classified.error_class,
+          };
+        }
         const errorDetail = adapterResult.classified
           ? `${adapterResult.classified.error_class}: ${adapterResult.classified.recovery}`
           : adapterResult.error;
@@ -317,6 +331,10 @@ export async function runCommand(opts) {
     }
   }
 
+  if (qaMissingCredentialsFallback) {
+    printManualQaFallback();
+  }
+
   // Recovery guidance for blocked/rejected states
   if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
     const recovery = deriveRecoveryDescriptor(result.state);
@@ -391,3 +409,18 @@ function promptUser(question) {
     rl.on('close', () => resolve(''));
   });
 }
+
+function shouldPrintManualQaFallback({ roleId, runtimeId, classified, rawConfig }) {
+  return classified?.error_class === 'missing_credentials'
+    && roleId === 'qa'
+    && runtimeId === 'api-qa'
+    && rawConfig?.runtimes?.['manual-qa']?.type === 'manual';
+}
+
+function printManualQaFallback() {
+  console.log('');
+  console.log(chalk.dim('  No-key QA fallback:'));
+  console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+  console.log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
+  console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+}

package/src/commands/step.js

@@ -71,7 +71,7 @@ export async function stepCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The step command is only available for governed projects.'));
@@ -422,6 +422,18 @@ export async function stepCommand(opts) {
         console.log(chalk.dim(`  Retry trace: ${apiResult.retry_trace_path}`));
       }
 
+      if (
+        apiResult.classified?.error_class === 'missing_credentials'
+        && roleId === 'qa'
+        && config.roles?.qa?.runtime_id === 'api-qa'
+        && rawConfig?.runtimes?.['manual-qa']?.type === 'manual'
+      ) {
+        console.log(chalk.dim('  No-key QA fallback:'));
+        console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+        console.log(chalk.dim('  - Then rerun: agentxchain step --resume'));
+        console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+      }
+
       console.log(chalk.dim('The turn remains assigned. You can:'));
       console.log(chalk.dim('  - Fix the issue and retry: agentxchain step --resume'));
       console.log(chalk.dim('  - Complete manually: edit .agentxchain/staging/turn-result.json'));

package/src/lib/adapters/manual-adapter.js

@@ -30,31 +30,100 @@ export function printManualDispatchInstructions(state, config, options = {}) {
   const role = config.roles?.[turn.assigned_role];
   const promptPath = getDispatchPromptPath(turn.turn_id);
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
+  const phase = state.phase || 'planning';
+  const roleId = turn.assigned_role;
 
   const lines = [];
   lines.push('');
   lines.push('  +---------------------------------------------------------+');
   lines.push('  |  MANUAL TURN REQUIRED                                    |');
   lines.push('  |                                                          |');
-  lines.push(`  |  Role:    ${pad(turn.assigned_role, 46)}|`);
+  lines.push(`  |  Role:    ${pad(roleId, 46)}|`);
   lines.push(`  |  Turn:    ${pad(turn.turn_id, 46)}|`);
-  lines.push(`  |  Phase:   ${pad(state.phase, 46)}|`);
+  lines.push(`  |  Phase:   ${pad(phase, 46)}|`);
   lines.push(`  |  Attempt: ${pad(String(turn.attempt), 46)}|`);
   lines.push('  |                                                          |');
   lines.push(`  |  Prompt:  ${pad(promptPath, 46)}|`);
   lines.push(`  |  Result:  ${pad(stagingPath, 46)}|`);
-  lines.push('  |                                                          |');
-  lines.push('  |  1. Read the prompt at the path above                    |');
-  lines.push('  |  2. Complete the work described in the prompt             |');
-  lines.push('  |  3. Write your turn result JSON to the result path       |');
-  lines.push('  |                                                          |');
-  lines.push('  |  The step command will detect the file and proceed.      |');
   lines.push('  +---------------------------------------------------------+');
   lines.push('');
+  lines.push('  Steps:');
+  lines.push(`    1. Read the prompt:   cat ${promptPath}`);
+  lines.push('    2. Do the work described in the prompt');
+  lines.push(`    3. Write turn-result.json to:  ${stagingPath}`);
+  lines.push('    4. The step command will detect the file and proceed');
+  lines.push('');
+
+  // Phase-aware guidance
+  const gateHints = getPhaseGateHints(phase, roleId, config);
+  if (gateHints.length > 0) {
+    lines.push('  Gate files to update this phase:');
+    for (const hint of gateHints) {
+      lines.push(`    - ${hint}`);
+    }
+    lines.push('');
+  }
+
+  // Minimal turn-result example
+  lines.push('  Minimal turn-result.json:');
+  lines.push('  {');
+  lines.push('    "schema_version": "1.0",');
+  lines.push(`    "run_id": "${state.run_id || 'run_...'}",`);
+  lines.push(`    "turn_id": "${turn.turn_id}",`);
+  lines.push(`    "role": "${roleId}",`);
+  lines.push(`    "runtime_id": "${role?.runtime || 'manual'}",`);
+  lines.push('    "status": "completed",');
+  lines.push('    "summary": "...",');
+  lines.push('    "decisions": [{"id":"DEC-001","category":"scope","statement":"...","rationale":"..."}],');
+  lines.push('    "objections": [{"id":"OBJ-001","severity":"medium","statement":"...","status":"raised"}],');
+  lines.push('    "files_changed": [],');
+  lines.push('    "verification": {"status":"skipped","commands":[],"evidence_summary":"..."},');
+  lines.push('    "artifact": {"type":"review","ref":null},');
+  lines.push(`    "proposed_next_role": "${getDefaultNextRole(roleId, config)}",`);
+  lines.push('    "phase_transition_request": null,');
+  lines.push('    "run_completion_request": null');
+  lines.push('  }');
+  lines.push('');
+  lines.push('  Docs: https://agentxchain.dev/docs/getting-started');
+  lines.push('');
 
   return lines.join('\n');
 }
 
+/**
+ * Return gate-file hints relevant to the current phase and role.
+ */
+function getPhaseGateHints(phase, roleId, config) {
+  const hints = [];
+  const gates = config.gates || {};
+
+  if (phase === 'planning' && (roleId === 'pm' || roleId === 'human')) {
+    hints.push('.planning/PM_SIGNOFF.md — change "Approved: NO" → "Approved: YES" when ready');
+    hints.push('.planning/ROADMAP.md — define phases and acceptance criteria');
+    hints.push('.planning/SYSTEM_SPEC.md — define ## Purpose, ## Interface, ## Acceptance Tests');
+  } else if (phase === 'implementation' && (roleId === 'dev' || roleId === 'human')) {
+    hints.push('.planning/IMPLEMENTATION_NOTES.md — record what you built and how to verify');
+  } else if (phase === 'qa' && (roleId === 'qa' || roleId === 'human')) {
+    hints.push('.planning/acceptance-matrix.md — mark each requirement PASS/FAIL');
+    hints.push('.planning/ship-verdict.md — change "## Verdict: PENDING" → "## Verdict: SHIP"');
+    hints.push('.planning/RELEASE_NOTES.md — user impact, verification summary, upgrade notes');
+  }
+
+  return hints;
+}
+
+/**
+ * Suggest a reasonable next role based on current role.
+ */
+function getDefaultNextRole(roleId, config) {
+  const routing = config.routing || {};
+  if (routing[roleId]?.default_next) return routing[roleId].default_next;
+  if (roleId === 'pm') return 'dev';
+  if (roleId === 'dev') return 'qa';
+  if (roleId === 'qa') return 'human';
+  return 'human';
+}
+
 /**
  * Wait for the staged turn result file to appear.
  *