@eventmodelers/cli 1.0.85 → 1.0.87

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

@@ -17,7 +17,8 @@
 //        RALPH_EXEC_CMD="opencode run" node ralph-exec.js
 // Or persist it as localAi.exec in .eventmodelers/config.json.
 
-import { startRalph, loadLocalConfig } from './lib/ralph.js';
+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';
@@ -29,6 +30,8 @@ const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir,
 
 const cfg = loadLocalConfig(kitDir);
 const localOnly = process.env.RALPH_LOCAL === '1';
+// Same as ralph-claude.js: childEnv is built at load time, before startRalph resolves identity.
+Object.assign(cfg, resolveAgentIdentity(kitDir, 'BUILD', cfg));
 const execCmd = process.env.RALPH_EXEC_CMD || cfg.localAi?.exec;
 
 if (!execCmd) {
@@ -50,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
@@ -60,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);
   });
 }

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -63,7 +63,6 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `render_screen` | `boardId`, `nodeId`, `elements[]?` (SCREEN) or `pages[]?`+`backgroundColor?` (HTML_SCREEN), `description?` | Update an existing screen's content — exactly one of `elements`/`pages` | §4 `POST .../images/:id/sketch` + `image-nodes` |
 | `add_field_examples` | `boardId`, `nodeId?`, `name?`, `cellName?`, `timelineId?` | Fill empty field examples using linked-node context | — (MCP-only convenience) |
 | `get_attribute_chain` | `boardId`, `timelineId`, `targetCellName`, `sourceCellName` | Resolve every node between two cells, ordered target→source. Both cell names must come from a node's reported `cellName` (`get_board_outline`, `get_nodes`, `get_node`) — a guessed address that happens to exist silently resolves the wrong chain | — (MCP-only convenience) |
-| `verify_screen` | `boardId`, `nodeId` | Check a screen node exists and has rendered content — works for both SCREEN and HTML_SCREEN, dispatching on the node's actual type | — (MCP-only convenience) |
 | `get_image_snapshot_description` | `boardId`, `nodeId` | Load the `{elements:[...]}` sketch description from storage | — (reads what §4 sketch endpoints write) |
 | `validate_slice_data` | `sliceData` | Offline validation of a `SliceDataOutput` payload — no board access | — (MCP-only, pure function) |
 | `commit_board_to_git` | `boardId` | Force a git-extension commit/push, bypassing the autoCommit gate | — (MCP-only; git extension) |

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-storyboarding-events/SKILL.md

@@ -231,6 +231,7 @@ mcp__eventmodelers__create_screen {
     "nodeId": "<node-uuid>",
     "chapterId": "<CHAPTER_ID>",
     "cellId": "<actorRowId>-<columnId>",
+    "title": "<Screen Title>",
     "pages": ["<div>...</div>"],
     "description": "<concise description of what this screen shows>",
     "fields": [ /* per "Mandatory Field Definitions" below — set in this same call */ ]
@@ -240,7 +241,7 @@ mcp__eventmodelers__create_screen {
 
 **Fallback (no MCP):** see `references/api-fallback.md` — "Mandatory Screen Rendering — Step B: Create the HTML_SCREEN node".
 
-The MCP `create_screen` call above already sets `meta.fields` (per "Mandatory Field Definitions" below) in the same call — no separate `node:changed` follow-up needed when using MCP.
+The MCP `create_screen` call above already sets the node's `title` and `meta.fields` (per "Mandatory Field Definitions" below) in the same call — no separate `node:changed` follow-up needed when using MCP.
 
 A storyboard screen is placed at a *provisional* position — Steps 4 and 5 wire it to its COMMAND / READMODEL once those exist, and may move it first. Pass `autoConnect: false` on `create_screen` here so the placement doesn't pre-wire the screen to whatever happens to sit in the adjacent column; the real `SCREEN → COMMAND` and `READMODEL → SCREEN` edges are created deliberately in Steps 4 and 5. When creating several screens whose HTML is already authored, put them all in one `create_screen` call's `screens` array with `autoConnect: false`.
 

package/stacks/modeling-kit/templates/.claude/skills/html-screen/SKILL.md

@@ -140,6 +140,7 @@ mcp__eventmodelers__create_screen {
     "nodeId": "<generated-uuid>",
     "chapterId": "<CHAPTER_ID>",
     "cellName": "<CELL_NAME>",
+    "title": "<Screen Title>",
     "pages": ["<div>...</div>"],
     "fields": [ /* optional — set meta.fields here too (see Step 5) instead of a separate call */ ]
   }]

package/stacks/react/templates/build-kit/README.md

@@ -1,134 +0,0 @@
-# .build-kit
-
-Ralph's runtime directory. Contains the agent loop, board poller, prompts, and Claude skills.
-
-> This is the **react** (API-access) stack — it talks to the board purely through
-> the plain REST `slicedata` endpoint on `api.eventmodelers.ai`, polled on an interval.
-> There is no Supabase/PocketBase realtime subscription and no direct database table
-> access anywhere in this kit. For instant push notifications instead of polling, use
-> the `supabase-react` stack.
-
-## Quick start
-
-```bash
-# Claude (default)
-node .build-kit/ralph-claude.js
-
-# Local or self-hosted model — Ollama (run `ollama serve` first)
-LOCAL_AI_TARGET=ollama node .build-kit/ralph-local-ai.js
-
-# …or any OpenAI-compatible server (vLLM, LM Studio, llama.cpp, TGI)
-LOCAL_AI_TARGET=vllm LOCAL_AI_MODEL=Qwen/Qwen3-8B node .build-kit/ralph-local-ai.js
-
-# Custom project directory (defaults to the parent of .build-kit)
-node .build-kit/ralph-claude.js /path/to/project
-```
-
-## Files
-
-**Entry points** (top level):
-
-| File | Purpose |
-|------|---------|
-| `ralph-claude.js` | Runs the full loop using Claude Code as the executor |
-| `ralph-local-ai.js` | Runs the full loop using a local/self-hosted model (Ollama, vLLM, LM Studio, llama.cpp) |
-| `ralph-exec.js` | Runs the full loop handing each prompt to an external agent command (Codex CLI, OpenCode, …) |
-| `ralph.sh` | Shell-based loop — alternative to the JS entry points |
-
-**Internals** (`lib/`):
-
-| File | Purpose |
-|------|---------|
-| `lib/ralph.js` | Shared library — board poller + loop logic; imported by the entry points |
-| `lib/local-ai-agent.js` | Local-AI executor — called by `ralph-local-ai.js`, can also run manually |
-| `lib/agent.sh` | Thin shell wrapper around `claude` — called by `ralph.sh` |
-| `lib/prompt.md` | Phase 1 prompt: tells Claude how to load a slice from the board |
-| `lib/backend-prompt.md` | Phase 2 prompt: tells Claude how to build a planned slice |
-| `lib/AGENT.md` | Agent instructions included in Claude's context |
-
-## How it works
-
-**Phase 1** — triggered when `tasks.json` has entries:
-- The poller writes a task to `tasks.json` each time it notices a slice's status changed since the last poll
-- The loop picks it up and runs Claude (or a local model) with `prompt.md`
-- Claude loads the slice data and updates `.slices/`
-
-**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)
-
-Both phases run in a continuous loop with a 3-second idle sleep. The board poller runs concurrently in the same process, re-fetching `slicedata/slices` every `RALPH_POLL_INTERVAL_MS` (default 10s — see `lib/ralph.js`).
-
-## Local-AI configuration
-
-`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.
-
-```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)
-LOCAL_AI_MODEL=qwen3.5:9b       # model name as the server knows it
-LOCAL_AI_API=openai             # force the wire dialect: ollama | openai (normally inferred)
-LOCAL_AI_API_KEY=local          # sent as `Authorization: Bearer` on the openai dialect
-LOCAL_AI_NUM_CTX=32768          # ollama only — context window (default 32768)
-```
-
-**Do not lower `LOCAL_AI_NUM_CTX`.** The MCP tool schemas are ~16k tokens on their own.
-Ollama's own default is 4096, which silently truncates them — the model then sees a
-fragment of the tool list and invents tool names instead of failing, which is why the
-default here is raised rather than left to the server. On the `openai` dialect the
-equivalent is set when you launch the server (vLLM `--max-model-len 32768`,
-llama.cpp `-c 32768`); an overflow there surfaces as an HTTP 400.
-
-
-## External agent commands (`--exec`)
-
-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:
-
-```bash
-npx @eventmodelers/cli run --exec "codex exec --full-auto"
-npx @eventmodelers/cli run --exec "opencode run"
-
-# …or persist it and use the bare flag
-RALPH_EXEC_CMD="codex exec --full-auto" node .build-kit/ralph-exec.js
-```
-
-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
-output format, so there is no condensed per-step logging here the way `ralph-claude.js`
-has it.
-
-Persist a default alongside the local-AI settings:
-
-```json
-{
-  "localAi": {
-    "exec": "codex exec --full-auto"
-  }
-}
-```
-
-One caveat worth knowing before reaching for this: the kits' prompts assume Claude
-Code's `Skill` tool and `CLAUDE.md`. Other harnesses read `AGENTS.md` and have no skill
-primitive, so `init-agents` puts the skill files where they can find them, but
-`lib/prompt.md` / `lib/backend-prompt.md` still need wording that says *read and follow*
-a skill file rather than *invoke* it.
-
-## Config
-
-Credentials are stored in `.build-kit/.eventmodelers/config.json` (written by `eventmodelers init`):
-
-```json
-{
-  "organizationId": "...",
-  "boardId": "...",
-  "token": "...",
-  "baseUrl": "https://api.eventmodelers.ai"
-}
-```
-
-Claude skills live in `.build-kit/.claude/skills/` and are available inside any Claude Code session started from `.build-kit/`.