@eventmodelers/cli 1.0.86 → 1.0.87

package/README.md

@@ -125,8 +125,8 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
 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]      # same, via a local/self-hosted model (ralph-local-ai.js)
-npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js)
+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 --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

package/cli.js

@@ -3193,8 +3193,8 @@ credentialFlags(program
 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. Claude remains the default when this flag is absent.`)
-  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent.')
+  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner: a build kit runs it via ralph-local-ai.js, and --modeling/--standalone via lib/modeling-local-ai.js (board tools over MCP, but no skills and no subagent fan-out — those are Claude Code features). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Board work only: --local-ai never builds a Planned slice (no file, shell or git tools). To build code with a local model, use --exec with a coding harness pointed at it, e.g. "codex exec --oss --full-auto". Claude remains the default when this flag is absent.`)
+  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent. With agent tracing on, include the harness\'s JSON output flag (codex exec --json, opencode run --format json, gemini --output-format stream-json) — without it no slice cost is recorded.')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--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/--global).')
@@ -3907,7 +3907,7 @@ program
 program
   .command('config')
   .description('Print the fully resolved config (merged across the directory hierarchy + EVENTMODELERS_* env vars), with the token masked')
-  .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all.")
+  .option('--agent-tracing <on|off>', "Turn agent tracing on or off for this project (saved as `agentTracing` in the project's .eventmodelers/config.json). Off: the build agent sends no slice cost data to the platform at all. A non-Claude agent via run --exec is only traced when its command includes the harness's JSON output flag, e.g. \"codex exec --json --full-auto\".")
   .action((opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);

package/package.json

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

package/shared/build-kit/README.md

@@ -51,7 +51,7 @@ node .build-kit/ralph-claude.js /path/to/project
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
 - The loop runs Claude with `backend-prompt.md`
 - Claude implements the slice in the project
-- Phase 2 is Claude-only; local-AI mode skips it (local-ai-agent handles its own queue)
+- Phase 2 (building slices) never runs with `--local-ai` — see *`--local-ai` does not build code*. Build with `--exec` instead
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
@@ -72,6 +72,34 @@ node .build-kit/realtime-agent.js
 `ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
 Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
 
+### `--local-ai` does not build code
+
+**`--local-ai` works on the board only. It never builds a slice.** Planned slices stay
+Planned. That is by design, not a bug:
+
+- **Planned slices are never handed to it.** `ralph-local-ai.js` gives `startRalph` no
+  `onPlannedSlice`, so the loop only feeds it `tasks.json` prompts.
+- **It has no coding tools.** `lib/local-ai-agent.js` exposes only the board MCP tools:
+  no file read/write, no shell, no git, no test run.
+- **Its system prompt forbids file and shell access.** Such a request is answered with
+  `Blocked: …`.
+- **A prompt stops after 12 tool-call rounds.** That is enough for board edits, but far
+  short of a slice build.
+
+Here the kit is the agent loop and the model only picks tools. Building would mean
+rewriting a full coding agent inside the kit, so it is left out on purpose.
+
+**To build with a local model, use `--exec`** with a coding harness pointed at that model
+(see *External agent commands* below):
+
+```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
+```
+
+Or keep Claude Code as the builder and point `anthropicBaseUrl` at a local endpoint that
+speaks the Anthropic API.
+
 ```bash
 LOCAL_AI_TARGET=ollama          # preset: ollama | vllm | lmstudio | llamacpp
 LOCAL_AI_URL=http://host:8000/v1  # any OpenAI-compatible server (overrides the preset URL)
@@ -109,6 +137,20 @@ child runs with the project dir as its cwd and inherits stdio — a harness owns
 output format, so there is no condensed per-step logging here the way `ralph-claude.js`
 has it.
 
+**Agent tracing needs the harness's JSON output flag.** With agent tracing on
+(`eventmodelers config --agent-tracing on`), slice builds are costed just like with Claude —
+but only if the harness runs in its JSON output mode. Its normal output has no token counts,
+so without the flag a turn is not traced (the runner logs a hint). Add the flag yourself:
+
+```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 "gemini --yolo --output-format stream-json -p"
+```
+
+The terminal then shows the raw JSON events. Only OpenCode reports a dollar cost; Codex and
+Gemini turns record tokens and duration with no cost. See `agent-tracking.md`.
+
 Persist a default alongside the local-AI settings:
 
 ```json

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

@@ -45,6 +45,69 @@ export function usageFromLocalAi(raw, durationMs) {
   };
 }
 
+/** One event from an external harness's JSON output (ralph-exec.js), or null if it carries no usage.
+ *  Matched on shape, not on the command name, so a wrapper script around a harness still counts:
+ *   - Codex `codex exec --json`: `turn.completed` with `usage` (input_tokens includes the cached ones)
+ *   - OpenCode `opencode run --format json`: `step_finish` per model step, with tokens and cost
+ *   - Gemini CLI `--output-format stream-json`: the final `result` with `stats`;
+ *     `--output-format json`: one object whose `stats.models` holds tokens per model
+ *  Only OpenCode reports a cost — the others leave costUsd null rather than guessing a price. */
+export function usageFromHarnessEvent(msg) {
+  if (msg?.type === 'turn.completed' && msg.usage) {
+    const u = msg.usage;
+    const cached = n(u.cached_input_tokens);
+    return { inputTokens: Math.max(0, n(u.input_tokens) - cached), outputTokens: n(u.output_tokens), cacheReadTokens: cached };
+  }
+  if (msg?.type === 'step_finish' && msg.part?.tokens) {
+    const t = msg.part.tokens;
+    return {
+      inputTokens: n(t.input),
+      outputTokens: n(t.output) + n(t.reasoning),
+      cacheReadTokens: n(t.cache?.read),
+      cacheWriteTokens: n(t.cache?.write),
+      costUsd: Number.isFinite(msg.part.cost) ? msg.part.cost : null,
+    };
+  }
+  if (msg?.type === 'result' && msg.stats && !('total_cost_usd' in msg)) {
+    const s = msg.stats;
+    return {
+      inputTokens: n(s.input_tokens),
+      outputTokens: n(s.output_tokens),
+      durationMs: Number.isFinite(s.duration_ms) ? s.duration_ms : null,
+    };
+  }
+  if (msg?.stats?.models && typeof msg.stats.models === 'object') {
+    const models = Object.entries(msg.stats.models);
+    const tok = (key) => models.reduce((sum, [, m]) => sum + n(m?.tokens?.[key]), 0);
+    const cached = tok('cached');
+    const [dominant] = models.sort((a, b) => n(b[1]?.tokens?.candidates) - n(a[1]?.tokens?.candidates))[0] ?? [];
+    return {
+      inputTokens: Math.max(0, tok('prompt') - cached),
+      outputTokens: tok('candidates') + tok('thoughts'),
+      cacheReadTokens: cached,
+      model: dominant ?? null,
+    };
+  }
+  return null;
+}
+
+/** Sums the usage of every event in one turn. A field no event reported stays null (cost, model)
+ *  or 0 (tokens), so a harness without a cost does not show up as a free turn. */
+export function sumUsage(parts) {
+  if (!parts.length) return null;
+  const add = (key) => parts.reduce((sum, p) => sum + n(p[key]), 0);
+  const costs = parts.map((p) => p.costUsd).filter(Number.isFinite);
+  return {
+    inputTokens: add('inputTokens'),
+    outputTokens: add('outputTokens'),
+    cacheReadTokens: add('cacheReadTokens'),
+    cacheWriteTokens: add('cacheWriteTokens'),
+    costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
+    durationMs: parts.findLast((p) => Number.isFinite(p.durationMs))?.durationMs ?? null,
+    model: parts.findLast((p) => p.model)?.model ?? null,
+  };
+}
+
 /** 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 } = {}) {

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

@@ -18,6 +18,7 @@
 // Or persist it as localAi.exec in .eventmodelers/config.json.
 
 import { startRalph, loadLocalConfig, resolveAgentIdentity } from './lib/ralph.js';
+import { createSliceTracer, usageFromHarnessEvent, sumUsage } from './lib/tracing.js';
 import { spawn } from 'child_process';
 import { writeFileSync, mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
@@ -52,6 +53,21 @@ const childEnv = {
   ...(cfg.agentId && !localOnly ? { EVENTMODELERS_AGENT_ID: cfg.agentId } : {}),
 };
 
+// What each slice build turn cost — see lib/tracing.js. Same opt-in as ralph-claude.js, but a
+// harness only reports usage in its JSON output mode (`codex exec --json`, `opencode run --format
+// json`, `gemini --output-format stream-json`), so without that flag a turn has nothing to record.
+const tracingOn = !localOnly && cfg.agentTracing === true;
+if (!tracingOn && !localOnly) console.log('[ralph-exec] agent tracing off — no slice cost data is sent (turn on: eventmodelers config --agent-tracing on)');
+const tracer = createSliceTracer({
+  baseUrl: cfg.baseUrl,
+  token: cfg.token,
+  organizationId: cfg.organizationId,
+  agentId: cfg.agentId,
+  traceFile: join(projectDir, '.eventmodelers', 'trace', 'slices.jsonl'),
+  log: (line) => console.log(`[ralph-exec] ${line}`),
+  enabled: tracingOn,
+});
+
 const promptDir = mkdtempSync(join(tmpdir(), 'ralph-exec-'));
 
 // POSIX single-quote escaping: close, insert an escaped quote, reopen. The prompt is
@@ -62,22 +78,59 @@ function shellQuote(s) {
 
 console.log(`[ralph-exec] command: ${execCmd}`);
 
-function runExec(prompt) {
+// Parses a harness's stdout for usage while still passing it through. Most harnesses emit JSONL;
+// Gemini's `--output-format json` is one pretty-printed object, hence the whole-output fallback.
+function collectUsage(stream) {
+  const parts = [];
+  let buffer = '';
+  let all = '';
+  const take = (text) => {
+    try { const u = usageFromHarnessEvent(JSON.parse(text)); if (u) parts.push(u); } catch { /* not JSON */ }
+  };
+  stream.on('data', (chunk) => {
+    process.stdout.write(chunk);
+    const text = chunk.toString();
+    all += text;
+    buffer += text;
+    const lines = buffer.split('\n');
+    buffer = lines.pop();
+    for (const line of lines) if (line.trim()) take(line);
+  });
+  return () => {
+    if (buffer.trim()) take(buffer);
+    if (!parts.length && all.trim()) take(all);
+    return sumUsage(parts);
+  };
+}
+
+// `slice` is set for a planned-slice build (see startRalph) — the only turns that are traced.
+function runExec(prompt, slice = null) {
   return new Promise((resolvePromise, reject) => {
     const full = inlineHeader + prompt;
     const promptFile = join(promptDir, 'prompt.md');
     writeFileSync(promptFile, full);
+    const traced = tracingOn && !!slice;
+    const startedAt = Date.now();
 
     // stdio inherit: the harness owns its own output format, and there is no
     // cross-harness stream schema to parse into the condensed per-step logging
-    // that ralph-claude.js does — so it goes straight through.
+    // that ralph-claude.js does — so it goes straight through. A traced turn pipes
+    // stdout instead, only to read usage from it; the output is still echoed as is.
     const proc = spawn(`${execCmd} ${shellQuote(full)}`, {
       cwd: projectDir,
-      stdio: 'inherit',
+      stdio: ['inherit', traced ? 'pipe' : 'inherit', 'inherit'],
       shell: true,
       env: { ...childEnv, RALPH_PROMPT_FILE: promptFile },
     });
-    proc.on('close', (code) => (code === 0 ? resolvePromise() : reject(new Error(`exec command exited ${code}`))));
+    const usage = traced ? collectUsage(proc.stdout) : null;
+    proc.on('close', (code) => {
+      if (traced) {
+        const u = usage();
+        if (u) tracer.record({ ...slice, status: code === 0 ? 'ok' : 'error' }, { ...u, durationMs: u.durationMs ?? Date.now() - startedAt });
+        else console.log('[ralph-exec] trace: no usage in the command output — run the harness in its JSON output mode to record slice cost');
+      }
+      code === 0 ? resolvePromise() : reject(new Error(`exec command exited ${code}`));
+    });
     proc.on('error', reject);
   });
 }