create-byan-agent 2.44.0 → 2.47.0

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

@@ -0,0 +1,116 @@
+// F4 — the ORCHESTRATOR core: the loop that makes an architect (Claude) and a
+// dev (Codex or Claude, per F1) exchange turn by turn through the shared board
+// (F3) until the exchange converges, then returns the result. This is the durable,
+// unit-testable heart of "launch a workflow and the agents talk to each other".
+//
+// It runs as full Node (main thread or an MCP worker), NOT inside a sandboxed
+// .claude/workflows script — that sandbox has no imports and no filesystem, so it
+// could never use F1/F2/F3. A native workflow script can only be a THIN launch
+// façade over this core (see docs). The core here owns the routing, the loop, and
+// the convergence rule.
+//
+// Executors are INJECTED so the loop is testable without real agents or Codex:
+//   executors.architect(ctx) -> { content, question? }   (always Claude)
+//   executors.claude(ctx)    -> { content, question? }   (dev work on Claude)
+//   executors.codex(ctx)     -> { content, question?, diff? }  (dev work on Codex)
+// The orchestrator picks executors[route.runtime] for the dev turn; the architect
+// is always Claude (judgment stays on Claude — the verification red line's sibling).
+//
+// Pure control flow: no direct I/O beyond the injected board writer/reader, which
+// default to F3's fs-backed pair but are overridable in tests.
+
+import { dispatch } from './dispatch-router.js';
+import {
+  KINDS,
+  makeEntry,
+  renderForAgent,
+  pendingQuestions,
+  appendEntry as fsAppend,
+  readEntries as fsRead,
+} from './dispatch-blackboard.js';
+
+export const ARCHITECT = 'claude-architect';
+export const DEV = 'dev';
+export const DEFAULT_MAX_ROUNDS = 4;
+
+// A board handle backed by F3's fs sidecar. Tests pass an in-memory one.
+export function fsBoard(projectDir, sessionId) {
+  return {
+    append: (entry) => fsAppend(projectDir, sessionId, entry),
+    read: () => fsRead(projectDir, sessionId),
+  };
+}
+
+// An in-memory board (no I/O) — the default when no projectDir is given, and what
+// tests use. Same shape as fsBoard.
+export function memoryBoard(seed = []) {
+  const entries = seed.map(makeEntry);
+  return {
+    append: (raw) => { const e = makeEntry(raw); entries.push(e); return e; },
+    read: () => entries.slice(),
+  };
+}
+
+// orchestrateTask — run ONE task to convergence. Returns
+//   { route, rounds, entries, status, diffs }
+// status: 'converged' (dev produced a result with no open question)
+//       | 'max-rounds' (hit the round cap still exchanging)
+//       | 'dev-failed' (the dev executor reported a failure -> caller may fall back)
+export function orchestrateTask({ task = {}, board, executors = {}, maxRounds = DEFAULT_MAX_ROUNDS } = {}) {
+  const route = dispatch({ nature: task.nature, complexity: task.complexity });
+  const devExec = executors[route.runtime];
+  const architectExec = executors.architect;
+  if (typeof devExec !== 'function' || typeof architectExec !== 'function') {
+    throw new Error(`orchestrateTask: missing executor for runtime "${route.runtime}" or architect`);
+  }
+
+  // Monotonic message counter (NOT per-round): each append gets the next turn, so
+  // an architect ANSWER always carries a turn strictly greater than the dev
+  // QUESTION it follows — which is what pendingQuestions needs to mark it resolved.
+  let turn = 0;
+  const post = (from, to, kind, content) => board.append({ turn: turn++, from, to, kind, content: content || '' });
+
+  // The architect opens with the design brief (addressed to dev).
+  const opening = architectExec({ task, route, round: 0, transcript: renderForAgent(board.read(), ARCHITECT) });
+  post(ARCHITECT, DEV, KINDS.DESIGN, (opening && opening.content) || task.brief || '');
+
+  const diffs = [];
+  let status = 'max-rounds';
+  for (let round = 1; round <= maxRounds; round++) {
+    // Dev turn: reads the board, does the work on its routed runtime.
+    const devOut = devExec({ task, route, round, transcript: renderForAgent(board.read(), DEV) }) || {};
+    if (devOut.ok === false || devOut.failed === true) {
+      post(DEV, ARCHITECT, KINDS.NOTE, `dev failed: ${devOut.detail || 'unknown'}`);
+      status = 'dev-failed';
+      break;
+    }
+    if (devOut.diff) diffs.push(devOut.diff);
+    post(DEV, ARCHITECT, devOut.question ? KINDS.WORK : KINDS.RESULT, devOut.content);
+    if (devOut.question) post(DEV, ARCHITECT, KINDS.QUESTION, devOut.question);
+
+    // Converged: dev delivered a result and left no open question.
+    if (!pendingQuestions(board.read()).length) { status = 'converged'; break; }
+
+    // Architect answers the open question(s); the higher turn resolves them.
+    const archOut = architectExec({ task, route, round, transcript: renderForAgent(board.read(), ARCHITECT) }) || {};
+    post(ARCHITECT, DEV, KINDS.ANSWER, archOut.content);
+  }
+
+  return { route, messages: board.read().filter((e) => e.turn > 0).length, entries: board.read(), status, diffs };
+}
+
+// orchestrate — run a whole task list. Each task gets its own board namespace when
+// an fs board factory is supplied; otherwise an in-memory board per task. Returns
+// one result per task, in order. Never routes verification to Codex (guaranteed by
+// F1's router, re-asserted here as defence in depth).
+export function orchestrate({ tasks = [], executors = {}, maxRounds = DEFAULT_MAX_ROUNDS, boardFor } = {}) {
+  return (Array.isArray(tasks) ? tasks : []).map((task, i) => {
+    const board = typeof boardFor === 'function' ? boardFor(task, i) : memoryBoard();
+    const result = orchestrateTask({ task, board, executors, maxRounds });
+    if (result.route.runtime === 'codex' && /verif|review|validate|audit/i.test(String(task.nature || ''))) {
+      // Should be impossible (router forces Claude), but fail loud if it ever regresses.
+      throw new Error(`orchestrate: verification task "${task.id || i}" routed to Codex — red line breached`);
+    }
+    return { taskId: task.id != null ? task.id : i, ...result };
+  });
+}

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

@@ -0,0 +1,149 @@
+// F1 — the dispatch BRAIN. Single source of truth for the intelligent dispatch:
+// given a task's NATURE and COMPLEXITY, decide which RUNTIME runs it (Codex or
+// Claude), which MODEL, and (Codex only) which reasoning EFFORT.
+//
+// It composes with, does not duplicate, native-tiers.js: the Claude-side model
+// tier is delegated to that module's TIER_MODEL vocabulary (which, by design,
+// only ever yields haiku / sonnet / null — so Fable can never leak in from the
+// Claude side either). This module adds the two NEW axes the intelligent dispatch
+// needs — runtime selection and Codex reasoning effort — on top of it.
+//
+// Routing table is the cross-checked result (5 independent sources, see
+// docs / CHANGELOG): Codex wins autonomous execution, shell/CI/DevOps, deploy,
+// browser/computer use ; Claude wins architecture, refactor-at-repo-scale,
+// quality, planning, and ALL verification. Two hard red lines are enforced here,
+// not left to the caller:
+//   1. Fable is NEVER emitted (long-term product decision).
+//   2. Verification is NEVER routed to Codex (a runtime must not grade its own
+//      work ; the reviewer stays on Claude).
+//
+// Pure: no I/O, no clock, deterministic. The Codex transport (F2) and the
+// orchestrating loop (F4) consume this; they never re-decide routing.
+
+import { TIER_MODEL } from './native-tiers.js';
+
+export const RUNTIMES = Object.freeze({ CODEX: 'codex', CLAUDE: 'claude' });
+
+// Codex runs on the ChatGPT-subscription entitled model. Kept as a named constant
+// so a plan change is a one-line edit, not a scatter of string literals.
+export const CODEX_MODEL = 'gpt-5.4';
+
+export const EFFORTS = Object.freeze({ LOW: 'low', MEDIUM: 'medium', HIGH: 'high' });
+
+// Models we refuse to emit, ever. Fable is excluded by explicit long-term
+// decision; the guard makes that refusal mechanical rather than a convention.
+export const FORBIDDEN_MODELS = Object.freeze(['fable', 'claude-fable-5']);
+
+// Task natures that route to Codex. Everything NOT here (and not a verification
+// nature) falls through to Claude — Claude is the safe default, so an unknown or
+// ambiguous nature keeps judgment on Claude rather than gambling it on Codex.
+const CODEX_NATURES = Object.freeze([
+  'execution', 'exec', 'shell', 'terminal', 'command',
+  'deploy', 'deployment', 'devops', 'ci', 'cd', 'pipeline',
+  'scripting', 'script', 'automation', 'browser', 'computer-use', 'e2e-run',
+]);
+
+// Natures that MUST stay on Claude even if a future edit mislabels them — the
+// verification red line. Checked before the Codex table so it can never be
+// overridden by a nature that also looks like execution (e.g. "run-and-verify").
+const VERIFICATION_NATURES = Object.freeze([
+  'verification', 'verify', 'validate', 'review', 'audit', 'check', 'qa',
+]);
+
+function normalize(value) {
+  return String(value == null ? '' : value).trim().toLowerCase();
+}
+
+function matchesAny(text, list) {
+  return list.some((kw) => text.includes(kw));
+}
+
+// assertNoFable(model) — mechanical enforcement of red line #1. Throws rather
+// than silently substituting, so a Fable request is a loud failure at the source.
+export function assertNoFable(model) {
+  const m = normalize(model);
+  if (FORBIDDEN_MODELS.some((f) => m.includes(f))) {
+    throw new Error(`dispatch-router: forbidden model "${model}" (Fable is excluded by long-term policy)`);
+  }
+  return model;
+}
+
+// isVerification(nature) — red line #2 helper. A verification nature never leaves
+// Claude.
+export function isVerification(nature) {
+  return matchesAny(normalize(nature), VERIFICATION_NATURES);
+}
+
+// routeRuntime(nature) -> 'codex' | 'claude'. Verification wins first (stays
+// Claude), then the Codex table, else Claude (safe default).
+export function routeRuntime(nature) {
+  const n = normalize(nature);
+  if (isVerification(n)) return RUNTIMES.CLAUDE;
+  if (matchesAny(n, CODEX_NATURES)) return RUNTIMES.CODEX;
+  return RUNTIMES.CLAUDE;
+}
+
+// Map a complexity input to a coarse bucket. Accepts a 0-100 number (the
+// complexity-scorer scale) OR a label (trivial/low/medium/high/hard). Anything
+// unrecognised is treated as medium — a safe middle that neither over-spends nor
+// under-powers.
+export function complexityBucket(complexity) {
+  if (typeof complexity === 'number' && Number.isFinite(complexity)) {
+    if (complexity < 34) return EFFORTS.LOW;
+    if (complexity < 67) return EFFORTS.MEDIUM;
+    return EFFORTS.HIGH;
+  }
+  const c = normalize(complexity);
+  if (['trivial', 'low', 'simple', 'easy'].includes(c)) return EFFORTS.LOW;
+  if (['high', 'hard', 'complex', 'frontier'].includes(c)) return EFFORTS.HIGH;
+  return EFFORTS.MEDIUM;
+}
+
+// effortForComplexity(complexity) -> a Codex reasoning-effort value. Codex is the
+// only side with a real effort knob (`codex exec -c model_reasoning_effort=...`);
+// this maps complexity onto it 1:1 with the bucket.
+export function effortForComplexity(complexity) {
+  return complexityBucket(complexity);
+}
+
+// claudeModelForComplexity(complexity) -> 'haiku' | 'sonnet' | null(omit=inherit).
+// Delegates to native-tiers' TIER_MODEL so the Claude vocabulary stays in one
+// place: low -> cheap(haiku), medium -> balanced(sonnet), high -> deep(null =
+// inherit the session model, i.e. Opus on an Opus session). Fable is structurally
+// impossible here (TIER_MODEL has no Fable entry), but we still assert to make the
+// guarantee explicit and catch a future TIER_MODEL drift.
+export function claudeModelForComplexity(complexity) {
+  const bucket = complexityBucket(complexity);
+  const model = bucket === EFFORTS.LOW
+    ? TIER_MODEL.cheap
+    : bucket === EFFORTS.MEDIUM
+      ? TIER_MODEL.balanced
+      : TIER_MODEL.deep; // null = inherit (never pinned to Fable)
+  return model == null ? null : assertNoFable(model);
+}
+
+// dispatch({ nature, complexity }) -> the full routing decision:
+//   { runtime, model, effort, reasoning }
+// - Codex: model = CODEX_MODEL, effort = complexity bucket (the real knob).
+// - Claude: model = haiku/sonnet/null(inherit), effort = null (Claude has no
+//   effort knob — its "effort" IS the model tier).
+// Both red lines are enforced here regardless of caller input.
+export function dispatch({ nature, complexity } = {}) {
+  const runtime = routeRuntime(nature);
+  if (runtime === RUNTIMES.CODEX) {
+    return {
+      runtime,
+      model: assertNoFable(CODEX_MODEL),
+      effort: effortForComplexity(complexity),
+      reasoning: `nature "${normalize(nature)}" routes to Codex ; effort scaled to complexity`,
+    };
+  }
+  return {
+    runtime,
+    model: claudeModelForComplexity(complexity), // null = inherit session model
+    effort: null, // Claude effort = model tier, no separate knob
+    reasoning: isVerification(nature)
+      ? 'verification stays on Claude (red line: a runtime never grades its own work)'
+      : `nature "${normalize(nature)}" stays on Claude (default-safe) ; model scaled to complexity`,
+  };
+}

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

@@ -1004,6 +1004,27 @@ const tools = [
       additionalProperties: false,
     },
   },
+  // Selective RAG retrieval — returns the top-k most relevant knowledge bodies
+  // VERBATIM (never truncated; negations/prohibitions are returned intact).
+  // GET /api/projects/:projectId/knowledge/retrieve?q=...&k=10&tokenBudget=0
+  // Backed by PG FTS (ts_rank) in prod, LIKE-degraded on SQLite (dev/tests).
+  // Use this instead of knowledge_list when you only need a focused subset.
+  {
+    name: 'byan_api_knowledge_retrieve',
+    description:
+      'Retrieve the top-k most relevant knowledge entries for a query using full-text search (PG) or LIKE fallback (SQLite). Returns bodies VERBATIM — negations and prohibitions are never truncated. GET /api/projects/:projectId/knowledge/retrieve?q=...&k=10&tokenBudget=0. RBAC viewer required. projectId and q are required. Requires BYAN_API_TOKEN.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Project id (required — RBAC guard).' },
+        q: { type: 'string', description: 'Search query (required).' },
+        k: { type: 'number', description: 'Max number of results (default 10).' },
+        tokenBudget: { type: 'number', description: 'Total token budget (0 = unlimited).' },
+      },
+      required: ['projectId', 'q'],
+      additionalProperties: false,
+    },
+  },
 
   // ─── Memory ───────────────────────────────────────────────────────────
   // Route: GET /api/projects/:projectId/memory (RBAC viewer)
@@ -1437,6 +1458,7 @@ const REMOTE_SAFE_TOOLS = new Set([
   'byan_api_workflow_runs_get',
   'byan_api_knowledge_list',
   'byan_api_knowledge_get',
+  'byan_api_knowledge_retrieve',
   'byan_api_memory_list',
   'byan_api_memory_search',
   'byan_api_custom_agents_list',
@@ -1982,6 +2004,21 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
+    if (name === 'byan_api_knowledge_retrieve') {
+      requireToken();
+      if (!args.projectId) throw new Error('projectId is required (RBAC: knowledge is project-scoped).');
+      if (!args.q || String(args.q).trim() === '') throw new Error('q (query) is required.');
+      const qs = buildQuery({
+        q: args.q,
+        k: args.k,
+        tokenBudget: args.tokenBudget,
+      });
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/knowledge/retrieve${qs}`
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+    }
+
     if (name === 'byan_api_memory_list') {
       requireToken();
       if (!args.projectId) throw new Error('projectId is required (RBAC: memory is project-scoped).');

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -94,7 +94,7 @@
       "name": "byan-byan",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "6798beb68df9831e0b9bf3ca17100174316c51b2671d96b2ef5bff6def4eabc7"
+      "sourceHash": "523ca56a08c8b85edba423e1bfdd0d9c777442bcb266b5a74e65c14814da128d"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",

package/install/templates/_byan/workflow/simple/byan/data/mantras.yaml

@@ -262,11 +262,22 @@ agents_ia:
         - "Contraintes légales/business"
         - "TODOs avec ticket"
 
+    - id: "IA-26"
+      name: "Parler Réel"
+      category: "code_quality"
+      description: "Parler en français réel et cohérent à l'utilisateur : pas d'anglais gratuit, pas de jargon interne brut, pas de métaphore collée de travers. Un terme technique sans équivalent est gardé mais expliqué une fois. Le test : le lecteur comprend sans dictionnaire."
+      priority: "critique"
+      forbidden:
+        - "Anglais quand le français existe (cutoff, fallback, housekeeping)"
+        - "Jargon interne balancé brut (leaf, tier, downgrade, gate, inline, advisory)"
+        - "Métaphore collée de travers (forger un token)"
+      rule_file: ".claude/rules/plain-language.md"
+
 metadata:
-  total_mantras: 64
+  total_mantras: 65
   conception_count: 39
-  agents_ia_count: 25
-  version: "1.0.0"
-  last_updated: "2026-02-02"
+  agents_ia_count: 26
+  version: "1.0.1"
+  last_updated: "2026-07-15"
   authors: ["Yan", "Carson"]
   methodology: "Merise Agile + TDD"

package/install/templates/docs/intelligent-dispatch.md

@@ -0,0 +1,84 @@
+# Intelligent dispatch — Codex/Claude routing + architect-dev loop
+
+Route each task to the runtime that is genuinely better for it (Codex or Claude),
+on the right model and effort for its complexity, and let an architect (Claude)
+and a dev (Codex or Claude) exchange turn by turn until the work converges.
+
+This is "option B": a deterministic orchestration loop (the durable, testable
+backbone), with the Codex transport behind a swappable adapter so the tighter
+`codex mcp-server` coupling can slot in later without touching the core.
+
+## The routing table (cross-checked, 5 independent sources)
+
+| Task nature | Runtime | Why |
+|-------------|---------|-----|
+| execution / shell / terminal / deploy / devops / CI / scripting / browser / automation | Codex | Codex leads autonomous execution, terminal-task benchmarks, browser/computer use |
+| architecture / design / planning / refactor / quality / analysis / exploration / anything unknown | Claude | Claude leads planning, repo-scale refactor, code quality ; unknown stays on Claude (safe default) |
+| verification / review / validate / audit / qa | Claude (hard rule) | A runtime must not grade its own work |
+
+The raw "who is better overall" score (SWE-bench Verified) is a near tie whose
+leader flips by leaderboard, so it is left out of the routing signal — only the
+task-type signal is used, which is stable across sources.
+
+## Model and effort by complexity
+
+- **Claude side**: complexity picks the model tier via `native-tiers` —
+  low -> haiku, medium -> sonnet, high -> inherit the session model (Opus). There
+  is no separate effort knob on Claude: the model tier IS the effort. Fable is
+  excluded (the router does not emit it).
+- **Codex side**: fixed model (`gpt-5.4`, the entitled subscription model) with a
+  real reasoning-effort knob — low / medium / high — scaled to complexity via
+  `codex exec -c model_reasoning_effort=...`.
+
+## The three red lines (enforced in code, not left to the caller)
+
+1. **No Fable.** `assertNoFable` throws rather than emit a Fable model.
+2. **Verification stays on Claude.** The router forces a verification nature to
+   Claude ; the orchestrator re-asserts it and throws if it ever regresses.
+3. **Codex does not write.** Codex runs read-only and returns a unified diff ;
+   Claude applies it with `git apply`. This works under a locked-down sandbox
+   (e.g. Landlock) and keeps the apply + later verification on Claude.
+
+## How the agents "talk" (the honest live-chat answer)
+
+There is no simultaneous free-form chat between two models — that does not exist
+natively. What delivers the same outcome is a turn-by-turn loop through a shared
+board, like a chat server holding a conversation:
+
+1. The architect (Claude) posts the design to the board.
+2. The dev (Codex or Claude) reads the board, does the work, posts a result — or
+   a question.
+3. If there is an open question, the architect answers ; the loop continues.
+4. Convergence when the dev delivers a result with no open question (or a round
+   cap is hit). If the dev runtime fails (Codex unavailable/errored), the loop
+   reports `dev-failed` so the caller falls back to Claude.
+
+## Files
+
+| File | Role |
+|------|------|
+| `lib/dispatch-router.js` | F1 — pure routing brain (nature+complexity -> runtime+model+effort) |
+| `lib/codex-bridge.js` | F2 — Codex transport: `codex exec` -> diff, `git apply`, adapter seam (exec shipped, mcp a V2 slot) |
+| `lib/dispatch-blackboard.js` | F3 — the turn-by-turn shared board (build/render pure, JSONL I/O isolated) |
+| `lib/dispatch-orchestrator.js` | F4 — the loop core (routes, runs architect<->dev, converges) ; executors injected |
+| `.claude/workflows/intelligent-dispatch.js` | Native launch facade for one routed task (design -> implement -> verify) |
+
+All four libs are pure/injectable and unit-tested under `test/dispatch-*.test.js`
+and `test/codex-bridge.test.js`.
+
+## Launching it
+
+The orchestrator runs as full Node on the main thread (or an MCP worker), because
+a native workflow script has no imports and no filesystem — it cannot use these
+libs directly. So the main-thread FD / hermes skill decides routing with F1,
+provides the executors (a Claude subagent for Claude turns, the Codex bridge for
+Codex turns), and drives `orchestrate({ tasks, executors })`. The native workflow
+script `intelligent-dispatch.js` is the thin facade for the single-task case: its
+dev leaf holds the Bash tool and is what actually invokes `codex exec`.
+
+## V2 slot — tighter coupling
+
+`getAdapter('codex-mcp')` is a declared but unavailable adapter. When
+`codex mcp-server` is wired, Codex becomes a tool Claude can call mid-reasoning
+(and Codex can call BYAN tools back) — the closest thing to live. It drops in as a
+new transport behind the same F2 seam, with no change to F1 or the loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.44.0",
+  "version": "2.47.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {