@eventmodelers/cli 1.0.97 → 1.0.99

package/README.md

@@ -129,6 +129,7 @@ npx @eventmodelers/cli re-init                      # refresh an already-install
 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 --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
@@ -199,20 +200,32 @@ instead of the warm Claude process — one process per turn, with the eventmodel
 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 --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 an unknown command the loop logs the MCP
+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`.
 
@@ -699,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 `docker.io/nebulit/`: `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

@@ -76,7 +76,10 @@ function resolveLocalAiTarget(opts) {
 // --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' },
+  // --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' },
 };
@@ -1176,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);
     }
@@ -1366,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);
 }
 
@@ -1542,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
@@ -1916,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');
@@ -1935,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
@@ -1951,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);
@@ -3552,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));
       }
@@ -3563,6 +3588,7 @@ credentialFlags(program
   .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('--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; --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.')
@@ -3587,6 +3613,22 @@ credentialFlags(program
     // --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.');
     }
@@ -3697,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);
@@ -3736,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.97",
+  "version": "1.0.99",
   "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
@@ -126,21 +126,29 @@ known ones have a shortcut that fills in the command, JSON flag for agent tracin
 (bare `--agent` lists them):
 
 ```bash
-npx @eventmodelers/cli run --agent opencode   # = --exec "opencode run --auto --format json"
+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
@@ -154,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 };
+}
+

package/shared/build-kit/lib/ralph.js

@@ -89,6 +89,17 @@ function* configCandidates(kitDir) {
   yield join(homedir(), '.eventmodelers', 'config.json');
 }
 
+const ENV_CONFIG_MAP = {
+  EVENTMODELERS_ORGANIZATION_ID: 'organizationId',
+  EVENTMODELERS_BOARD_ID: 'boardId',
+  EVENTMODELERS_TOKEN: 'token',
+  EVENTMODELERS_BASE_URL: 'baseUrl',
+  EVENTMODELERS_ANTHROPIC_BASE_URL: 'anthropicBaseUrl',
+  EVENTMODELERS_MODEL: 'model',
+  EVENTMODELERS_SUBAGENT_MODEL: 'subagentModel',
+  EVENTMODELERS_AGENT_NAME: 'agentName',
+};
+
 function loadLocalConfig(kitDir) {
   const merged = {};
   const sources = [];
@@ -109,6 +120,11 @@ function loadLocalConfig(kitDir) {
     if (hasCredentials(merged)) break;
   }
 
+  // EVENTMODELERS_* env vars win over any config.json, as they do for the CLI's own commands —
+  // a container gets its credentials this way, and a stale file in a mounted project must not beat them.
+  for (const [envVar, field] of Object.entries(ENV_CONFIG_MAP)) {
+    if (process.env[envVar]) merged[field] = process.env[envVar];
+  }
   if (process.env.BASE_URL) merged.baseUrl = process.env.BASE_URL;
   else if (!merged.baseUrl) merged.baseUrl = 'https://api.eventmodelers.ai';
 
@@ -280,6 +296,37 @@ async function fetchAndPersistSlices(cfg, kitDir) {
   console.log(`[agent] Persisted ${slices.length} slice(s)`);
 }
 
+// The summary refresh above leaves slice.json as an id/title/status stub, and a build agent that
+// reads a stub reports the slice as empty. So before a slice is handed to an agent — a Planned
+// build or a queued task — its full definition (elements, fields, specifications) is fetched
+// here and merged in. Best effort: on failure the agent still has /load-slice to fall back on.
+async function fetchFullSlice(cfg, kitDir, sliceId) {
+  if (!sliceId) return;
+  const slicesDir = join(kitDir, '.slices');
+  try {
+    let entry = null;
+    for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+      if (!ctx.isDirectory()) continue;
+      const indexPath = join(slicesDir, ctx.name, 'index.json');
+      if (!existsSync(indexPath)) continue;
+      const found = (JSON.parse(readFileSync(indexPath, 'utf-8')).slices ?? []).find((e) => e.id === sliceId);
+      if (found) { entry = { ...found, contextSlug: found.contextSlug ?? ctx.name }; break; }
+    }
+    if (!entry) return;
+    const query = new URLSearchParams({ contextName: entry.contextName, sliceId });
+    const url = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?${query}`;
+    const { slices } = await fetchJSON(url, { headers: { 'x-token': cfg.token, ...agentHeaders(cfg) } });
+    const full = slices?.find((sl) => sl.id === sliceId);
+    if (!full) return;
+    const sliceJsonPath = join(slicesDir, entry.contextSlug, entry.folder, 'slice.json');
+    const existing = existsSync(sliceJsonPath) ? JSON.parse(readFileSync(sliceJsonPath, 'utf-8')) : {};
+    mkdirSync(dirname(sliceJsonPath), { recursive: true });
+    writeFileSync(sliceJsonPath, JSON.stringify({ ...existing, ...full }, null, 2), 'utf-8');
+  } catch (err) {
+    console.log(`[ralph] full slice fetch failed for ${sliceId} (${err.message}) — the agent will have to /load-slice it`);
+  }
+}
+
 // tasks.json has two writers: this process, queueing slice changes, and the agent, removing
 // the task it just handled (as each stack's prompt.md tells it to). An unlocked read-modify-
 // write from both sides at once lost whichever update landed first. So the two never overlap:
@@ -655,6 +702,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
 
     if (credentialed && hasPendingTasks(kitDir)) {
       const prompt = readFileSync(promptFile, 'utf-8');
+      for (const t of readTasks(join(kitDir, 'tasks.json'))) await fetchFullSlice(cfg, kitDir, t.payload?.sliceId);
       await runWithRetry('onTask: loading slice from board...', () => inTurn(kitDir, () => onTask(prompt)));
       await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;
@@ -674,6 +722,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
       }
 
       const prompt = readFileSync(backendPromptFile, 'utf-8');
+      if (credentialed) await fetchFullSlice(cfg, kitDir, planned.id);
       const built = await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt, {
         sliceId: planned.id,
         sliceTitle: planned.title,

package/shared/build-kit/lib/tracing.js

@@ -1,5 +1,5 @@
 // What a slice costs: one trace per build turn against one slice, posted to the platform's
-// /api/org/:orgId/agent-traces. Only the runner can see what a turn cost, so it reports it.
+// /api/org/:orgId/boards/:boardId/agent-traces. Only the runner can see what a turn cost, so it reports it.
 //
 // Best effort: each trace is appended to a local JSONL file, then POSTed once. No retries, no
 // buffering. A failed upload is logged and forgotten; the file is the record.
@@ -110,13 +110,14 @@ export function sumUsage(parts) {
 
 /** Records slice build turns. The agent id is the session: the platform requires one, and a
  *  restart of the same build agent is still the same agent building the same slices. */
-export function createSliceTracer({ baseUrl, token, organizationId, agentId, traceFile, log = () => {}, enabled = true } = {}) {
+export function createSliceTracer({ baseUrl, token, organizationId, boardId: defaultBoardId, agentId, traceFile, log = () => {}, enabled = true } = {}) {
   const canUpload = !!(enabled && baseUrl && token && organizationId && agentId);
 
   async function post(trace) {
-    if (!canUpload) return;
+    // The route is per board — a trace without a board has nowhere to go, so it stays local.
+    if (!canUpload || !trace.boardId) return;
     try {
-      const res = await fetch(`${baseUrl}/api/org/${organizationId}/agent-traces`, {
+      const res = await fetch(`${baseUrl}/api/org/${organizationId}/boards/${trace.boardId}/agent-traces`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'x-token': token, 'x-agent-id': agentId },
         body: JSON.stringify({ traces: [trace] }),
@@ -141,7 +142,7 @@ export function createSliceTracer({ baseUrl, token, organizationId, agentId, tra
   return {
     /** One build turn: `{sliceId, sliceTitle, context, ticketNumber, boardId, attempt, status}` plus its usage.
      *  ticketNumber is the slice's ticket at build time — it can change, so it travels with each turn. */
-    record({ sliceId, sliceTitle = null, context = null, ticketNumber = null, boardId = null, attempt = null, status = 'ok' }, usage) {
+    record({ sliceId, sliceTitle = null, context = null, ticketNumber = null, boardId = defaultBoardId ?? null, attempt = null, status = 'ok' }, usage) {
       if (!sliceId || !usage) return;
       const trace = {
         id: newId(), occurredAt: new Date().toISOString(),

package/shared/build-kit/ralph-claude.js

@@ -26,6 +26,7 @@ const tracer = createSliceTracer({
   baseUrl: cfg.baseUrl,
   token: cfg.token,
   organizationId: cfg.organizationId,
+  boardId: cfg.boardId,
   agentId: cfg.agentId,
   traceFile: join(projectDir, '.eventmodelers', 'trace', 'slices.jsonl'),
   log: (line) => console.log(`[ralph] ${line}`),
@@ -40,7 +41,9 @@ const timeoutMs = turnTimeoutMs(cfg);
 const verbose = process.env.RALPH_VERBOSE === '1';
 
 const claudeArgs = ['--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose'];
-if (cfg.model) claudeArgs.push('--model', cfg.model);
+// RALPH_MODEL is `eventmodelers run --model` — one run's choice, over the configured `model`.
+const model = process.env.RALPH_MODEL || cfg.model;
+if (model) claudeArgs.push('--model', model);
 const claudeEnv = {
   ...process.env,
   ...(cfg.anthropicBaseUrl ? { ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl } : {}),