@chorus-aidlc/chorus 0.19.0 → 0.20.0

package/cli/event-router.mjs

@@ -8,6 +8,8 @@
 // action, resolve the root-idea key and enqueue the wake. Never throws into the
 // SSE loop.
 
+import { OPERATION_ACTIONS, validateOperation } from "./operation.mjs";
+
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
 // Map a Notification.action to its DaemonSessionTurn trigger category — the daemon-side
@@ -70,6 +72,9 @@ export class EventRouter {
     // dispatch time (before any async work) so concurrent dispatches for the
     // same uuid collapse to one wake.
     this.seen = opts.seen ?? new Set();
+    this.validatingOperations = new Set();
+    this.pendingDispatchCount = 0;
+    this.pendingDispatch = Promise.resolve();
   }
 
   /**
@@ -150,9 +155,9 @@ export class EventRouter {
     // (`notificationUuid` vs `turn:{uuid}`) — the double-execution bug — and would fan the
     // wake out to EVERY connection of the agent rather than the session's origin. So the
     // notification path explicitly defers `human_instruction` to the turn-keyed paths.
-    if (n.action === "human_instruction") {
+    if (n.action === "human_instruction" || OPERATION_ACTIONS.has(n.action)) {
       this.logger.info(
-        `[Chorus] human_instruction ${notificationUuid} is delivered via deliver_turn / pending-turn backfill — not the notification path; ignoring here`
+        `[Chorus] ${n.action} ${notificationUuid} is delivered via deliver_turn / pending-turn backfill — not the notification path; ignoring here`
       );
       return;
     }
@@ -293,6 +298,20 @@ export class EventRouter {
    *           trigger?: string, promptText?: string|null }} pending
    */
   dispatchPendingTurn(pending) {
+    // Creation identity reads are async. Keep subsequent turn deliveries behind
+    // them so validation cannot reorder the session's ordinary/operation FIFO.
+    if (OPERATION_ACTIONS.has(pending?.trigger) || this.pendingDispatchCount > 0) {
+      this.pendingDispatchCount++;
+      this.pendingDispatch = this.pendingDispatch
+        .then(() => this.#dispatchPendingTurnNow(pending))
+        .catch((err) => this.logger.warn(`[Chorus] pending-turn dispatch failed: ${err}`))
+        .finally(() => { this.pendingDispatchCount--; });
+      return this.pendingDispatch;
+    }
+    return this.#dispatchPendingTurnNow(pending);
+  }
+
+  #dispatchPendingTurnNow(pending) {
     const turnUuid = pending?.turnUuid;
     const sessionId = pending?.sessionId;
     if (typeof turnUuid !== "string" || !turnUuid) {
@@ -303,6 +322,9 @@ export class EventRouter {
       this.logger.warn(`[Chorus] pending-turn ${turnUuid} missing sessionId, skipping`);
       return;
     }
+    if (OPERATION_ACTIONS.has(pending.trigger)) {
+      return this.#dispatchOperation(pending);
+    }
     // A DIRECTED autonomous turn (mentioned / task_assigned / elaboration_verified /
     // start_development / yolo_requested) is delivered by the deliver_turn ping too (T2).
     // Its prompt must be rebuilt from the notification (promptText is null), so it takes a
@@ -377,6 +399,8 @@ export class EventRouter {
       entityType: directIdeaUuid ? "idea" : "daemon_session",
       entityUuid: directIdeaUuid ? directIdeaUuid : sessionId,
       instructionText: instruction,
+      // Research must retain its exact turn for admission immediately before spawn.
+      ...(instruction.startsWith("[Chorus Tracker Research]") ? { turnUuid, researchOnly: true } : {}),
       ...(typeof pending.runtimeCwd === "string" ? { runtimeCwd: pending.runtimeCwd } : {}),
     };
     const key = directIdeaUuid ? `idea:${directIdeaUuid}` : `entity:daemon_session:${sessionId}`;
@@ -392,7 +416,45 @@ export class EventRouter {
     // 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 });
+    this.queue.enqueue(key, {
+      notification: n, attribution,
+      ...(n.researchOnly ? { isolated: true } : {}),
+    });
+  }
+
+  async #dispatchOperation(pending) {
+    const seenKey = `turn:${pending.turnUuid}`;
+    if (this.seen.has(seenKey) || this.validatingOperations.has(seenKey)) return;
+    this.validatingOperations.add(seenKey);
+    try {
+      const payload = { ...validateOperation(pending.trigger, pending.operationPayload, pending) };
+      // Pending DTOs carry the session's Idea anchor but no authoritative project.
+      // Read the Idea for creation before trusting the payload's project identity.
+      if (payload.kind === "idea_creation") {
+        const idea = await this.mcp.callTool("chorus_get_idea", { ideaUuid: pending.directIdeaUuid });
+        if (idea?.uuid !== pending.directIdeaUuid || idea?.project?.uuid !== payload.projectUuid) {
+          throw new Error("Operation protocol error: creation project does not match its Idea");
+        }
+      }
+      const n = {
+        action: pending.trigger, turnUuid: pending.turnUuid,
+        sessionId: pending.sessionId, directIdeaUuid: pending.directIdeaUuid,
+        entityType: "idea", entityUuid: pending.directIdeaUuid,
+        operationPayload: payload, promptText: pending.promptText,
+        ...(payload.kind === "idea_creation" ? { projectUuid: payload.projectUuid } : {}),
+        ...(typeof pending.runtimeCwd === "string" ? { runtimeCwd: pending.runtimeCwd } : {}),
+      };
+      const key = `idea:${pending.directIdeaUuid}`;
+      const attribution = { key, rootIdeaUuid: pending.directIdeaUuid, directIdeaUuid: pending.directIdeaUuid };
+      this.queue.enqueue(key, { notification: n, attribution, isolated: true });
+      this.seen.add(seenKey); // Only accepted, valid queue entries own dedup.
+      try { this.waker.markQueued?.(n, key, attribution); }
+      catch (err) { this.logger.warn(`[Chorus] markQueued failed for ${pending.turnUuid}: ${err}`); }
+    } catch (err) {
+      this.logger.warn(`[Chorus] operation turn ${pending.turnUuid} remains pending and retryable: ${err}`);
+    } finally {
+      this.validatingOperations.delete(seenKey);
+    }
   }
 
   /**

package/cli/init/adapters.mjs

@@ -64,8 +64,8 @@ function readJsonSafe(path) {
  * @param {{ home?: string, readJson?: (p: string) => any }} [deps]
  * @returns {{ marketplaceRegistered: boolean, pluginInstalled: boolean, version?: string }}
  */
-export function readClaudeInstallState({ home = homedir(), readJson = readJsonSafe } = {}) {
-  const pluginsDir = join(home, ".claude", "plugins");
+export function readClaudeInstallState({ env = process.env, home = env.HOME || env.USERPROFILE || homedir(), readJson = readJsonSafe } = {}) {
+  const pluginsDir = join(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), "plugins");
   const installed = readJson(join(pluginsDir, "installed_plugins.json"));
   const markets = readJson(join(pluginsDir, "known_marketplaces.json"));
 

package/cli/init/file-template.mjs

@@ -136,6 +136,7 @@ export function mergeChorusServer(existingText, serverObj) {
  *   backup?: (path: string) => (string|null),
  *   platform?: NodeJS.Platform,
  *   log?: (m: string) => void,
+ *   preserveExistingChorus?: boolean,
  * }} opts
  * @returns {Promise<{ skills: number, reviewerAgents: number, hookScripts: number, kiroDir: string, chorusBinAbs: string }>}
  */
@@ -146,6 +147,7 @@ export async function installFileTemplate({
   backup,
   platform = process.platform,
   log,
+  preserveExistingChorus = false,
 } = {}) {
   const assetBase = normalizeAssetBase(chorusUrl); // throws on bad/empty URL
   const doFetch = fetchImpl ?? globalThis.fetch;
@@ -216,6 +218,14 @@ export async function installFileTemplate({
   }
   serverObj.url = `${assetBase}/api/mcp`;
 
+  // Validate the destination before dropping any assets. Upgrade preserves an
+  // existing Chorus connection too; changing credentials is an agents-add action.
+  const mcpJsonPath = join(kiroDir, "settings", "mcp.json");
+  const existed = existsSync(mcpJsonPath);
+  const existingText = existed ? readFileSync(mcpJsonPath, "utf8") : "";
+  const existingServer = existingText.trim() ? JSON.parse(existingText)?.mcpServers?.chorus : undefined;
+  const merged = mergeChorusServer(existingText, preserveExistingChorus && existingServer ? existingServer : serverObj);
+
   // ---- phase 2: write to disk (every fetch already verified) ----
   for (const [dest, { text, exec }] of files) {
     mkdirSync(dirname(dest), { recursive: true });
@@ -230,12 +240,9 @@ export async function installFileTemplate({
   }
 
   // ---- merge the `chorus` MCP server into settings/mcp.json (back up first) ----
-  const mcpJsonPath = join(kiroDir, "settings", "mcp.json");
   mkdirSync(dirname(mcpJsonPath), { recursive: true });
-  const existed = existsSync(mcpJsonPath);
   if (existed && typeof backup === "function") backup(mcpJsonPath);
-  const existingText = existed ? readFileSync(mcpJsonPath, "utf8") : "";
-  writeFileSync(mcpJsonPath, mergeChorusServer(existingText, serverObj));
+  writeFileSync(mcpJsonPath, merged);
 
   log?.(`[chorus agents add] kiro: wrote .kiro/ template into ${kiroDir}`);
   return {

package/cli/init/install-methods.mjs

@@ -135,7 +135,7 @@ export function installCodex(ctx) {
   // (agents[0]) — that covers the interactive path where the operator typed the URL at a
   // prompt (credential-seed, order 10, already wrote it there before this step runs).
   let chorusUrl = nonEmpty(ctx.flags?.url) ?? nonEmpty(env.CHORUS_URL);
-  if (!chorusUrl) {
+  if (!chorusUrl && !ctx.flags?.pluginOnly) {
     try {
       chorusUrl = nonEmpty(resolveCreds(ctx.flags ?? {}, { env }).url);
     } catch {
@@ -147,6 +147,7 @@ export function installCodex(ctx) {
   // form. Idempotent; runs on both fresh install and re-run. Never writes a secret. A missing
   // URL is a non-fatal skip (the plugin surface is still installed). Returns a note suffix.
   const ensureMcp = () => {
+    if (ctx.flags?.pluginOnly) return ""; // Upgrade preserves existing connection settings.
     if (!chorusUrl) {
       return " (skipped [mcp_servers.chorus]: no Chorus URL — pass --url or set CHORUS_URL)";
     }
@@ -648,6 +649,7 @@ export async function installKiro(ctx) {
       backup: ctx.backup,
       platform: ctx.platform,
       log: ctx.io?.log,
+      preserveExistingChorus: ctx.flags?.pluginOnly === true,
     });
     return out(
       "kiro",

package/cli/operation-contract.mjs

@@ -0,0 +1,3 @@
+// Shared wire constraints; this dependency-free module is shipped with the CLI.
+export const CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS = 3000;
+export const RESEARCH_INSTRUCTION_PREFIX = "[Chorus Tracker Research]";

package/cli/operation-prompts.mjs

@@ -0,0 +1,99 @@
+// Shared by the server compatibility snapshot and payload-driven CLI execution.
+// Keep historical entry prefixes: older clients use the Research prefix for isolation.
+import { RESEARCH_INSTRUCTION_PREFIX } from "./operation-contract.mjs";
+
+const PROJECT_INSTRUCTION_LABEL_MAX_CHARS = 200;
+
+/**
+ * Compose the conversational-idea wake instruction (template v2 — the REVIEWED CONTRACT
+ * between the conversational create-idea entry and the woken daemon agent, superseding
+ * the client-side create→claim template of add-conversational-idea-entry).
+ *
+ * The idea is PRE-CREATED and already instance-assigned + elaborating, so both templates
+ * direct EDIT (never create, never claim — a claim would fail on the existing assignee).
+ *  - `elaborate` (default): edit → optional research → elaboration → panel guidance → end turn.
+ *  - `decompose`: edit the CONTAINER → keep isContainer → one lightweight scope-clarifying
+ *    elaboration → propose candidate CHILDREN as a structured elaboration round (one
+ *    single-select question per child, ≤15/round, never a multi-select) → end turn → on the
+ *    confirm re-wake create each accepted child via chorus_pm_create_idea with
+ *    parentUuid=<container>, children starting `open`, no auto-elaboration; the container's
+ *    own status stays `elaborated`. The confirm re-wake rides the EXISTING
+ *    `elaboration_answered` wake — no new wake/notification action is introduced.
+ *
+ * English (agent-facing, matching cli/prompts.mjs precedent); the user's description
+ * passes through VERBATIM under the delimiter. Exported for unit tests: the template's
+ * wording is code, and any change is a review-visible diff.
+ * @param {{ideaUuid: string, projectUuid: string, projectName?: string|null,
+ *   descriptionText: string, mode?: 'elaborate'|'decompose', researchFirst?: boolean}} params
+ */
+export function composeConversationalIdeaInstruction(params) {
+  // Name is display sugar; bound this user-controlled metadata independently of
+  // the description. The complete UUID remains the authoritative machine anchor.
+  const projectName = params.projectName?.trim();
+  const displayName = projectName && projectName.length > PROJECT_INSTRUCTION_LABEL_MAX_CHARS
+    ? `${projectName.slice(0, PROJECT_INSTRUCTION_LABEL_MAX_CHARS - 1)}…`
+    : projectName;
+  const projectLabel = displayName
+    ? `"${displayName}" (projectUuid: ${params.projectUuid})`
+    : `projectUuid: ${params.projectUuid}`;
+
+  const researchInstruction = [
+    params.researchFirst
+      ? "The user explicitly requested lightweight research before clarification."
+      : "Research is optional: use automatic judgment for a concrete, externally verifiable factual gap.",
+    "An explicit request to skip research in the user's instructions takes precedence.",
+    "Follow the shared research skill before the first formal elaboration: one bounded pass, approximately 2–5 minutes, at most 5 deeply read relevant sources; reuse existing evidence.",
+    "Save useful findings in the existing Idea content, preserving the user's meaning, and attach evidence with real ref:UUID citations. Do not create or claim this already-created Idea.",
+    "If tools are unavailable, results are empty, or the budget is exhausted, record the limitation and continue the normal steps in this turn. Do not research user preferences; ask through the elaboration panel when needed.",
+    "This initialization request applies once, not on every later wake or stage re-entry.",
+  ].join(" ");
+
+  if (params.mode === "decompose") {
+    return [
+      `[Chorus container-decompose entry] A new CONTAINER idea has been PRE-CREATED for project ${projectLabel} from the user's description below, and it is already assigned to you (status: elaborating, isContainer: true).`,
+      `  ideaUuid: ${params.ideaUuid}`,
+      ``,
+      `This conversation IS that container idea's root session. The user wants help DECOMPOSING it into child ideas. Do the following, in order:`,
+      `1. Edit the container via chorus_edit_idea: derive a concise title from the description and polish the content (keep the user's meaning). The current title is a placeholder.`,
+      `2. Ensure it stays a container: it was pre-created with isContainer=true — do NOT clear that flag (a container groups its child ideas and MUST NOT get a proposal of its own).`,
+      `Before step 3: ${researchInstruction}`,
+      `3. Run ONE lightweight elaboration round (chorus_pm_start_elaboration) to clarify the decomposition scope/dimension — how to slice the work into children. Keep it short; you may self-answer in headless or ask the user, then continue.`,
+      `4. Propose the candidate child ideas AS A STRUCTURED ELABORATION ROUND (chorus_pm_start_elaboration) for the user to review/edit/confirm — use ONE elaboration question PER proposed child (the child's title as the question text, a short rationale as its description), single-select. Elaboration questions are single-select and a round is capped at 15 questions, so propose at most 15 candidates per round and NEVER a single multi-select question; if you need more children, propose them across additional rounds. Do NOT create any child ideas yet — this round is the preview the user accepts/edits/declines per child.`,
+      `5. End the turn. The user's answers in the idea's elaboration panel will wake this same conversation (the existing elaboration-answered wake).`,
+      `6. On that re-wake, create each ACCEPTED child via chorus_pm_create_idea with parentUuid=${params.ideaUuid}. Each child starts in the "open" state — do NOT auto-elaborate them. The container's OWN status stays "elaborated"; creating children does not advance or alter it.`,
+      ``,
+      `Reference reflex: whenever an external link is evidence for this work (a precedent issue/PR, a reference implementation, official docs, a paper/blog), attach it via references — prefer the inline references[] param at creation time over a post-hoc chorus_add_reference.`,
+      ``,
+      `--- User's idea description ---`,
+      params.descriptionText,
+    ].join("\n");
+  }
+
+  return [
+    `[Chorus conversational idea entry] A new idea has been PRE-CREATED for project ${projectLabel} from the user's description below, and it is already assigned to you (status: elaborating).`,
+    `  ideaUuid: ${params.ideaUuid}`,
+    ``,
+    `This conversation IS that idea's root session — its elaboration and lifecycle wakes will continue here. Do the following, in order:`,
+    `1. Edit the idea via chorus_edit_idea: derive a concise title from the description and polish the content (keep the user's meaning; you may restructure). The current title is a placeholder.`,
+    `2. ${researchInstruction}`,
+    `3. After that optional step, start elaboration on the idea (chorus_pm_start_elaboration), following the idea skill — do NOT wait for another wake. Post a short summary of your questions in this conversation and direct the user to answer in the idea's elaboration panel.`,
+    `4. End the turn. The user's panel answers will wake this same conversation.`,
+    ``,
+    `Reference reflex: whenever an external link is evidence for this idea (a precedent issue/PR, a reference implementation, official docs, a paper/blog), attach it via references — prefer the inline references[] param at creation time over a post-hoc chorus_add_reference.`,
+    ``,
+    `--- User's idea description ---`,
+    params.descriptionText,
+  ].join("\n");
+}
+
+/** @param {string} ideaUuid */
+export function composeResearchInstruction(ideaUuid) {
+  return [
+    `${RESEARCH_INSTRUCTION_PREFIX} Explicit, one-time research request for ideaUuid: ${ideaUuid}.`,
+    "This is the existing Idea's root conversation. Before research and again before saving, re-read the Idea, ALL related proposals/tasks and execution history including theme descendants. If development has begun, report that the stage changed and STOP without research or edits.",
+    "Invoke the shared research skill for ONE bounded pass (approximately 2–5 minutes, at most 5 deeply read sources). Reuse existing evidence. An explicit user instruction to skip research takes precedence. Tools unavailable, empty results, or exhausted budget: record the limitation and stop.",
+    "Attach useful sources through existing references and obtain real UUIDs. Read the latest Idea content immediately before saving and MERGE concise findings, source citations using ref:UUID, implications, unknowns, and the stopping reason; preserve user text and existing evidence.",
+    "Preserve all elaboration rounds, questions, answers and resolved state. Do not create or claim an Idea, start elaboration, submit or modify a Proposal, change task status, or start development. If findings affect an approved proposal, only record the impact and revision needs in the Idea.",
+    "Report the findings and END this turn. This menu invocation does not resume the Idea or Proposal workflow. A later explicit Research request may run another bounded pass.",
+  ].join("\n");
+}

package/cli/operation.mjs

@@ -0,0 +1,46 @@
+import { CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS, RESEARCH_INSTRUCTION_PREFIX } from "./operation-contract.mjs";
+import { composeConversationalIdeaInstruction, composeResearchInstruction } from "./operation-prompts.mjs";
+
+// Canonical operations are identified by their trigger, never by prompt text.
+export const OPERATION_ACTIONS = new Set(["idea_creation_requested", "research_requested"]);
+
+const identity = (value) => typeof value === "string" && value.length > 0 && value.length <= 100;
+
+/** Validate before dedup/admission. Routing authority always comes from the session. */
+export function validateOperation(trigger, payload, { sessionId, directIdeaUuid, projectUuid }) {
+  const creation = trigger === "idea_creation_requested";
+  const fields = creation
+    ? ["version", "kind", "ideaUuid", "projectUuid", "mode", "researchFirst", "descriptionText"]
+    : ["version", "kind", "ideaUuid"];
+  if (!OPERATION_ACTIONS.has(trigger) ||
+      !payload || typeof payload !== "object" || Array.isArray(payload) ||
+      Object.keys(payload).length !== fields.length ||
+      fields.some((field) => !Object.hasOwn(payload, field)) ||
+      payload.version !== 1 || payload.kind !== (creation ? "idea_creation" : "research") ||
+      !identity(payload.ideaUuid) || payload.ideaUuid !== directIdeaUuid ||
+      sessionId !== directIdeaUuid ||
+      (creation && (!identity(payload.projectUuid) ||
+        (projectUuid !== undefined && payload.projectUuid !== projectUuid) ||
+        !["elaborate", "decompose"].includes(payload.mode) ||
+        typeof payload.researchFirst !== "boolean" ||
+        typeof payload.descriptionText !== "string" || !payload.descriptionText.trim() ||
+        payload.descriptionText.length > CONVERSATIONAL_IDEA_DESCRIPTION_MAX_CHARS))) {
+    throw new Error("Operation protocol error: invalid payload or session/Idea identity mismatch");
+  }
+  return payload;
+}
+
+export function isExactOperation(n) {
+  return OPERATION_ACTIONS.has(n?.action) ||
+    (n?.action === "human_instruction" &&
+      n.instructionText?.startsWith(RESEARCH_INSTRUCTION_PREFIX));
+}
+
+export function buildOperationPrompt(n) {
+  const p = validateOperation(n.action, n.operationPayload, {
+    sessionId: n.sessionId, directIdeaUuid: n.directIdeaUuid, projectUuid: n.projectUuid,
+  });
+  return p.kind === "research"
+    ? composeResearchInstruction(p.ideaUuid)
+    : composeConversationalIdeaInstruction(p);
+}