agentxchain 2.78.0 → 2.80.0

package/bin/agentxchain.js

@@ -82,6 +82,7 @@ import { reportCommand } from '../src/commands/report.js';
 import {
   pluginInstallCommand,
   pluginListCommand,
+  pluginListAvailableCommand,
   pluginRemoveCommand,
   pluginUpgradeCommand,
 } from '../src/commands/plugin.js';
@@ -485,6 +486,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"
+}

package/builtin-plugins/plugin-slack-notify/README.md

@@ -0,0 +1,34 @@
+# @agentxchain/plugin-slack-notify
+
+Built-in AgentXchain plugin that posts advisory lifecycle notifications to a Slack incoming webhook.
+
+Install from this repo:
+
+```bash
+agentxchain plugin install ./plugins/plugin-slack-notify
+```
+
+Optional install-time config:
+
+```bash
+agentxchain plugin install ./plugins/plugin-slack-notify \
+  --config '{"webhook_env":"MY_SLACK_WEBHOOK_URL","mention":"@ops"}'
+```
+
+Runtime inputs:
+
+- `webhook_env` (optional): which env var contains the Slack incoming webhook URL
+- `mention` (optional): prefix added to each message
+- default webhook lookup is `AGENTXCHAIN_SLACK_WEBHOOK_URL`, then `SLACK_WEBHOOK_URL`
+- `AGENTXCHAIN_SLACK_MENTION` remains a runtime fallback when `mention` is not configured
+
+Hook phases:
+
+- `after_acceptance`
+- `before_gate`
+- `on_escalation`
+
+Failure semantics:
+
+- advisory only
+- missing webhook config or delivery failures return `warn`, never `block`

package/builtin-plugins/plugin-slack-notify/agentxchain-plugin.json

@@ -0,0 +1,47 @@
+{
+  "schema_version": "0.1",
+  "name": "@agentxchain/plugin-slack-notify",
+  "version": "0.1.0",
+  "description": "Posts governed lifecycle notifications to a Slack incoming webhook.",
+  "hooks": {
+    "after_acceptance": [
+      {
+        "name": "slack_notify_acceptance",
+        "type": "process",
+        "command": ["node", "./hooks/after-acceptance.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "before_gate": [
+      {
+        "name": "slack_notify_gate",
+        "type": "process",
+        "command": ["node", "./hooks/before-gate.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "on_escalation": [
+      {
+        "name": "slack_notify_escalation",
+        "type": "process",
+        "command": ["node", "./hooks/on-escalation.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ]
+  },
+  "config_schema": {
+    "type": "object",
+    "properties": {
+      "webhook_env": {
+        "type": "string",
+        "default": "AGENTXCHAIN_SLACK_WEBHOOK_URL"
+      },
+      "mention": {
+        "type": "string"
+      }
+    }
+  }
+}

package/builtin-plugins/plugin-slack-notify/hooks/_shared.js

@@ -0,0 +1,115 @@
+import http from 'node:http';
+import https from 'node:https';
+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 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 resolveWebhookSetting(config) {
+  const configuredEnv = typeof config?.webhook_env === 'string' ? config.webhook_env.trim() : '';
+  if (configuredEnv) {
+    return {
+      envName: configuredEnv,
+      url: process.env[configuredEnv] || '',
+    };
+  }
+
+  return {
+    envName: 'AGENTXCHAIN_SLACK_WEBHOOK_URL or SLACK_WEBHOOK_URL',
+    url: process.env.AGENTXCHAIN_SLACK_WEBHOOK_URL || process.env.SLACK_WEBHOOK_URL || '',
+  };
+}
+
+function buildText(title, lines, config) {
+  const mention = typeof config?.mention === 'string' && config.mention.trim()
+    ? config.mention.trim()
+    : (process.env.AGENTXCHAIN_SLACK_MENTION || '');
+  return [mention, title, ...lines.filter(Boolean)].filter(Boolean).join('\n');
+}
+
+export async function sendSlackMessage(title, lines) {
+  const config = parsePluginConfig();
+  if (config === null) {
+    return {
+      verdict: 'warn',
+      message: 'Invalid AGENTXCHAIN_PLUGIN_CONFIG JSON',
+    };
+  }
+
+  const webhookSetting = resolveWebhookSetting(config);
+  const webhookUrl = webhookSetting.url;
+  if (!webhookUrl) {
+    return {
+      verdict: 'warn',
+      message: `Missing Slack webhook env ${webhookSetting.envName}`,
+    };
+  }
+
+  const body = JSON.stringify({
+    text: buildText(title, lines, config),
+  });
+
+  const url = new URL(webhookUrl);
+  const transport = url.protocol === 'https:' ? https : http;
+  let response;
+  try {
+    response = await new Promise((resolve, reject) => {
+      const req = transport.request(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+        },
+        timeout: 4000,
+      }, (res) => {
+        res.resume();
+        res.on('end', () => resolve({ ok: (res.statusCode || 500) >= 200 && (res.statusCode || 500) < 300, status: res.statusCode || 500 }));
+      });
+
+      req.on('timeout', () => {
+        req.destroy(new Error('request timed out'));
+      });
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  } catch (error) {
+    return {
+      verdict: 'warn',
+      message: `Slack webhook request failed: ${error.message}`,
+    };
+  }
+
+  if (!response.ok) {
+    return {
+      verdict: 'warn',
+      message: `Slack webhook failed with HTTP ${response.status}`,
+    };
+  }
+
+  return {
+    verdict: 'allow',
+    message: 'Slack notification delivered',
+  };
+}
+
+export function writeResult(result) {
+  process.stdout.write(JSON.stringify(result));
+}

package/builtin-plugins/plugin-slack-notify/hooks/after-acceptance.js

@@ -0,0 +1,16 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const result = await sendSlackMessage('AgentXchain accepted turn', [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `phase: ${payload.phase || 'unknown'}`,
+  `role: ${payload.role_id || 'unknown'}`,
+  `turn: ${payload.turn_id || 'unknown'}`,
+  `decisions: ${payload.decisions_count ?? 0}`,
+  `objections: ${payload.objections_count ?? 0}`,
+  `status: ${payload.run_status || 'unknown'}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/hooks/before-gate.js

@@ -0,0 +1,18 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const title = payload.gate_type === 'run_completion'
+  ? 'AgentXchain run completion awaiting approval'
+  : 'AgentXchain phase gate awaiting approval';
+
+const result = await sendSlackMessage(title, [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `gate type: ${payload.gate_type || 'unknown'}`,
+  `current phase: ${payload.current_phase || 'unknown'}`,
+  `target phase: ${payload.target_phase || 'n/a'}`,
+  `history length: ${payload.history_length ?? 0}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/hooks/on-escalation.js

@@ -0,0 +1,15 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const result = await sendSlackMessage('AgentXchain escalation', [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `blocked reason: ${payload.blocked_reason || 'unknown'}`,
+  `recovery: ${payload.recovery_action || 'unknown'}`,
+  `role: ${payload.failed_role || 'unknown'}`,
+  `turn: ${payload.failed_turn_id || 'unknown'}`,
+  `error: ${payload.last_error || 'unknown'}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@agentxchain/plugin-slack-notify",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Built-in AgentXchain plugin that posts advisory lifecycle notifications to Slack.",
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.78.0",
+  "version": "2.80.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "src/",
     "dashboard/",
     "scripts/",
+    "builtin-plugins/",
     "README.md"
   ],
   "scripts": {

package/src/commands/plugin.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import { installPlugin, listInstalledPlugins, removePlugin, upgradePlugin } from '../lib/plugins.js';
+import { installPlugin, listInstalledPlugins, listAvailablePlugins, removePlugin, upgradePlugin } from '../lib/plugins.js';
 
 function parsePluginConfigOptions(options) {
   if (options.config && options.configFile) {
@@ -117,6 +117,36 @@ export async function pluginRemoveCommand(name, options) {
   console.log(`  Path: ${result.install_path}`);
 }
 
+export async function pluginListAvailableCommand(options) {
+  const result = listAvailablePlugins();
+
+  if (!result.ok) {
+    console.error(result.error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ plugins: result.plugins }, null, 2));
+    return;
+  }
+
+  if (result.plugins.length === 0) {
+    console.log('No built-in plugins available.');
+    return;
+  }
+
+  console.log(`Available built-in plugins: ${result.plugins.length}`);
+  for (const plugin of result.plugins) {
+    console.log(`  ${plugin.short_name}`);
+    console.log(`    ${plugin.description}`);
+    console.log(`    Install: ${plugin.install_command}`);
+  }
+}
+
 export async function pluginUpgradeCommand(name, source, options) {
   const config = parsePluginConfigOptions(options);
   if (!config.ok) {

package/src/lib/plugins.js

@@ -9,7 +9,8 @@ import {
   statSync,
 } from 'fs';
 import { createHash } from 'crypto';
-import { join, resolve, relative } from 'path';
+import { dirname, join, resolve, relative } from 'path';
+import { fileURLToPath } from 'url';
 import { tmpdir } from 'os';
 import { spawnSync } from 'child_process';
 
@@ -23,6 +24,55 @@ export const PLUGINS_DIR = '.agentxchain/plugins';
 const PLUGIN_SCHEMA_VERSION = '0.1';
 const PLUGIN_NAME_RE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/;
 
+const __filename_local = fileURLToPath(import.meta.url);
+const __dirname_local = dirname(__filename_local);
+const BUILTIN_PLUGINS_DIR = join(__dirname_local, '../../builtin-plugins');
+
+const BUILTIN_PLUGIN_SHORT_NAMES = {
+  'slack-notify': 'plugin-slack-notify',
+  'json-report': 'plugin-json-report',
+  'github-issues': 'plugin-github-issues',
+};
+
+function resolveBuiltinPlugin(spec) {
+  const dirName = BUILTIN_PLUGIN_SHORT_NAMES[spec];
+  if (!dirName) return null;
+  const pluginDir = join(BUILTIN_PLUGINS_DIR, dirName);
+  if (!existsSync(pluginDir)) return null;
+  const root = findManifestRoot(pluginDir);
+  if (!root) return null;
+  return {
+    ok: true,
+    type: 'builtin',
+    root,
+    sourceSpec: spec,
+    cleanup: null,
+  };
+}
+
+export function listAvailablePlugins() {
+  const available = [];
+  for (const [shortName, dirName] of Object.entries(BUILTIN_PLUGIN_SHORT_NAMES)) {
+    const pluginDir = join(BUILTIN_PLUGINS_DIR, dirName);
+    if (!existsSync(pluginDir)) continue;
+    const manifestPath = join(pluginDir, PLUGIN_MANIFEST_FILE);
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = readJson(manifestPath);
+      available.push({
+        short_name: shortName,
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        install_command: `agentxchain plugin install ${shortName}`,
+      });
+    } catch {
+      // skip broken manifests
+    }
+  }
+  return { ok: true, plugins: available };
+}
+
 function clone(value) {
   return JSON.parse(JSON.stringify(value));
 }
@@ -199,6 +249,9 @@ function resolvePluginSource(spec, startDir) {
     }
   }
 
+  const builtin = resolveBuiltinPlugin(spec);
+  if (builtin) return builtin;
+
   const packed = packNpmPlugin(spec);
   if (!packed.ok) {
     return packed;