agentxchain 2.79.0 → 2.81.0

package/README.md

@@ -167,6 +167,8 @@ agentxchain step
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
+| `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
+| `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
 | `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |

package/bin/agentxchain.js

@@ -60,6 +60,7 @@ import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
+import { replayTurnCommand } from '../src/commands/replay.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -82,6 +83,7 @@ import { reportCommand } from '../src/commands/report.js';
 import {
   pluginInstallCommand,
   pluginListCommand,
+  pluginListAvailableCommand,
   pluginRemoveCommand,
   pluginUpgradeCommand,
 } from '../src/commands/plugin.js';
@@ -387,6 +389,17 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyExportCommand);
 
+const replayCmd = program
+  .command('replay')
+  .description('Replay accepted governed evidence against the current workspace');
+
+replayCmd
+  .command('turn [turn_id]')
+  .description('Replay an accepted turn\'s declared machine-evidence commands from history')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
+  .action(replayTurnCommand);
+
 program
   .command('migrate')
   .description('Migrate a legacy v3 project to governed format')
@@ -485,6 +498,12 @@ pluginCmd
   .option('-j, --json', 'Output as JSON')
   .action(pluginListCommand);
 
+pluginCmd
+  .command('list-available')
+  .description('List built-in plugins available for installation')
+  .option('-j, --json', 'Output as JSON')
+  .action(pluginListAvailableCommand);
+
 pluginCmd
   .command('remove <name>')
   .description('Remove an installed plugin')

package/builtin-plugins/plugin-github-issues/README.md

@@ -0,0 +1,31 @@
+# @agentxchain/plugin-github-issues
+
+Built-in AgentXchain plugin that mirrors governed run status into a configured GitHub issue.
+
+Install from this repo:
+
+```bash
+agentxchain plugin install ./plugins/plugin-github-issues
+```
+
+Hook phases:
+
+- `after_acceptance`
+- `on_escalation`
+
+Required config:
+
+- `repo`: GitHub repository in `owner/name` form
+- `issue_number`: GitHub issue number
+
+Optional config:
+
+- `token_env`: token environment variable name (default runtime fallback: `GITHUB_TOKEN`)
+- `api_base_url`: GitHub API base URL (default runtime fallback: `https://api.github.com`)
+- `label_prefix`: managed label prefix (default runtime fallback: `agentxchain`)
+
+Scope notes:
+
+- One plugin-owned comment per run, updated in place
+- Managed labels track phase or blocked state only
+- This plugin does **not** close issues or claim post-gate approval state because the hook surface does not provide post-gate truth

package/builtin-plugins/plugin-github-issues/agentxchain-plugin.json

@@ -0,0 +1,53 @@
+{
+  "schema_version": "0.1",
+  "name": "@agentxchain/plugin-github-issues",
+  "version": "0.1.0",
+  "description": "Mirrors governed run status into a configured GitHub issue using advisory hooks.",
+  "hooks": {
+    "after_acceptance": [
+      {
+        "name": "github_issues_acceptance",
+        "type": "process",
+        "command": ["node", "./hooks/after-acceptance.js"],
+        "timeout_ms": 8000,
+        "mode": "advisory"
+      }
+    ],
+    "on_escalation": [
+      {
+        "name": "github_issues_escalation",
+        "type": "process",
+        "command": ["node", "./hooks/on-escalation.js"],
+        "timeout_ms": 8000,
+        "mode": "advisory"
+      }
+    ]
+  },
+  "config_schema": {
+    "type": "object",
+    "required": ["repo", "issue_number"],
+    "additionalProperties": false,
+    "properties": {
+      "repo": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_.-]+\\/[A-Za-z0-9_.-]+$"
+      },
+      "issue_number": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "token_env": {
+        "type": "string",
+        "minLength": 1
+      },
+      "api_base_url": {
+        "type": "string",
+        "minLength": 1
+      },
+      "label_prefix": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

package/builtin-plugins/plugin-github-issues/hooks/_shared.js

@@ -0,0 +1,305 @@
+import http from 'node:http';
+import https from 'node:https';
+import process from 'node:process';
+
+const DEFAULT_API_BASE = 'https://api.github.com';
+const DEFAULT_TOKEN_ENV = 'GITHUB_TOKEN';
+const DEFAULT_LABEL_PREFIX = 'agentxchain';
+
+export async function readEnvelope() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input.trim() ? JSON.parse(input) : {};
+}
+
+function writeResult(result) {
+  process.stdout.write(JSON.stringify(result));
+}
+
+function warn(message) {
+  writeResult({ verdict: 'warn', message });
+}
+
+function ok(message) {
+  writeResult({ verdict: 'allow', message });
+}
+
+function parsePluginConfig() {
+  try {
+    return JSON.parse(process.env.AGENTXCHAIN_PLUGIN_CONFIG || '{}');
+  } catch {
+    return null;
+  }
+}
+
+function normalizeConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return null;
+  }
+
+  const repo = typeof raw.repo === 'string' ? raw.repo.trim() : '';
+  const issueNumber = Number.isInteger(raw.issue_number) ? raw.issue_number : null;
+  if (!repo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || !issueNumber || issueNumber < 1) {
+    return null;
+  }
+
+  const [owner, name] = repo.split('/');
+  return {
+    owner,
+    repo: name,
+    issue_number: issueNumber,
+    token_env: typeof raw.token_env === 'string' && raw.token_env.trim() ? raw.token_env.trim() : DEFAULT_TOKEN_ENV,
+    api_base_url: typeof raw.api_base_url === 'string' && raw.api_base_url.trim()
+      ? raw.api_base_url.trim().replace(/\/+$/, '')
+      : DEFAULT_API_BASE,
+    label_prefix: typeof raw.label_prefix === 'string' && raw.label_prefix.trim()
+      ? raw.label_prefix.trim()
+      : DEFAULT_LABEL_PREFIX,
+  };
+}
+
+function getToken(config) {
+  return process.env[config.token_env] || '';
+}
+
+function buildHeaders(token, body) {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body),
+    'user-agent': '@agentxchain/plugin-github-issues',
+    'x-github-api-version': '2022-11-28',
+  };
+}
+
+async function requestJson(config, token, method, path, bodyValue) {
+  const url = new URL(path, `${config.api_base_url}/`);
+  const body = bodyValue === undefined ? '' : JSON.stringify(bodyValue);
+  const transport = url.protocol === 'https:' ? https : http;
+
+  const response = await new Promise((resolve, reject) => {
+    const req = transport.request(url, {
+      method,
+      headers: buildHeaders(token, body),
+      timeout: 7000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        resolve({
+          status: res.statusCode || 500,
+          body: data,
+        });
+      });
+    });
+
+    req.on('timeout', () => req.destroy(new Error('request timed out')));
+    req.on('error', reject);
+    if (body) {
+      req.write(body);
+    }
+    req.end();
+  });
+
+  let parsed = null;
+  if (response.body) {
+    try {
+      parsed = JSON.parse(response.body);
+    } catch {
+      parsed = null;
+    }
+  }
+
+  return {
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    body: parsed,
+    raw: response.body,
+  };
+}
+
+async function listComments(config, token) {
+  const comments = [];
+  for (let page = 1; page <= 10; page += 1) {
+    const response = await requestJson(
+      config,
+      token,
+      'GET',
+      `/repos/${config.owner}/${config.repo}/issues/${config.issue_number}/comments?per_page=100&page=${page}`,
+    );
+
+    if (!response.ok) {
+      return response;
+    }
+
+    const pageItems = Array.isArray(response.body) ? response.body : [];
+    comments.push(...pageItems);
+    if (pageItems.length < 100) {
+      break;
+    }
+  }
+
+  return { ok: true, body: comments };
+}
+
+function runMarker(runId) {
+  return `<!-- agentxchain:github-issues:run:${runId || 'unknown'} -->`;
+}
+
+function buildManagedLabels(config, event) {
+  const labels = [config.label_prefix];
+  if (event.type === 'after_acceptance' && event.phase) {
+    labels.push(`${config.label_prefix}:phase:${event.phase}`);
+  }
+  if (event.type === 'on_escalation') {
+    labels.push(`${config.label_prefix}:blocked`);
+  }
+  return labels;
+}
+
+function mergeLabels(existingLabels, managedLabels, labelPrefix) {
+  const retained = existingLabels
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.name))
+    .filter((name) => typeof name === 'string' && name && !name.startsWith(`${labelPrefix}:`) && name !== labelPrefix);
+
+  return [...retained, ...managedLabels];
+}
+
+function buildAcceptanceBody(envelope) {
+  const payload = envelope.payload || {};
+  return [
+    runMarker(envelope.run_id),
+    '## AgentXchain Run Update',
+    '',
+    `- Run: \`${envelope.run_id || 'unknown'}\``,
+    '- Event: `after_acceptance`',
+    `- Status: \`${payload.run_status || 'active'}\``,
+    `- Phase: \`${payload.phase || 'unknown'}\``,
+    `- Latest accepted turn: \`${payload.turn_id || 'unknown'}\` (\`${payload.role_id || 'unknown'}\`)`,
+    `- History index: \`${payload.history_entry_index ?? 'unknown'}\``,
+    `- Decisions on latest turn: \`${payload.decisions_count ?? 0}\``,
+    `- Objections on latest turn: \`${payload.objections_count ?? 0}\``,
+    `- Updated: \`${envelope.timestamp || new Date().toISOString()}\``,
+    '',
+    'Plugin-owned comment from `@agentxchain/plugin-github-issues`.',
+  ].join('\n');
+}
+
+function buildEscalationBody(envelope) {
+  const payload = envelope.payload || {};
+  return [
+    runMarker(envelope.run_id),
+    '## AgentXchain Run Update',
+    '',
+    `- Run: \`${envelope.run_id || 'unknown'}\``,
+    '- Event: `on_escalation`',
+    '- Status: `blocked`',
+    `- Blocked reason: \`${payload.blocked_reason || 'unknown'}\``,
+    `- Failed turn: \`${payload.failed_turn_id || 'unknown'}\` (\`${payload.failed_role || 'unknown'}\`)`,
+    `- Recovery action: ${payload.recovery_action || 'unknown'}`,
+    `- Last error: ${payload.last_error || 'unknown'}`,
+    `- Updated: \`${envelope.timestamp || new Date().toISOString()}\``,
+    '',
+    'Plugin-owned comment from `@agentxchain/plugin-github-issues`.',
+  ].join('\n');
+}
+
+async function upsertComment(config, token, envelope, body) {
+  const comments = await listComments(config, token);
+  if (!comments.ok) {
+    return comments;
+  }
+
+  const marker = runMarker(envelope.run_id);
+  const existing = comments.body.find((comment) => typeof comment?.body === 'string' && comment.body.includes(marker));
+
+  if (existing) {
+    return requestJson(
+      config,
+      token,
+      'PATCH',
+      `/repos/${config.owner}/${config.repo}/issues/comments/${existing.id}`,
+      { body },
+    );
+  }
+
+  return requestJson(
+    config,
+    token,
+    'POST',
+    `/repos/${config.owner}/${config.repo}/issues/${config.issue_number}/comments`,
+    { body },
+  );
+}
+
+async function syncLabels(config, token, event) {
+  const issue = await requestJson(
+    config,
+    token,
+    'GET',
+    `/repos/${config.owner}/${config.repo}/issues/${config.issue_number}`,
+  );
+  if (!issue.ok) {
+    return issue;
+  }
+
+  const labels = mergeLabels(issue.body?.labels || [], buildManagedLabels(config, event), config.label_prefix);
+  return requestJson(
+    config,
+    token,
+    'PUT',
+    `/repos/${config.owner}/${config.repo}/issues/${config.issue_number}/labels`,
+    { labels },
+  );
+}
+
+export async function publishRunUpdate(kind) {
+  try {
+    const rawConfig = parsePluginConfig();
+    if (rawConfig === null) {
+      warn('Invalid AGENTXCHAIN_PLUGIN_CONFIG JSON');
+      return;
+    }
+
+    const config = normalizeConfig(rawConfig);
+    if (!config) {
+      warn('Missing or invalid GitHub issue plugin config');
+      return;
+    }
+
+    const token = getToken(config);
+    if (!token) {
+      warn(`Missing GitHub token env ${config.token_env}`);
+      return;
+    }
+
+    const envelope = await readEnvelope();
+    const body = kind === 'after_acceptance'
+      ? buildAcceptanceBody(envelope)
+      : buildEscalationBody(envelope);
+
+    const comment = await upsertComment(config, token, envelope, body);
+    if (!comment.ok) {
+      warn(`GitHub comment sync failed with HTTP ${comment.status}`);
+      return;
+    }
+
+    const labels = await syncLabels(config, token, {
+      type: kind,
+      phase: envelope.payload?.phase || null,
+    });
+    if (!labels.ok) {
+      warn(`GitHub label sync failed with HTTP ${labels.status}`);
+      return;
+    }
+
+    ok('GitHub issue updated');
+  } catch (error) {
+    warn(`GitHub issue sync failed: ${error.message || String(error)}`);
+  }
+}

package/builtin-plugins/plugin-github-issues/hooks/after-acceptance.js

@@ -0,0 +1,3 @@
+import { publishRunUpdate } from './_shared.js';
+
+await publishRunUpdate('after_acceptance');

package/builtin-plugins/plugin-github-issues/hooks/on-escalation.js

@@ -0,0 +1,3 @@
+import { publishRunUpdate } from './_shared.js';
+
+await publishRunUpdate('on_escalation');

package/builtin-plugins/plugin-github-issues/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@agentxchain/plugin-github-issues",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Built-in AgentXchain plugin that mirrors governed run status into a GitHub issue.",
+  "license": "MIT"
+}

package/builtin-plugins/plugin-json-report/README.md

@@ -0,0 +1,30 @@
+# @agentxchain/plugin-json-report
+
+Built-in AgentXchain plugin that writes structured lifecycle report artifacts into `.agentxchain/reports/`.
+
+Install from this repo:
+
+```bash
+agentxchain plugin install ./plugins/plugin-json-report
+```
+
+Optional install-time config:
+
+```bash
+agentxchain plugin install ./plugins/plugin-json-report \
+  --config '{"report_dir":".agentxchain/custom-reports"}'
+```
+
+Hook phases:
+
+- `after_acceptance`
+- `before_gate`
+- `on_escalation`
+
+Outputs:
+
+- timestamped JSON file per invocation
+- `latest.json`
+- `latest-<hook_phase>.json`
+- default output path `.agentxchain/reports`
+- `report_dir` may override the path, but it must stay inside the governed project root

package/builtin-plugins/plugin-json-report/agentxchain-plugin.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": "0.1",
+  "name": "@agentxchain/plugin-json-report",
+  "version": "0.1.0",
+  "description": "Writes structured JSON lifecycle reports into .agentxchain/reports/.",
+  "hooks": {
+    "after_acceptance": [
+      {
+        "name": "json_report_acceptance",
+        "type": "process",
+        "command": ["node", "./hooks/after-acceptance.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "before_gate": [
+      {
+        "name": "json_report_gate",
+        "type": "process",
+        "command": ["node", "./hooks/before-gate.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "on_escalation": [
+      {
+        "name": "json_report_escalation",
+        "type": "process",
+        "command": ["node", "./hooks/on-escalation.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ]
+  },
+  "config_schema": {
+    "type": "object",
+    "properties": {
+      "report_dir": {
+        "type": "string",
+        "default": ".agentxchain/reports"
+      }
+    }
+  }
+}

package/builtin-plugins/plugin-json-report/hooks/_shared.js

@@ -0,0 +1,92 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+
+export async function readEnvelope() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input.trim() ? JSON.parse(input) : {};
+}
+
+function safeTimestamp(timestamp) {
+  return (timestamp || new Date().toISOString()).replace(/[:]/g, '-');
+}
+
+function parsePluginConfig() {
+  try {
+    const parsed = JSON.parse(process.env.AGENTXCHAIN_PLUGIN_CONFIG || '{}');
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function resolveReportDir(projectRoot, config) {
+  const configuredDir = typeof config?.report_dir === 'string' && config.report_dir.trim()
+    ? config.report_dir.trim()
+    : '.agentxchain/reports';
+  const reportDir = resolve(projectRoot, configuredDir);
+  const relativePath = relative(projectRoot, reportDir);
+  if (relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath))) {
+    return reportDir;
+  }
+  return null;
+}
+
+export function writeReport(pluginName, envelope) {
+  const projectRoot = process.env.AGENTXCHAIN_PROJECT_ROOT;
+  if (!projectRoot) {
+    process.stdout.write(JSON.stringify({
+      verdict: 'warn',
+      message: 'Missing AGENTXCHAIN_PROJECT_ROOT',
+    }));
+    return;
+  }
+
+  const config = parsePluginConfig();
+  if (config === null) {
+    process.stdout.write(JSON.stringify({
+      verdict: 'warn',
+      message: 'Invalid AGENTXCHAIN_PLUGIN_CONFIG JSON',
+    }));
+    return;
+  }
+
+  const hookPhase = envelope.hook_phase || 'unknown';
+  const timestamp = envelope.timestamp || new Date().toISOString();
+  const reportDir = resolveReportDir(projectRoot, config);
+  if (!reportDir) {
+    process.stdout.write(JSON.stringify({
+      verdict: 'warn',
+      message: 'Configured report_dir must stay within the governed project root',
+    }));
+    return;
+  }
+
+  mkdirSync(reportDir, { recursive: true });
+
+  const report = {
+    plugin_name: pluginName,
+    hook_phase: hookPhase,
+    run_id: envelope.run_id || null,
+    hook_name: envelope.hook_name || null,
+    turn_id: envelope.payload?.turn_id || envelope.turn_id || envelope.payload?.failed_turn_id || null,
+    timestamp,
+    payload: envelope.payload || {},
+  };
+
+  const stampedName = `${safeTimestamp(timestamp)}-${hookPhase}.json`;
+  writeFileSync(join(reportDir, stampedName), JSON.stringify(report, null, 2) + '\n');
+  writeFileSync(join(reportDir, 'latest.json'), JSON.stringify(report, null, 2) + '\n');
+  writeFileSync(join(reportDir, `latest-${hookPhase}.json`), JSON.stringify(report, null, 2) + '\n');
+
+  process.stdout.write(JSON.stringify({
+    verdict: 'allow',
+    message: `Wrote ${stampedName}`,
+  }));
+}

package/builtin-plugins/plugin-json-report/hooks/after-acceptance.js

@@ -0,0 +1,4 @@
+import { readEnvelope, writeReport } from './_shared.js';
+
+const envelope = await readEnvelope();
+writeReport('@agentxchain/plugin-json-report', envelope);

package/builtin-plugins/plugin-json-report/hooks/before-gate.js

@@ -0,0 +1,4 @@
+import { readEnvelope, writeReport } from './_shared.js';
+
+const envelope = await readEnvelope();
+writeReport('@agentxchain/plugin-json-report', envelope);

package/builtin-plugins/plugin-json-report/hooks/on-escalation.js

@@ -0,0 +1,4 @@
+import { readEnvelope, writeReport } from './_shared.js';
+
+const envelope = await readEnvelope();
+writeReport('@agentxchain/plugin-json-report', envelope);

package/builtin-plugins/plugin-json-report/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@agentxchain/plugin-json-report",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Built-in AgentXchain plugin that writes JSON lifecycle reports for CI and operators.",
+  "license": "MIT"
+}