create-byan-agent 2.11.3 → 2.12.1

package/_byan/mcp/byan-mcp-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/_byan/mcp/byan-mcp-server/README.md

@@ -0,0 +1,56 @@
+# byan-mcp-server
+
+MCP (Model Context Protocol) server that exposes the [byan_web](https://github.com/Les-fous-du-bus/byan_web) REST API as tools usable from Claude Code, Codex, or any MCP-aware client.
+
+## What it exposes
+
+- `byan_ping`, `byan_list_projects`, `byan_import_project` — project inventory
+- `byan_dispatch` — task routing heuristic
+- `byan_soul_read`, `byan_soul_memory_append` — BYAN soul system
+- `byan_elo_summary` / `byan_elo_context` / `byan_elo_record` — ELO trust calibration
+- `byan_fc_check` / `byan_fc_parse` — fact-check engine
+- `byan_fd_start` / `byan_fd_status` / `byan_fd_advance` / `byan_fd_update` / `byan_fd_abort` — Feature Development (FD) lifecycle
+- `byan_review_request` / `byan_review_verdict` / `byan_review_get` / `byan_review_pending` / `byan_review_pick_reviewer` — peer review
+- `byan_kanban_create` / `byan_kanban_add` / `byan_kanban_move` / `byan_kanban_assign` / `byan_kanban_get` — party-mode kanban
+- `byan_standup_post` / `byan_standup_read` / `byan_standup_blocked` — stand-up feed
+- `byan_copilot_sessions` / `byan_copilot_session_events` / `byan_copilot_search` — Copilot CLI session inspector
+- `byan_workflow_script_list` / `_get` / `_create` / `_update` / `_delete` / `_history` / `_rollback` / `_import` / `_validate` — workflow-node scripts CRUD
+
+## Install
+
+```bash
+npm install -g byan-mcp-server
+```
+
+## Configure
+
+Register the server in your MCP client config. Example for Claude Code (`~/.config/claude/mcp.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "byan": {
+      "command": "byan-mcp",
+      "env": {
+        "BYAN_API_URL": "https://byan-api.example.com",
+        "BYAN_API_TOKEN": "byan_xxx_or_jwt"
+      }
+    }
+  }
+}
+```
+
+## Env vars
+
+- `BYAN_API_URL` — byan_web API base URL (default `http://localhost:3737`)
+- `BYAN_API_TOKEN` — API key (prefix `byan_` uses `ApiKey` scheme) or JWT (uses `Bearer`)
+- `CLAUDE_PROJECT_DIR` — project root for filesystem-backed tools (soul, FD state, kanban)
+
+## Requirements
+
+- Node.js >= 18
+- A running byan_web API (for auth-gated tools)
+
+## License
+
+MIT

package/_byan/mcp/byan-mcp-server/lib/cli.js

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+const CLI_REL_PATH = 'bin/byan-v2-cli.js';
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export function parseCliOutput(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return { raw: '' };
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // fall through
+  }
+
+  const firstBracket = trimmed.search(/[\[{]/);
+  if (firstBracket >= 0) {
+    const candidate = trimmed.slice(firstBracket);
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      // still not valid JSON
+    }
+  }
+
+  return { raw: trimmed };
+}
+
+function resolveProjectRoot(envRoot) {
+  return envRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+export function runByanCli(args, options = {}) {
+  const root = resolveProjectRoot(options.projectRoot);
+  const script = path.join(root, CLI_REL_PATH);
+  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [script, ...args], {
+      cwd: root,
+      env: { ...process.env },
+    });
+
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`byan-v2-cli timed out after ${timeoutMs}ms: ${args.join(' ')}`));
+    }, timeoutMs);
+
+    child.stdout.on('data', (d) => (stdout += d.toString()));
+    child.stderr.on('data', (d) => (stderr += d.toString()));
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        const err = new Error(
+          `byan-v2-cli exited ${code}: ${stderr.trim() || stdout.trim()}`
+        );
+        err.code = code;
+        err.stderr = stderr;
+        err.stdout = stdout;
+        reject(err);
+        return;
+      }
+      resolve(parseCliOutput(stdout));
+    });
+  });
+}
+
+export async function eloSummary(opts) {
+  return runByanCli(['elo', 'summary'], opts);
+}
+
+export async function eloContext({ domain, ...opts }) {
+  if (!domain) throw new Error('domain is required');
+  return runByanCli(['elo', 'context', domain], opts);
+}
+
+export async function eloDashboard({ domain, ...opts }) {
+  return runByanCli(domain ? ['elo', 'dashboard', domain] : ['elo', 'dashboard'], opts);
+}
+
+export async function eloRecord({ domain, result, reason, ...opts }) {
+  if (!domain) throw new Error('domain is required');
+  if (!['VALIDATED', 'BLOCKED', 'PARTIAL'].includes(result)) {
+    throw new Error(`result must be VALIDATED|BLOCKED|PARTIAL, got: ${result}`);
+  }
+  const args = ['elo', 'record', domain, result];
+  if (reason) args.push(reason);
+  return runByanCli(args, opts);
+}
+
+export async function fcCheck({ text, ...opts }) {
+  if (!text || typeof text !== 'string') throw new Error('text is required');
+  return runByanCli(['fc', 'check', text], opts);
+}
+
+export async function fcParse({ text, ...opts }) {
+  if (!text || typeof text !== 'string') throw new Error('text is required');
+  return runByanCli(['fc', 'parse', text], opts);
+}

package/_byan/mcp/byan-mcp-server/lib/copilot.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const COPILOT_ROOT = process.env.BYAN_COPILOT_ROOT || path.join(os.homedir(), '.copilot', 'session-state');
+
+function readJsonl(filePath, limit) {
+  if (!fs.existsSync(filePath)) return [];
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+    if (typeof limit === 'number' && out.length >= limit) break;
+  }
+  return out;
+}
+
+function summarizeSession(sessionId) {
+  const eventsPath = path.join(COPILOT_ROOT, sessionId, 'events.jsonl');
+  if (!fs.existsSync(eventsPath)) return null;
+
+  const events = readJsonl(eventsPath);
+  if (events.length === 0) return null;
+
+  const start = events.find((e) => e.type === 'session.start');
+  const shutdown = events.find((e) => e.type === 'session.shutdown');
+  const agent = events.find((e) => e.type === 'subagent.selected');
+
+  const counts = {};
+  for (const e of events) {
+    counts[e.type] = (counts[e.type] || 0) + 1;
+  }
+
+  const userMessages = events.filter((e) => e.type === 'user.message');
+  const assistantMessages = events.filter((e) => e.type === 'assistant.message');
+
+  return {
+    sessionId,
+    startTime: start?.data?.startTime || null,
+    endTime: shutdown?.timestamp || null,
+    cwd: start?.data?.context?.cwd || null,
+    branch: start?.data?.context?.branch || null,
+    agent: agent?.data?.agentName || null,
+    event_count: events.length,
+    user_messages: userMessages.length,
+    assistant_messages: assistantMessages.length,
+    tool_calls: counts['tool.execution_start'] || 0,
+    event_type_counts: counts,
+  };
+}
+
+export function listSessions({ limit = 20, sinceIso = null, cwdFilter = null } = {}) {
+  if (!fs.existsSync(COPILOT_ROOT)) return { root: COPILOT_ROOT, sessions: [], total: 0, exists: false };
+
+  const dirs = fs
+    .readdirSync(COPILOT_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  const summaries = [];
+  for (const id of dirs) {
+    const s = summarizeSession(id);
+    if (!s) continue;
+    if (sinceIso && s.startTime && Date.parse(s.startTime) < Date.parse(sinceIso)) continue;
+    if (cwdFilter && s.cwd && !s.cwd.includes(cwdFilter)) continue;
+    summaries.push(s);
+  }
+
+  summaries.sort((a, b) => {
+    const at = Date.parse(a.startTime || 0);
+    const bt = Date.parse(b.startTime || 0);
+    return bt - at;
+  });
+
+  return {
+    root: COPILOT_ROOT,
+    total: summaries.length,
+    exists: true,
+    sessions: summaries.slice(0, limit),
+  };
+}
+
+export function readSessionEvents({ sessionId, types = null, limit = 200 } = {}) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new Error('sessionId is required');
+  }
+  const eventsPath = path.join(COPILOT_ROOT, sessionId, 'events.jsonl');
+  if (!fs.existsSync(eventsPath)) {
+    throw new Error(`events.jsonl not found for session ${sessionId}`);
+  }
+
+  const allEvents = readJsonl(eventsPath);
+  const filtered = Array.isArray(types) && types.length > 0
+    ? allEvents.filter((e) => types.includes(e.type))
+    : allEvents;
+
+  return {
+    sessionId,
+    total: allEvents.length,
+    returned: Math.min(filtered.length, limit),
+    filtered_by_type: Array.isArray(types) ? types : null,
+    events: filtered.slice(0, limit),
+  };
+}
+
+export function searchSessions({ query, types = ['user.message', 'assistant.message'], limit = 50 } = {}) {
+  if (!query || typeof query !== 'string') {
+    throw new Error('query is required');
+  }
+  if (!fs.existsSync(COPILOT_ROOT)) return { matches: [], total: 0 };
+
+  const q = query.toLowerCase();
+  const dirs = fs
+    .readdirSync(COPILOT_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  const matches = [];
+  for (const sessionId of dirs) {
+    const eventsPath = path.join(COPILOT_ROOT, sessionId, 'events.jsonl');
+    if (!fs.existsSync(eventsPath)) continue;
+    const events = readJsonl(eventsPath);
+    for (const e of events) {
+      if (!types.includes(e.type)) continue;
+      const text = typeof e.data?.content === 'string'
+        ? e.data.content
+        : typeof e.data?.text === 'string'
+          ? e.data.text
+          : JSON.stringify(e.data || {});
+      if (text.toLowerCase().includes(q)) {
+        matches.push({
+          sessionId,
+          timestamp: e.timestamp,
+          type: e.type,
+          excerpt: text.slice(0, 300),
+        });
+        if (matches.length >= limit) break;
+      }
+    }
+    if (matches.length >= limit) break;
+  }
+
+  return { query, total: matches.length, matches };
+}

package/_byan/mcp/byan-mcp-server/lib/dispatch.js

@@ -0,0 +1,23 @@
+export function dispatch({ task, complexity, parallelizable }) {
+  const score =
+    typeof complexity === 'number'
+      ? complexity
+      : Math.min(100, Math.floor((task?.length || 0) / 10));
+  const isPar = parallelizable === true;
+
+  let route, reasoning;
+  if (score < 15) {
+    route = 'main-thread';
+    reasoning = `Score ${score} < 15. Inline in current context, no delegation overhead.`;
+  } else if (score < 40 && isPar) {
+    route = 'agent-subagent-worktree';
+    reasoning = `Score ${score} + parallelizable. Spawn Claude Code Agent tool with worktree isolation.`;
+  } else if (score < 40) {
+    route = 'mcp-worker-haiku';
+    reasoning = `Score ${score}, sequential. Delegate to lightweight Haiku worker via MCP.`;
+  } else {
+    route = 'main-thread-opus';
+    reasoning = `Score ${score} >= 40. Complex task, keep in main thread with Opus reasoning.`;
+  }
+  return { score, route, reasoning, parallelizable: isPar };
+}

package/_byan/mcp/byan-mcp-server/lib/fd-state.js

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PHASES = ['BRAINSTORM', 'PRUNE', 'DISPATCH', 'BUILD', 'VALIDATE', 'COMPLETED', 'ABORTED'];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function statePath(projectRoot) {
+  return path.join(resolveRoot(projectRoot), '_byan-output', 'fd-state.json');
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state, projectRoot) {
+  const p = statePath(projectRoot);
+  ensureDir(p);
+  fs.writeFileSync(p, JSON.stringify(state, null, 2));
+  return p;
+}
+
+function slugify(s) {
+  return String(s || 'feature')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .slice(0, 40);
+}
+
+function stampId(now = new Date(), slug) {
+  const pad = (n) => String(n).padStart(2, '0');
+  const s =
+    now.getFullYear().toString() +
+    pad(now.getMonth() + 1) +
+    pad(now.getDate()) +
+    '-' +
+    pad(now.getHours()) +
+    pad(now.getMinutes()) +
+    pad(now.getSeconds());
+  return `${s}-${slugify(slug)}`;
+}
+
+export function start({ featureName, projectRoot, now = new Date(), force = false } = {}) {
+  const existing = readState(projectRoot);
+  if (existing && !['COMPLETED', 'ABORTED'].includes(existing.phase) && !force) {
+    throw new Error(
+      `FD already in progress (phase ${existing.phase}, fd_id ${existing.fd_id}). Abort or complete it first, or pass force=true.`
+    );
+  }
+
+  const state = {
+    fd_id: stampId(now, featureName),
+    feature_name: featureName || 'unnamed',
+    phase: 'BRAINSTORM',
+    started_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    phase_history: [{ phase: 'BRAINSTORM', entered_at: now.toISOString() }],
+    raw_ideas: [],
+    backlog: [],
+    dispatch_table: [],
+    commits: [],
+    notes: [],
+  };
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function status({ projectRoot } = {}) {
+  const state = readState(projectRoot);
+  if (!state) {
+    return { active: false, phase: null, fd_id: null };
+  }
+  return {
+    active: !['COMPLETED', 'ABORTED'].includes(state.phase),
+    ...state,
+  };
+}
+
+const BRAINSTORM_MIN_IDEAS = 10;
+
+export function advance({ to, note, projectRoot, now = new Date(), force = false } = {}) {
+  if (!PHASES.includes(to)) {
+    throw new Error(`Invalid target phase ${to}. Must be one of ${PHASES.join(', ')}`);
+  }
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No active FD session. Call start() first.');
+  if (['COMPLETED', 'ABORTED'].includes(state.phase)) {
+    throw new Error(`Current FD session is ${state.phase} and cannot advance.`);
+  }
+
+  const order = PHASES.indexOf(state.phase);
+  const target = PHASES.indexOf(to);
+  if (target < order && !['ABORTED', 'COMPLETED'].includes(to)) {
+    throw new Error(
+      `Cannot move backwards from ${state.phase} to ${to}. Use abort() or fix the workflow.`
+    );
+  }
+
+  // BRAINSTORM exit gate : need >= BRAINSTORM_MIN_IDEAS raw ideas
+  if (
+    state.phase === 'BRAINSTORM' &&
+    to !== 'BRAINSTORM' &&
+    !['ABORTED'].includes(to) &&
+    !force
+  ) {
+    const n = Array.isArray(state.raw_ideas) ? state.raw_ideas.length : 0;
+    if (n < BRAINSTORM_MIN_IDEAS) {
+      throw new Error(
+        `BRAINSTORM requires at least ${BRAINSTORM_MIN_IDEAS} raw ideas before advancing (currently ${n}). Add more via update({ patch: { raw_ideas: [...] } }), or pass force=true to skip.`
+      );
+    }
+  }
+
+  state.phase = to;
+  state.updated_at = now.toISOString();
+  state.phase_history.push({ phase: to, entered_at: now.toISOString(), note: note || null });
+
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function update({ patch = {}, projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No active FD session.');
+
+  const allowed = ['raw_ideas', 'backlog', 'dispatch_table', 'commits', 'notes', 'feature_name'];
+  for (const key of Object.keys(patch)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`Field "${key}" is not patchable. Allowed: ${allowed.join(', ')}`);
+    }
+    state[key] = patch[key];
+  }
+  state.updated_at = now.toISOString();
+
+  writeState(state, projectRoot);
+  return state;
+}
+
+export function abort({ reason, projectRoot, now = new Date() } = {}) {
+  const state = readState(projectRoot);
+  if (!state) throw new Error('No FD session to abort.');
+  state.phase = 'ABORTED';
+  state.updated_at = now.toISOString();
+  state.phase_history.push({ phase: 'ABORTED', entered_at: now.toISOString(), note: reason || null });
+  writeState(state, projectRoot);
+  return state;
+}
+
+export const ALL_PHASES = PHASES;
+export const BRAINSTORM_MIN = BRAINSTORM_MIN_IDEAS;