@the-open-engine/zeroshot 6.38.1 → 6.39.1

package/cli/message-formatters-normal.ts

@@ -0,0 +1,250 @@
+import chalk = require('chalk');
+import eventCopy = require('./event-copy');
+import formatterUtils = require('./message-formatter-utils');
+
+const { EVENT_COPY, formatMergeStatus } = eventCopy;
+const { formatLifecycleEvent, partitionValidationCriteria } = formatterUtils;
+
+interface CriterionResult {
+  status?: string;
+  id?: string | number;
+  reason?: string;
+}
+
+interface NormalMessageData {
+  event?: string;
+  triggers?: readonly string[];
+  triggeredBy?: string | number;
+  iteration?: string | number;
+  model?: string;
+  stack?: string;
+  commit?: string;
+  approved?: boolean | string;
+  criteriaResults?: readonly CriterionResult[];
+  reason?: string;
+  pr_number?: string | number;
+  pr_url?: string;
+  merged?: unknown;
+}
+
+interface NormalMessage {
+  cluster_id?: string;
+  topic?: string;
+  content?: {
+    text?: string;
+    data?: NormalMessageData;
+  };
+}
+
+type PrintLine = (text: string) => void;
+
+function isCriterionResults(value: unknown): value is readonly CriterionResult[] {
+  return Array.isArray(value);
+}
+
+function formatAgentLifecycle(
+  msg: NormalMessage,
+  prefix: string,
+  print: PrintLine = console.log
+): true {
+  const { icon, eventText } = formatLifecycleEvent(msg.content?.data);
+  print(`${prefix} ${icon} ${eventText}`);
+  return true;
+}
+
+function formatAgentError(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  print('');
+  print(chalk.bold.red(`${'─'.repeat(60)}`));
+  print(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.red('Error: agent failed')}`);
+  if (msg.content?.text) {
+    print(`${prefix} ${chalk.red(msg.content.text)}`);
+  }
+  if (msg.content?.data?.stack) {
+    const stackLines = msg.content.data.stack.split('\n').slice(0, 5);
+    for (const line of stackLines) {
+      if (line.trim()) print(`${prefix} ${chalk.dim(line)}`);
+    }
+  }
+  print(`${prefix} Next: inspect the agent logs and retry after fixing the cause.`);
+  print(chalk.bold.red(`${'─'.repeat(60)}`));
+  return true;
+}
+
+function formatIssueOpened(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  shownNewTaskForCluster: Set<string | undefined>,
+  print: PrintLine = console.log
+): true {
+  // Skip duplicate - conductor re-publishes after spawning agents
+  if (!shownNewTaskForCluster.has(msg.cluster_id)) {
+    shownNewTaskForCluster.add(msg.cluster_id);
+    print('');
+    print(chalk.bold.blue(`${'─'.repeat(60)}`));
+    print(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.blue('📋 New task')}`);
+    if (msg.content?.text) {
+      const lines = msg.content.text.split('\n').slice(0, 3);
+      for (const line of lines) {
+        if (line.trim() && line.trim() !== '# Manual Input') {
+          print(`${prefix} ${chalk.white(line)}`);
+        }
+      }
+    }
+    print(chalk.bold.blue(`${'─'.repeat(60)}`));
+  }
+  return true;
+}
+
+function formatImplementationReady(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  print(
+    `${prefix} ${chalk.gray(timestamp)} ${chalk.bold.yellow(`✅ ${EVENT_COPY.IMPLEMENTATION_READY.toUpperCase()}`)}`
+  );
+  if (msg.content?.data?.commit) {
+    print(
+      `${prefix} ${chalk.gray('Commit:')} ${chalk.cyan(msg.content.data.commit.substring(0, 8))}`
+    );
+  }
+  return true;
+}
+
+function formatValidationResult(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  const data = msg.content?.data || {};
+  const approved = data.approved === true || data.approved === 'true';
+  const status = approved ? chalk.bold.green('✓ Approved') : chalk.bold.red('✗ Rejected');
+  print(`${prefix} ${chalk.gray(timestamp)} ${status}`);
+  // Show summary if present and not a template variable
+  if (msg.content?.text && !msg.content.text.includes('{{')) {
+    print(`${prefix} ${msg.content.text.substring(0, 100)}`);
+  }
+  // Show CANNOT_VALIDATE (permanent) as warnings, CANNOT_VALIDATE_YET (temporary) as errors
+  const criteriaResults = data.criteriaResults;
+  if (isCriterionResults(criteriaResults)) {
+    const { cannotValidateYet, cannotValidate } =
+      partitionValidationCriteria(criteriaResults);
+    if (cannotValidateYet.length > 0) {
+      print(
+        `${prefix} ${chalk.red('❌ Cannot validate yet')} (${cannotValidateYet.length} criteria - work incomplete):`
+      );
+      for (const criterion of cannotValidateYet) {
+        print(
+          `${prefix}   ${chalk.red('•')} ${criterion.id}: ${criterion.reason || 'No reason provided'}`
+        );
+      }
+    }
+    if (cannotValidate.length > 0) {
+      print(
+        `${prefix} ${chalk.yellow('⚠️ Could not validate')} (${cannotValidate.length} criteria - permanent):`
+      );
+      for (const criterion of cannotValidate) {
+        print(
+          `${prefix}   ${chalk.yellow('•')} ${criterion.id}: ${criterion.reason || 'No reason provided'}`
+        );
+      }
+    }
+  }
+  // Show full JSON data structure
+  print(`${prefix} ${chalk.dim(JSON.stringify(data, null, 2).split('\n').join(`\n${prefix} `))}`);
+  return true;
+}
+
+function formatClusterComplete(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  print('');
+  print(chalk.bold.green(`${'═'.repeat(60)}`));
+  print(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.green('🎉 Cluster complete')}`);
+  if (msg.content?.data?.reason) {
+    print(`${prefix} ${chalk.green(msg.content.data.reason)}`);
+  }
+  print(chalk.bold.green(`${'═'.repeat(60)}`));
+  return true;
+}
+
+function formatClusterFailed(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  print('');
+  print(chalk.bold.red(`${'═'.repeat(60)}`));
+  print(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold.red('Error: cluster failed')}`);
+  if (msg.content?.text) print(`${prefix} ${chalk.red(msg.content.text)}`);
+  if (msg.content?.data?.reason) print(`${prefix} ${chalk.red(msg.content.data.reason)}`);
+  print(`${prefix} Next: inspect the cluster logs, then resume after fixing the cause.`);
+  print(chalk.bold.red(`${'═'.repeat(60)}`));
+  return true;
+}
+
+function formatPrCreated(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  const prNumber = msg.content?.data?.pr_number || '';
+  const prUrl = msg.content?.data?.pr_url || '';
+  print(''); // Blank line before PR notification
+  print(chalk.bold.green(`${'─'.repeat(60)}`));
+  print(
+    `${prefix} ${chalk.gray(timestamp)} ${chalk.bold.green(`🎉 ${EVENT_COPY.PR_CREATED.toUpperCase()}`)}`
+  );
+  if (prNumber) {
+    print(`${prefix} ${chalk.gray('PR:')} ${chalk.cyan(`#${prNumber}`)}`);
+  }
+  if (prUrl) {
+    print(`${prefix} ${chalk.gray('URL:')} ${chalk.blue(prUrl)}`);
+  }
+  const mergeStatus = formatMergeStatus(msg.content?.data?.merged);
+  if (mergeStatus) {
+    const formattedMergeStatus =
+      mergeStatus === 'merged' ? chalk.green(mergeStatus) : chalk.yellow(mergeStatus);
+    print(`${prefix} ${chalk.gray('Merge:')} ${formattedMergeStatus}`);
+  }
+  print(chalk.bold.green(`${'─'.repeat(60)}`));
+  return true;
+}
+
+function formatGenericMessage(
+  msg: NormalMessage,
+  prefix: string,
+  timestamp: string,
+  print: PrintLine = console.log
+): true {
+  print(`${prefix} ${chalk.gray(timestamp)} ${chalk.bold(msg.topic)}`);
+  if (msg.content?.text) {
+    print(`${prefix} ${msg.content.text}`);
+  }
+  return true;
+}
+
+export = {
+  formatAgentLifecycle,
+  formatAgentError,
+  formatIssueOpened,
+  formatImplementationReady,
+  formatValidationResult,
+  formatPrCreated,
+  formatClusterComplete,
+  formatClusterFailed,
+  formatGenericMessage,
+};

package/cli/message-formatters-watch.js

@@ -1,104 +1,101 @@
-const chalk = require('chalk');
-const {
-  buildClusterPrefix,
-  getColorForSender,
-  parseDataField,
-} = require('./message-formatter-utils');
-const { EVENT_COPY, formatMergeStatus } = require('./event-copy');
-
-const DEFAULT_WRITER = Object.freeze({ printLine: (text) => console.log(text) });
-
+"use strict";
+const chalk = require("chalk");
+const formatterUtils = require("./message-formatter-utils");
+const eventCopy = require("./event-copy");
+const { buildClusterPrefix, getColorForSender, parseDataField } = formatterUtils;
+const { EVENT_COPY, formatMergeStatus } = eventCopy;
+const DEFAULT_WRITER = Object.freeze({
+    printLine: (text) => console.log(text),
+});
+function isCountableData(value) {
+    if (typeof value === 'string')
+        return true;
+    return (typeof value === 'object' &&
+        value !== null &&
+        'length' in value &&
+        typeof value.length === 'number');
+}
 function formatAgentError(msg, clusterPrefix, writer) {
-  writer.printLine(`${clusterPrefix} ${chalk.bold.red(`Error: ${msg.sender}`)}`);
-  if (msg.content?.text) {
-    writer.printLine(`${clusterPrefix}   ${chalk.red(msg.content.text)}`);
-  }
-  writer.printLine(`${clusterPrefix}   Next: zeroshot logs ${msg.cluster_id} -f`);
+    writer.printLine(`${clusterPrefix} ${chalk.bold.red(`Error: ${msg.sender}`)}`);
+    if (msg.content?.text) {
+        writer.printLine(`${clusterPrefix}   ${chalk.red(msg.content.text)}`);
+    }
+    writer.printLine(`${clusterPrefix}   Next: zeroshot logs ${msg.cluster_id} -f`);
 }
-
 function formatIssueOpened(msg, clusterPrefix, writer) {
-  const issueNum = msg.content?.data?.issue_number || '';
-  const title = msg.content?.data?.title || '';
-  const prompt = msg.content?.data?.prompt || msg.content?.text || '';
-  const taskDesc = title === 'Manual Input' && prompt ? prompt : title;
-  const truncatedDesc =
-    taskDesc && taskDesc.length > 60 ? `${taskDesc.substring(0, 60)}...` : taskDesc;
-  const eventText = `Started ${issueNum ? `#${issueNum}` : 'task'}${truncatedDesc ? chalk.dim(` - ${truncatedDesc}`) : ''}`;
-  writer.printLine(`${clusterPrefix} ${eventText}`);
+    const issueNum = msg.content?.data?.issue_number || '';
+    const title = msg.content?.data?.title || '';
+    const prompt = msg.content?.data?.prompt || msg.content?.text || '';
+    const taskDesc = title === 'Manual Input' && prompt ? prompt : title;
+    const truncatedDesc = taskDesc && taskDesc.length > 60 ? `${taskDesc.substring(0, 60)}...` : taskDesc;
+    const issueLabel = issueNum ? `#${issueNum}` : 'task';
+    const description = truncatedDesc ? chalk.dim(` - ${truncatedDesc}`) : '';
+    const eventText = `Started ${issueLabel}${description}`;
+    writer.printLine(`${clusterPrefix} ${eventText}`);
 }
-
 function formatImplementationReady(msg, clusterPrefix, writer = DEFAULT_WRITER) {
-  const agentName = getColorForSender(msg.sender)(msg.sender);
-  writer.printLine(
-    `${clusterPrefix} ${agentName} ${EVENT_COPY.IMPLEMENTATION_READY.toLowerCase()}`
-  );
+    const agentName = getColorForSender(msg.sender)(msg.sender);
+    writer.printLine(`${clusterPrefix} ${agentName} ${EVENT_COPY.IMPLEMENTATION_READY.toLowerCase()}`);
 }
-
 function printRejectionDetails(data, clusterPrefix, writer) {
-  const errors = parseDataField(data.errors);
-  const issues = parseDataField(data.issues);
-  if (errors.length > 0) {
-    const count = JSON.stringify(errors).length;
-    writer.printLine(
-      `${clusterPrefix}   ${chalk.red('•')} ${errors.length} error${errors.length > 1 ? 's' : ''} (${count} chars)`
-    );
-  }
-  if (issues.length > 0) {
-    const count = JSON.stringify(issues).length;
-    writer.printLine(
-      `${clusterPrefix}   ${chalk.yellow('•')} ${issues.length} issue${issues.length > 1 ? 's' : ''} (${count} chars)`
-    );
-  }
+    const errors = parseDataField(data.errors);
+    const issues = parseDataField(data.issues);
+    if (isCountableData(errors) && errors.length > 0) {
+        const count = JSON.stringify(errors).length;
+        writer.printLine(`${clusterPrefix}   ${chalk.red('•')} ${errors.length} error${errors.length > 1 ? 's' : ''} (${count} chars)`);
+    }
+    if (isCountableData(issues) && issues.length > 0) {
+        const count = JSON.stringify(issues).length;
+        writer.printLine(`${clusterPrefix}   ${chalk.yellow('•')} ${issues.length} issue${issues.length > 1 ? 's' : ''} (${count} chars)`);
+    }
 }
-
 function formatValidationResult(msg, clusterPrefix, writer) {
-  const agentName = getColorForSender(msg.sender)(msg.sender);
-  const data = msg.content?.data;
-  const approved = data?.approved === 'true' || data?.approved === true;
-  const status = approved ? chalk.green('Approved') : chalk.red('Rejected');
-  let eventText = `${agentName} ${status}`;
-  if (data?.summary && !approved) eventText += chalk.dim(` - ${data.summary}`);
-  writer.printLine(`${clusterPrefix} ${eventText}`);
-  if (!approved) printRejectionDetails(data, clusterPrefix, writer);
+    const agentName = getColorForSender(msg.sender)(msg.sender);
+    const data = msg.content?.data;
+    const approved = data?.approved === 'true' || data?.approved === true;
+    const status = approved ? chalk.green('Approved') : chalk.red('Rejected');
+    let eventText = `${agentName} ${status}`;
+    if (data?.summary && !approved)
+        eventText += chalk.dim(` - ${data.summary}`);
+    writer.printLine(`${clusterPrefix} ${eventText}`);
+    if (!approved && data)
+        printRejectionDetails(data, clusterPrefix, writer);
 }
-
 function formatPrCreated(msg, clusterPrefix, writer = DEFAULT_WRITER) {
-  const agentName = getColorForSender(msg.sender)(msg.sender);
-  const prNum = msg.content?.data?.pr_number || '';
-  let eventText = `${agentName} ${EVENT_COPY.PR_CREATED.toLowerCase()}${prNum ? ` #${prNum}` : ''}`;
-  const mergeStatus = formatMergeStatus(msg.content?.data?.merged);
-  if (mergeStatus) eventText += chalk.dim(` — ${mergeStatus}`);
-  writer.printLine(`${clusterPrefix} ${eventText}`);
+    const agentName = getColorForSender(msg.sender)(msg.sender);
+    const prNum = msg.content?.data?.pr_number || '';
+    let eventText = `${agentName} ${EVENT_COPY.PR_CREATED.toLowerCase()}${prNum ? ` #${prNum}` : ''}`;
+    const mergeStatus = formatMergeStatus(msg.content?.data?.merged);
+    if (mergeStatus)
+        eventText += chalk.dim(` — ${mergeStatus}`);
+    writer.printLine(`${clusterPrefix} ${eventText}`);
 }
-
 function formatPrMerged(msg, clusterPrefix, writer) {
-  const agentName = getColorForSender(msg.sender)(msg.sender);
-  writer.printLine(`${clusterPrefix} ${agentName} merged PR`);
+    const agentName = getColorForSender(msg.sender)(msg.sender);
+    writer.printLine(`${clusterPrefix} ${agentName} merged PR`);
 }
-
 function formatUnknownTopic(msg, clusterPrefix, writer) {
-  const agentName = getColorForSender(msg.sender)(msg.sender);
-  const eventText = `${agentName} ${msg.topic.toLowerCase().replace(/_/g, ' ')}`;
-  writer.printLine(`${clusterPrefix} ${eventText}`);
+    const agentName = getColorForSender(msg.sender)(msg.sender);
+    const eventText = `${agentName} ${msg.topic.toLowerCase().replace(/_/g, ' ')}`;
+    writer.printLine(`${clusterPrefix} ${eventText}`);
 }
-
 function formatWatchMode(msg, isActive, writer = DEFAULT_WRITER) {
-  if (msg.topic === 'AGENT_OUTPUT' || msg.topic === 'AGENT_LIFECYCLE') return true;
-  const clusterPrefix = buildClusterPrefix(msg.cluster_id, isActive);
-  const handlers = {
-    AGENT_ERROR: formatAgentError,
-    ISSUE_OPENED: formatIssueOpened,
-    IMPLEMENTATION_READY: formatImplementationReady,
-    VALIDATION_RESULT: formatValidationResult,
-    PR_CREATED: formatPrCreated,
-    PR_MERGED: formatPrMerged,
-  };
-  (handlers[msg.topic] || formatUnknownTopic)(msg, clusterPrefix, writer);
-  return true;
+    if (msg.topic === 'AGENT_OUTPUT' || msg.topic === 'AGENT_LIFECYCLE')
+        return true;
+    const clusterPrefix = buildClusterPrefix(msg.cluster_id, isActive);
+    const handlers = {
+        AGENT_ERROR: formatAgentError,
+        ISSUE_OPENED: formatIssueOpened,
+        IMPLEMENTATION_READY: formatImplementationReady,
+        VALIDATION_RESULT: formatValidationResult,
+        PR_CREATED: formatPrCreated,
+        PR_MERGED: formatPrMerged,
+    };
+    (handlers[msg.topic] ?? formatUnknownTopic)(msg, clusterPrefix, writer);
+    return true;
 }
-
 module.exports = {
-  formatWatchMode,
-  formatImplementationReady,
-  formatPrCreated,
+    formatWatchMode,
+    formatImplementationReady,
+    formatPrCreated,
 };

package/cli/message-formatters-watch.ts

@@ -0,0 +1,189 @@
+import chalk = require('chalk');
+import formatterUtils = require('./message-formatter-utils');
+import eventCopy = require('./event-copy');
+
+const { buildClusterPrefix, getColorForSender, parseDataField } = formatterUtils;
+const { EVENT_COPY, formatMergeStatus } = eventCopy;
+
+interface WatchMessageData {
+  issue_number?: string | number;
+  title?: string;
+  prompt?: string;
+  approved?: boolean | string;
+  summary?: string;
+  errors?: unknown;
+  issues?: unknown;
+  pr_number?: string | number;
+  merged?: unknown;
+}
+
+interface WatchMessage {
+  sender: string;
+  cluster_id: string;
+  topic: string;
+  content?: {
+    text?: string;
+    data?: WatchMessageData;
+  };
+}
+
+interface LineWriter {
+  printLine(text: string): void;
+}
+
+type WatchMessageHandler = (
+  message: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+) => void;
+
+interface CountableData {
+  readonly length: number;
+}
+
+const DEFAULT_WRITER: Readonly<LineWriter> = Object.freeze({
+  printLine: (text: string) => console.log(text),
+});
+
+function isCountableData(value: unknown): value is CountableData {
+  if (typeof value === 'string') return true;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'length' in value &&
+    typeof value.length === 'number'
+  );
+}
+
+function formatAgentError(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  writer.printLine(`${clusterPrefix} ${chalk.bold.red(`Error: ${msg.sender}`)}`);
+  if (msg.content?.text) {
+    writer.printLine(`${clusterPrefix}   ${chalk.red(msg.content.text)}`);
+  }
+  writer.printLine(`${clusterPrefix}   Next: zeroshot logs ${msg.cluster_id} -f`);
+}
+
+function formatIssueOpened(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  const issueNum = msg.content?.data?.issue_number || '';
+  const title = msg.content?.data?.title || '';
+  const prompt = msg.content?.data?.prompt || msg.content?.text || '';
+  const taskDesc = title === 'Manual Input' && prompt ? prompt : title;
+  const truncatedDesc =
+    taskDesc && taskDesc.length > 60 ? `${taskDesc.substring(0, 60)}...` : taskDesc;
+  const issueLabel = issueNum ? `#${issueNum}` : 'task';
+  const description = truncatedDesc ? chalk.dim(` - ${truncatedDesc}`) : '';
+  const eventText = `Started ${issueLabel}${description}`;
+  writer.printLine(`${clusterPrefix} ${eventText}`);
+}
+
+function formatImplementationReady(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter = DEFAULT_WRITER
+): void {
+  const agentName = getColorForSender(msg.sender)(msg.sender);
+  writer.printLine(
+    `${clusterPrefix} ${agentName} ${EVENT_COPY.IMPLEMENTATION_READY.toLowerCase()}`
+  );
+}
+
+function printRejectionDetails(
+  data: WatchMessageData,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  const errors = parseDataField(data.errors);
+  const issues = parseDataField(data.issues);
+  if (isCountableData(errors) && errors.length > 0) {
+    const count = JSON.stringify(errors).length;
+    writer.printLine(
+      `${clusterPrefix}   ${chalk.red('•')} ${errors.length} error${errors.length > 1 ? 's' : ''} (${count} chars)`
+    );
+  }
+  if (isCountableData(issues) && issues.length > 0) {
+    const count = JSON.stringify(issues).length;
+    writer.printLine(
+      `${clusterPrefix}   ${chalk.yellow('•')} ${issues.length} issue${issues.length > 1 ? 's' : ''} (${count} chars)`
+    );
+  }
+}
+
+function formatValidationResult(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  const agentName = getColorForSender(msg.sender)(msg.sender);
+  const data = msg.content?.data;
+  const approved = data?.approved === 'true' || data?.approved === true;
+  const status = approved ? chalk.green('Approved') : chalk.red('Rejected');
+  let eventText = `${agentName} ${status}`;
+  if (data?.summary && !approved) eventText += chalk.dim(` - ${data.summary}`);
+  writer.printLine(`${clusterPrefix} ${eventText}`);
+  if (!approved && data) printRejectionDetails(data, clusterPrefix, writer);
+}
+
+function formatPrCreated(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter = DEFAULT_WRITER
+): void {
+  const agentName = getColorForSender(msg.sender)(msg.sender);
+  const prNum = msg.content?.data?.pr_number || '';
+  let eventText = `${agentName} ${EVENT_COPY.PR_CREATED.toLowerCase()}${prNum ? ` #${prNum}` : ''}`;
+  const mergeStatus = formatMergeStatus(msg.content?.data?.merged);
+  if (mergeStatus) eventText += chalk.dim(` — ${mergeStatus}`);
+  writer.printLine(`${clusterPrefix} ${eventText}`);
+}
+
+function formatPrMerged(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  const agentName = getColorForSender(msg.sender)(msg.sender);
+  writer.printLine(`${clusterPrefix} ${agentName} merged PR`);
+}
+
+function formatUnknownTopic(
+  msg: WatchMessage,
+  clusterPrefix: string,
+  writer: LineWriter
+): void {
+  const agentName = getColorForSender(msg.sender)(msg.sender);
+  const eventText = `${agentName} ${msg.topic.toLowerCase().replace(/_/g, ' ')}`;
+  writer.printLine(`${clusterPrefix} ${eventText}`);
+}
+
+function formatWatchMode(
+  msg: WatchMessage,
+  isActive: boolean,
+  writer: LineWriter = DEFAULT_WRITER
+): true {
+  if (msg.topic === 'AGENT_OUTPUT' || msg.topic === 'AGENT_LIFECYCLE') return true;
+  const clusterPrefix = buildClusterPrefix(msg.cluster_id, isActive);
+  const handlers: Readonly<Record<string, WatchMessageHandler>> = {
+    AGENT_ERROR: formatAgentError,
+    ISSUE_OPENED: formatIssueOpened,
+    IMPLEMENTATION_READY: formatImplementationReady,
+    VALIDATION_RESULT: formatValidationResult,
+    PR_CREATED: formatPrCreated,
+    PR_MERGED: formatPrMerged,
+  };
+  (handlers[msg.topic] ?? formatUnknownTopic)(msg, clusterPrefix, writer);
+  return true;
+}
+
+export = {
+  formatWatchMode,
+  formatImplementationReady,
+  formatPrCreated,
+};