@eventmodelers/cli 1.0.70 → 1.0.71

package/README.md

@@ -416,6 +416,18 @@ npx @eventmodelers/cli run --id <id>                           # pin ONE identit
 
 `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
+```
+
+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)
 
 Every config field can be set via an `EVENTMODELERS_*` env var instead of the interactive prompts — these always win over whatever's in `config.json`, so a fully env-driven install never prompts for credentials or Claude execution settings:

package/cli.js

@@ -1672,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\`.`);
@@ -1710,6 +1716,12 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     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;
 
@@ -1928,6 +1940,13 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
       ? `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() {
@@ -1947,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));
@@ -1964,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.
@@ -2806,6 +2867,7 @@ 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.')
@@ -2822,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 = {
@@ -2902,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.70",
+  "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