@eventmodelers/cli 1.0.95 → 1.0.97

package/README.md

@@ -128,7 +128,8 @@ npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made de
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
 npx @eventmodelers/cli run --local-ai [target]      # board work only via a local/self-hosted model (ralph-local-ai.js) — does NOT build slices; build locally with --exec
-npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
+npx @eventmodelers/cli run --agent <name>           # pick the agent: claude (default), opencode, codex, gemini — bare --agent lists them with their exact commands
+npx @eventmodelers/cli run --exec "<command>"        # manual fallback for any other harness (ralph-exec.js) — agent tracing needs its JSON flag, e.g. "codex exec --json --full-auto"
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue
@@ -191,8 +192,31 @@ npx @eventmodelers/cli run --modeling               # react to prompts sent to t
 npx @eventmodelers/cli run --standalone             # …and to board changes, on its own initiative
 ```
 
-`--standalone` implies `--modeling`, so you never need both. To drive either one with a local
-model instead of Claude, see [Running the modeling agent on a local model](#running-the-modeling-agent-on-a-local-model).
+`--standalone` implies `--modeling`, so you never need both.
+
+**Another coding agent.** `--agent` hands each prompt and chat message to another harness
+instead of the warm Claude process — one process per turn, with the eventmodelers MCP server
+registered for it (`opencode.json`, `.gemini/settings.json`, or `-c` flags for Codex):
+
+```bash
+npx @eventmodelers/cli run --standalone --agent opencode   # = --exec "opencode run"
+npx @eventmodelers/cli run --modeling --agent codex        # = --exec "codex exec --full-auto"
+npx @eventmodelers/cli run --modeling --agent gemini       # = --exec "gemini --yolo -p"
+npx @eventmodelers/cli run --modeling --agent claude       # the default, spelled out
+npx @eventmodelers/cli run --agent                         # list the agents and the command each runs
+```
+
+`--agent` is only a shortcut: to run a harness it does not know, or the same one with other
+flags, pass the command yourself with `--exec "<command>"`. Keep the harness in its plain-text
+output mode — its stdout is the turn's answer. For an unknown command the loop logs the MCP
+server to register by hand (`<baseUrl>/mcp`, header `x-token` from `$EVENTMODELERS_TOKEN`).
+Run `init-agents --hosts <harness>` to install the skills for a harness that does not read
+`.claude/skills`. There are no subagents: self-directed work is done inline.
+
+`--agent`, `--exec`, `--local-ai` and `--bash` each pick the runner, so pass at most one of them —
+any two together are rejected. For a local or self-hosted model use `--local-ai`, not `--agent`.
+
+To drive either one with a local model instead of Claude, see [Running the modeling agent on a local model](#running-the-modeling-agent-on-a-local-model).
 
 **No install required.** A modeling agent never touches the directory it was started from —
 it works against the board over MCP/REST — so it doesn't need a kit scaffolded there. When

package/cli.js

@@ -67,6 +67,55 @@ function resolveLocalAiTarget(opts) {
   return raw;
 }
 
+// --- --agent: named shortcuts for --exec ---------------------------------------
+// `run --agent opencode` is exactly `run --exec "<preset>"` — the harness command spelled out
+// once here, so nobody has to remember its headless flags. The two loops want different output
+// from the same harness: the modeling loop reads a turn's answer from plain-text stdout, while a
+// build kit wants the JSON mode, the only one that reports the usage agent tracing records.
+// claude has no command — it is the default runner, named so it can be picked explicitly.
+// --exec stays the fallback for any harness or flag set not listed here.
+const AGENT_PRESETS = {
+  claude: null,
+  opencode: { modeling: 'opencode run', build: 'opencode run --auto --format json' },
+  codex: { modeling: 'codex exec --full-auto', build: 'codex exec --json --full-auto' },
+  gemini: { modeling: 'gemini --yolo -p', build: 'gemini --yolo --output-format stream-json -p' },
+};
+
+function printAgentPresets() {
+  console.log('Supported agents for run --agent <name>:\n');
+  for (const [name, preset] of Object.entries(AGENT_PRESETS)) {
+    console.log(`  ${name.padEnd(9)}${preset ? `modeling: ${preset.modeling}\n  ${''.padEnd(9)}build:    ${preset.build}` : 'the default runner (warm Claude process / ralph-claude.js)'}`);
+  }
+  console.log('\nAny other harness: run --exec "<command>".');
+  console.log(`A local or self-hosted model: run --local-ai [${LOCAL_AI_TARGETS.join('|')}].`);
+}
+
+// Resolves --agent into the --exec command it stands for, or null for the default Claude runner.
+// Bare --agent lists the presets and stops.
+function resolveAgentPreset(opts, loop) {
+  if (opts.agent === undefined) return null;
+  if (opts.agent === true) {
+    printAgentPresets();
+    process.exit(0);
+  }
+  const name = String(opts.agent).toLowerCase();
+  if (!(name in AGENT_PRESETS)) {
+    console.error(`❌ Unknown --agent "${opts.agent}" — one of: ${Object.keys(AGENT_PRESETS).join(', ')}.`);
+    console.error('   Any other harness works via --exec "<command>".');
+    console.error(`   A local or self-hosted model works via --local-ai [${LOCAL_AI_TARGETS.join('|')}].`);
+    process.exit(1);
+  }
+  if (opts.exec) {
+    console.error('❌ --agent and --exec are mutually exclusive — --agent is a shortcut for --exec.');
+    process.exit(1);
+  }
+  if (resolveLocalAiTarget(opts) !== null || opts.bash) {
+    console.error('❌ --agent is mutually exclusive with --local-ai/--bash — pick one runner.');
+    process.exit(1);
+  }
+  return AGENT_PRESETS[name]?.[loop] ?? null;
+}
+
 const STACKS = {
   node: {
     label: 'Node.js / TypeScript',
@@ -1867,7 +1916,7 @@ async function ensureGlobalKit(baseUrl) {
 // untargeted is handed straight back to the queue for another agent to take. It says
 // nothing about the standalone lane — a self-directed turn is nobody's task, so an
 // exclusive standalone agent still works the board on its own initiative.
-async function runModeling(kitDir, projectDir, { verbose = false, standalone = false, exclusive = false, worker = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}, localAi = null } = {}) {
+async function runModeling(kitDir, projectDir, { verbose = false, standalone = false, exclusive = false, worker = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}, localAi = null, exec = null } = {}) {
   // --worker: only prompts — no chat, and no board-change turns (it has nowhere to propose).
   const chat = !worker;
   const configLibPath = join(kitDir, 'lib', 'config.js');
@@ -1934,6 +1983,24 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
       process.exit(1);
     }
   }
+  // --exec: any agent harness, one process per turn (lib/modeling-exec.js). Unlike a local model
+  // it brings its own tool loop and reads the kit — CLAUDE.md and whatever skills `init-agents`
+  // installed for it — so its turns keep the session header; what it lacks is the Agent tool, so
+  // they drop the fan-out like a local model's do. Imported only here: its turn supervisor
+  // installs signal handlers on import, which no other command should get.
+  let execRunner = null;
+  if (exec) {
+    const { createModelingExecRunner } = await import('./lib/modeling-exec.js');
+    try {
+      execRunner = createModelingExecRunner({ cfg, command: exec === true ? cfg.localAi?.exec : exec, projectDir, log });
+    } catch (err) {
+      console.error(`❌ --exec: ${err.message}`);
+      process.exit(1);
+    }
+  }
+  // The runner that is not the warm `claude` process, if any — for the few places that only care
+  // whether one is.
+  const otherRunner = localRunner ?? execRunner;
 
   const QUESTIONING_RULE =
     'IMPORTANT: You are running autonomously — no human is available to answer questions. ' +
@@ -1944,6 +2011,17 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     '(see "Chat turns" in .agent-modeling-kit/CLAUDE.md), and never by pausing the session. ' +
     'A chat message is at most 1000 characters.\n\n';
 
+  // An exec turn is a fresh process on every turn, so the kit's connect step would run — and
+  // re-verify the same credentials — once per message. It has nothing left to do: registerMcp
+  // (lib/modeling-exec.js) put the eventmodelers server into the harness's config before the
+  // first turn, authenticated from the env this process hands it. The credentials in the header
+  // stay, for the skills' REST fallback.
+  const EXEC_CONNECTED =
+    'The eventmodelers MCP server is already registered and authenticated for you, so you are connected: ' +
+    'do NOT run /connect and do not check any MCP config file — wherever the kit or a skill says to connect ' +
+    'first, that is already done. Use the eventmodelers tools directly, with the board_id of this turn. The ' +
+    'credentials above are only for a REST fallback, should a tool you need be missing.\n\n';
+
   // Sent once, on the first turn only — it's what tells the agent to follow
   // .agent-modeling-kit/CLAUDE.md's per-turn steps for this warm session (instead
   // of the root router's default of reading every installed kit's CLAUDE.md), and
@@ -1961,9 +2039,11 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
     // (its tools are already authenticated), and handing it the raw token would put credentials
     // in a context that has no way to use them.
     if (localRunner) return body;
-    if (!firstTurn) return body;
+    // Every exec turn is a fresh process — a new session that has read nothing, so each one gets
+    // the header its first turn would.
+    if (!firstTurn && !execRunner) return body;
     firstTurn = false;
-    return `MODE=modeling token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
+    return `MODE=modeling token=$EVENTMODELERS_TOKEN org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}${execRunner?.mcpRegistered ? EXEC_CONNECTED : ''}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
   }
 
   function buildTurn(p) {
@@ -2174,18 +2254,19 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // The one thing that knew a `claude` process was behind a turn. Both lanes — the prompt
   // queue (drain) and the self-directed one (dispatchStandaloneTurn) — go through here.
   async function runTurn(text) {
-    if (localRunner) return localRunner.runTurn(text);
+    if (otherRunner) return otherRunner.runTurn(text);
     if (!proc) spawnProcess();
     await warmUpSession();
     return sendTurn(text);
   }
 
-  if (!localRunner) spawnProcess();
+  if (!otherRunner) spawnProcess();
   log(`agent: ${cfg.agentName ? `${cfg.agentName} (${cfg.agentId})` : cfg.agentId}`);
   if (localRunner) log(`runner: local model — ${localRunner.describe()} (board tools over MCP; no skills, no subagents)`);
+  if (execRunner) log(`runner: ${execRunner.describe()} — one process per turn (skills from the kit; no subagents)`);
   log(
     standalone
-      ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (${localRunner ? 'work is done inline — a local model has no subagents' : `max ${maxAgents} subagent(s) per self-directed turn`})`
+      ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (${localRunner ? 'work is done inline — a local model has no subagents' : execRunner ? 'work is done inline — an exec agent has no subagents' : `max ${maxAgents} subagent(s) per self-directed turn`})`
       : worker
         ? 'worker: ON — working prompts only (no chat, board changes are dropped)'
         : 'standalone: off — board changes get a proposal in the chat, nothing is changed without a yes',
@@ -2201,8 +2282,10 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // Both warm-ups are the same bet — pay the session's fixed setup cost before a turn arrives
   // rather than making whoever sends the first prompt wait for it. For a local model that cost
   // is the MCP tool set; for Claude it is reading CLAUDE.md and running /connect.
+  // An exec runner has nothing to warm: every turn is its own process, so a warm-up would connect
+  // a session that exits right after.
   if (localRunner) localRunner.warmUp().catch((err) => log(`local-ai warm-up failed (the first turn will retry): ${err.message}`));
-  else warmUpSession();
+  else if (!execRunner) warmUpSession();
 
   async function getRealtimeToken() {
     const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/realtime-token`, {
@@ -2580,6 +2663,9 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   const AGENT_BUDGET = localRunner
     ? 'You have no subagents and no skills here — the board tools are all you have. Do the single most ' +
       'valuable piece of work yourself, inline, in this turn, and leave the rest for a later turn.'
+    : execRunner
+      ? 'You have no subagents here — wherever the kit says to dispatch an Agent, do that work yourself instead. ' +
+        'Do the single most valuable piece of work yourself, inline, in this turn, and leave the rest for a later turn.'
     : maxAgents > 1
       ? `Dispatch at most ${maxAgents} Agents in this turn (--max-agents=${maxAgents}). Merge pieces that share a slice or ` +
         'chain first — that is a correctness rule, not a way to fit the cap — and if more than that is still left, ' +
@@ -2595,6 +2681,9 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // from disk; a local model has neither, so it just works the board directly.
   const FAN_OUT = localRunner
     ? `get the most valuable piece of it done with the board tools in this turn. ${AGENT_BUDGET}`
+    : execRunner
+      ? `get the most valuable piece of it done in this turn. ${AGENT_BUDGET} Read ` +
+        '.agent-modeling-kit/CLAUDE-STANDALONE.md now and follow it: it holds the steps for this kind of turn, and only this kind.'
     : 'work in parallel rather than serially — dispatch one Agent per piece of ' +
       'work that needs doing, all in a single message, merging pieces that share a slice or chain so no two ' +
       `agents write to the same area. ${AGENT_BUDGET} Read .agent-modeling-kit/CLAUDE-STANDALONE.md now (once ` +
@@ -3473,9 +3562,10 @@ credentialFlags(program
   .command('run')
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
   .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Board work only: --local-ai never builds a Planned slice (no file, shell or git tools). To build code with a local model, use --exec with a coding harness pointed at it, e.g. "codex exec --oss --full-auto". Claude remains the default when this flag is absent.`)
-  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. With agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded.')
+  .option('--agent [name]', `Pick the agent that does the work by name: ${Object.keys(AGENT_PRESETS).join(', ')}. claude is the default runner; any other is a shortcut for --exec with that harness's headless command filled in — plain-text output for --modeling/--standalone/--worker, JSON output (for agent tracing) for a build kit. Bare --agent lists the agents and the exact command each runs, then stops. Mutually exclusive with --exec, --local-ai and --bash.`)
+  .option('--exec [command]', 'Fallback for any harness --agent does not cover, or other flags than its preset. Hand each prompt to an external agent command instead of the default Claude runner — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto", "gemini --yolo -p" or "opencode run". One process per prompt; the prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. A build kit runs it via ralph-exec.js; there, with agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded. With --modeling/--standalone/--worker it is how any agent takes board prompts and chats: the loop claims each prompt or chat message and runs the command once for it. Keep the harness in its plain-text output mode there — stdout is the turn\'s answer — the eventmodelers MCP server is registered for it on every run (opencode.json, .gemini/settings.json, or -c flags for codex; any other command logs what to register by hand), authenticating with $EVENTMODELERS_TOKEN from the env the command inherits, and `init-agents --hosts <harness>` installs the skills for a harness that does not read .claude/skills. No subagents: self-directed work is done inline.')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
-  .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
+  .option('--modeling', 'Connect a modeling agent to the board: it takes prompts and chat messages and hands each to an AI — by default one Claude process kept warm across prompts, for low-latency voice/live use; --agent (or --local-ai, or --exec as the manual fallback) picks another. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--non-interactive', 'Never ask anything: take the board and credentials that resolve from flags, EVENTMODELERS_* env vars and the config files, and fail with the reason if they are incomplete instead of interviewing for them. A TTY was previously the only signal — right for CI or a supervisor, wrong for a loop started from a terminal, where stdin is a TTY nobody is watching and the run stops on a question. Only affects the modeling loop (--modeling/--standalone/--worker/--global).')
   .option('--standalone', 'Let the modeling agent act on board changes on its own initiative, without asking: it subscribes to the board\'s change channel and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for, judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, specs for a new command or read model, a missing attribute along a chain, a screen, a question). Filling that detail in while the human keeps modeling is the point. A plain --modeling agent only proposes, and only to the people chatting with it: after their edits it says in the chat what it would do and waits for a yes; everyone else\'s edits are ignored. Implies --modeling.')
   .option('--max-agents <n>', 'Cap how many subagents a self-directed --standalone turn may dispatch at once, to bound what an unattended agent can spend per turn. The agent merges work that shares a slice or chain first, then takes the most valuable pieces up to this many and leaves the rest for a later turn. 1 makes it do the single most valuable piece itself, without spawning anything. Default 5. Ignored without --standalone — prompt turns are one piece of work by definition.', '5')
@@ -3494,6 +3584,9 @@ credentialFlags(program
     // should fail on the spot, not once the loop is already up — and a cap passed where
     // nothing will read it is worth saying out loud rather than ignoring silently.
     const maxAgents = parseMaxAgents(opts.maxAgents);
+    // --agent is --exec with the command filled in for the loop this run picks.
+    const agentExec = resolveAgentPreset(opts, (opts.modeling || opts.standalone || opts.worker || opts.global) ? 'modeling' : 'build');
+    if (agentExec) opts.exec = agentExec;
     if (command.getOptionValueSource('maxAgents') === 'cli' && !opts.standalone) {
       console.log('ℹ️  --max-agents only applies to --standalone turns; ignoring it here.');
     }
@@ -3550,14 +3643,19 @@ credentialFlags(program
     // no meaning for a build kit, which is scaffolded per project by definition.
     if (opts.modeling || opts.standalone || opts.worker || opts.global) {
       const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : opts.worker ? '--worker' : '--global';
-      // --bash/--exec stay build-kit only: they drive the cold-spawn tasks.json loop, which the
-      // modeling loop has no equivalent of. --local-ai is different — it names a *model*, not a
-      // queue, and the modeling loop has its own runner for one (lib/modeling-local-ai.js).
-      if (opts.bash || opts.exec) {
-        console.error(`❌ ${picked} is mutually exclusive with --bash/--exec — those select a build-kit runner, which the modeling loop has no use for.`);
+      // --bash stays build-kit only: it is the bash tasks.json loop, which the modeling loop has
+      // no equivalent of. --local-ai and --exec are different — they name what does a turn, not a
+      // queue, and the modeling loop has its own runner for each (lib/modeling-local-ai.js,
+      // lib/modeling-exec.js).
+      if (opts.bash) {
+        console.error(`❌ ${picked} is mutually exclusive with --bash — that selects a build-kit runner, which the modeling loop has no use for.`);
         process.exit(1);
       }
       const modelingLocalAi = resolveLocalAiTarget(opts);
+      if (modelingLocalAi !== null && opts.exec) {
+        console.error('❌ --local-ai and --exec are mutually exclusive — pick one runner.');
+        process.exit(1);
+      }
       if (opts.local) {
         console.error(`❌ ${picked} has no local-only mode — it is always driven by the org-wide realtime prompt queue, so --local has no use for it.`);
         process.exit(1);
@@ -3596,10 +3694,10 @@ credentialFlags(program
       // needed to drain, so a piped watcher sees the ping arrive after runModeling's own
       // [modeling] log lines instead of before them.
       const shown = relative(cwd, kitDir);
-      const runnerLabel = modelingLocalAi ? 'local model' : 'warm Claude process';
+      const runnerLabel = modelingLocalAi ? 'local model' : opts.exec ? 'one agent process per turn' : 'warm Claude process';
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (${runnerLabel}) for ${shown && !shown.startsWith('..') ? shown : kitDir}...\n\n`, res));
       try {
-        await runModeling(kitDir, projectDir, { verbose: !!opts.verbose, standalone: !!opts.standalone, exclusive: !!opts.exclusive, worker: !!opts.worker, overrides, maxAgents, identity, localAi: modelingLocalAi });
+        await runModeling(kitDir, projectDir, { verbose: !!opts.verbose, standalone: !!opts.standalone, exclusive: !!opts.exclusive, worker: !!opts.worker, overrides, maxAgents, identity, localAi: modelingLocalAi, exec: opts.exec ?? null });
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);

package/lib/modeling-exec.js

@@ -0,0 +1,164 @@
+// `run --modeling --exec "<command>"`: the modeling loop's baseline runner — any agent
+// harness with a headless mode, one process per turn.
+//
+// The warm Claude runner and --local-ai own the whole session; this one owns nothing. The loop
+// around it already does everything that needs no model — the heartbeat, the realtime channel,
+// claiming prompts and chat messages — so all a turn needs is an agent that takes one prompt,
+// does the board work over MCP and exits. The MCP registration is written for it (registerMcp).
+// That is what `codex exec`, `gemini -p`, `opencode run` and whatever comes next already are,
+// so one generic spawn covers them, the same bet shared/build-kit/ralph-exec.js makes for a
+// build kit. The price is a fresh process per turn: seconds of startup, and a session that
+// remembers nothing — which the chat can afford, since a chat turn reads its conversation from
+// the platform anyway rather than from the session's memory.
+//
+// The prompt is appended to the command as one quoted argument and also written to the file
+// named by RALPH_PROMPT_FILE, for a command that would rather read it — as ralph-exec.js does.
+// What the command prints on stdout is the turn's result: the standalone lane reads its
+// NOOP/DONE answer from it, and a chat turn that forgot post_chat_message has it posted as the
+// reply. So run the harness in its plain-text mode, not a JSON one.
+
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { turnTimeoutMs, superviseTurn } from '../shared/build-kit/lib/turn.js';
+
+// POSIX single-quote escaping: close, insert an escaped quote, reopen. A turn is multi-line
+// text with backticks and $ in it, so it cannot go in unquoted.
+function shellQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// Adds or refreshes one key in a project JSON config, leaving everything else in it alone. A file
+// that isn't plain JSON (a JSONC one with comments) is not rewritten — returns false instead, and
+// the caller says what to add by hand.
+function mergeJsonConfig(path, apply) {
+  let config = {};
+  if (existsSync(path)) {
+    try { config = JSON.parse(readFileSync(path, 'utf8')); } catch { return false; }
+  }
+  apply(config);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+  return true;
+}
+
+// How each known harness learns about the eventmodelers MCP server — the --exec counterpart of
+// ensureMcpRegistered's `.mcp.json` for Claude, and like it rewritten every run, always into the
+// harness's *project* config in the agent's working dir (never a user-wide one), and always with
+// the token as an env reference the harness resolves from the env this runner hands it, never its
+// value. Each entry returns the command to run, which is where a harness without a usable project
+// config (Codex only loads one for a trusted project) takes the server as flags instead. Adding a
+// harness is one entry here.
+const MCP_REGISTRATIONS = {
+  opencode: (command, projectDir, url) => {
+    const entry = {
+      type: 'remote',
+      url,
+      headers: { 'x-token': '{env:EVENTMODELERS_TOKEN}', 'x-agent-id': '{env:EVENTMODELERS_AGENT_ID}' },
+    };
+    const ok = mergeJsonConfig(join(projectDir, 'opencode.json'), (config) => {
+      // OpenCode 2 nests servers under mcp.servers and still reads the older flat mcp.<name>;
+      // follow whichever form the file already uses.
+      config.mcp = config.mcp || {};
+      if (config.mcp.servers) config.mcp.servers.eventmodelers = entry;
+      else config.mcp.eventmodelers = entry;
+    });
+    return { command, file: ok ? 'opencode.json' : null, manual: ok ? null : `add mcp.eventmodelers = ${JSON.stringify(entry)} to opencode.json` };
+  },
+  gemini: (command, projectDir, url) => {
+    const entry = { httpUrl: url, headers: { 'x-token': '$EVENTMODELERS_TOKEN', 'x-agent-id': '$EVENTMODELERS_AGENT_ID' } };
+    const ok = mergeJsonConfig(join(projectDir, '.gemini', 'settings.json'), (config) => {
+      config.mcpServers = config.mcpServers || {};
+      config.mcpServers.eventmodelers = entry;
+    });
+    return { command, file: ok ? '.gemini/settings.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .gemini/settings.json` };
+  },
+  codex: (command, _projectDir, url) => ({
+    // -c values are TOML; env_http_headers names the env var each header is read from.
+    command: `${command} -c ${shellQuote(`mcp_servers.eventmodelers.url="${url}"`)} -c ${shellQuote('mcp_servers.eventmodelers.env_http_headers={x-token="EVENTMODELERS_TOKEN",x-agent-id="EVENTMODELERS_AGENT_ID"}')}`,
+    file: null,
+    manual: null,
+  }),
+};
+
+// Which known harness a command runs — the first word naming one, so `npx @openai/codex exec`
+// and `/opt/bin/opencode run` are recognised as well as the bare names.
+export function harnessOf(command) {
+  for (const word of String(command).trim().split(/\s+/).slice(0, 3)) {
+    const name = word.split('/').pop().replace(/@.*$/, '');
+    if (MCP_REGISTRATIONS[name]) return name;
+  }
+  return null;
+}
+
+// Registers the MCP server for the command's harness. Returns the command to run with it, and
+// whether the server is now registered — false for an unknown command or a config it could not
+// update, where the turn still has to connect the way the kit says to.
+export function registerMcp(command, projectDir, baseUrl, log) {
+  const url = `${baseUrl}/mcp`;
+  const harness = harnessOf(command);
+  if (!harness) {
+    log(`MCP: unknown agent command — register the eventmodelers MCP server with it yourself: ${url}, header x-token from $EVENTMODELERS_TOKEN (and x-agent-id from $EVENTMODELERS_AGENT_ID)`);
+    return { command, registered: false };
+  }
+  const reg = MCP_REGISTRATIONS[harness](command, projectDir, url);
+  if (reg.manual) log(`MCP: could not update the ${harness} config (not plain JSON) — ${reg.manual}`);
+  else log(`MCP: eventmodelers registered for ${harness}${reg.file ? ` in ${reg.file}` : ' via -c flags'}`);
+  return { command: reg.command, registered: !reg.manual };
+}
+
+export function createModelingExecRunner({ cfg, command: rawCommand, projectDir, log }) {
+  if (!rawCommand) {
+    throw new Error('no agent command — pass one, e.g. --exec "codex exec --full-auto", or persist it as localAi.exec in .eventmodelers/config.json');
+  }
+  const { command, registered: mcpRegistered } = registerMcp(rawCommand, projectDir, cfg.baseUrl, log);
+  const timeoutMs = turnTimeoutMs(cfg);
+  const promptDir = mkdtempSync(join(tmpdir(), 'modeling-exec-'));
+  const env = {
+    ...process.env,
+    // What the skills' curl fallback and an MCP registration reading ${EVENTMODELERS_TOKEN}
+    // authenticate with, and what attributes the agent's board writes to this agent.
+    EVENTMODELERS_TOKEN: cfg.token,
+    ...(cfg.agentId ? { EVENTMODELERS_AGENT_ID: cfg.agentId } : {}),
+  };
+
+  function runTurn(text) {
+    return new Promise((resolveTurn, rejectTurn) => {
+      const promptFile = join(promptDir, 'prompt.md');
+      writeFileSync(promptFile, text);
+      const startedAt = Date.now();
+      // stdin ignored: some harnesses append a piped stdin to the prompt, and nobody is there to
+      // type into it. stdout is echoed as it comes — the harness owns its output format, there is
+      // no cross-harness stream to condense — and kept as the turn's result.
+      const proc = spawn(`${command} ${shellQuote(text)}`, {
+        cwd: projectDir,
+        stdio: ['ignore', 'pipe', 'inherit'],
+        shell: true,
+        env: { ...env, RALPH_PROMPT_FILE: promptFile },
+      });
+      const turn = superviseTurn(proc, { timeoutMs, label: 'exec turn', viaShell: true, log });
+      let out = '';
+      proc.stdout.on('data', (chunk) => {
+        process.stdout.write(chunk);
+        out += chunk.toString();
+      });
+      proc.on('close', (code) => {
+        const timeout = turn.timeoutError();
+        if (timeout) return rejectTurn(timeout);
+        if (code !== 0) return rejectTurn(new Error(`exec command exited ${code}`));
+        log(`done (${Date.now() - startedAt}ms)`);
+        resolveTurn(out.trim());
+      });
+      proc.on('error', rejectTurn);
+    });
+  }
+
+  return {
+    runTurn,
+    // Nothing to warm: every turn is its own process.
+    warmUp: async () => {},
+    describe: () => rawCommand,
+    mcpRegistered,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.95",
+  "version": "1.0.97",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/README.md

@@ -121,7 +121,17 @@ llama.cpp `-c 32768`); an overflow there surfaces as an HTTP 400.
 
 Agentic harnesses that bring their own tool loop — Codex CLI, OpenCode, Gemini CLI —
 are not `--local-ai` targets: `--local-ai` *supplies* the agent loop, while a harness
-already is one and only wants a prompt. They go through `ralph-exec.js` instead:
+already is one and only wants a prompt. They go through `ralph-exec.js` instead. The
+known ones have a shortcut that fills in the command, JSON flag for agent tracing included
+(bare `--agent` lists them):
+
+```bash
+npx @eventmodelers/cli run --agent opencode   # = --exec "opencode run --auto --format json"
+npx @eventmodelers/cli run --agent codex      # = --exec "codex exec --json --full-auto"
+npx @eventmodelers/cli run --agent gemini     # = --exec "gemini --yolo --output-format stream-json -p"
+```
+
+`--exec` is the manual fallback: any other harness, or one of these with other flags:
 
 ```bash
 npx @eventmodelers/cli run --exec "codex exec --full-auto"