@eventmodelers/cli 1.0.69 → 1.0.71

package/README.md

@@ -211,8 +211,10 @@ starting in one command. Resolution order for a run is `--credentials` and the i
 `--token`/`--organization-id`/`--board-id`/`--base-url` flags, then `EVENTMODELERS_*` env vars,
 then `~/.eventmodelers/boards/<board>.json`, then the usual `.eventmodelers/config.json` walk,
 and finally the account's default board. Whatever a run resolves is saved back to the
-per-board file (`0600`, in a `0700` directory) along with a stable agent id for the board's
-alive-ping. One machine can therefore drive several boards, across several accounts, at once.
+per-board file (`0600`, in a `0700` directory). The agent id is *not* stored there — a standalone
+run mints a fresh one each time, so two ad-hoc agents on one board stay two agents (see
+[Naming an agent](#naming-an-agent)). One machine can therefore drive several boards, across
+several accounts, at once.
 The global kit itself holds no credentials at all — the token reaches `claude` through the
 spawned process's environment.
 
@@ -401,16 +403,30 @@ npx @eventmodelers/cli init-config --name ci-builder     # name the agent this c
 
 ### Naming an agent
 
-Every agent identifies itself to the platform with a stable `agentId` it mints on first use (per project, or per board for `run --standalone`), and the board's live-agent view shows that bare uuid. `--name` gives it a readable one instead — accepted by `init`, `re-init`, and `init-config`, saved into `config.json` as `agentName`, and sent with every heartbeat from then on:
+Every agent identifies itself to the platform with an `agentId`, and the board's live-agent view shows that bare uuid. A **project install** mints one on first use and reuses it on every restart (`agentIds` in the project root's `.eventmodelers/config.json`). A **standalone/global run** mints a fresh one per run instead: nothing stops two ad-hoc agents running for one board, and since the heartbeat is keyed on `(token, agentId, agentType)`, a shared id would make the second agent replace the first — one agent visible however many are running, and their board writes indistinguishable.
+
+`--name` gives an agent a readable label instead of the uuid — accepted by `init`, `re-init`, and `init-config`, saved into `config.json` as `agentName`, and sent with every heartbeat from then on:
 
 ```bash
 npx @eventmodelers/cli init --stack node --name ci-builder     # persisted for every later run of this kit
 npx @eventmodelers/cli init-config --name martins-laptop       # same, without re-installing
 npx @eventmodelers/cli run --name one-off-check                # override for a single run, nothing written
-npx @eventmodelers/cli run --id <id>                           # …and a second agent of the same type, side by side
+npx @eventmodelers/cli run --id <id>                           # pin ONE identity across restarts
+```
+
+`run --id` is what you want when an agent has to keep the same identity every time it starts: a supervisor that already knows the id, a second agent of the same type in one *project* (which would otherwise share the project's single minted id), or an agent a board has starred as its **preferred agent** — that star addresses prompts to one id, so an agent whose id changes per run loses it on restart. `run --id`/`run --name` are per-run only: nothing is written to disk.
+
+#### Working only what you were addressed (`--exclusive`)
+
+By default an agent claims two kinds of prompt: the ones addressed to its own id, and every prompt nobody addressed to anyone. That's right for the single agent on a board, and wrong for a dedicated one — a specialist sitting next to a general agent, or an agent a supervisor drives by id, ends up answering whatever the queue happens to hold. `--exclusive` drops that second kind:
+
+```bash
+npx @eventmodelers/cli run --standalone --board-id <uuid> --id <agent-uuid> --exclusive
 ```
 
-The heartbeat is keyed on `(token, agentId, agentType)`, so two agents of the same type in one project need distinct ids to both show up — that's what `run --id` is for. `run --id`/`run --name` are per-run only: the persisted `agentName` (and the minted id) stay untouched, so the next plain `run` is the same agent the platform already knows.
+Only prompts carrying this agent's id are worked. Anything untargeted is handed straight back to the queue (status `ADDED`) for another agent to take — the addressee filter lives in the queue's claim query, which hands an agent its own prompts *and* the untargeted ones, so claiming is the only way to find out which arrived. An exclusive run therefore claims as usual and gives back what wasn't meant for it, once it has walked past it to its own work.
+
+Pair it with `--id`: a `--standalone`/`--global` run mints a fresh id per run, so prompts addressed to the previous run's id are never claimed. `--exclusive` applies to the prompt queue only — a `--standalone` agent's self-directed turns are nobody's prompt, and it keeps taking them.
 
 ### Env vars and `--config` (scripted/CI installs)
 

package/cli.js

@@ -1390,7 +1390,7 @@ function ensureEnvToken(targetDir, token) {
 const GLOBAL_DIR = join(homedir(), '.eventmodelers');
 const GLOBAL_KIT_DIR = join(GLOBAL_DIR, 'kit');
 
-// One file per board: `{token, organizationId, boardId, baseUrl, agentId}`. Credentials
+// One file per board: `{token, organizationId, boardId, baseUrl}`. Credentials
 // ARE per board — a token is scoped to the org that owns it — so one machine can drive
 // several boards across several accounts at once, each with its own. Written 0600 in a
 // 0700 dir: unlike a project's .eventmodelers/config.json, there is no .gitignore standing
@@ -1408,21 +1408,20 @@ function boardCredentialsPath(boardId) {
 function writeBoardCredentials(config) {
   const path = boardCredentialsPath(config.boardId);
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  // agentName rides along with agentId in both credential-bearing shapes: it is per-board
-  // identity, same as the id, and this file is the only config a `run --standalone` from an
-  // arbitrary directory ever reads — drop it here and `init-config --name` would be lost on
-  // the very next run.
+  // agentName is stored, the agent id is not: the name is a label for whoever runs here (and
+  // this file is the only config a `run --standalone` from an arbitrary directory reads, so
+  // dropping it would lose `init-config --name` on the very next run), while the id is minted
+  // per run now — see resolveModelingCredentials for why.
   const agentName = config.agentName ? { agentName: config.agentName } : {};
   const body = config.useBoard
     ? { boardId: config.boardId, useBoard: config.useBoard }
     : config.useGlobal
-    ? { boardId: config.boardId, useGlobal: true, agentId: config.agentId, ...agentName }
+    ? { boardId: config.boardId, useGlobal: true, ...agentName }
     : {
         token: config.token,
         organizationId: config.organizationId,
         boardId: config.boardId,
         baseUrl: config.baseUrl,
-        agentId: config.agentId,
         ...agentName,
       };
   writeFileSync(path, JSON.stringify(body, null, 2), { mode: 0o600 });
@@ -1605,12 +1604,18 @@ async function resolveModelingCredentials(cwd, flags, explicitConfigPath, print)
     process.exit(1);
   }
 
-  // Distinguishes this agent from any other pinging the same board, and has to stay stable
-  // across runs or the platform sees a brand-new agent on every restart. Per board, since
-  // that is the identity the alive-ping is scoped to.
-  config.agentId = stored.agentId || readJsonSafe(boardCredentialsPath(config.boardId)).agentId || randomUUID();
+  // A fresh identity for every standalone run, deliberately not persisted. A standalone agent
+  // is started ad hoc from wherever, and nothing stops two of them running for the same board —
+  // with one id stored per board they upserted the same alive row (the heartbeat is keyed on
+  // token + agent_id + agent_type), so the second agent replaced the first instead of joining
+  // it: the board showed one agent however many were running, and their writes were
+  // indistinguishable. A per-run uuid costs the identity its continuity across restarts (a
+  // restarted agent is a new row, and the old one lingers until its 45s window lapses) — pass
+  // `run --id <uuid>` when an agent needs to keep one identity, which is also what makes
+  // "preferred agent" on the board stick to it.
+  config.agentId = randomUUID();
   writeBoardCredentials(stored.useGlobal
-    ? { boardId: config.boardId, useGlobal: true, agentId: config.agentId, agentName: config.agentName }
+    ? { boardId: config.boardId, useGlobal: true, agentName: config.agentName }
     : config);
 
   return config;
@@ -1667,7 +1672,13 @@ async function ensureGlobalKit(baseUrl) {
 // question, sketch a screen. Without the flag that channel is still subscribed on
 // the same connection and every event on it is dropped, so the two modes differ by
 // one filter rather than by a whole second realtime stack.
-async function runModeling(kitDir, projectDir, verbose = false, standalone = false, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {}) {
+//
+// `exclusive` narrows the prompt lane to this agent alone: only a prompt the user
+// addressed to this agent id (the board's "preferred agent") is worked, and anything
+// 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, overrides = null, maxAgents = DEFAULT_MAX_AGENTS, identity = {} } = {}) {
   const configLibPath = join(kitDir, 'lib', 'config.js');
   if (!existsSync(configLibPath)) {
     console.error(`❌ ${relative(process.cwd(), configLibPath)} not found — --modeling needs a kit installed via \`init --modeling\`.`);
@@ -1697,14 +1708,20 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     console.error('❌ --modeling needs platform credentials in .eventmodelers/config.json (token + organizationId) — run `/connect` once or paste your config first.');
     process.exit(1);
   }
-  // The identity flags go on last: the global install's `overrides` carry the board's own
-  // stored agentId (already persisted by resolveModelingCredentials), which would otherwise
-  // win back over an explicit --id.
+  // 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
   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);
   }
+  // Nothing can be addressed to an agent with no id, so an exclusive run without one would
+  // hand every prompt back and sit idle forever — a silent no-op worth failing on instead.
+  if (exclusive && !cfg.agentId) {
+    console.error('❌ --exclusive needs an agent id — that is what a prompt is addressed to. Pass `run --id <uuid>` (or let the kit mint one) and address the prompt to it on the board.');
+    process.exit(1);
+  }
 
   const subagentModel = cfg.subagentModel || DEFAULT_SUBAGENT_MODEL;
 
@@ -1917,11 +1934,19 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   }
 
   spawnProcess();
+  log(`agent: ${cfg.agentName ? `${cfg.agentName} (${cfg.agentId})` : cfg.agentId}`);
   log(
     standalone
       ? `standalone: ON — reacting to direct prompts AND to board changes on its own initiative (max ${maxAgents} subagent(s) per self-directed turn)`
       : 'standalone: off — reacting to direct prompts only (board changes are dropped)',
   );
+  if (exclusive) {
+    log(`exclusive: ON — only prompts addressed to ${cfg.agentId} are worked; every untargeted prompt is handed back to the queue`);
+    // A global/standalone run mints its id per run (see resolveModelingCredentials), so an id
+    // someone addressed a prompt to yesterday is not this agent — worth saying out loud here,
+    // where the alternative is an agent that looks healthy and quietly works nothing.
+    if (overrides && !identity.agentId) log('exclusive: this run minted a fresh agent id — star it on the board now, or restart with `--id <uuid>` to keep one addressable identity');
+  }
   warmUpSession();
 
   async function getRealtimeToken() {
@@ -1941,15 +1966,47 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     return res.json();
   }
 
+  // Puts a prompt this agent claimed but will not work back on the queue (CLAIMED -> ADDED),
+  // so whichever agent it was actually open to can still take it. `x-token` only — the status
+  // endpoint is meant to be called by the agent holding the prompt.
+  async function releasePrompt(promptId) {
+    const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/${promptId}/status`, {
+      method: 'POST',
+      headers: { 'x-token': cfg.token, 'Content-Type': 'application/json', ...agentHeaders(cfg) },
+      body: JSON.stringify({ status: 'ADDED' }),
+    });
+    if (!res.ok) throw new Error(`prompts/${promptId}/status: HTTP ${res.status}`);
+  }
+
   let realtimeToken = await getRealtimeToken();
 
   let draining = false;
   async function drain() {
     if (draining) return;
     draining = true;
+    // --exclusive only: prompts claimed in this pass that weren't addressed to this agent,
+    // handed back once the pass is over (see below).
+    const handBack = [];
     try {
       let p;
       while ((p = await fetchNextPrompt(realtimeToken)) !== null) {
+        // The queue can't filter by addressee for us: `prompts/next` hands an agent both the
+        // prompts addressed to it and every untargeted one (`agent_id IS NULL`) — claiming is
+        // what reveals which kind arrived — so an exclusive run claims as usual and gives back
+        // what wasn't meant for it.
+        //
+        // The hand-back is deferred to the end of the pass on purpose: a prompt released
+        // mid-loop goes straight back to the head of the very queue this loop is reading, so
+        // the next fetch would return the prompt just released instead of the addressed one
+        // queued behind it, and the agent would never reach its own work. Holding them CLAIMED
+        // until the queue runs dry walks past them instead. The cost is a brief CLAIMED blip on
+        // someone else's prompt, and — if no other agent happens to be draining when the
+        // hand-back lands — that prompt waiting for the next `prompt:created` to be noticed.
+        if (exclusive && (p.agent_id ?? null) !== cfg.agentId) {
+          log(`prompt ${p.id} ${p.agent_id ? `is addressed to agent ${p.agent_id}` : 'is addressed to no agent'} — handing it back (--exclusive)`);
+          handBack.push(p.id);
+          continue;
+        }
         log(`prompt received: "${p.prompt}" (board=${p.board_id ?? cfg.boardId ?? 'n/a'}, priority=${p.priority})`);
         try {
           await runClaudeWarm(buildTurn(p));
@@ -1958,6 +2015,16 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
         }
       }
     } finally {
+      for (const id of handBack) {
+        try {
+          await releasePrompt(id);
+        } catch (err) {
+          // Left CLAIMED, which is worse for whoever sent it than a retry would be — but
+          // retrying here risks wedging the loop, and the next pass claims nothing new
+          // while this one is still unwinding. Say so and move on.
+          log(`handing prompt ${id} back failed, it stays CLAIMED: ${err.message}`);
+        }
+      }
       draining = false;
       // A prompt turn counts as activity: the board isn't idle just because nobody edited
       // it while the agent was busy answering someone.
@@ -2710,9 +2777,6 @@ credentialFlags(program
         process.exit(1);
       }
       if (!parsed.baseUrl) parsed.baseUrl = DEFAULT_BASE_URL;
-      // Preserved across re-configuration: the platform keys a board's alive-ping on it, so
-      // regenerating it would present a long-running agent as a brand-new one.
-      parsed.agentId = readJsonSafe(boardCredentialsPath(parsed.boardId)).agentId || randomUUID();
       writeBoardCredentials(parsed);
       console.log('\n  ✓ Saved credentials for board ' + parsed.boardId + ' to ' + boardCredentialsPath(parsed.boardId));
       console.log('\n  Start the agent from anywhere with:\n');
@@ -2803,10 +2867,11 @@ credentialFlags(program
   .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('--standalone', 'Let the modeling agent work the board in the background, on its own initiative: on top of direct prompts it subscribes to the board\'s change channel (like the build agents do) and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for. Changed nodes are a notification, not the task: it judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, specs for a new command or read model, a missing attribute along a chain, a screen, a question comment). Filling that detail in while the human keeps modeling is the point — it does not wait for the board to be finished. Implies --modeling.')
   .option('--max-agents <n>', 'Cap how many subagents a self-directed --standalone turn may dispatch at once, to bound what an unattended agent can spend per turn. The agent merges work that shares a slice or chain first, then takes the most valuable pieces up to this many and leaves the rest for a later turn. 1 makes it do the single most valuable piece itself, without spawning anything. Default 5. Ignored without --standalone — prompt turns are one piece of work by definition.', '5')
+  .option('--exclusive', 'Work only the prompts addressed to this agent\'s id — the board\'s "preferred agent" (the star in the prompts panel) — and hand every untargeted prompt straight back to the queue for another agent to take. Without it an agent also works everything nobody addressed to anyone, which is what you want for a single agent and exactly what you do not want for a dedicated one (a board with a general agent plus a specialist, or an agent a supervisor drives by id). Pair it with --id so the same agent is addressable across restarts — --global/--standalone otherwise mint a fresh id per run, and prompts addressed to the previous run\'s id are never claimed. Leaves --standalone alone: a self-directed turn is nobody\'s prompt, so an exclusive standalone agent still works the board on its own initiative.')
   .option('--global', 'Run the modeling agent from the global install (~/.eventmodelers/kit), initializing it on first use, and ignore any kit in this directory. This is also what --modeling/--standalone fall back to on their own when nothing is installed here — pass it explicitly to prefer the global install over a local one. Credentials come from the flags below, EVENTMODELERS_* env vars, or ~/.eventmodelers/boards/<board>.json, so nothing is written into the current directory.')
   .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
-  .option('--id <id>', 'Override the agent id this run identifies itself with on the platform, instead of the stable one minted once per project (per board for --global/--standalone) and reused on every restart. The heartbeat is keyed on (token, agent_id, agent_type), so this is what lets a second agent of the same type run side by side without the two overwriting each other\'s row — or pins one to an id a supervisor already knows. Per-run only: nothing is written to disk, so the next run without the flag is the original agent again.')
+  .option('--id <id>', 'Pin the agent id this run identifies itself with on the platform. A project install otherwise mints one id per project and reuses it on every restart; --global/--standalone mints a fresh one per run, since two ad-hoc agents for one board must not share a row (the heartbeat is keyed on token + agent_id + agent_type, so the second would replace the first). Pass this when an agent has to keep ONE identity across restarts — a supervisor that already knows the id, or a board where it is the starred "preferred agent". Per-run only: nothing is written to disk.')
   .option('--name <name>', 'A human-readable name for this agent, sent with every heartbeat so the board shows which agent is live rather than a bare uuid (e.g. "ci-builder", "martins-laptop"). Per-run only, like --id: the persistent name is `agentName` in config.json (set via `init --name` / `init-config --name`), and this overrides it for one run without writing anything.')
   .option('--credentials <values>', 'Credentials as the comma-separated blob from app.eventmodelers.ai/account (token=...,boardId=...,organizationId=...,baseUrl=...), the equivalent JSON, or - to read either from stdin. Saved to ~/.eventmodelers/boards/<board>.json, so it is only needed once per board, and passing it skips the first-run question. The individual flags below override single fields of it.'))
   .action(async (opts, command) => {
@@ -2819,6 +2884,11 @@ credentialFlags(program
     if (command.getOptionValueSource('maxAgents') === 'cli' && !opts.standalone) {
       console.log('ℹ️  --max-agents only applies to --standalone turns; ignoring it here.');
     }
+    // The build-kit runners claim their work from the same queue but have no addressee
+    // filter, so the flag would silently do nothing there rather than half of what it says.
+    if (opts.exclusive && !(opts.modeling || opts.standalone || opts.global)) {
+      console.log('ℹ️  --exclusive only applies to the modeling loop (--modeling/--standalone/--global); ignoring it here.');
+    }
     // --id/--name are what the platform will see for this run, so a blank one is a
     // mistake worth failing on rather than silently falling back to the stored identity.
     const identity = {
@@ -2899,7 +2969,7 @@ credentialFlags(program
       const shown = relative(cwd, kitDir);
       await new Promise((res) => process.stdout.write(`▶ Starting modeling loop (warm Claude process) for ${shown && !shown.startsWith('..') ? shown : kitDir}...\n\n`, res));
       try {
-        await runModeling(kitDir, projectDir, !!opts.verbose, !!opts.standalone, overrides, maxAgents, identity);
+        await runModeling(kitDir, projectDir, { verbose: !!opts.verbose, standalone: !!opts.standalone, exclusive: !!opts.exclusive, overrides, maxAgents, identity });
       } catch (err) {
         console.error('[modeling] Fatal:', err);
         process.exit(1);

package/package.json

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

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

@@ -860,6 +860,8 @@ Claim the next pending (`ADDED`) prompt for a board — atomically flips it to `
 
 Send `x-agent-id` here too: a prompt the user addressed to one preferred agent (`prompts.agent_id`) is only ever handed to the agent claiming with that id, and a caller without the header claims untargeted prompts only. Addressing one is `POST /api/org/:orgId/prompts` with `agent_id: "<uuid>"` — the board's prompts panel does it when someone stars an agent.
 
+Note what this endpoint does *not* do: an agent that sends its id still gets every untargeted prompt on top of its own. A caller that wants only what was addressed to it has to hand the rest back itself (`POST /prompts/:id/status` with `status: 'ADDED'`), which is what `eventmodelers run --exclusive` does.
+
 **Query params**: `board_id` (required)
 **Response**: `200` — the claimed row (now `status: "CLAIMED"`), including its parsed `context` and the `hidden` flag · `404` — no `ADDED` prompts available