create-byan-agent 2.45.0 → 2.47.0

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/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/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.45.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": {