@chorus-aidlc/chorus 0.16.1 → 0.16.3

package/cli/event-router.mjs

@@ -37,8 +37,8 @@ export class EventRouter {
   /**
    * @param {{
    *   mcpClient: { callTool: (name: string, args?: Record<string, unknown>) => Promise<any> },
-   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wake: (n: any, key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
-   *   queue: { enqueue: (key: string, task: () => Promise<void>) => void },
+   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wakeBatch: (ns: any[], key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
+   *   queue: { enqueue: (key: string, item: { notification: any, attribution: any }) => void },
    *   wakeActions: Set<string>,
    *   getConnectionUuid?: () => (string|null),  This daemon's registered connection uuid
    *                                             (null until the SSE handshake reports it).
@@ -228,7 +228,8 @@ export class EventRouter {
    * reason ("user" | "crash") threaded from the control event; it is stamped on the
    * synthetic notification as `resumedFrom` so the prompt builder can state a crash
    * explicitly. Absent/unknown → not stamped → the user-resume prompt.
-   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string }} target
+   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string,
+   *   orchestrator?: { type?: string, uuid?: string, name?: string } | null }} target
    */
   dispatchResume(target) {
     const entityType = target?.entityType;
@@ -247,6 +248,11 @@ export class EventRouter {
       entityUuid,
       ...(resumedFrom ? { resumedFrom } : {}),
       ...(typeof target?.runtimeCwd === "string" ? { runtimeCwd: target.runtimeCwd } : {}),
+      ...(target?.orchestrator?.type === "agent" &&
+      typeof target.orchestrator.uuid === "string" &&
+      typeof target.orchestrator.name === "string"
+        ? { orchestrator: target.orchestrator }
+        : {}),
     };
     this.#resolveAndEnqueue(n, `resume:${entityType}:${entityUuid}`).catch((err) => {
       this.logger.error(`[Chorus] failed to dispatch resume for ${entityType}:${entityUuid}: ${err}`);
@@ -383,7 +389,10 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for pending turn ${turnUuid}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 
   /**
@@ -531,6 +540,9 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for ${label}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 }

package/cli/prompts.mjs

@@ -25,6 +25,7 @@
  * @property {string} actorType
  * @property {string} actorUuid
  * @property {string} actorName
+ * @property {{type: string, uuid: string, name: string} | null} [orchestrator]
  * @property {string} [instructionText]  Free-text body of a `human_instruction` wake
  *   (子1 — daemon-session-conversation). The server denormalizes the canonical turn
  *   promptText onto the wake notification so the daemon reads it in the
@@ -40,6 +41,29 @@ function mentionGuidance(n, entityType) {
   );
 }
 
+/**
+ * Orchestrator-handoff guidance, appended to every wake body by buildPrompt. This is
+ * the SINGLE home of the "hand back to the agent that dispatched you" instruction —
+ * it is runtime PE (it depends on who the wake resolved as orchestrator), so it lives
+ * here in the wake prompt, NOT in the static skill docs. Its OpenClaw twin is
+ * `buildOrchestratorGuidance` in packages/openclaw-plugin/src/event-router.ts —
+ * KEEP THE TWO WORDINGS IN SYNC.
+ * Returns null unless the resource has an AGENT orchestrator; a human-assigned
+ * resource hands back to the human via the per-event actor @mention (mentionGuidance).
+ * @param {NotificationDetail} n
+ */
+function orchestratorGuidance(n) {
+  if (n.orchestrator?.type !== "agent") return null;
+  return (
+    `Your orchestrator for this resource is @${n.orchestrator.name}.\n` +
+    `At a human-only gate you cannot cross, or when this child resource is complete, hand control ` +
+    `back by commenting on the resource and mentioning ` +
+    `@[${n.orchestrator.name}](agent:${n.orchestrator.uuid}) with the decision needed or completion ` +
+    `evidence, then leave any human-gated resource pending and end the turn. Do not @mention the ` +
+    `orchestrator for ordinary internal progress.`
+  );
+}
+
 /**
  * Shared headless preamble prepended to EVERY wake prompt (add-daemon-headless-
  * interaction-guard). A daemon-woken session is a headless `claude -p` run with no
@@ -96,7 +120,98 @@ export const HEADLESS_PREAMBLE = [
 export function buildPrompt(n) {
   const body = buildPromptBody(n);
   if (body == null) return null;
-  return `${HEADLESS_PREAMBLE}\n\n${body}`;
+  const handoff = orchestratorGuidance(n);
+  return `${HEADLESS_PREAMBLE}\n\n${body}${handoff ? `\n\n${handoff}` : ""}`;
+}
+
+/**
+ * Build ONE combined wake prompt for a coalesced batch of same-session notifications
+ * (add-daemon-wake-coalescing, tech design §C2). The daemon serializes wakes per session
+ * key; while a turn runs, later same-key wakes pile up and — when the slot frees — are
+ * drained together into a single `claude --resume` turn. This composes their one prompt.
+ *
+ * Rules:
+ *  - **Size 1** → delegate to `buildPrompt(n)` verbatim, so the single-event path is
+ *    BYTE-IDENTICAL to today (and all current prompt tests keep passing). This is keyed on
+ *    the count of RENDERABLE events (non-null body): a batch that reduces to a single
+ *    renderable event — e.g. a real wake plus an empty `human_instruction` — also takes
+ *    the single-event path.
+ *  - **Size > 1 renderable** → `HEADLESS_PREAMBLE` ONCE (it is a per-turn guard, paid once
+ *    per turn, not per event), then a short backlog preamble, then one labeled block per
+ *    event in ARRIVAL order, each block being the reused per-action `buildPromptBody(n)` so
+ *    every event keeps its own tool hints and @mention guidance.
+ *  - **Same-entity collapse (Q2)**: events sharing `(action, entityUuid)` collapse into one
+ *    block at the group's FIRST-SEEN position, noting the occurrence count and showing the
+ *    NEWEST message. This is safe only because such actions' full content is re-derivable
+ *    server-side (comments via chorus_get_comments, task lifecycle via chorus_get_*).
+ *  - **`human_instruction` is NEVER collapsed (Q3, Round-1 BLOCKER-2)**: every queued chat
+ *    message carries `action=human_instruction` and `entityUuid=directIdeaUuid`, and its
+ *    text lives ONLY on the turn/notification (not re-fetchable), so collapsing to
+ *    newest-only would silently drop earlier chat and defeat the feature. Each renders its
+ *    full body as its own block, in arrival order.
+ *  - Events whose body is null (empty `human_instruction`, non-wake action) are omitted; a
+ *    batch with no renderable event returns null (the router then spawns nothing).
+ *
+ * @param {NotificationDetail[]} notifications  Arrival-ordered batch (FIFO drain order).
+ * @returns {string | null}
+ */
+export function buildBatchPrompt(notifications) {
+  if (!Array.isArray(notifications) || notifications.length === 0) return null;
+
+  // Keep only events with a renderable per-action body, in arrival order.
+  const items = [];
+  for (const n of notifications) {
+    const body = buildPromptBody(n);
+    if (body != null) items.push({ n, body });
+  }
+  if (items.length === 0) return null;
+  // One renderable event → byte-identical single-event prompt (delegates to buildPrompt so
+  // the exact "PREAMBLE\n\nbody" shape is preserved). Covers a true batch of size 1 and a
+  // batch that reduced to one renderable event after null-body events were dropped.
+  if (items.length === 1) return buildPrompt(items[0].n);
+
+  // Group into ordered blocks. Collapsible actions merge by (action, entityUuid) at their
+  // first-seen slot; human_instruction is exempt and always gets its own block.
+  const blocks = [];
+  const collapseIndex = new Map(); // "action::entityUuid" -> index into `blocks`
+  for (const { n, body } of items) {
+    if (n.action === "human_instruction") {
+      blocks.push({ notif: n, body, count: 1 });
+      continue;
+    }
+    const groupKey = `${n.action}::${n.entityUuid ?? ""}`;
+    const existing = collapseIndex.get(groupKey);
+    if (existing != null) {
+      const g = blocks[existing];
+      g.count += 1;
+      g.notif = n; // newest wins (arrival order → last member is newest)
+      g.body = body; // newest body
+    } else {
+      collapseIndex.set(groupKey, blocks.length);
+      blocks.push({ notif: n, body, count: 1 });
+    }
+  }
+
+  // Backlog preamble. N = number of renderable events that arrived (not the collapsed block
+  // count) — collapse is a rendering optimization; each collapsed block states its own count.
+  const backlogPreamble =
+    `You have ${items.length} queued Chorus events on this session that arrived while you ` +
+    `were busy — handle them together, in order; each is labeled with its type below.`;
+
+  const rendered = blocks.map((g, idx) => {
+    const n = g.notif;
+    const entityType = n.entityType || "session";
+    const entityUuid = n.entityUuid || "";
+    const header = `### Event ${idx + 1} — ${n.action} on ${entityType} ${entityUuid}`.replace(/\s+$/, "");
+    const collapseNote =
+      g.count > 1
+        ? `\n(${g.count} ${n.action} events on this ${entityType} arrived — showing the newest ` +
+          `below; earlier ones are re-derivable via the entity's own chorus_get_* tools.)`
+        : "";
+    return `${header}${collapseNote}\n\n${g.body}`;
+  });
+
+  return [HEADLESS_PREAMBLE, backlogPreamble, ...rendered].join("\n\n");
 }
 
 /**
@@ -205,10 +320,20 @@ function buildPromptBody(n) {
       );
     }
     case "idea_claimed":
+      // The assignment ALREADY set you as the assignee, so there is nothing to claim —
+      // chorus_claim_idea would throw (AlreadyClaimedError, and a hard "Cannot claim an
+      // elaborated Idea" for the elaborated-backfill case). Do NOT emit a claim
+      // instruction here (a prompt test asserts the literal never appears). Instead tell
+      // the already-assigned agent to review and advance from the idea's CURRENT stage,
+      // stopping at the human proposal/verify gates. Names the assigner via n.actorName /
+      // n.actorType (already on the notification — no server change). Mirrored in the
+      // OpenClaw twin handleIdeaClaimed (event-router.ts) — KEEP THE TWO WORDINGS IN SYNC.
       return (
-        `[Chorus] Idea '${n.entityTitle}' was assigned to you (ideaUuid: ${n.entityUuid}, ` +
-        `projectUuid: ${n.projectUuid}). Use chorus_get_idea to review it, then claim it ` +
-        `(chorus_claim_idea) to begin elaboration.\n${mentionGuidance(n, "idea")}`
+        `[Chorus] Idea '${n.entityTitle}' was assigned to you by ${n.actorName} (${n.actorType}) ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). You are now the assignee — no need ` +
+        `to claim it. Use chorus_get_idea to review it, then advance it from its CURRENT stage: if it is ` +
+        `still elaborating, run or continue elaboration; if it is already elaborated, author the proposal. ` +
+        `Stop at the human proposal/verify gates and never merge automatically.\n${mentionGuidance(n, "idea")}`
       );
     case "task_reopened":
       return (

package/cli/turn-reporter.mjs

@@ -52,7 +52,7 @@ export const TURN_INTERRUPT_REASONS = new Set([
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  *   fetchImpl?: typeof fetch,             Injectable for tests.
  * }} opts
- * @returns {(params: { sessionId: string, status: "running"|"ended"|"interrupted", entityType?: string|null, entityUuid?: string|null, interruptedReason?: "user"|"crash"|"shutdown"|"invalid_path"|null, transcriptRelayError?: string|null, usage?: import("./upload-hooks.mjs").TokenUsage|null }) => Promise<void>}
+ * @returns {(params: { sessionId: string, status: "running"|"ended"|"interrupted", entityType?: string|null, entityUuid?: string|null, interruptedReason?: "user"|"crash"|"shutdown"|"invalid_path"|null, transcriptRelayError?: string|null, usage?: import("./upload-hooks.mjs").TokenUsage|null, coalescedCount?: number }) => Promise<void>}
  */
 export function createTurnReporter(opts) {
   const logger = opts.logger ?? NOOP_LOGGER;
@@ -76,6 +76,7 @@ export function createTurnReporter(opts) {
     transcriptRelayError,
     usage,
     backendSessionId,
+    coalescedCount,
   }) {
     if (typeof sessionId !== "string" || !sessionId || !TURN_STATUSES.has(status)) {
       logger.warn(
@@ -111,6 +112,9 @@ export function createTurnReporter(opts) {
       // only on a terminal edge. No validation here — usage is an opaque nested object.
       usage,
       backendSessionId,
+      // Coalesced-wake count (add-daemon-wake-coalescing): threaded straight through; the
+      // client sends it only on the → running edge and only when > 1 (a single wake omits it).
+      coalescedCount,
     });
   };
 }

package/cli/wake-queue.mjs

@@ -1,14 +1,22 @@
 // cli/wake-queue.mjs
-// Per-key FIFO scheduler with a global concurrency cap. This is what makes the
-// idea_root session anchor safe (cli-daemon spec "Per-root-idea wake
-// serialization", design.md "Concurrency model"):
-//   • within one key (root idea) → strictly serial, FIFO. The 2nd wake waits
-//     for the 1st subprocess to exit, so we never run two
+// Per-key FIFO scheduler with a global concurrency cap, coalescing same-key
+// wakes into batches. This is what makes the idea_root session anchor safe
+// (cli-daemon spec "Per-root-idea wake serialization", design.md "Concurrency
+// model") AND implements daemon-wake-coalescing (design.md §C1):
+//   • within one key (root idea) → strictly serial, FIFO. The next batch waits
+//     for the current runBatch to settle, so we never run two
 //     `claude --resume <sameSessionId>` against one session.
+//   • coalescing: when a key's slot frees, the ENTIRE pending array for that key
+//     is drained (splice) and delivered to runBatch ONCE as a single batch. So
+//     N events that pile up while the previous turn runs become ONE turn.
+//     Natural batching only — NO debounce/collect timer, NO batch-size cap.
 //   • across keys → concurrent, bounded by maxConcurrency.
 //   • enqueue() returns immediately — never blocks the SSE loop.
-//   • a task that throws is logged and the next task for that key proceeds (a
-//     poisoned wake must not wedge the key's queue forever).
+//   • a batch whose runBatch throws is logged and the next batch for that key
+//     proceeds (a poisoned wake must not wedge the key's queue forever).
+// The queue carries opaque DATA items (the router passes `{ notification,
+// attribution }`); it never introspects them — the runBatch callback (supplied
+// at construction, wired to waker.wakeBatch in daemon.mjs) does.
 // Plain ESM, zero deps, in-memory.
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
@@ -18,41 +26,49 @@ export class WakeQueue {
    * @param {{
    *   maxConcurrency?: number,
    *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+   *   runBatch?: (key: string, items: any[]) => Promise<void>,
    * }} [opts]
    */
   constructor(opts = {}) {
     this.maxConcurrency = opts.maxConcurrency ?? 4;
     this.logger = opts.logger ?? NOOP_LOGGER;
-    /** @type {Map<string, Array<() => Promise<void>>>} pending tasks per key. */
+    // The batch runner: called ONCE per drained batch with every pending item
+    // for the key. Defaults to a no-op so an unwired queue never throws (the
+    // daemon always supplies the real waker.wakeBatch runner).
+    this.runBatch = opts.runBatch ?? (async () => {});
+    /** @type {Map<string, any[]>} pending data items per key. */
     this.pending = new Map();
-    /** @type {Set<string>} keys with a task currently running. */
+    /** @type {Set<string>} keys with a batch currently running. */
     this.running = new Set();
     /** @type {string[]} keys waiting for a global concurrency slot. */
     this.readyKeys = [];
     this.activeCount = 0;
-    // Graceful-shutdown latch: once set, #pump starts NOTHING new — in-flight tasks
-    // finish (drain observes them) but queued work stays queued and dies with the
-    // process. Never cleared; a stopping queue is on its way out.
+    // Graceful-shutdown latch: once set, #pump starts NOTHING new — in-flight
+    // batches finish (drain observes them) but queued work stays queued and dies
+    // with the process. Never cleared; a stopping queue is on its way out.
     this.stopped = false;
   }
 
-  /** Stop starting new tasks (graceful shutdown). In-flight tasks are unaffected. */
+  /** Stop starting new batches (graceful shutdown). In-flight batches are unaffected. */
   stop() {
     this.stopped = true;
   }
 
   /**
-   * Enqueue a wake task under a key. Returns immediately. The task is a thunk
-   * returning a promise (the actual wake). Same key → serialized; different
-   * keys → concurrent up to maxConcurrency.
+   * Enqueue an opaque data item under a key. Returns immediately. Items on the
+   * same key coalesce: while a key's batch runs, later items pile up and are
+   * drained together as ONE batch when the slot frees. Different keys run
+   * concurrently up to maxConcurrency.
    * @param {string} key
-   * @param {() => Promise<void>} task
+   * @param {any} item  opaque data (e.g. `{ notification, attribution }`)
    */
-  enqueue(key, task) {
+  enqueue(key, item) {
     if (!this.pending.has(key)) this.pending.set(key, []);
-    this.pending.get(key).push(task);
+    this.pending.get(key).push(item);
     // A key becomes "ready" to claim a global slot only when it's not already
-    // running (serial-per-key) and not already queued for a slot.
+    // running (serial-per-key) and not already queued for a slot. While it IS
+    // running, later items simply accumulate in `pending` and are picked up by
+    // the next batch — this is where coalescing happens.
     if (!this.running.has(key) && !this.readyKeys.includes(key)) {
       this.readyKeys.push(key);
     }
@@ -65,7 +81,7 @@ export class WakeQueue {
   }
 
   /**
-   * Snapshot of the keys with a task currently running (observability read).
+   * Snapshot of the keys with a batch currently running (observability read).
    * Returns a fresh array so a caller can't mutate the internal Set.
    * @returns {string[]}
    */
@@ -74,7 +90,7 @@ export class WakeQueue {
   }
 
   /**
-   * Snapshot of the keys that have at least one task still waiting to run —
+   * Snapshot of the keys that have at least one item still waiting to run —
    * i.e. enqueued but not yet started (observability read). A key that is
    * currently running with no further queued work is NOT pending. Returns a
    * fresh array so a caller can't mutate internal state.
@@ -85,13 +101,13 @@ export class WakeQueue {
   }
 
   /**
-   * Wait (bounded) for every in-flight task to finish — the graceful-shutdown drain
+   * Wait (bounded) for every in-flight batch to finish — the graceful-shutdown drain
    * (fix-daemon-exit-orphan-running-turn). Resolves `true` when the queue went idle
-   * (no active task) within `timeoutMs`, `false` on timeout — the caller exits
+   * (no active batch) within `timeoutMs`, `false` on timeout — the caller exits
    * anyway and leaves the rest to the server-side reconcile backstop. Pending
-   * (not-yet-started) tasks are NOT waited for: a shutting-down daemon stops
+   * (not-yet-started) items are NOT waited for: a shutting-down daemon stops
    * starting new work, so only the in-flight subprocesses (and their exit reports)
-   * matter. Polling (50ms) keeps this zero-dep and independent of task internals.
+   * matter. Polling (50ms) keeps this zero-dep and independent of batch internals.
    * @param {number} timeoutMs
    * @returns {Promise<boolean>}
    */
@@ -112,33 +128,39 @@ export class WakeQueue {
       if (this.running.has(key)) continue; // already running under another slot
       const queue = this.pending.get(key);
       if (!queue || queue.length === 0) continue;
-      this.#runNext(key);
+      this.#startBatch(key);
     }
   }
 
-  /** Run the next task for a key, then chain to the following one. */
-  #runNext(key) {
+  /**
+   * Drain the ENTIRE pending array for a key into one batch and run it, then
+   * chain to the following batch. No batch-size cap (design.md §C1, Q7).
+   */
+  #startBatch(key) {
     const queue = this.pending.get(key);
     if (!queue || queue.length === 0) {
       this.running.delete(key);
       return;
     }
-    const task = queue.shift();
+    // Coalesce: take everything pending for this key right now as one batch.
+    // Items that arrive after this splice accumulate for the NEXT batch.
+    const items = queue.splice(0);
     this.running.add(key);
     this.activeCount++;
 
     Promise.resolve()
-      .then(task)
+      .then(() => this.runBatch(key, items))
       .catch((err) => {
-        // Poisoned wake: log, do NOT let it wedge the key's queue.
-        this.logger.warn(`[Chorus] wake task for ${key} failed: ${err}`);
+        // Poisoned batch: log, do NOT let it wedge the key's queue.
+        this.logger.warn(`[Chorus] wake batch for ${key} failed: ${err}`);
       })
       .finally(() => {
         this.activeCount--;
         const remaining = this.pending.get(key);
         if (remaining && remaining.length > 0) {
-          // Same key still has work → it must run serially. Re-mark ready;
-          // #pump will pick it up (respecting the global cap).
+          // Same key accumulated more work while this batch ran → it must run
+          // serially as the next batch. Re-mark ready; #pump will pick it up
+          // (respecting the global cap).
           if (!this.readyKeys.includes(key)) this.readyKeys.push(key);
           this.running.delete(key); // free the key so #pump can re-claim it
         } else {