create-byan-agent 2.29.2 → 2.38.0

package/install/templates/_byan/mcp/byan-mcp-server/lib/channel-server.js

@@ -0,0 +1,234 @@
+/**
+ * lib/channel-server.js — Serveur MCP channel Claude Code pour byan_web.
+ *
+ * POURQUOI ce fichier est une factory et non un entrypoint direct :
+ * la même factory est importée par channel-entry.js (entrypoint stdio pour
+ * --dangerously-load-development-channels) ET par les tests, sans effet de
+ * bord transport au import-time.
+ *
+ * Protocole Channel (research preview CC v2.1.80+) :
+ *   - capabilities.experimental['claude/channel'] = {}
+ *     -> CC enregistre un listener de notification
+ *   - mcp.notification({ method: 'notifications/claude/channel', params })
+ *     -> event injecté dans la session CC comme <channel source="byan" ...>
+ *   - reply tool "byan_session_reply" (capabilities.tools = {})
+ *     -> CC appelle le tool quand Claude veut répondre
+ *
+ * Gate sender : le poll utilise BYAN_API_TOKEN (scope user). La barrière
+ * anti-injection est le RBAC owner côté serveur byan_web ; ce channel ne
+ * reçoit que les messages des sessions du user authentifié.
+ */
+
+import { Server }              from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { startPollLoop } from './channel-poll.js';
+
+/** Intervalle de poll par défaut (ms). Exposé pour override dans les tests. */
+export const DEFAULT_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Reply tool : Claude l'appelle pour renvoyer une réponse vers byan_web.
+ *
+ * Hypothèse F2b : POST /api/sessions/:session_id/reply { content }
+ *   -> { ok: true }
+ * Le nom du tool côté CC sera mcp__byan-channel__byan_session_reply.
+ */
+const REPLY_TOOL = {
+  name: 'byan_session_reply',
+  description:
+    'Reply to a user message received from byan_web. Call this when a <channel source="byan"> event arrives and a response is expected. Pass the session_id from the event meta attribute and the text to send back.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      session_id: {
+        type: 'string',
+        description: 'The session_id from the inbound <channel> event meta.',
+      },
+      content: {
+        type: 'string',
+        description: 'The reply text to send back to the user in byan_web.',
+      },
+    },
+    required: ['session_id', 'content'],
+    additionalProperties: false,
+  },
+};
+
+/**
+ * Crée un serveur MCP channel byan sans le connecter (transport séparé).
+ * Accepte un fetchImpl pour permettre le mock en test.
+ *
+ * @param {object} opts
+ * @param {string}   opts.apiUrl        Base URL byan_web
+ * @param {string}   opts.apiToken      Token du user (ApiKey scheme si préfixe byan_)
+ * @param {number}   [opts.intervalMs]  Override intervalle de poll (tests)
+ * @param {object}   [opts.fetchImpl]   Override fetch (tests)
+ * @returns {Server} Instance MCP Server (non connectée)
+ */
+export function createChannelServer({ apiUrl, apiToken, intervalMs, fetchImpl } = {}) {
+  const fetchFn    = fetchImpl ?? globalThis.fetch;
+  const interval   = intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+  const authHeader = () => {
+    if (!apiToken) return {};
+    const scheme = apiToken.startsWith('byan_') ? 'ApiKey' : 'Bearer';
+    return { Authorization: `${scheme} ${apiToken}` };
+  };
+
+  const mcp = new Server(
+    { name: 'byan-channel', version: '0.1.0' },
+    {
+      capabilities: {
+        // Clé qui fait de ce serveur un channel CC.
+        // CC enregistre un listener de notification sur cette capability.
+        experimental: { 'claude/channel': {} },
+        // tools: {} requis pour que CC découvre les tools de réponse.
+        tools: {},
+      },
+      // Instructions injectées dans le system prompt CC.
+      // Dis à Claude : les events arrivent comme <channel source="byan" ...>,
+      // il doit répondre via byan_session_reply en passant session_id.
+      instructions:
+        'Events from byan_web arrive as <channel source="byan" session_id="..." msg_id="...">. ' +
+        'When a user message arrives, read it and reply using the byan_session_reply tool, ' +
+        'passing the session_id from the tag attribute. ' +
+        'Do not reply if the event is a system notification (no reply expected).',
+    }
+  );
+
+  // Découverte des tools par CC.
+  mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [REPLY_TOOL],
+  }));
+
+  // Appel du reply tool par Claude.
+  mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+
+    if (name === 'byan_session_reply') {
+      const { session_id, content } = args;
+      if (!session_id || !content) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: 'Error: session_id and content are required.' }],
+        };
+      }
+      if (!apiToken) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: 'Error: BYAN_API_TOKEN is not configured.' }],
+        };
+      }
+
+      // Hypothèse F2b : POST /api/sessions/:session_id/reply { content }
+      try {
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), 8_000);
+        let res;
+        try {
+          res = await fetchFn(
+            `${apiUrl}/api/sessions/${encodeURIComponent(session_id)}/reply`,
+            {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                ...authHeader(),
+              },
+              body: JSON.stringify({ content }),
+              signal: ctrl.signal,
+            }
+          );
+        } finally {
+          clearTimeout(timeout);
+        }
+
+        if (!res.ok) {
+          const text = await res.text().catch(() => '');
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `Error: byan_web replied ${res.status} — ${text}` }],
+          };
+        }
+
+        return { content: [{ type: 'text', text: JSON.stringify({ ok: true, session_id }) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Error sending reply: ${err.message}` }],
+        };
+      }
+    }
+
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+    };
+  });
+
+  // Boucle de poll : démarrée après la connexion transport pour que
+  // mcp.notification() ait un transport actif. La connexion est gérée par
+  // l'entrypoint ; ici on expose startPolling() pour que l'entrypoint
+  // démarre la boucle au bon moment.
+  let pollLoop = null;
+
+  /**
+   * Démarre la boucle de poll. Appeler APRÈS mcp.connect(transport).
+   * Retourne { stop } pour arrêter proprement.
+   */
+  function startPolling() {
+    if (!apiUrl || !apiToken) {
+      process.stderr.write(
+        '[byan-channel] BYAN_API_URL ou BYAN_API_TOKEN manquant — poll désactivé\n'
+      );
+      return { stop: () => {} };
+    }
+
+    pollLoop = startPollLoop({
+      apiUrl,
+      apiToken,
+      intervalMs: interval,
+      fetchImpl: fetchFn,
+      onMessage: async (msg) => {
+        // Émettre la notification CC pour chaque message outbox.
+        // meta : chaque clé devient un attribut sur le tag <channel>.
+        // Les clés contenant des tirets sont silencieusement ignorées par CC
+        // (constraint doc) ; on n'utilise que des underscores.
+        await mcp.notification({
+          method: 'notifications/claude/channel',
+          params: {
+            content: msg.content ?? '',
+            meta: {
+              session_id: String(msg.session_id),
+              msg_id:     String(msg.id),
+              ...(msg.meta && typeof msg.meta === 'object' ? msg.meta : {}),
+            },
+          },
+        });
+      },
+    });
+
+    return pollLoop;
+  }
+
+  // Attache startPolling sur le serveur pour l'entrypoint.
+  mcp.startPolling = startPolling;
+
+  return mcp;
+}
+
+/**
+ * Lance le channel en mode stdio (entrypoint direct).
+ * Appelé uniquement depuis channel-entry.js, pas depuis les tests.
+ */
+export async function runChannelStdio({ apiUrl, apiToken, intervalMs, fetchImpl } = {}) {
+  const mcp = createChannelServer({ apiUrl, apiToken, intervalMs, fetchImpl });
+  await mcp.connect(new StdioServerTransport());
+  // La boucle de poll démarre APRÈS connect pour que la notification
+  // ait un transport actif.
+  mcp.startPolling();
+  // Le process reste vivant grâce au transport stdio.
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/completeness-evidence.js

@@ -0,0 +1,159 @@
+// BYAN completeness-evidence (F2).
+//
+// Strict mode already forces >= 3 self-verify passes whose verdict is the
+// agent's word. This module adds an EVIDENCE layer on top: for each locked
+// acceptance criterion it classifies the criterion (code-shaped vs prose) and
+// collects whatever objective proof is available — a captured test-runner exit,
+// a `git diff --stat` constrained to the allowedPaths, or the existence of a
+// named file. The result is { perCriterion, missing }.
+//
+// It ships DISARMED. The strict complete() ATTACHES this report (so the agent
+// and the audit trail see it) but only HARD-REJECTS when
+// delivery-default.json completenessGate.armed === true (default false). With
+// armed=false the report is pure observation: complete() behaves exactly as
+// before. This is the same disarmed-net posture as the autobench Stop guard.
+//
+// The risky-but-pure half (classification, the report shape, the missing list)
+// takes no I/O. The I/O half (running git, reading files) is injected via an
+// `io` object so the unit tests pin behaviour without touching the real
+// filesystem or spawning git — the same shape strict-sync / suitability-store use.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// A criterion is "code-shaped" when it names a testable/file/command artifact:
+// a path, an extension, a test/spec word, a backticked token, or a runner. Else
+// it is prose (a human-judged outcome with no mechanical proof). Pure.
+const CODE_SHAPED_PATTERNS = [
+  /`[^`]+`/, // a backticked token (file, command, symbol)
+  /\b[\w./-]+\.(js|ts|mjs|cjs|json|yaml|yml|md|py|rs|go|sh)\b/i, // a filename with a known ext
+  /\b(test|tests|spec|coverage|passe?s?|green|exit\s*0)\b/i, // test/run vocabulary
+  /\b(npm|node|jest|git|curl|build|lint)\b/i, // a runner / command
+  /\//, // a path separator
+];
+
+export function classifyCriterion(criterion) {
+  const text = String(criterion || '');
+  const isCode = CODE_SHAPED_PATTERNS.some((re) => re.test(text));
+  return isCode ? 'code' : 'prose';
+}
+
+// Default I/O surface. Overridable for tests.
+function defaultIo(projectRoot) {
+  const root = projectRoot || process.cwd();
+  return {
+    existsSync: (p) => fs.existsSync(path.isAbsolute(p) ? p : path.join(root, p)),
+    // git diff --stat constrained to the given paths, run at the project root.
+    gitDiffStat: (paths) => {
+      const argPaths = Array.isArray(paths) && paths.length ? ['--', ...paths] : [];
+      try {
+        const out = execFileSync('git', ['diff', '--stat', ...argPaths], {
+          cwd: root,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim();
+      } catch {
+        return '';
+      }
+    },
+  };
+}
+
+// Pull the candidate file tokens out of a code-shaped criterion: backticked
+// tokens and bare filenames-with-extension. Pure (string-only).
+export function fileTokens(criterion) {
+  const text = String(criterion || '');
+  const tokens = new Set();
+  const backtick = /`([^`]+)`/g;
+  let m;
+  while ((m = backtick.exec(text))) {
+    const inner = m[1].trim();
+    // Only treat a backticked token as a file when it LOOKS like a path/file
+    // (has a separator or an extension); a backticked `npm test` is a command.
+    if (/[./]/.test(inner) && !/\s/.test(inner)) tokens.add(inner);
+  }
+  const bare = /\b[\w./-]+\.(?:js|ts|mjs|cjs|json|yaml|yml|md|py|rs|go|sh)\b/gi;
+  while ((m = bare.exec(text))) tokens.add(m[0]);
+  return [...tokens];
+}
+
+// Build the evidence report for a set of criteria.
+//
+//   criteria      : array of acceptance-criterion strings (the locked scope)
+//   allowedPaths  : the locked allowed paths (scopes the git diff)
+//   context       : { testRun } where testRun is an optional captured run
+//                   { ran:bool, exitCode:number, summary?:string } — the agent
+//                   passes what it observed; we never re-run the suite here.
+//   io            : injected I/O (existsSync, gitDiffStat). Defaults to real fs/git.
+//
+// Returns { perCriterion:[{criterion, kind, hasEvidence, evidence}], missing:[...] }.
+// A code criterion HAS evidence when a named file exists OR a constrained git
+// diff is non-empty OR a green test run was captured. A prose criterion never
+// claims mechanical evidence (it is human-judged) and is reported as such — it
+// is NOT counted as missing, because prose criteria have no mechanical proof by
+// nature; only code criteria without any evidence land in `missing`.
+export function buildEvidence({
+  criteria = [],
+  allowedPaths = [],
+  context = {},
+  projectRoot,
+  io,
+} = {}) {
+  const surface = io || defaultIo(projectRoot);
+  const testRun = context && context.testRun;
+  const diffStat =
+    typeof surface.gitDiffStat === 'function' ? surface.gitDiffStat(allowedPaths) : '';
+  const hasDiff = Boolean(diffStat && diffStat.length);
+  const greenTest = Boolean(testRun && testRun.ran && Number(testRun.exitCode) === 0);
+
+  const perCriterion = [];
+  const missing = [];
+
+  for (const c of Array.isArray(criteria) ? criteria : []) {
+    const kind = classifyCriterion(c);
+    if (kind === 'prose') {
+      perCriterion.push({
+        criterion: c,
+        kind,
+        hasEvidence: false,
+        evidence: { type: 'prose', note: 'human-judged outcome — no mechanical proof expected' },
+      });
+      continue;
+    }
+
+    const tokens = fileTokens(c);
+    const existing = tokens.filter((t) => {
+      try {
+        return surface.existsSync(t);
+      } catch {
+        return false;
+      }
+    });
+
+    let hasEvidence = false;
+    let evidence = null;
+    if (existing.length) {
+      hasEvidence = true;
+      evidence = { type: 'file', files: existing };
+    } else if (greenTest) {
+      hasEvidence = true;
+      evidence = {
+        type: 'test',
+        exitCode: 0,
+        summary: testRun.summary || 'test run captured green',
+      };
+    } else if (hasDiff) {
+      hasEvidence = true;
+      evidence = { type: 'diff', stat: diffStat };
+    } else {
+      evidence = { type: 'none', note: 'no file, no green test run, no diff in allowedPaths' };
+    }
+
+    perCriterion.push({ criterion: c, kind, hasEvidence, evidence });
+    if (!hasEvidence) missing.push(c);
+  }
+
+  return { perCriterion, missing };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/gdoc-client.js

@@ -0,0 +1,203 @@
+// gdoc-client -- headless, byan-owned Google Docs publisher (service account).
+//
+// Turns a content object (see gdoc-content) into a branded Google Doc and returns
+// its URL. Auth is a SERVICE ACCOUNT key (JWT, durable, no browser, no refresh
+// token, no ~7-day expiry) -- distinct from the gw OAuth path. The SA key path is
+// resolved with the same precedence as the rest of the server (env ->
+// ~/.byan/credentials.json), via resolve-config.
+//
+// CONTRACT : never throws. Every failure (no key, dep not installed, API error)
+// is returned as { ok:false, reason, message } so the MCP tool surfaces a clean
+// message instead of crashing the server. On success : { ok:true, documentId,
+// url }.
+//
+// TESTABILITY : googleapis is LAZY-loaded through an injectable `load()` so (a)
+// the server boots even when googleapis is not installed, and (b) tests inject a
+// mock and never touch the network or the real dependency.
+
+import fs from 'node:fs';
+import { resolveConfig } from './resolve-config.js';
+
+// Narrowest scopes that let the SA create a Doc and share it : per-file Drive
+// access + Docs editing. Not the broad .../auth/drive.
+const SCOPES = [
+  'https://www.googleapis.com/auth/documents',
+  'https://www.googleapis.com/auth/drive.file',
+];
+
+function oneLine(err) {
+  return String((err && err.message) || err).split('\n')[0];
+}
+
+// Default lazy loader : import googleapis only when a publish actually runs. A
+// missing dependency is caught by the caller and turned into reason:'dep-missing'
+// -- it must NOT crash the server at import time.
+async function defaultLoad() {
+  const mod = await import('googleapis');
+  return { google: mod.google || (mod.default && mod.default.google) };
+}
+
+/**
+ * Read + parse the service-account JSON key at `keyPath`. Returns the parsed
+ * credentials object, or null on any failure (missing/unreadable/invalid).
+ */
+function readServiceAccount(keyPath, readFileSync) {
+  try {
+    const raw = readFileSync(keyPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.client_email && parsed.private_key) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * createPublisher(deps) -> { publish, status }. All side-effecting deps are
+ * injectable so the flow is fully unit-testable.
+ * @param {object} [deps]
+ * @param {Function} [deps.load]          async () => ({ google }) ; default lazy-imports googleapis
+ * @param {Function} [deps.resolve]       () => config ; default resolveConfig
+ * @param {Function} [deps.readFileSync]  default fs.readFileSync (reads the SA key)
+ */
+function createPublisher(deps = {}) {
+  const load = deps.load || defaultLoad;
+  const resolve = deps.resolve || resolveConfig;
+  const readFileSync = deps.readFileSync || fs.readFileSync;
+
+  // Read-only view of whether a SA key is configured (for a doctor/status surface).
+  function status() {
+    const cfg = resolve();
+    const keyPath = cfg.GOOGLE_APPLICATION_CREDENTIALS || '';
+    const sa = keyPath ? readServiceAccount(keyPath, readFileSync) : null;
+    return {
+      credentialsConfigured: Boolean(keyPath),
+      credentialsValid: Boolean(sa),
+      clientEmail: sa ? sa.client_email : null,
+      templateConfigured: Boolean(cfg.GDOC_TEMPLATE_ID),
+    };
+  }
+
+  /**
+   * publish(content, opts) -> { ok, documentId?, url?, mode?, shared?, reason?, message? }.
+   * opts : { templateId?, shareWith?, role? }. Never throws.
+   */
+  async function publish(content, opts = {}) {
+    const cfg = resolve();
+
+    // 1. SA key present + valid ?
+    const keyPath = cfg.GOOGLE_APPLICATION_CREDENTIALS || '';
+    if (!keyPath) {
+      return {
+        ok: false,
+        reason: 'no-credentials',
+        message:
+          'Aucune cle service account. Definis GOOGLE_APPLICATION_CREDENTIALS (chemin du JSON) dans l\'env ou ~/.byan/credentials.json. Voir docs/google-docs-publish.md.',
+      };
+    }
+    const credentials = readServiceAccount(keyPath, readFileSync);
+    if (!credentials) {
+      return {
+        ok: false,
+        reason: 'bad-credentials',
+        message: `La cle service account a ${keyPath} est introuvable ou invalide (client_email + private_key requis).`,
+      };
+    }
+
+    // 2. content shape (pure) -- import lazily to keep this module's top clean.
+    let content$;
+    let buildReplaceRequests;
+    let buildDocumentRequests;
+    try {
+      const gc = await import('./gdoc-content.js');
+      content$ = gc.normalizeContent(content);
+      buildReplaceRequests = gc.buildReplaceRequests;
+      buildDocumentRequests = gc.buildDocumentRequests;
+    } catch (err) {
+      return { ok: false, reason: 'invalid-content', message: oneLine(err) };
+    }
+
+    // 3. googleapis available ?
+    let google;
+    try {
+      ({ google } = await load());
+      if (!google) throw new Error('googleapis loaded but google export missing');
+    } catch {
+      return {
+        ok: false,
+        reason: 'dep-missing',
+        message:
+          'googleapis non installe. Lance : npm install googleapis google-auth-library (dans _byan/mcp/byan-mcp-server).',
+      };
+    }
+
+    // 4. auth + API + publish. Any API failure -> graceful api-error.
+    try {
+      const auth = new google.auth.GoogleAuth({ credentials, scopes: SCOPES });
+      const docs = google.docs({ version: 'v1', auth });
+      const drive = google.drive({ version: 'v3', auth });
+
+      const templateId = opts.templateId || cfg.GDOC_TEMPLATE_ID || '';
+      let documentId;
+      let mode;
+
+      if (templateId) {
+        const copy = await drive.files.copy({
+          fileId: templateId,
+          requestBody: { name: content$.title },
+          fields: 'id',
+        });
+        documentId = copy.data.id;
+        mode = 'template';
+        await docs.documents.batchUpdate({
+          documentId,
+          requestBody: { requests: buildReplaceRequests(content) },
+        });
+      } else {
+        const created = await docs.documents.create({
+          requestBody: { title: content$.title },
+        });
+        documentId = created.data.documentId;
+        mode = 'programmatic';
+        await docs.documents.batchUpdate({
+          documentId,
+          requestBody: {
+            requests: buildDocumentRequests(content, {
+              logoPngUrl: opts.logoPngUrl || cfg.GDOC_LOGO_PNG_URL || '',
+            }),
+          },
+        });
+      }
+
+      let shared = false;
+      if (opts.shareWith) {
+        await drive.permissions.create({
+          fileId: documentId,
+          requestBody: {
+            type: 'user',
+            role: opts.role === 'commenter' || opts.role === 'writer' ? opts.role : 'reader',
+            emailAddress: opts.shareWith,
+          },
+          sendNotificationEmail: false,
+        });
+        shared = true;
+      }
+
+      return {
+        ok: true,
+        documentId,
+        url: `https://docs.google.com/document/d/${documentId}/edit`,
+        mode,
+        shared,
+      };
+    } catch (err) {
+      return { ok: false, reason: 'api-error', message: oneLine(err) };
+    }
+  }
+
+  return { publish, status };
+}
+
+export { createPublisher, readServiceAccount, SCOPES };