@eventmodelers/cli 1.0.96 → 1.0.98

package/README.md

@@ -128,7 +128,9 @@ 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 --agent <name> --model <id>  # …on a given model: -m for opencode/codex/gemini, --model for Claude, LOCAL_AI_MODEL for --local-ai
+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 +193,43 @@ 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 --standalone --auto"
+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 --worker --agent opencode --model opencode/big-pickle  # pick the model (a free OpenCode Zen one here)
+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 OpenCode the loop adds `--standalone` if you
+leave it out — a plain `opencode run` goes to OpenCode's shared background service, which never
+sees `$EVENTMODELERS_TOKEN`, so every eventmodelers tool fails to authenticate. 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.
+
+**In a container.** `docker/<agent>/Dockerfile` runs the modeling agent for one coding agent
+(so far `docker/opencode`). Build from this directory and pass the board's credentials as env vars:
+
+```bash
+docker build -f docker/opencode/Dockerfile -t eventmodelers-agent-opencode .
+docker run --rm -e EVENTMODELERS_TOKEN=... -e EVENTMODELERS_ORGANIZATION_ID=... -e EVENTMODELERS_BOARD_ID=... \
+  -e OPENCODE_API_KEY=... eventmodelers-agent-opencode --model opencode/big-pickle
+```
+
+`--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
@@ -675,6 +712,36 @@ Once your `init --build-kit` scaffold (see above) works against a real backend,
 2. Add an entry for `<name>` to the `STACKS` object in `cli.js` (`label`, `kitSubdir: 'build-kit'`, `kitDirName: '.build-kit'`, `useShared: true`, `needsBoardId: true`).
 3. Add it to this README's stack list, the "What gets installed" section, and the `stacks` command's output (generated from `STACKS`, so nothing to add there beyond the entry itself).
 
+## Publishing a release
+
+Pushing a version tag publishes the npm package **and** the agent docker images from the same commit, via `.github/workflows/release.yml`.
+
+1. Write the release notes (`/release-notes` fills `RELEASE_NOTES.md` from the git history since the last release).
+2. Bump `version` in `package.json` (`npm version <patch|minor|major> --no-git-tag-version`), and commit it together with the notes.
+3. Tag that commit with the version, prefixed with `v`, and push the tag:
+
+   ```bash
+   git tag v1.0.98
+   git push origin main v1.0.98
+   ```
+
+The workflow then:
+
+| Job | What it does |
+|---|---|
+| `test` | Fails unless the tag equals `package.json`'s version (`v1.0.98` ↔ `1.0.98`), then runs `npm test` |
+| `npm` | `npm publish --access public --provenance` for `@eventmodelers/cli` |
+| `images` | Builds the six agent images for `linux/amd64` and `linux/arm64`, **scans each for credentials** (`.github/scripts/scan-image.sh`), and only then pushes it |
+| `merge` | Combines the two architectures into one multi-arch image per name, tagged `:<tag>` and `:latest` |
+
+Images land in `ghcr.io/nebulit-gmbh/`: `eventmodelers-agent-claude`, `eventmodelers-agent-opencode`, and `em-studio-buildkit-{claude,opencode}-{node,java}`. They run the CLI from the tagged checkout, not from npm, so they don't wait on the npm publish.
+
+**One-time setup:** an `NPM_TOKEN` repo secret (an npm automation token allowed to publish `@eventmodelers/cli`). The images push with the built-in `GITHUB_TOKEN`; new GHCR packages start private, so make them public in the org's package settings if they should be pullable without a login.
+
+A failed run can't be re-published under the same version — npm refuses to overwrite one. If `npm` succeeded but an image job failed, re-run just the failed jobs from the Actions tab. If the tag itself was wrong, delete it (`git push --delete origin v1.0.98`), fix, bump to a new version and tag again.
+
+To check an image locally before tagging: `docker build -f docker/<name>/Dockerfile -t scan/<name>:ci .` from this directory, then `../.github/scripts/scan-image.sh scan/<name>:ci`.
+
 ## Contributors
 
 | Contributor | Contribution |

package/cli.js

@@ -67,6 +67,58 @@ 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,
+  // --standalone: a plain `opencode run` hands the turn to opencode's shared background service,
+  // started with some other env — so the MCP header's {env:EVENTMODELERS_TOKEN} resolves to nothing
+  // there and every eventmodelers tool fails to authenticate. A private server inherits ours.
+  opencode: { modeling: 'opencode run --standalone --auto', build: 'opencode run --standalone --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',
@@ -1127,6 +1179,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
       // placeholder, never the literal secret (see connect/SKILL.md's Security notes).
       ensureMcpRegistered(targetDir, config.baseUrl || DEFAULT_BASE_URL);
       ensureEnvToken(targetDir, config.token);
+      ensureMcpEnabled(targetDir);
       // Only build stacks trace (slice build cost); they are the ones running the shared runtime.
       if (stackCfg.useShared) await configureAgentTracing(configPath, options.print);
     }
@@ -1317,6 +1370,7 @@ async function refreshSharedRuntime({ targetDir, kitDir, globalOpts, opts }) {
   });
   ensureMcpRegistered(targetDir, cfg.baseUrl || DEFAULT_BASE_URL);
   ensureEnvToken(targetDir, cfg.token);
+  ensureMcpEnabled(targetDir);
   await configureAgentTracing(configPath, globalOpts.print, true);
 }
 
@@ -1493,6 +1547,25 @@ function ensureMcpRegistered(projectDir, baseUrl) {
   writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
 }
 
+// `.mcp.json` alone does not make Claude Code use a server: a project server also has to be
+// approved, and declining that prompt (or dismissing `/mcp`) in an interactive session writes
+// `disabledMcpjsonServers` into `.claude/settings.local.json`, after which every later `claude` in
+// the project — the runner's included — silently runs without the eventmodelers tools and the
+// agent falls back to curl. Whoever starts the runner wants the server on, so this clears that
+// entry and approves it explicitly. Only this project-local file is touched.
+function ensureMcpEnabled(projectDir) {
+  const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+  const settings = readJsonSafe(settingsPath);
+  const disabled = settings.disabledMcpjsonServers ?? [];
+  const enabled = settings.enabledMcpjsonServers ?? [];
+  if (!disabled.includes('eventmodelers') && enabled.includes('eventmodelers')) return;
+  settings.disabledMcpjsonServers = disabled.filter((n) => n !== 'eventmodelers');
+  if (!settings.disabledMcpjsonServers.length) delete settings.disabledMcpjsonServers;
+  settings.enabledMcpjsonServers = [...enabled, 'eventmodelers'].filter((n, i, a) => a.indexOf(n) === i);
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+}
+
 // Companion to ensureMcpRegistered: that function deliberately never writes the
 // token itself, on the assumption the caller sets EVENTMODELERS_TOKEN in whatever
 // process spawns `claude` (true for `run --modeling`'s own spawn). It is NOT true
@@ -1867,7 +1940,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, exec = 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, model = 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');
@@ -1886,7 +1959,7 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // run (resolveModelingCredentials) and handed over whole. Walking the filesystem here
   // would also print loadLocalConfig's "no config found — platform sync disabled" note,
   // which is exactly backwards when a complete config was just passed in.
-  const local = overrides ? { ...overrides } : loadLocalConfig(kitDir);
+  const local = overrides ? { ...overrides } : applyEnvOverrides(loadLocalConfig(kitDir));
   // The global install's overrides carry their own agent id, kept per board in
   // ~/.eventmodelers/boards/<board>.json — one dir driving several boards must not have
   // them all upsert one shared alive row. A project install keeps its id in the project
@@ -1902,7 +1975,7 @@ async function runModeling(kitDir, projectDir, { verbose = false, standalone = f
   // The identity flags go on last: the global install's `overrides` carry the agent id
   // resolveModelingCredentials just minted for this run, which would otherwise win back over
   // an explicit --id.
-  const cfg = { ...(await fetchPlatformConfig(local)), ...(overrides ?? {}), ...(identity.agentId ? { agentId: identity.agentId } : {}), ...(identity.agentName ? { agentName: identity.agentName } : {}) }; // adds realtimeProvider + its provider-specific fields (supabaseUrl/supabaseAnonKey or pocketbaseUrl), + boardId if the config has a default one
+  const cfg = { ...applyEnvOverrides(await fetchPlatformConfig(local)), ...(overrides ?? {}), ...(identity.agentId ? { agentId: identity.agentId } : {}), ...(identity.agentName ? { agentName: identity.agentName } : {}), ...(model ? { model } : {}) }; // adds realtimeProvider + its provider-specific fields (supabaseUrl/supabaseAnonKey or pocketbaseUrl), + boardId if the config has a default one
   if (!cfg.boardId) {
     console.error('❌ --modeling needs a boardId — a modeling agent always runs for exactly one board. Run `/connect board=<uuid>` once, or add boardId to .eventmodelers/config.json.');
     process.exit(1);
@@ -3503,6 +3576,7 @@ credentialFlags(program
       // (see the beta-api protected-resource-metadata incident this fixed).
       ensureMcpRegistered(targetDir, cfg.baseUrl || DEFAULT_BASE_URL);
       ensureEnvToken(targetDir, cfg.token);
+      ensureMcpEnabled(targetDir);
       if (existsSync(join(targetDir, STACKS.node.kitDirName))) {
         await configureAgentTracing(configPath, globalOpts.print, !Object.values(overrides).some(Boolean));
       }
@@ -3513,9 +3587,11 @@ 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 — 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('--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('--model <id>', 'The model the agent runs on, for this run only: `-m <id>` on the --agent opencode/codex/gemini command (e.g. opencode/big-pickle, gpt-5-codex, gemini-2.5-pro), `--model <id>` for Claude (overriding `model` from config), LOCAL_AI_MODEL for --local-ai. Not with --exec — put the harness\'s own model flag in the command there.')
+  .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', '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; --local-ai or --exec pick 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('--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')
@@ -3534,6 +3610,25 @@ 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;
+    // --model: one flag, spelled the way each runner takes it. A hand-written --exec command is
+    // the one place it can't go — where the model flag goes in an unknown command is the author's.
+    const model = opts.model === undefined ? null : String(opts.model).trim();
+    if (model === '') {
+      console.error('❌ --model needs a non-empty value.');
+      process.exit(1);
+    }
+    if (model && opts.exec && !agentExec) {
+      console.error('❌ --model does not apply to --exec — put the harness\'s own model flag in the command (e.g. --exec "opencode run --standalone -m <id>"), or use --agent.');
+      process.exit(1);
+    }
+    if (model && agentExec) opts.exec = `${agentExec} -m '${model.replace(/'/g, `'\\''`)}'`;
+    else if (model && resolveLocalAiTarget(opts) !== null) process.env.LOCAL_AI_MODEL = model;
+    // The default Claude runner: the build kit's ralph-claude.js reads RALPH_MODEL from the env it
+    // inherits; the modeling loop takes it as runModeling's `model`.
+    else if (model) process.env.RALPH_MODEL = model;
     if (command.getOptionValueSource('maxAgents') === 'cli' && !opts.standalone) {
       console.log('ℹ️  --max-agents only applies to --standalone turns; ignoring it here.');
     }
@@ -3644,7 +3739,7 @@ credentialFlags(program
       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, exec: opts.exec ?? null });
+        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, model: !opts.exec && modelingLocalAi === null ? model : null });
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);
@@ -3683,6 +3778,18 @@ credentialFlags(program
       process.exit(1);
     }
 
+    // ralph-claude.js hands every turn to a `claude` that only discovers MCP servers from
+    // `.mcp.json` at its own startup, so it is rewritten on every run (see ensureMcpRegistered) —
+    // a file deleted, or written for another baseUrl, since `init` would otherwise leave the agent
+    // without its MCP tools. The token needs no file here: the runner puts it in claude's env.
+    if (runner === 'ralph-claude.js' && !opts.local) {
+      const runCfg = loadEffectiveConfig(cwd, kitDir, globalOpts.config).config;
+      if (runCfg.token) {
+        ensureMcpRegistered(dirname(kitDir), runCfg.baseUrl || DEFAULT_BASE_URL);
+        ensureMcpEnabled(dirname(kitDir));
+      }
+    }
+
     console.log(`▶ Starting ${relative(cwd, runnerPath)}...\n`);
     const cmd = runner.endsWith('.sh') ? `"${runnerPath}"` : `node "${runnerPath}"`;
     try {

package/lib/modeling-exec.js

@@ -18,95 +18,13 @@
 // 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 { mkdtempSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
-import { dirname, join } from 'path';
+import { join } from 'path';
 import { turnTimeoutMs, superviseTurn } from '../shared/build-kit/lib/turn.js';
+import { shellQuote, harnessOf, registerMcp } from '../shared/build-kit/lib/mcp-register.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 { harnessOf, registerMcp };
 
 export function createModelingExecRunner({ cfg, command: rawCommand, projectDir, log }) {
   if (!rawCommand) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.96",
+  "version": "1.0.98",
   "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": {
@@ -39,5 +39,10 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebulit-GmbH/Eventmodelers-Build-Kits.git",
+    "directory": "eventmodelers-cli"
   }
 }

package/shared/build-kit/README.md

@@ -94,7 +94,7 @@ rewriting a full coding agent inside the kit, so it is left out on purpose.
 
 ```bash
 npx @eventmodelers/cli run --exec "codex exec --oss --json --full-auto"   # Codex on local Ollama
-npx @eventmodelers/cli run --exec "opencode run --auto --format json"     # OpenCode, with an Ollama/vLLM/LM Studio provider in its config
+npx @eventmodelers/cli run --exec "opencode run --standalone --auto --format json"     # OpenCode, with an Ollama/vLLM/LM Studio provider in its config
 ```
 
 Or keep Claude Code as the builder and point `anthropicBaseUrl` at a local endpoint that
@@ -121,16 +121,34 @@ 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 --standalone --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"
+```
+
+Add `--model <id>` to pick the model — it becomes the harness's `-m <id>`
+(`run --agent opencode --model opencode/big-pickle`); on the default Claude runner it
+overrides `model` from config for that run.
+
+`--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"
-npx @eventmodelers/cli run --exec "opencode run"
+npx @eventmodelers/cli run --exec "opencode run --standalone --auto"   # --standalone: see below
 
 # …or persist it and use the bare flag
 RALPH_EXEC_CMD="codex exec --full-auto" node .build-kit/ralph-exec.js
 ```
 
+Run OpenCode with `--standalone`: a plain `opencode run` hands the turn to OpenCode's shared
+background service, which was started with another environment and never sees the variables
+this runner sets (`EVENTMODELERS_TOKEN`, `RALPH_PROMPT_FILE`, …).
+
 The prompt is appended to the command as one shell-quoted argument, and is also written
 to a temp file named by `RALPH_PROMPT_FILE` for commands that prefer to read it. The
 child runs with the project dir as its cwd and inherits stdio — a harness owns its own
@@ -144,7 +162,7 @@ so without the flag a turn is not traced (the runner logs a hint). Add the flag
 
 ```bash
 npx @eventmodelers/cli run --exec "codex exec --json --full-auto"
-npx @eventmodelers/cli run --exec "opencode run --auto --format json"
+npx @eventmodelers/cli run --exec "opencode run --standalone --auto --format json"
 npx @eventmodelers/cli run --exec "gemini --yolo --output-format stream-json -p"
 ```
 

package/shared/build-kit/lib/mcp-register.js

@@ -0,0 +1,96 @@
+// Registers the eventmodelers MCP server with an external agent harness (OpenCode, Gemini, Codex),
+// for both loops that hand turns to one: the modeling loop (lib/modeling-exec.js) and the build
+// loop (ralph-exec.js).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+// 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.
+export 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;
+    });
+    // A plain `opencode run` hands the turn to opencode's shared background service, which was
+    // started with some other env: {env:EVENTMODELERS_TOKEN} resolves to nothing there and the
+    // server refuses every call. --standalone runs a private server that inherits this one's env.
+    const standalone = /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
+    return { command: standalone, 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 };
+}
+