@eventmodelers/cli 2.0.9 → 2.0.11

package/extensions/eventcatalog/model.js

@@ -0,0 +1,111 @@
+// Slices → a neutral EventCatalog model: one domain, one flow per chapter, and the events, commands and queries
+// (read models) of the event model. Processors, screens and services are not part of it — the model has no
+// such thing as a service, so none is imported or invented. Pure — no I/O — so it is testable without a catalog.
+
+const ELEMENT_KINDS = [
+  ['commands', 'command'],
+  ['events', 'event'],
+  ['readmodels', 'query'],
+];
+const DEP_KINDS = { COMMAND: 'command', EVENT: 'event', READMODEL: 'query' };
+
+// "Payment confirmed" / "Payment Confirmed" / "payment_confirmed" are one element.
+const normalize = (title) => String(title ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+export function pascal(title) {
+  return String(title ?? '')
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join('');
+}
+
+const clean = (title) => String(title ?? '').trim().replace(/\s+/g, ' ');
+
+export function buildModel(slices, { context } = {}) {
+  const ordered = [...slices].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+  const contextName = clean(context || ordered[0]?.context || 'Default');
+  const nodes = new Map(); // `${kind}:${normalized}` → node
+  const byElementId = new Map(); // board element id (and linkedId) → node
+  const edges = new Map(); // `${from}>${to}` → { from, to }
+
+  function node(kind, title, slice) {
+    const key = `${kind}:${normalize(title)}`;
+    let n = nodes.get(key);
+    if (!n) {
+      n = { key, kind, id: pascal(title), name: clean(title), description: '', fields: [], slices: [], elementIds: [] };
+      nodes.set(key, n);
+    }
+    if (slice && !n.slices.includes(slice)) n.slices.push(slice);
+    return n;
+  }
+
+  function mergeFields(n, fields = []) {
+    for (const f of fields) if (!n.fields.some((x) => x.name === f.name)) n.fields.push(f);
+  }
+
+  const link = (from, to) => edges.set(`${from.key}>${to.key}`, { from, to });
+
+  const pending = [];
+  for (const slice of ordered) {
+    for (const [prop, kind] of ELEMENT_KINDS) {
+      for (const el of slice[prop] ?? []) {
+        const n = node(kind, el.title, slice.title);
+        if (!n.description && el.description) n.description = el.description;
+        mergeFields(n, el.fields);
+        byElementId.set(el.id, n);
+        if (el.linkedId) byElementId.set(el.linkedId, n);
+        // The board's ids survive a rename of the title, so a later export can tell a rename from a new element.
+        for (const id of [el.id, el.linkedId]) if (id && !n.elementIds.includes(id)) n.elementIds.push(id);
+        pending.push([n, el]);
+      }
+    }
+  }
+
+  // Dependencies are resolved after every element is known, by id first and by title second.
+  // A target nothing in the slices defines (e.g. a read model from another context) becomes a stub.
+  for (const [n, el] of pending) {
+    for (const dep of el.dependencies ?? []) {
+      const kind = DEP_KINDS[dep.elementType];
+      if (!kind) continue;
+      // A message nothing defines (e.g. from another context) becomes a stub. Dependencies on processors
+      // and screens never get here: DEP_KINDS doesn't know them, so they are dropped above.
+      const target = byElementId.get(dep.id) ?? nodes.get(`${kind}:${normalize(dep.title)}`) ?? node(kind, dep.title);
+      if (dep.type === 'INBOUND') link(target, n);
+      else link(n, target);
+    }
+  }
+
+  const real = [...nodes.values()];
+
+  const ctxId = pascal(contextName);
+  const find = (kind) => real.filter((n) => n.kind === kind);
+
+  // The flow: one step per element in order of first appearance, edges from the dependencies.
+  const inFlow = real;
+  const stepId = (n) => `${n.kind}-${n.id}`;
+  const steps = inFlow.map((n) => {
+    const next = [...edges.values()].filter((e) => e.from === n && inFlow.includes(e.to)).map((e) => stepId(e.to));
+    return { id: stepId(n), node: n, next };
+  });
+
+  const chapters = new Set(ordered.map((s) => clean(s.chapter || contextName)));
+  const flows = [...chapters].map((chapter) => {
+    const inChapter = new Set(ordered.filter((s) => clean(s.chapter || contextName) === chapter).map((s) => s.title));
+    const chapterSteps = steps.filter((s) => s.node.slices.some((t) => inChapter.has(t)));
+    const ids = new Set(chapterSteps.map((s) => s.id));
+    return {
+      id: `${pascal(chapter)}Flow`,
+      name: chapter,
+      steps: chapterSteps.map((s) => ({ ...s, next: s.next.filter((x) => ids.has(x)) })),
+    };
+  });
+
+  return {
+    domain: { id: ctxId, name: contextName },
+    events: find('event'),
+    commands: find('command'),
+    queries: find('query'),
+    flows,
+  };
+}

package/extensions/eventcatalog/render.js

@@ -0,0 +1,82 @@
+// Model → file contents. Everything returned is `{ path, content }`, relative to the catalog root.
+
+const JSON_TYPES = {
+  string: { type: 'string' },
+  text: { type: 'string' },
+  uuid: { type: 'string', format: 'uuid' },
+  date: { type: 'string', format: 'date' },
+  datetime: { type: 'string', format: 'date-time' },
+  time: { type: 'string', format: 'time' },
+  boolean: { type: 'boolean' },
+  int: { type: 'integer' },
+  integer: { type: 'integer' },
+  long: { type: 'integer' },
+  double: { type: 'number' },
+  float: { type: 'number' },
+  decimal: { type: 'number' },
+  number: { type: 'number' },
+};
+
+function fieldSchema(f) {
+  const base = f.subfields?.length ? objectSchema(f.subfields) : { ...(JSON_TYPES[String(f.type ?? '').toLowerCase()] ?? { type: 'string' }) };
+  if (f.example !== undefined && f.example !== '') base.examples = [f.example];
+  if (f.description) base.description = f.description;
+  return /^(list|multiple|array)$/i.test(f.cardinality ?? '') ? { type: 'array', items: base } : base;
+}
+
+function objectSchema(fields) {
+  const properties = {};
+  for (const f of fields) properties[f.name] = fieldSchema(f);
+  const required = fields.filter((f) => !f.optional).map((f) => f.name);
+  return { type: 'object', properties, ...(required.length ? { required } : {}) };
+}
+
+export function toJsonSchema(fields) {
+  return { $schema: 'http://json-schema.org/draft-07/schema#', ...objectSchema(fields) };
+}
+
+const KIND_LABEL = { event: 'Event', command: 'Command', query: 'Query' };
+const VERSION = '1.0.0';
+
+// EventCatalog's linter requires a summary; fall back to a plain statement when the model has no description.
+const summary = (n, context) => n.description || `${KIND_LABEL[n.kind]} ${n.name} of ${context}.`;
+const usedIn = (n) => (n.slices.length ? `\nUsed in: ${n.slices.join(', ')}.\n` : '\n');
+
+// Model → resources in the shape the EventCatalog SDK writes (`writeEvent`, `writeQuery`, …), plus the
+// schema files to attach afterwards. Nothing is written here.
+export function toResources(model, { owners = [] } = {}) {
+  const ctx = model.domain.name;
+  const owned = owners.length ? { owners } : {};
+  const message = (n) => ({
+    resource: {
+      id: n.id, name: n.name, version: VERSION, summary: summary(n, ctx), ...owned,
+      ...(n.fields.length ? { schemaPath: 'schema.json' } : {}),
+      markdown: `## Overview\n\n${n.name}.${usedIn(n)}`,
+    },
+    schema: n.fields.length ? JSON.stringify(toJsonSchema(n.fields), null, 2) + '\n' : null,
+  });
+  return {
+    events: model.events.map(message),
+    commands: model.commands.map(message),
+    queries: model.queries.map(message),
+    flows: model.flows.map((flow) => ({
+      resource: {
+        id: flow.id, name: flow.name, version: VERSION, summary: `Event model of ${flow.name}.`, ...owned,
+        steps: flow.steps.map((s) => ({
+          id: s.id,
+          title: s.node.name,
+          message: { id: s.node.id },
+          ...(s.next.length > 1 ? { next_steps: s.next } : s.next.length ? { next_step: s.next[0] } : {}),
+        })),
+        markdown: `## Overview\n\nGenerated from the event model chapter "${flow.name}".\n`,
+      },
+    })),
+    domain: {
+      resource: {
+        id: model.domain.id, name: ctx, version: VERSION, summary: `Event model context ${ctx}.`, ...owned,
+        ...(model.flows.length ? { flows: model.flows.map((f) => ({ id: f.id })) } : {}),
+        markdown: `## Overview\n\nExported from the Eventmodelers context "${ctx}".\n`,
+      },
+    },
+  };
+}

package/extensions/eventcatalog/write.js

@@ -0,0 +1,63 @@
+// Writes the resources through the EventCatalog SDK, which the *catalog* provides: it is resolved from the
+// target directory's node_modules, never bundled with this CLI, so it always matches the catalog's version.
+
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { join } from 'path';
+
+const PACKAGE = '@eventcatalog/sdk';
+
+// An EventCatalog project has an eventcatalog.config.* file and/or depends on @eventcatalog/core.
+export function isCatalog(dir) {
+  if (['js', 'mjs', 'cjs', 'ts'].some((ext) => existsSync(join(dir, `eventcatalog.config.${ext}`)))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }['@eventcatalog/core']);
+  } catch {
+    return false;
+  }
+}
+
+// The SDK's `utils` factory, or null when the catalog doesn't have the package.
+export async function loadSdk(catalogDir) {
+  let file;
+  try {
+    file = createRequire(join(catalogDir, 'package.json')).resolve(PACKAGE);
+  } catch {
+    return null;
+  }
+  const mod = await import(file);
+  return typeof mod.default === 'function' ? mod.default : mod.default.default; // CJS entry nests the factory
+}
+
+// `npm install` into the catalog — adds the SDK to the *catalog's* package.json, not this CLI's.
+export function installSdk(catalogDir) {
+  execFileSync('npm', ['install', PACKAGE], { cwd: catalogDir, stdio: 'inherit' });
+}
+
+// [resources key, SDK name part, singular for `<x>HasVersion`, label folder]
+const KINDS = [
+  ['events', 'Event', 'event', 'events'], ['commands', 'Command', 'command', 'commands'], ['queries', 'Query', 'query', 'queries'],
+  ['flows', 'Flow', 'flow', 'flows'], ['domain', 'Domain', 'domain', 'domains'],
+];
+
+// Existing resources (same id and version) are left alone — they may have been edited. `force` overwrites them.
+// The schema file is attached after the resource (its `schemaPath` is already in the frontmatter).
+export async function writeResources(utils, resources, { force = false } = {}) {
+  const written = [];
+  const skipped = [];
+  for (const [key, Name, singular, folder] of KINDS) {
+    const items = key === 'domain' ? [resources.domain] : resources[key];
+    for (const { resource, schema } of items) {
+      const label = `${folder}/${resource.id}`;
+      if (await utils[`${singular}HasVersion`](resource.id, resource.version)) {
+        if (!force) { skipped.push(label); continue; }
+      }
+      await utils[`write${Name}`](resource, { override: force });
+      if (schema) await utils[`addSchemaTo${Name}`](resource.id, { schema, fileName: 'schema.json' }, resource.version);
+      written.push(label);
+    }
+  }
+  return { written, skipped };
+}

package/lib/modeling-exec.js

@@ -22,7 +22,7 @@ import { mkdtempSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 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';
+import { shellQuote, harnessOf, harnessFor, registerMcp } from '../shared/build-kit/lib/harnesses/index.js';
 
 export { harnessOf, registerMcp };
 
@@ -31,6 +31,19 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
     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);
+  // A harness with a session of its own (Cursor's chat) keeps what it read across turns: the process
+  // is still one per turn, but its turns share that session — see harnesses/cursor.js. Such a
+  // harness takes its turns one at a time (two turns resuming one session would race on it) and
+  // the kit preamble is only skipped once a turn has completed in it.
+  const session = harnessFor(rawCommand)?.session ?? null;
+  let sessionId = null;
+  let primed = false;
+  let queue = Promise.resolve();
+  function withSession(cmd) {
+    if (!session) return cmd;
+    if (sessionId === null) sessionId = session.start(cmd, { cwd: projectDir, env, log });
+    return sessionId ? session.resume(cmd, sessionId) : cmd;
+  }
   const timeoutMs = turnTimeoutMs(cfg);
   const promptDir = mkdtempSync(join(tmpdir(), 'modeling-exec-'));
   const env = {
@@ -42,6 +55,13 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
   };
 
   function runTurn(text) {
+    if (!session) return runTurnNow(text);
+    const result = queue.then(() => runTurnNow(text));
+    queue = result.catch(() => {});
+    return result;
+  }
+
+  function runTurnNow(text) {
     return new Promise((resolveTurn, rejectTurn) => {
       const promptFile = join(promptDir, 'prompt.md');
       writeFileSync(promptFile, text);
@@ -49,7 +69,7 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
       // 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)}`, {
+      const proc = spawn(`${withSession(command)} ${shellQuote(text)}`, {
         cwd: projectDir,
         stdio: ['ignore', 'pipe', 'inherit'],
         shell: true,
@@ -65,6 +85,7 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
         const timeout = turn.timeoutError();
         if (timeout) return rejectTurn(timeout);
         if (code !== 0) return rejectTurn(new Error(`exec command exited ${code}`));
+        if (sessionId) primed = true;
         log(`done (${Date.now() - startedAt}ms)`);
         resolveTurn(out.trim());
       });
@@ -74,9 +95,11 @@ export function createModelingExecRunner({ cfg, command: rawCommand, projectDir,
 
   return {
     runTurn,
-    // Nothing to warm: every turn is its own process.
-    warmUp: async () => {},
+    // Only a harness with a session has anything to warm (the loop sends its warm-up turn through runTurn).
+    hasSession: Boolean(session),
     describe: () => rawCommand,
     mcpRegistered,
+    // True once a turn has succeeded in the shared session — until then every turn still carries the preamble.
+    get keepsSession() { return primed; },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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": {
@@ -12,6 +12,7 @@
   "files": [
     "cli.js",
     "lib",
+    "extensions",
     "shared",
     "stacks",
     "README.md",

package/shared/build-kit/lib/harnesses/codex.js

@@ -0,0 +1,25 @@
+// OpenAI Codex CLI (`codex exec`).
+
+import { shellQuote } from './util.js';
+
+export default {
+  name: 'codex',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'codex'),
+  preset(loop, env = process.env) {
+    const p = { modeling: 'codex exec --full-auto', build: 'codex exec --json --full-auto' };
+    // The docker images set this: Codex's own sandbox (landlock) can't start inside a container, and the
+    // container already is the sandbox — the flag Codex documents for externally sandboxed environments.
+    if (env.EVENTMODELERS_CODEX_NO_SANDBOX === '1') {
+      return { modeling: p.modeling.replace('--full-auto', '--dangerously-bypass-approvals-and-sandbox'), build: p.build.replace('--full-auto', '--dangerously-bypass-approvals-and-sandbox') };
+    }
+    return p;
+  },
+
+  // Codex only loads a project config for a trusted project, so the server rides on the command as flags.
+  registerMcp: (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,
+  }),
+};

package/shared/build-kit/lib/harnesses/cursor.js

@@ -0,0 +1,62 @@
+// Cursor's CLI (`cursor-agent`, or plain `agent` on current installs).
+//
+// The one harness with a session of its own. The CLI takes one prompt per process, but it can keep
+// a chat across runs: `create-chat` once, `--resume <id>` on every turn. The process is still new
+// each turn; what carries over is the conversation — the kit's CLAUDE.md and the MCP tool set it
+// has already read — so only the first turn pays for them.
+
+import { execFileSync, spawnSync } from 'child_process';
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+const binName = (word) => word.split('/').pop().replace(/@.*$/, '');
+
+// Whichever Cursor binary is on PATH; with neither, `cursor-agent` so the failure names a real binary.
+export function cursorBinary() {
+  for (const bin of ['cursor-agent', 'agent']) {
+    try { execFileSync('which', [bin], { stdio: 'ignore' }); return bin; } catch {}
+  }
+  return 'cursor-agent';
+}
+
+export default {
+  name: 'cursor',
+  // `agent` is far too generic a word to match anywhere but first.
+  matches: (words) => binName(words[0]) === 'agent' || words.slice(0, 3).some((w) => ['cursor-agent', 'cursor'].includes(binName(w))),
+  preset() {
+    const bin = cursorBinary();
+    return {
+      modeling: `${bin} -p --output-format text --approve-mcps --force --trust`,
+      build: `${bin} -p --output-format stream-json --approve-mcps --force --trust`,
+    };
+  },
+  modelFlag: '--model', // `-m` is an unknown option to this CLI
+
+  // The same project .cursor/mcp.json the editor reads; ${env:NAME} is resolved from the env the
+  // runner hands it. --approve-mcps in the command is what lets a headless run load it unprompted.
+  registerMcp(command, projectDir, url) {
+    const entry = { url, headers: { 'x-token': '${env:EVENTMODELERS_TOKEN}', 'x-agent-id': '${env:EVENTMODELERS_AGENT_ID}' } };
+    const ok = mergeJsonConfig(join(projectDir, '.cursor', 'mcp.json'), (config) => {
+      config.mcpServers = config.mcpServers || {};
+      config.mcpServers.eventmodelers = entry;
+    });
+    return { command, file: ok ? '.cursor/mcp.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .cursor/mcp.json` };
+  },
+
+  // Turns share one chat. start() makes it (returns its id, or '' when it could not); resume() puts
+  // it on a command — right after the binary, ahead of the flags and the prompt.
+  session: {
+    start(command, { cwd, env, log }) {
+      const bin = command.trim().split(/\s+/)[0];
+      const r = spawnSync(bin, ['create-chat'], { cwd, encoding: 'utf8', env });
+      const id = String(r.stdout || '').trim().split(/\s+/).pop();
+      if (r.status !== 0 || !id) {
+        log(`cursor: could not create a chat (${String(r.stderr || '').trim() || `exit ${r.status}`}) — running without resume, every turn starts cold`);
+        return '';
+      }
+      log(`cursor: resuming chat ${id} on every turn`);
+      return id;
+    },
+    resume: (command, id) => command.replace(/^(\s*\S+)/, `$1 --resume ${id}`),
+  },
+};

package/shared/build-kit/lib/harnesses/gemini.js

@@ -0,0 +1,19 @@
+// Gemini CLI (`gemini -p`).
+
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+export default {
+  name: 'gemini',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'gemini'),
+  preset: () => ({ modeling: 'gemini --yolo -p', build: 'gemini --yolo --output-format stream-json -p' }),
+
+  registerMcp(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` };
+  },
+};

package/shared/build-kit/lib/harnesses/hermes.js

@@ -0,0 +1,28 @@
+// Hermes (`hermes chat`).
+
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export default {
+  name: 'hermes',
+  matches: (words) => words.slice(0, 3).some((w) => w.split('/').pop().replace(/@.*$/, '') === 'hermes'),
+  // -q takes the prompt, so the preset ends with it (the --model flag is inserted before it, see withModel).
+  // -Q is the plain-text mode a modeling turn reads its answer from; --format stream-json is the build kit's.
+  preset: () => ({ modeling: 'hermes chat --yolo -Q -q', build: 'hermes chat --yolo --format stream-json -q' }),
+  withModel: (command, flag) => (command.endsWith(' -q') ? `${command.slice(0, -3)} ${flag} -q` : `${command} ${flag}`),
+
+  // Hermes reads MCP servers from ~/.hermes/config.yaml only (there is no project-level file), so
+  // this never writes it — a user-wide file is not ours to rewrite. It reports the server as
+  // registered when the file already names it (the docker images ship it), and says what to add otherwise.
+  registerMcp(command, _projectDir, url) {
+    const file = join(process.env.HERMES_HOME || join(homedir(), '.hermes'), 'config.yaml');
+    const has = existsSync(file) && /^\s+eventmodelers:/m.test(readFileSync(file, 'utf8'));
+    return {
+      command,
+      file: null,
+      reason: '', // not a JSON file — there is nothing to say about its format
+      manual: has ? null : `add to ${file}:\nmcp_servers:\n  eventmodelers:\n    url: "${url}"\n    headers:\n      x-token: "\${EVENTMODELERS_TOKEN}"`,
+    };
+  },
+};

package/shared/build-kit/lib/harnesses/index.js

@@ -0,0 +1,66 @@
+// The agent harnesses `run --exec` / `run --agent` can hand a turn to, one module each — everything
+// a harness needs (its headless command, how to recognise it, how the eventmodelers MCP server gets
+// registered with it, its model flag, any session of its own) lives in its file. Claude is not here:
+// it has a dedicated runner. Adding a harness is one module and one line in HARNESSES.
+//
+// A module exports: name, matches(words), preset(loop?) -> {modeling, build}, registerMcp(command,
+// projectDir, url) -> {command, file, manual, reason?}, and optionally modelFlag (default `-m`),
+// withModel(command, flag) and session {start, resume}.
+
+import opencode from './opencode.js';
+import codex from './codex.js';
+import gemini from './gemini.js';
+import hermes from './hermes.js';
+import cursor from './cursor.js';
+import { shellQuote } from './util.js';
+
+export { shellQuote };
+export { opencodeSupportsStandalone, setOpencodeStandaloneSupport } from './opencode.js';
+
+const HARNESSES = [opencode, codex, gemini, hermes, cursor];
+
+// Every name `--agent` takes, claude (the default runner, no command) first.
+export const AGENT_NAMES = ['claude', ...HARNESSES.map((h) => h.name)];
+
+export function harnessByName(name) {
+  return HARNESSES.find((h) => h.name === name) ?? null;
+}
+
+// Which known harness a command runs — the first words naming one, so `npx @openai/codex exec`
+// and `/opt/bin/opencode run` are recognised as well as the bare names.
+export function harnessFor(command) {
+  const words = String(command).trim().split(/\s+/);
+  return HARNESSES.find((h) => h.matches(words)) ?? null;
+}
+
+export function harnessOf(command) {
+  return harnessFor(command)?.name ?? null;
+}
+
+// The headless command --agent <name> stands for, for the `modeling` or `build` loop.
+export function presetCommand(name, loop) {
+  return harnessByName(name)?.preset(loop)[loop] ?? null;
+}
+
+// `--model <id>` on a preset command, spelled the way that harness wants it.
+export function withModel(command, id) {
+  const h = harnessFor(command);
+  const flag = `${h?.modelFlag ?? '-m'} ${shellQuote(id)}`;
+  return h?.withModel ? h.withModel(command, flag) : `${command} ${flag}`;
+}
+
+// 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 = harnessFor(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 = harness.registerMcp(command, projectDir, url);
+  if (reg.manual) log(`MCP: could not update the ${harness.name} config${reg.reason ?? ' (not plain JSON)'} — ${reg.manual}`);
+  else log(`MCP: eventmodelers registered for ${harness.name}${reg.file ? ` in ${reg.file}` : ' via -c flags'}`);
+  return { command: reg.command, registered: !reg.manual };
+}

package/shared/build-kit/lib/harnesses/opencode.js

@@ -0,0 +1,51 @@
+// OpenCode (`opencode run`).
+
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { mergeJsonConfig } from './util.js';
+
+// Older OpenCode releases have no `run --standalone`; passing it makes `opencode run` print its
+// usage and exit 1, so every turn fails. Ask the installed binary once. Overridable for tests.
+let standaloneSupported = null;
+export function opencodeSupportsStandalone() {
+  if (standaloneSupported === null) {
+    const r = spawnSync('opencode', ['run', '--help'], { encoding: 'utf8' });
+    standaloneSupported = /--standalone\b/.test(`${r.stdout || ''}${r.stderr || ''}`);
+  }
+  return standaloneSupported;
+}
+export function setOpencodeStandaloneSupport(value) { standaloneSupported = value; }
+
+export default {
+  name: 'opencode',
+  matches: (words) => words.slice(0, 3).some((w) => binName(w) === 'opencode'),
+  // --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.
+  preset: () => ({ modeling: 'opencode run --standalone --auto', build: 'opencode run --standalone --auto --format json' }),
+
+  registerMcp(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.
+    // A binary without the flag runs the turn in-process already, so the flag is dropped, not added.
+    const supported = opencodeSupportsStandalone();
+    const standalone = !supported ? command.replace(/\s--standalone\b/, '')
+      : /\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` };
+  },
+};
+
+function binName(word) { return word.split('/').pop().replace(/@.*$/, ''); }

package/shared/build-kit/lib/harnesses/util.js

@@ -0,0 +1,24 @@
+// Helpers the harness modules share.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } 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.
+export 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;
+}