chatroom-cli 1.130.2 → 1.131.0

package/README.md

@@ -168,6 +168,14 @@ The chatroom handoff command is of this format:
 chatroom handoff --chatroom-id=<id> --role=<role> --next-role=<role>
 ```
 
+The chatroom notify-user command (interim update, no task transition) is of this format:
+
+```
+chatroom notify-user --chatroom-id=<id> --role=<role> << 'CHATROOM_NOTIFY_END'
+<update>
+CHATROOM_NOTIFY_END
+```
+
 **Non-production only** (local dev, preview): prefix commands with `CHATROOM_CONVEX_URL=<convex-url> `.
 
 ### CRITICAL: Execution Rules for Chatroom Commands
@@ -178,7 +186,7 @@ The correct session loop is:
 
 1. **Immediately run** `get-next-task` via `bash` and block until a task arrives
 2. **Process** the task
-3. **Run** `handoff` via `bash` to signal completion and pass control
+3. **Run** `handoff` via `bash` to signal completion and pass control. Run `handoff` exactly once per task
 4. **Immediately run** `get-next-task` again to wait for the next task
 
 **Common mistakes to avoid:**

package/dist/index.js

@@ -2165,6 +2165,7 @@ __export(exports_stdin_heredoc, {
   validateStdinHeredocBody: () => validateStdinHeredocBody,
   formatStdinHeredocCommand: () => formatStdinHeredocCommand,
   findReservedDelimiterLines: () => findReservedDelimiterLines,
+  NOTIFY_USER_STDIN_DELIMITER: () => NOTIFY_USER_STDIN_DELIMITER,
   HANDOFF_STDIN_DELIMITER: () => HANDOFF_STDIN_DELIMITER,
   HANDOFF_MESSAGE_MARKER: () => HANDOFF_MESSAGE_MARKER,
   ENHANCER_STDIN_DELIMITER: () => ENHANCER_STDIN_DELIMITER,
@@ -2206,13 +2207,14 @@ function findReservedDelimiterLines(content) {
   }
   return hits;
 }
-var HANDOFF_STDIN_DELIMITER = "CHATROOM_HANDOFF_END", CONTEXT_STDIN_DELIMITER = "CHATROOM_CONTEXT_END", BACKLOG_STDIN_DELIMITER = "CHATROOM_BACKLOG_END", AGENTIC_QUERY_STDIN_DELIMITER = "CHATROOM_AGENTIC_QUERY_END", ENHANCER_STDIN_DELIMITER = "CHATROOM_ENHANCER_END", CLASSIFY_STDIN_DELIMITER = "CHATROOM_CLASSIFY_END", HANDOFF_MESSAGE_MARKER = "---MESSAGE---", RESERVED_STDIN_HEREDOC_DELIMITERS, RESERVED_STRUCTURED_PARAM_MARKERS;
+var HANDOFF_STDIN_DELIMITER = "CHATROOM_HANDOFF_END", CONTEXT_STDIN_DELIMITER = "CHATROOM_CONTEXT_END", BACKLOG_STDIN_DELIMITER = "CHATROOM_BACKLOG_END", AGENTIC_QUERY_STDIN_DELIMITER = "CHATROOM_AGENTIC_QUERY_END", NOTIFY_USER_STDIN_DELIMITER = "CHATROOM_NOTIFY_END", ENHANCER_STDIN_DELIMITER = "CHATROOM_ENHANCER_END", CLASSIFY_STDIN_DELIMITER = "CHATROOM_CLASSIFY_END", HANDOFF_MESSAGE_MARKER = "---MESSAGE---", RESERVED_STDIN_HEREDOC_DELIMITERS, RESERVED_STRUCTURED_PARAM_MARKERS;
 var init_stdin_heredoc = __esm(() => {
   RESERVED_STDIN_HEREDOC_DELIMITERS = [
     HANDOFF_STDIN_DELIMITER,
     CONTEXT_STDIN_DELIMITER,
     BACKLOG_STDIN_DELIMITER,
     AGENTIC_QUERY_STDIN_DELIMITER,
+    NOTIFY_USER_STDIN_DELIMITER,
     ENHANCER_STDIN_DELIMITER,
     CLASSIFY_STDIN_DELIMITER
   ];
@@ -35800,6 +35802,7 @@ var init_errorCodes = __esm(() => {
     INVALID_TASK_ENVELOPE: "INVALID_TASK_ENVELOPE",
     TOO_MANY_ATTACHMENTS: "TOO_MANY_ATTACHMENTS",
     INVALID_ANCHOR: "INVALID_ANCHOR",
+    NO_ACTIVE_TASK: "NO_ACTIVE_TASK",
     CONTENT_TOO_LONG: "CONTENT_TOO_LONG",
     EMPTY_PROMPT: "EMPTY_PROMPT",
     INVALID_SCHEDULE: "INVALID_SCHEDULE",
@@ -35908,6 +35911,7 @@ var init_errorCodes = __esm(() => {
     BACKEND_ERROR_CODES.INVALID_TASK_ENVELOPE,
     BACKEND_ERROR_CODES.TOO_MANY_ATTACHMENTS,
     BACKEND_ERROR_CODES.INVALID_ANCHOR,
+    BACKEND_ERROR_CODES.NO_ACTIVE_TASK,
     BACKEND_ERROR_CODES.CONTENT_TOO_LONG,
     BACKEND_ERROR_CODES.EMPTY_PROMPT,
     BACKEND_ERROR_CODES.INVALID_SCHEDULE,
@@ -58155,7 +58159,7 @@ get-next-task → do work → handoff → get-next-task → repeat
 
 1. **Run \`get-next-task\`** immediately via \`bash\` — block until task arrives
 2. **Process** the task
-3. **Run \`handoff\`** to signal completion
+3. **Run \`handoff\`** to signal completion. Run \`handoff\` exactly once per task
 4. **Run \`get-next-task\`** again to wait for next task
 
 ### Reliability
@@ -58175,6 +58179,7 @@ This ensures you never forget to pass control back — just copy the command fro
 |--------|---------|
 | Fetch next task | \`chatroom get-next-task --chatroom-id=<id> --role=<role>\` |
 | Pass control | \`chatroom handoff --chatroom-id=<id> --role=<role> --next-role=<role>\` |
+| Update the user without completing the task | \`chatroom notify-user --chatroom-id=<id> --role=<role> << 'CHATROOM_NOTIFY_END'\` |
 | Refresh system prompt (after compaction) | \`chatroom get-system-prompt --chatroom-id=<id> --role=<role>\` |
 
 **Non-production only** (local dev, preview): prefix commands with \`CHATROOM_CONVEX_URL=<convex-url> \` (e.g. \`CHATROOM_CONVEX_URL=http://127.0.0.1:3210 chatroom get-next-task ...\`).
@@ -99489,14 +99494,14 @@ var init_task_started = __esm(() => {
 
 // ../../services/backend/prompts/cli/get-next-task/reminder.ts
 function getNextTaskReminder() {
-  return "A foreground `get-next-task` blocks until the user or team message is ready, then resolves with that message as a chatroom task—infer what to do from the message, not only from numbered next-steps. Message availability requires exactly one such blocking tool call; the harness delivers chatroom tasks only while it blocks. Duplicate or backgrounded listeners can acknowledge tasks early and trigger grace-period cooldowns where your active session receives nothing.";
+  return "A foreground `get-next-task` blocks until the user or team message is ready, then resolves with that message as a chatroom task—treat the message content as the source of truth for what to do. Message availability requires exactly one such blocking tool call; the harness delivers chatroom tasks only while it blocks. Duplicate or backgrounded listeners can acknowledge tasks early and trigger grace-period cooldowns where your active session receives nothing.";
 }
 function getNextTaskGuidance() {
   return `\uD83D\uDD17 STAYING CONNECTED TO YOUR TEAM
 
 Your primary directive: Stay available to receive chatroom tasks from your team.
 
-When the user or team is ready, your blocking \`get-next-task\` resolves and delivers their message as the next chatroom task. That message is the source of truth for what to do—numbered next-steps in task delivery are typical role patterns, not a rigid script.
+When the user or team is ready, your blocking \`get-next-task\` resolves and delivers their message as the next chatroom task. That message content is the source of truth for what to do.
 
 The harness delivers the next chatroom task only through a single foreground \`get-next-task\` that blocks as a tool call. After completing work and handing off, that blocking listener is what keeps you connected to your team.
 
@@ -100243,24 +100248,34 @@ var init_command2 = __esm(() => {
 });
 
 // ../../services/backend/prompts/native/handoff-visibility.ts
-function recipientLabel(toRole) {
-  return toRole.toLowerCase() === "user" ? "The user" : `The \`${toRole}\` agent`;
-}
 function getHandoffRecipientVisibilityCallout(toRole) {
-  const recipient = recipientLabel(toRole);
-  const sessionExample = toRole.toLowerCase() === "user" ? ' (including direct replies like "Hello!")' : "";
+  if (toRole.toLowerCase() === "user") {
+    return `---
+
+⚠️ **CRITICAL — Recipient visibility**
+
+The user receives the text inside your \`handoff --next-role="user"\` command, plus any \`notify-user\` notices you sent earlier in this task.
+
+They **cannot** see:
+- Anything you write in this agent session (including direct replies like "Hello!")
+- Tool output
+
+When you write this handoff, put your **complete** deliverable in the handoff message. Do not rely on session text or on earlier notices.
+
+---`;
+  }
   return `---
 
 ⚠️ **CRITICAL — Recipient visibility**
 
-${recipient} **only** receives the text inside your \`handoff --next-role="${toRole}"\` command.
+The \`${toRole}\` agent **only** receives the text inside your \`handoff --next-role="${toRole}"\` command.
 
 They **cannot** see:
-- Anything you write in this agent session${sessionExample}
-- Progress reports
+- Anything you write in this agent session
+- \`notify-user\` notices (notices go to the user only)
 - Tool output
 
-Put your **complete** deliverable in the handoff message — not in session text.
+When you write this handoff, put your **complete** deliverable in the handoff message — not in session text.
 
 ---`;
 }
@@ -100962,7 +100977,7 @@ var init_unresolved_decisions = () => {};
 // ../../services/backend/prompts/utils/handoff-report-template-body.ts
 function getHandoffReportTemplateBody(roleGuidanceContext, options = {}) {
   return `<handoff-overview>
-<!-- For informational tasks (summaries, feedback, Q&amp;A with no code changes): put the complete primary answer in Summary and What changed — the user only sees this handoff. -->
+<!-- When the task is informational (summaries, feedback, Q&amp;A with no code changes): put the complete primary answer in Summary and What changed. Do not rely on earlier \`notify-user\` notices or session text. -->
 ## Summary
 <what was accomplished, in plain terms — no references to prior messages>
 
@@ -101915,17 +101930,18 @@ function formatDecodeError(error51) {
 
 // ../../services/backend/prompts/native/session-continuity.ts
 function getNativeHandoffTurnEndGuidance(nextRole) {
-  return getHandoffTurnEndGuidance(nextRole);
+  return getHandoffTurnEndGuidance(nextRole, true);
 }
-function getHandoffTurnEndGuidance(nextRole) {
+function getHandoffTurnEndGuidance(nextRole, nativeIntegration = false) {
+  const delivery = nativeIntegration ? "the system sends it to you when it is ready" : "your blocking `get-next-task` returns it";
   const lines = [
-    "",
-    "**Handoff complete. End your turn now — stop tool calls. The system will send you a message when further action is required.**"
+    nativeIntegration ? "**Handoff complete. End your turn now — stop tool calls. When the harness supports native integration: the system sends you a message when further action is required.**" : "**Handoff complete. When the harness does not support native integration: run `get-next-task` in the foreground now; it blocks until the next chatroom task is ready.**",
+    "After a successful handoff, do not run `handoff` or `notify-user` again for this task."
   ];
   if (nextRole.toLowerCase() === "user") {
-    lines.push("The system delivers the next chatroom task when the user sends one.");
+    lines.push(`When the next task arrives: the user sends it, and ${delivery}.`);
   } else {
-    lines.push(`The system delivers \`${nextRole}\`'s handback when they finish — do not poll \`messages download\` while waiting. For history reconstruction tasks, \`messages download\` is the correct tool.`);
+    lines.push(`When you are waiting for \`${nextRole}\`'s handback: do not poll \`messages download\`; ${delivery}.`, "When you need the history of how this task was done: `messages download` is the correct tool.");
   }
   return lines.join(`
 `);
@@ -102041,19 +102057,29 @@ var init_general_knowledge = __esm(() => {
   init_proof_of_verification();
 });
 
+// ../../services/backend/prompts/cli/notify-user/command.ts
+var init_command4 = __esm(() => {
+  init_stdin_heredoc();
+});
+
 // ../../services/backend/prompts/sections/commands-reference.ts
 var init_commands_reference = __esm(() => {
   init_general_knowledge();
   init_command();
   init_reminder();
   init_command2();
+  init_command4();
   init_utils3();
 });
 // ../../services/backend/prompts/cli/sections/core-responsibilities.ts
 var init_core_responsibilities = () => {};
 // ../../services/backend/prompts/cli/sections/inter-role-handoff-rule.ts
 function getInterRoleHandoffRule() {
-  return "- **To communicate with another team role** → Use `chatroom handoff` to that role, even for a short test or status message. Do not use `chatroom message(s) send`: those are user-ingress commands that persist `senderRole=user` and `type=message`.";
+  return [
+    "- **When you need to send any message to another team role (including a short test or status message)** → Run `chatroom handoff --next-role=<role>`. This completes your current task. Do not use `chatroom message(s) send`: those are user-ingress commands that persist `senderRole=user` and `type=message`.",
+    "- **When you need to give the user an interim update and you still have work left on your current task** → Run `chatroom notify-user`. It posts a notice to the user and does not complete, reassign, or transition your task. Run it before you run `handoff`; after `handoff` it fails with `NO_ACTIVE_TASK`."
+  ].join(`
+`);
 }
 
 // ../../services/backend/prompts/cli/sections/handoff-rules.ts
@@ -102197,7 +102223,7 @@ var init_verifier3 = __esm(() => {
   [ACHIEVED2, NOT_ACHIEVED2, INCONCLUSIVE2] = VERIFIER_VERDICTS;
   VERIFIER_GUIDANCE = `## Verifier Operating Model
 
-You are the verifier. Your main job is to check whether the user's goal was accomplished, judged from chatroom logs. You are advisory and read-only: do not edit files, implement code, run builds or linters, run \`chatroom context new\`, or act as the planner or builder. The one exception to running nothing is the test rule below: it ${VERIFIER_TEST_RULE}.
+You are the verifier. Your main job is to check whether the user's goal was accomplished, judged from chatroom logs. You are advisory and read-only: do not edit files, implement code, run builds or linters, run \`chatroom context new\`, or act as the planner or builder. The one exception is test execution: it ${VERIFIER_TEST_RULE}.
 
 ${"{SESSION_CONTINUITY}"}
 
@@ -102208,9 +102234,9 @@ ${getInterRoleHandoffRule()}
 2a. Requested test runs: if the user's last message (or prior user messages for this objective) explicitly asks for tests to be run, run exactly those commands from the repository root, record the command and exit result, and count the output as evidence. Run no test the user did not ask for. If the request is absent, run nothing.
 3. Run \`chatroom context read --chatroom-id="<chatroom-id>" --role="verifier"\` and note any mismatch with the request's context id.
 4. Decompose the objective into numbered requirements R1..Rn. Split compound requests and ignore anything the user did not actually ask for.
-4a. User expectations: the user's handoff template (the section at the end of this prompt) defines what the user expects from the work. In a code mode, turn each applicable item that concerns the work into an expectation \`U1..Un\`: each requirement's evidence (PR, commit, or file), files changed, Code Change Verification, backlog items moved to \`pending_user_review\` after a verified end-to-end feature with a PR, and any manual steps or unresolved decisions the user must act on. Skip presentation-only items: template disclosure checkboxes, section order, collapsing, diagram format, and Proof of Planning. In \`chat\` mode the template asks only for a direct, concise answer, so add no expectations beyond the requirements.
+4a. User expectations: the user's handoff template defines what the user expects from the work. In a code mode, turn each applicable item that concerns the work into a user expectation: each requirement's evidence (PR, commit, or file), files changed, Code Change Verification, backlog items moved to \`pending_user_review\` after a verified end-to-end feature with a PR, and any manual steps or unresolved decisions the user must act on. Skip presentation-only items: template disclosure checkboxes, section order, collapsing, diagram format, and Proof of Planning. In \`chat\` mode the template asks only for a direct, concise answer, so add no expectations beyond the requirements.
 5. Find evidence for every requirement in the logs alone: builder handoff reports, planner delegations, quoted test output, commits, and PRs. \`met\` requires concrete evidence in the logs. The planner's claimed outcome is a claim, not evidence. Silence means \`unverified\`. A contradiction, or a log showing the requirement was not done, means \`unmet\`. Never state that tests passed unless a log reports it, or you ran the requested tests yourself.
-6. Choose the verdict by the rules in the injected verdict template: exactly one of ${VERIFIER_VERDICTS.join(", ")}. ${ACHIEVED2} only if every requirement and every U-expectation is met; ${NOT_ACHIEVED2} if any is unmet; ${INCONCLUSIVE2} if none is unmet but any is unverified.
+6. Choose exactly one verdict from ${VERIFIER_VERDICTS.join(", ")}: ${ACHIEVED2} only if every requirement and every user expectation is met; ${NOT_ACHIEVED2} if any requirement or user expectation is unmet; ${INCONCLUSIVE2} if none is unmet but any is unverified.
 7. Follow the injected \`<handoff-templates>\` verdict template exactly, in its order, and put the complete verdict in the handoff. Then hand off to the configured entry point with the normal command, then stop:
 
 \`\`\`bash
@@ -102462,11 +102488,10 @@ function generateHandoffOutput(params) {
     lines.push(getNativeHandoffTurnEndGuidance(nextRole));
   } else {
     lines.push("");
-    lines.push("✅ Level B complete (chatroom task handed off).");
-    lines.push("⏳ Level A continues (session is still active) — run get-next-task to stay connected:");
+    lines.push("✅ Chatroom task complete (handoff sent).");
+    lines.push(getHandoffTurnEndGuidance(nextRole, false));
     lines.push("");
     lines.push(`\`${getNextTaskCommand({ chatroomId, role, cliEnvPrefix })}\``);
-    lines.push(getHandoffTurnEndGuidance(nextRole));
   }
   return lines.join(`
 `);
@@ -102651,6 +102676,79 @@ var init_handoff = __esm(() => {
   init_error_formatting();
 });
 
+// src/commands/notify-user/index.ts
+var exports_notify_user = {};
+__export(exports_notify_user, {
+  notifyUserEffect: () => notifyUserEffect,
+  notifyUser: () => notifyUser
+});
+function handleNotifyUserError(err) {
+  return exports_Effect.sync(() => {
+    if (err._tag === "NotAuthenticated") {
+      formatAuthError(err.convexUrl, err.otherUrls);
+      process.exit(1);
+    } else if (err._tag === "InvalidChatroomId") {
+      formatChatroomIdError(err.id);
+      process.exit(1);
+    } else if (err._tag === "NotifyUserFailed") {
+      console.error(`
+❌ ERROR: Notice not sent`);
+      const message = err.errorData?.message ?? (err.cause instanceof Error ? err.cause.message : String(err.cause));
+      console.error(`
+${message}`);
+      if (process.env.CHATROOM_DEBUG === "true") {
+        console.error(`
+\uD83D\uDD0D Debug Info:`);
+        console.error(JSON.stringify(err.errorData ?? err.cause, null, 2));
+      }
+      if (err.errorData?.code === "NO_ACTIVE_TASK") {
+        console.error(`
+\uD83D\uDCA1 If you already ran handoff for this task, end your turn — do not hand off again.`);
+      } else if (err.errorData?.code === "INVALID_ROLE") {
+        console.error(`
+\uD83D\uDCA1 Check your team configuration and use a valid role`);
+      }
+      console.error(`
+\uD83D\uDCDA Need help? Check the docs or run:`);
+      console.error(`   chatroom notify-user --help`);
+      process.exit(1);
+    }
+  });
+}
+async function notifyUser(chatroomId, options, deps) {
+  const d = deps ?? await createConvexCommandDeps();
+  await exports_Effect.runPromise(notifyUserEffect(chatroomId, options).pipe(exports_Effect.catch((err) => handleNotifyUserError(err)), exports_Effect.provide(commandServicesLayerFromDeps(d))));
+}
+var notifyUserEffect = (chatroomId, options) => exports_Effect.gen(function* () {
+  const sessionId = yield* requireSessionForChatroomEffect({ chatroomId });
+  const backend2 = yield* BackendService;
+  const result3 = yield* backend2.mutation(api.messages.notifyUser, {
+    sessionId,
+    chatroomId,
+    senderRole: options.role,
+    content: options.message
+  }).pipe(exports_Effect.mapError((cause) => {
+    let errorData;
+    if (cause instanceof ConvexError) {
+      errorData = cause.data;
+    }
+    return { _tag: "NotifyUserFailed", cause, errorData };
+  }));
+  yield* exports_Effect.sync(() => {
+    console.log("✅ Notice sent to user (task state unchanged)");
+    console.log(`   Message ID: ${result3.messageId}`);
+    console.log("Continue working. Run `handoff` exactly once when this task is complete.");
+  });
+});
+var init_notify_user = __esm(() => {
+  init_values();
+  init_dist();
+  init_api3();
+  init_create_convex_command_deps();
+  init_services();
+  init_error_formatting();
+});
+
 // src/commands/agentic-query/complete.ts
 var exports_complete = {};
 __export(exports_complete, {
@@ -138258,6 +138356,31 @@ handoffCommandGroup.option("--chatroom-id <id>", "Chatroom identifier").option("
     nextRole
   });
 });
+program2.command("notify-user").description("Send the user an update while you keep working (does not complete or transition your task)").requiredOption("--chatroom-id <id>", "Chatroom identifier").requiredOption("--role <role>", "Your role").action(async (options) => {
+  await maybeRequireAuth();
+  const { decode: decode5 } = await Promise.resolve().then(() => exports_decode);
+  const stdinContent = await readStdin();
+  let message;
+  try {
+    const { NOTIFY_USER_STDIN_DELIMITER: NOTIFY_USER_STDIN_DELIMITER2, validateStdinHeredocBody: validateStdinHeredocBody2 } = await Promise.resolve().then(() => (init_stdin_heredoc(), exports_stdin_heredoc));
+    const result3 = decode5(stdinContent, { singleParam: "message" });
+    message = result3.message;
+    validateStdinHeredocBody2(message, NOTIFY_USER_STDIN_DELIMITER2);
+  } catch (err) {
+    console.error(`❌ Failed to decode stdin: ${err.message}`);
+    process.exit(1);
+  }
+  if (!message || message.trim().length === 0) {
+    console.error("❌ Message is empty");
+    console.error(`   Usage: chatroom notify-user --chatroom-id=<id> --role=<role> << 'CHATROOM_NOTIFY_END'`);
+    process.exit(1);
+  }
+  const { notifyUser: notifyUser2 } = await Promise.resolve().then(() => (init_notify_user(), exports_notify_user));
+  await notifyUser2(options.chatroomId, {
+    role: options.role,
+    message
+  });
+});
 var agenticQueryCommand = program2.command("agentic-query").description("Agentic search/ask query commands");
 agenticQueryCommand.command("complete").description("Submit the structured agentic query result markdown").requiredOption("--chatroom-id <id>", "Chatroom identifier").requiredOption("--query-id <id>", "Agentic query identifier").action(async (options) => {
   await maybeRequireAuth();
@@ -138637,4 +138760,4 @@ program2.hook("preAction", async (_thisCommand, actionCommand) => {
 });
 program2.parse();
 
-//# debugId=107270B63CF350A064756E2164756E21
+//# debugId=87F31BFD12DBC8AF64756E2164756E21